feat(passport): implement SetPassportDataErrors

Add the PassportElementError sealed union (data field, front/reverse
side, selfie, file, files, translation file/files, unspecified) mapping
to MTProto secure-value errors with base64 hash decoding and the
element-type -> SecureValueType mapping. The conformance deferred list is
now empty: every published method is implemented or categorized. Tell
goconst to ignore test files so enum-mapping case labels aren't flagged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

.golangci.yml

@@ -42,6 +42,9 @@ linters:
     goconst:
       min-len: 2
       min-occurrences: 3
+      # Enum-mapping switch labels (e.g. secureValueType) repeat as test inputs;
+      # that is not a reason to introduce a constant.
+      ignore-tests: true
     misspell:
       locale: US
     lll:

conformance_test.go

@@ -20,9 +20,10 @@ var coveredByOtherMeans = map[string]string{
 // deferredMethods lists published methods that are planned but not yet
 // implemented. Each is an acknowledged gap tracked in docs/roadmap.md; the
 // conformance test allows them so it can still catch *unacknowledged* drift.
-var deferredMethods = map[string]string{
-	"setPassportDataErrors": "Telegram Passport — deferred",
-}
+//
+// Empty: every method published in the snapshot is now implemented or
+// categorized as not-applicable below.
+var deferredMethods = map[string]string{}
 
 // notApplicableMethods lists published methods that do not apply to the
 // MTProto-native model and are intentionally not implemented.

passport.go

@@ -0,0 +1,254 @@
+package botapi
+
+import (
+	"context"
+	"encoding/base64"
+
+	"github.com/gotd/td/tg"
+)
+
+// PassportElementError is a sealed union describing one error in a Telegram
+// Passport element. The user will not be able to resubmit the element until the
+// error is resolved.
+//
+// Concrete variants mirror the Bot API: *PassportElementErrorDataField,
+// *PassportElementErrorFrontSide, *PassportElementErrorReverseSide,
+// *PassportElementErrorSelfie, *PassportElementErrorFile,
+// *PassportElementErrorFiles, *PassportElementErrorTranslationFile,
+// *PassportElementErrorTranslationFiles, *PassportElementErrorUnspecified.
+type PassportElementError interface {
+	isPassportElementError()
+	toTg() (tg.SecureValueErrorClass, error)
+}
+
+// PassportElementErrorDataField is an error in a data field.
+type PassportElementErrorDataField struct {
+	Type      string `json:"type"`
+	FieldName string `json:"field_name"`
+	DataHash  string `json:"data_hash"`
+	Message   string `json:"message"`
+}
+
+// PassportElementErrorFrontSide is an error in the document's front side.
+type PassportElementErrorFrontSide struct {
+	Type     string `json:"type"`
+	FileHash string `json:"file_hash"`
+	Message  string `json:"message"`
+}
+
+// PassportElementErrorReverseSide is an error in the document's reverse side.
+type PassportElementErrorReverseSide struct {
+	Type     string `json:"type"`
+	FileHash string `json:"file_hash"`
+	Message  string `json:"message"`
+}
+
+// PassportElementErrorSelfie is an error in the selfie with the document.
+type PassportElementErrorSelfie struct {
+	Type     string `json:"type"`
+	FileHash string `json:"file_hash"`
+	Message  string `json:"message"`
+}
+
+// PassportElementErrorFile is an error in a document scan.
+type PassportElementErrorFile struct {
+	Type     string `json:"type"`
+	FileHash string `json:"file_hash"`
+	Message  string `json:"message"`
+}
+
+// PassportElementErrorFiles is an error in a list of document scans.
+type PassportElementErrorFiles struct {
+	Type       string   `json:"type"`
+	FileHashes []string `json:"file_hashes"`
+	Message    string   `json:"message"`
+}
+
+// PassportElementErrorTranslationFile is an error in a translation scan.
+type PassportElementErrorTranslationFile struct {
+	Type     string `json:"type"`
+	FileHash string `json:"file_hash"`
+	Message  string `json:"message"`
+}
+
+// PassportElementErrorTranslationFiles is an error in a list of translation
+// scans.
+type PassportElementErrorTranslationFiles struct {
+	Type       string   `json:"type"`
+	FileHashes []string `json:"file_hashes"`
+	Message    string   `json:"message"`
+}
+
+// PassportElementErrorUnspecified is an error in an unspecified place.
+type PassportElementErrorUnspecified struct {
+	Type        string `json:"type"`
+	ElementHash string `json:"element_hash"`
+	Message     string `json:"message"`
+}
+
+func (*PassportElementErrorDataField) isPassportElementError()        {}
+func (*PassportElementErrorFrontSide) isPassportElementError()        {}
+func (*PassportElementErrorReverseSide) isPassportElementError()      {}
+func (*PassportElementErrorSelfie) isPassportElementError()           {}
+func (*PassportElementErrorFile) isPassportElementError()             {}
+func (*PassportElementErrorFiles) isPassportElementError()            {}
+func (*PassportElementErrorTranslationFile) isPassportElementError()  {}
+func (*PassportElementErrorTranslationFiles) isPassportElementError() {}
+func (*PassportElementErrorUnspecified) isPassportElementError()      {}
+
+func (e *PassportElementErrorDataField) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.DataHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorData{Type: secureValueType(e.Type), DataHash: h, Field: e.FieldName, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorFrontSide) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.FileHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorFrontSide{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorReverseSide) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.FileHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorReverseSide{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorSelfie) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.FileHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorSelfie{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorFile) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.FileHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorFile{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorFiles) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHashes(e.FileHashes)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorFiles{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorTranslationFile) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.FileHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorTranslationFile{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorTranslationFiles) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHashes(e.FileHashes)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueErrorTranslationFiles{Type: secureValueType(e.Type), FileHash: h, Text: e.Message}, nil
+}
+
+func (e *PassportElementErrorUnspecified) toTg() (tg.SecureValueErrorClass, error) {
+	h, err := decodeHash(e.ElementHash)
+	if err != nil {
+		return nil, err
+	}
+	return &tg.SecureValueError{Type: secureValueType(e.Type), Hash: h, Text: e.Message}, nil
+}
+
+// SetPassportDataErrors reports errors in the Telegram Passport data the user
+// submitted to the bot, so the user can fix and resubmit them.
+func (b *Bot) SetPassportDataErrors(ctx context.Context, userID int64, errs []PassportElementError) error {
+	user, err := b.resolveInputUser(ctx, userID)
+	if err != nil {
+		return err
+	}
+
+	tgErrors := make([]tg.SecureValueErrorClass, 0, len(errs))
+	for _, e := range errs {
+		if e == nil {
+			continue
+		}
+		converted, err := e.toTg()
+		if err != nil {
+			return err
+		}
+		tgErrors = append(tgErrors, converted)
+	}
+
+	if _, err := b.raw.UsersSetSecureValueErrors(ctx, &tg.UsersSetSecureValueErrorsRequest{
+		ID:     user,
+		Errors: tgErrors,
+	}); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// decodeHash decodes a base64 Passport data hash into raw bytes.
+func decodeHash(s string) ([]byte, error) {
+	h, err := base64.StdEncoding.DecodeString(s)
+	if err != nil {
+		return nil, &Error{Code: 400, Description: "Bad Request: invalid passport data hash"}
+	}
+	return h, nil
+}
+
+func decodeHashes(hashes []string) ([][]byte, error) {
+	out := make([][]byte, 0, len(hashes))
+	for _, s := range hashes {
+		h, err := decodeHash(s)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, h)
+	}
+	return out, nil
+}
+
+// secureValueType maps a Bot API Passport element type to the MTProto secure
+// value type. An unknown type falls back to personal details.
+func secureValueType(t string) tg.SecureValueTypeClass {
+	switch t {
+	case "personal_details":
+		return &tg.SecureValueTypePersonalDetails{}
+	case "passport":
+		return &tg.SecureValueTypePassport{}
+	case "driver_license":
+		return &tg.SecureValueTypeDriverLicense{}
+	case "identity_card":
+		return &tg.SecureValueTypeIdentityCard{}
+	case "internal_passport":
+		return &tg.SecureValueTypeInternalPassport{}
+	case "address":
+		return &tg.SecureValueTypeAddress{}
+	case "utility_bill":
+		return &tg.SecureValueTypeUtilityBill{}
+	case "bank_statement":
+		return &tg.SecureValueTypeBankStatement{}
+	case "rental_agreement":
+		return &tg.SecureValueTypeRentalAgreement{}
+	case "passport_registration":
+		return &tg.SecureValueTypePassportRegistration{}
+	case "temporary_registration":
+		return &tg.SecureValueTypeTemporaryRegistration{}
+	case "phone_number":
+		return &tg.SecureValueTypePhone{}
+	case "email":
+		return &tg.SecureValueTypeEmail{}
+	default:
+		return &tg.SecureValueTypePersonalDetails{}
+	}
+}

