Documentation
¶
Overview ¶
Package errmodel is AuthKit's one error model: the catalog fixing every wire code's HTTP status and message, the concrete error value, and its constructors. Hosts see these values only through iam.Error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( CodeTwoFAEnrollmentRequired = def("2fa_enrollment_required", 403, "Two-factor authentication setup is required to finish signing in.") CodeTwoFAFactorExists = def("2fa_factor_exists", 409, "A two-factor method is already enrolled. Remove it before adding another.") CodeTwoFARequired = def("2fa_required", 403, "Two-factor authentication is required.") CodeAccessTokenHasSub = def("access_token_has_sub", 401, "An access token must not carry a subject.") CodeAccessTokenWrongTyp = def("access_token_wrong_typ", 401, "The token type is wrong for an access token.") CodeAccountAuthorityEscalation = def("account_authority_escalation", 403, "That account holds authority you do not.") CodeAccountDisabled = def("account_disabled", 401, "This account is disabled.") CodeAccountExistsLinkRequired = def("account_exists_link_required", 409, "An account with this email already exists. Sign in, then link the provider from your account page.") CodeAccountRecoveryExpired = def("account_recovery_expired", 409, "The account recovery window has ended.") CodeAccountRecoveryRequired = def("account_recovery_required", 409, "Confirm account recovery before signing in.") CodeAddressMismatch = def("address_mismatch", 400, "The address does not match.") CodeAddressRequired = def("address_required", 400, "An address is required.") CodeAPIKeyExpired = def("api_key_expired", 401, "The API key has expired.") CodeAPIKeyInvalid = def("api_key_invalid", 401, "The API key is invalid.") CodeAPIKeyNotFound = def("api_key_not_found", 404, "The API key was not found.") CodeAPIKeyRevoked = def("api_key_revoked", 401, "The API key has been revoked.") CodeAuthRequiredForLink = def("auth_required_for_link", 401, "Sign in before linking a provider.") CodeAuthenticationFailed = def("authentication_failed", 401, "Authentication failed.") CodeAvatarURLInvalid = def("avatar_url_invalid", 400, "The avatar URL is invalid.") CodeBadAudience = def("bad_audience", 401, "The token audience is not accepted.") CodeBadIssuer = def("bad_issuer", 401, "The token issuer is not trusted.") CodeBootstrapDatabaseNotEmpty = def("bootstrap_database_not_empty", 409, "The database is not empty; bootstrap refused.") CodeCannotRemoveLastContact = def("cannot_remove_last_contact", 409, "Verify an email address before removing your phone number.") CodeCannotTargetSelf = def("cannot_target_self", 403, "You cannot perform this action on yourself.") CodeCannotUnlinkLastLoginMethod = def("cannot_unlink_last_login_method", 400, "You can't unlink your last way to sign in.") CodeChallengeExpired = def("challenge_expired", 401, "Your verification session has expired. Start again.") CodeChallengeMismatch = def("challenge_mismatch", 401, "Authentication failed.") CodeChallengeNotFound = def("challenge_not_found", 401, "Your verification session has expired. Start again.") CodeCodeExpired = def("code_expired", 401, "This code has expired or can't be used again. Send a new code.") CodeConfirmationWrongTokenType = def("confirmation_wrong_token_type", 401, "This token type does not accept a confirmation claim.") CodeConflictingSubject = def("conflicting_subject", 401, "The token carries conflicting subjects.") CodeContactNotVerified = def("contact_not_verified", 409, "The email address or phone number is not verified.") CodeDelegatedAccessWrongTyp = def("delegated_access_wrong_typ", 401, "The token type is wrong for delegated access.") CodeDelegationRefused = def("delegation_refused", 403, "The delegation was refused.") CodeDeviceKeysDisabled = def("device_keys_disabled", 403, "Device keys are disabled.") CodeEmailAlreadyVerified = def("email_already_verified", 409, "Your email address is already verified.") CodeEmailDeliveryFailed = def("email_delivery_failed", 502, "We couldn't deliver the email. Please try again, or contact support.") CodeEmailInUse = def("email_in_use", 400, "This email is already in use.") CodeExternalInvitesDisabled = def("external_invites_disabled", 403, "Invite links are disabled.") CodeForbidden = def("forbidden", 403, "You don't have permission to do that.") CodeGroupConflict = def("group_conflict", 409, "The group id is taken by a deleted group or a group of another persona.") CodeGroupNotFound = def("group_not_found", 404, "The group was not found.") CodeInsufficientAuthority = def("insufficient_authority", 403, "You do not have the authority for this operation.") CodeInternalError = def("internal_error", 500, "Something went wrong on our side. Please try again.") CodeInvalidTwoFAMethod = def("invalid_2fa_method", 400, "The two-factor method is invalid.") CodeInvalidAddress = def("invalid_address", 400, "The address is invalid.") CodeInvalidAudiences = def("invalid_audiences", 400, "The audiences are invalid.") CodeInvalidBootstrapManifest = def("invalid_bootstrap_manifest", 400, "The bootstrap manifest is invalid.") CodeInvalidChallenge = def("invalid_challenge", 401, "Your 2FA session is invalid or expired.") CodeInvalidCode = def("invalid_code", 401, "Invalid verification code.") CodeInvalidConfirmation = def("invalid_confirmation", 401, "The confirmation claim is invalid.") CodeInvalidCredentials = def("invalid_credentials", 401, "Wrong email or password.") CodeInvalidDelegateCertificate = def("invalid_delegate_certificate", 400, "The delegate certificate is invalid.") CodeInvalidDomain = def("invalid_domain", 401, "Authentication failed.") CodeInvalidEmail = defParam("invalid_email", 400, "email", "Please enter a valid email address.") CodeInvalidExpiry = def("invalid_expiry", 400, "The expiry is invalid.") CodeInvalidIdentifier = def("invalid_identifier", 400, "Please enter a valid email address or phone number.") CodeInvalidInvite = def("invalid_invite", 400, "The invite is invalid.") CodeInvalidLink = def("invalid_link", 400, "This link is invalid or has expired.") CodeInvalidMessageEncoding = def("invalid_message_encoding", 400, "The message encoding is invalid.") CodeInvalidPassword = def("invalid_password", 401, "Incorrect password. Please try again.") CodeInvalidPhoneNumber = defParam("invalid_phone_number", 400, "phone_number", "Please enter a valid phone number.") CodeInvalidPreferredLanguage = defParam("invalid_preferred_language", 400, "preferred_language", "The preferred language is invalid.") CodeInvalidProvider = def("invalid_provider", 400, "That sign-in provider is not supported.") CodeInvalidRemoteApplication = def("invalid_remote_application", 400, "The remote application is invalid.") CodeInvalidRequest = def("invalid_request", 400, "Invalid request. Please check your input and try again.") CodeInvalidRequestedGrant = def("invalid_requested_grant", 400, "The requested grant is invalid.") CodeInvalidServiceJWT = def("invalid_service_jwt", 401, "The service token is invalid.") CodeInvalidSignature = def("invalid_signature", 401, "The wallet signature is invalid.") CodeInvalidSignatureEncoding = def("invalid_signature_encoding", 400, "The signature encoding is invalid.") CodeInvalidState = def("invalid_state", 400, "The sign-in session is invalid. Please try again.") CodeInvalidTimestamp = def("invalid_timestamp", 401, "Your verification session has expired. Start again.") CodeInvalidToken = def("invalid_token", 401, "The authentication token is invalid.") CodeInvalidUI = def("invalid_ui", 400, "The ui parameter is invalid.") CodeInvalidUntil = def("invalid_until", 400, "The until value is invalid.") CodeInvitationExpired = def("invitation_expired", 400, "The invitation has expired.") CodeInvitationNotFound = def("invitation_not_found", 404, "The invitation was not found.") CodeInvitationRevoked = def("invitation_revoked", 400, "The invitation was revoked.") CodeLastOwner = def("last_owner", 409, "The last owner cannot be removed.") CodeMalformedPermissions = def("malformed_permissions", 401, "The permissions claim is malformed.") CodeMethodNotAllowed = def("method_not_allowed", 405, "That method is not allowed on this path.") CodeMissingAudience = def("missing_audience", 401, "The token carries no audience.") CodeMissingDelegatedSub = def("missing_delegated_sub", 401, "The delegated token carries no subject.") CodeMissingExp = def("missing_exp", 401, "The token carries no expiry.") CodeMissingFields = def("missing_fields", 400, "Please fill in all required fields.") CodeMissingIAT = def("missing_iat", 401, "The token carries no issued-at.") CodeMissingKID = def("missing_kid", 401, "The token names no key.") CodeMissingName = def("missing_name", 400, "A name is required.") CodeMissingNBF = def("missing_nbf", 401, "The token carries no not-before.") CodeMissingSessionID = def("missing_session_id", 400, "A session id is required.") CodeMissingSidClaim = def("missing_sid_claim", 400, "The token carries no session.") CodeMissingSub = def("missing_sub", 401, "The token carries no subject.") CodeMissingTokenTyp = def("missing_token_typ", 401, "The token carries no type.") CodeNameAdmissionRefused = def("name_admission_refused", 403, "That name was refused.") CodeNoSession = def("no_session", 401, "No session is signed in.") CodeNotDelegatedAccessToken = def("not_delegated_access_token", 401, "The token is not a delegated access token.") CodeNotFound = def("not_found", 404, "The requested resource was not found.") CodeNotImplemented = def("not_implemented", 501, "Not implemented.") CodeOIDCBeginFailed = def("oidc_begin_failed", 400, "The provider sign-in could not be started.") CodeOIDCExchangeFailed = def("oidc_exchange_failed", 401, "The provider sign-in could not be completed.") CodeOriginNotAllowed = def("origin_not_allowed", 403, "The request origin is not allowed.") CodePasskeyCloneDetected = def("passkey_clone_detected", 401, "The passkey appears to have been cloned.") CodePasskeyNotFound = def("passkey_not_found", 404, "The passkey was not found.") CodePasskeyRequired = def("passkey_required", 403, "This account signs in with a passkey. Use your passkey to continue.") CodePasskeyUserVerificationRequired = def("passkey_user_verification_required", 401, "The passkey must verify the user.") CodePasswordChangeFailed = def("password_change_failed", 400, "The password could not be changed.") CodePasswordContainsIdentifier = defParam("password_contains_identifier", 400, "password", "Password can't contain your username or email.") CodePasswordRequirementsUnmet = defParam("password_requirements_unmet", 400, "password", "Password doesn't meet the requirements.") CodePasswordResetRequired = def("password_reset_required", 401, "A password reset is required before you can sign in.") CodePasswordTooCommon = defParam("password_too_common", 400, "password", "This password is too common. Choose a less predictable one.") CodePasswordTooLong = defParam("password_too_long", 400, "password", "Password is too long.") CodePasswordTooShort = defParam("password_too_short", 400, "password", "Password is too short.") CodePasswordlessDisabled = def("passwordless_disabled", 403, "Passwordless sign-in is disabled.") CodePermissionNotGranted = def("permission_not_granted", 403, "The token claims a permission it was not granted.") CodePhoneAlreadyVerified = def("phone_already_verified", 409, "Your phone number is already verified.") CodePhoneInUse = def("phone_in_use", 400, "This phone number is already in use.") CodePhoneNumberMustBeE164 = def("phone_number_must_be_e164", 400, "Enter the phone number in international format, e.g. +1234567890.") CodePhoneNumberRequired = def("phone_number_required", 400, "A phone number is required.") CodeProviderAlreadyLinked = def("provider_already_linked", 409, "This provider account is already linked to a different user.") CodeProviderChangeRequiresUnlink = def("provider_change_requires_unlink", 409, "Unlink the current account before linking another.") CodeProviderError = def("provider_error", 400, "The provider returned an error. Please try again.") CodeProviderNotLinked = def("provider_not_linked", 400, "That provider is not linked.") CodeRateLimited = def("rate_limited", 429, "Too many attempts. Please try again later.") CodeRegistrationDisabled = def("registration_disabled", 403, "Registration is currently disabled.") CodeRemoteApplicationAccessHasSubject = def("remote_application_access_has_subject", 401, "A remote-application token must not carry a subject.") CodeRemoteApplicationIssuerConflict = def("remote_application_issuer_conflict", 409, "That issuer already belongs to another remote application.") CodeRemoteApplicationNotFound = def("remote_application_not_found", 404, "The remote application was not found.") CodeRenameRateLimited = def("rename_rate_limited", 429, "Too many username changes. Please try again later.") CodeRenamesDisabled = def("renames_disabled", 403, "Username changes are disabled.") CodeReservedIssuer = def("reserved_issuer", 400, "That issuer is reserved.") CodeRoleAssignmentEscalation = def("role_assignment_escalation", 403, "That role confers authority you do not hold.") CodeRoleNotAssignable = def("role_not_assignable", 400, "The role cannot be assigned in this group.") CodeSenderProofRequired = def("sender_proof_required", 401, "The token requires sender proof.") CodeServerBusy = def("server_busy", 503, "The server is busy. Try again in a moment.") CodeServiceJWTLifetimeExceeded = def("service_jwt_lifetime_exceeded", 401, "The service token lifetime is too long.") CodeSessionRevoked = def("session_revoked", 401, "Your session has ended. Please sign in again.") CodeSMSDeliveryFailed = def("sms_delivery_failed", 502, "We couldn't deliver the text message. Please try again, or contact support.") CodeStepUpRequired = def("step_up_required", 403, "Please confirm it's you to continue.") CodeSubjectMFARequired = def("subject_mfa_required", 409, "The account must enroll two-factor authentication before it can hold this role.") CodeTokenExpired = def("token_expired", 401, "Your session has expired. Please sign in again.") CodeTokenNotYetValid = def("token_not_yet_valid", 401, "The token is not yet valid.") CodeTTLExceedsDelegateCertificate = def("ttl_exceeds_delegate_certificate", 400, "The TTL exceeds the delegate certificate.") CodeUnauthenticated = def("unauthenticated", 401, "Please sign in to continue.") CodeUnknownGroupPersona = def("unknown_group_persona", 400, "Unknown group persona.") CodeUnknownKID = def("unknown_kid", 401, "The token names an unknown key.") CodeUnknownProvider = def("unknown_provider", 400, "Unknown sign-in provider.") CodeUnsupportedMediaType = def("unsupported_media_type", 415, "Request bodies must be JSON (Content-Type: application/json).") CodeUnsupportedTokenTyp = def("unsupported_token_typ", 401, "The token type is not supported.") CodeUserBanned = def("user_banned", 401, "Your account is disabled.") CodeUserNotFound = def("user_not_found", 404, "User not found.") CodeUserReferenced = def("user_referenced", 409, "The user is still referenced.") CodeUsernameCannotContainAt = defParam("username_cannot_contain_at", 400, "username", "Username cannot contain @.") CodeUsernameCannotStartWithPlus = defParam("username_cannot_start_with_plus", 400, "username", "Username cannot start with +.") CodeUsernameInUse = defParam("username_in_use", 400, "username", "This username is already in use.") CodeUsernameInvalidCharacters = defParam("username_invalid_characters", 400, "username", "Username can only contain letters, numbers, and underscores (_).") CodeUsernameMustStartWithLetter = defParam("username_must_start_with_letter", 400, "username", "Username must start with a letter.") CodeUsernameNotAllowed = defParam("username_not_allowed", 400, "username", "This username is not allowed.") CodeUsernameTooLong = defParam("username_too_long", 400, "username", "Username is too long.") CodeUsernameTooShort = defParam("username_too_short", 400, "username", "Username is too short.") CodeVerificationRequired = def("verification_required", 403, "Verify your contact details to continue.") CodeWalletAlreadyLinked = def("wallet_already_linked", 409, "That wallet is already linked to another account.") CodeWalletChangeRequiresUnlink = def("wallet_change_requires_unlink", 409, "Unlink your current wallet before connecting another.") )
var ( ErrAccountExistsLinkRequired = E(CodeAccountExistsLinkRequired) ErrAddressMismatch = E(CodeAddressMismatch) ErrAvatarURLInvalid = E(CodeAvatarURLInvalid) ErrBootstrapDatabaseNotEmpty = E(CodeBootstrapDatabaseNotEmpty) ErrCannotRemoveLastContact = E(CodeCannotRemoveLastContact) ErrChallengeExpired = E(CodeChallengeExpired) ErrChallengeMismatch = E(CodeChallengeMismatch) ErrChallengeNotFound = E(CodeChallengeNotFound) ErrCodeExpired = E(CodeCodeExpired) ErrEmailAlreadyVerified = E(CodeEmailAlreadyVerified) ErrEmailDeliveryFailed = E(CodeEmailDeliveryFailed) ErrEmailVerificationSendFailed = Internal("email_verification_failed", nil) ErrInvalidBootstrapManifest = E(CodeInvalidBootstrapManifest) ErrInvalidCode = E(CodeInvalidCode) ErrInvalidCredentials = E(CodeInvalidCredentials) ErrInvalidDomain = E(CodeInvalidDomain) ErrInvalidExpiry = E(CodeInvalidExpiry) ErrInvalidIdentifier = E(CodeInvalidIdentifier) ErrInvalidInvite = E(CodeInvalidInvite) ErrInvalidSignature = E(CodeInvalidSignature) ErrInvalidTimestamp = E(CodeInvalidTimestamp) ErrInvalidTwoFAMethod = E(CodeInvalidTwoFAMethod) ErrInvitationExpired = E(CodeInvitationExpired) ErrInvitationRevoked = E(CodeInvitationRevoked) ErrMissingName = E(CodeMissingName) ErrNameAdmissionRefused = E(CodeNameAdmissionRefused) ErrPasskeyCloneDetected = E(CodePasskeyCloneDetected) ErrPasskeyNotFound = E(CodePasskeyNotFound) ErrPasskeyRequired = E(CodePasskeyRequired) ErrPasskeyUserVerificationRequired = E(CodePasskeyUserVerificationRequired) ErrPasswordResetRequired = E(CodePasswordResetRequired) ErrPasswordlessDisabled = E(CodePasswordlessDisabled) ErrPhoneAlreadyVerified = E(CodePhoneAlreadyVerified) ErrPhoneNumberMustBeE164 = E(CodePhoneNumberMustBeE164) ErrPhoneNumberRequired = E(CodePhoneNumberRequired) ErrPhoneVerificationSendFailed = Internal("phone_verification_failed", nil) ErrProviderAlreadyLinked = E(CodeProviderAlreadyLinked) ErrProviderChangeRequiresUnlink = E(CodeProviderChangeRequiresUnlink) ErrRegistrationDisabled = E(CodeRegistrationDisabled) ErrSMSDeliveryFailed = E(CodeSMSDeliveryFailed) ErrStepUpRequired = E(CodeStepUpRequired) ErrTwoFAEnableFailed = Internal("enable_2fa_failed", nil) ErrTwoFAFactorExists = E(CodeTwoFAFactorExists) ErrTwoFASetupCodeSendFailed = Internal("send_code_failed", nil) ErrUserBanned = E(CodeUserBanned) ErrUserReferenced = E(CodeUserReferenced) ErrWalletAlreadyLinked = E(CodeWalletAlreadyLinked) ErrWalletChangeRequiresUnlink = E(CodeWalletChangeRequiresUnlink) )
Sentinels the engine and the HTTP layer match with errors.Is. Host-facing sentinels live in iam.
Functions ¶
Types ¶
type ActionAvailability ¶ added in v0.149.0
type ActionAvailability struct {
Action string `json:"action"`
Allowed bool `json:"allowed"`
Reason string `json:"reason"`
RetryAfterSeconds int64 `json:"retry_after_seconds"`
NextAllowedAt *time.Time `json:"next_allowed_at"`
Limit *int `json:"limit"`
Remaining *int `json:"remaining"`
WindowSeconds *int64 `json:"window_seconds"`
CooldownSeconds *int64 `json:"cooldown_seconds"`
}
ActionAvailability says whether a limited action is allowed now, and when it will be: the metadata of rate_limited and rename_rate_limited.
type Code ¶
type Code string
Code is a stable, snake_case wire error code.
type ContactProofRequired ¶ added in v0.149.0
type ContactProofRequired struct {
Identifier string `json:"identifier"`
Channel string `json:"channel"`
Reason string `json:"reason"`
}
ContactProofRequired names the address an account must prove first: the metadata of verification_required and contact_not_verified. Reason says why ("contact_unproven" when no address is proven yet).
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is the one error value. Its status is always the catalog's for its code: no call site can override it. An uncatalogued code, and every Internal failure, answers 500 internal_error on the wire.
func Internal ¶ added in v0.147.0
Internal is a server failure: internal_error on the wire, op and cause in the log.
func Recode ¶
Recode re-tags err with a route-specific code, keeping err as the cause and carrying an inner Error's param and metadata forward.
func Wire ¶ added in v0.147.0
Wire is what the envelope carries for err: anything that is not an *Error is a 500 internal_error.
func (*Error) Is ¶
Is matches any *Error with the same code (and, for Internal failures, the same op), so a sentinel, a fresh E() and a wrapped copy are one identity.
func (*Error) Metadata ¶ added in v0.147.0
Metadata is a copy of the machine-readable context (nil when empty or for a server failure).
func (*Error) Param ¶
Param names the offending request field: the site's, else the catalog's. A server failure carries none.
type LengthBounds ¶ added in v0.149.0
LengthBounds is a length rule a value broke: the metadata of username_too_short/long and password_too_short/long.
type Option ¶
type Option func(*Error)
Option customises an E() value.
func WithDetails ¶ added in v0.149.0
WithDetails sets the metadata from v, a struct: one member per json-tagged field, in wire form, keeping its Go type for Go callers of Metadata.
type PasswordRequirements ¶ added in v0.149.0
type PasswordRequirements struct {
Missing []string `json:"missing"`
}
PasswordRequirements lists the character classes a new password lacks: the metadata of password_requirements_unmet.
type RetryAfter ¶ added in v0.149.0
type RetryAfter struct {
RetryAfterSeconds int64 `json:"retry_after_seconds"`
}
RetryAfter is server_busy's metadata: when to try again (also the Retry-After header).