passport_test.go

@@ -0,0 +1,56 @@
+package botapi
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestPassportErrorToTg(t *testing.T) {
+	hash := base64.StdEncoding.EncodeToString([]byte("abc"))
+
+	df := &PassportElementErrorDataField{Type: "passport", FieldName: "first_name", DataHash: hash, Message: "blurry"}
+	got, err := df.toTg()
+	if err != nil {
+		t.Fatal(err)
+	}
+	data, ok := got.(*tg.SecureValueErrorData)
+	if !ok || data.Field != "first_name" || data.Text != "blurry" || string(data.DataHash) != "abc" {
+		t.Fatalf("data field: %#v", got)
+	}
+	if _, ok := data.Type.(*tg.SecureValueTypePassport); !ok {
+		t.Fatalf("type: %T", data.Type)
+	}
+
+	files := &PassportElementErrorFiles{Type: "utility_bill", FileHashes: []string{hash, hash}, Message: "x"}
+	fg, err := files.toTg()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f, ok := fg.(*tg.SecureValueErrorFiles); !ok || len(f.FileHash) != 2 {
+		t.Fatalf("files: %#v", fg)
+	}
+}
+
+func TestPassportErrorInvalidHash(t *testing.T) {
+	df := &PassportElementErrorFrontSide{Type: "driver_license", FileHash: "!!!not-base64!!!", Message: "x"}
+	if _, err := df.toTg(); err == nil {
+		t.Fatal("expected error for invalid base64 hash")
+	}
+}
+
+func TestSecureValueTypeMapping(t *testing.T) {
+	cases := map[string]any{
+		"driver_license":   &tg.SecureValueTypeDriverLicense{},
+		"email":            &tg.SecureValueTypeEmail{},
+		"phone_number":     &tg.SecureValueTypePhone{},
+		"unknown_whatever": &tg.SecureValueTypePersonalDetails{}, // fallback
+	}
+	for in, want := range cases {
+		got := secureValueType(in)
+		if got.TypeID() != want.(tg.SecureValueTypeClass).TypeID() {
+			t.Fatalf("%q: got %T, want %T", in, got, want)
+		}
+	}
+}