Documentation
¶
Overview ¶
Package accesshttp serves the access HTTP routes over an account.Service. It mounts nothing itself: Routes returns each route's Descriptor and handler for the app's own mux, and every refusal goes through the app's ErrorWriter.
Index ¶
- Constants
- func Reasons() []string
- type AdminUsersQuery
- type AuditEvent
- type CeremonyResponse
- type Class
- type Code
- type Config
- type CurrentSessionView
- type Descriptor
- type Error
- type ErrorWriter
- type Handler
- type InviteAcceptRequest
- type InviteRequest
- type KeyCreatedResponse
- type KeyView
- type Kind
- type LoginRequest
- type MeResponse
- type MethodLockView
- type MethodsView
- type NameRequest
- type NewKeyRequest
- type NewUserRequest
- type OIDCCallbackQuery
- type OIDCSignInQuery
- type OIDCStartResponse
- type PasskeyBeginQuery
- type PasskeyView
- type PasswordChangeRequest
- type PasswordRemoveRequest
- type PasswordRequest
- type PendingLinkResponse
- type ProfileRequest
- type RecoverPasswordRequest
- type RecoveryPasskeyFinishQuery
- type RecoveryResponse
- type RedirectRequest
- type Route
- type SessionView
- type SetupPasskeyBeginRequest
- type SetupPasswordRequest
- type SignedInResponse
- type StateResponse
- type TTLRequest
- type TokenRequest
- type TokenResponse
- type TokenView
- type UserMethodsView
- type UserUpdateRequest
- type UserView
Constants ¶
const ( ReasonSSOGoverned = "sso_governed" ReasonTTLTooLong = "ttl_too_long" ReasonTTLNegative = "ttl_negative" ReasonNoChange = "no_change" ReasonExpiryInvalid = "expiry_invalid" ReasonRedirectTooLong = "redirect_too_long" ReasonCurrentPasswordRequired = "current_password_required" ReasonSessionGone = "session_gone" ReasonPendingTooLarge = "pending_too_large" ReasonStaleAuthentication = "stale_authentication" ReasonFlowInvalid = "flow_invalid" ReasonDiscoveryFailed = "discovery_failed" ReasonExchangeFailed = "exchange_failed" ReasonTokenInvalid = "token_invalid" ReasonNonceMismatch = "nonce_mismatch" ReasonNoUsername = "no_username" ReasonProvisioningDisabled = "provisioning_disabled" ReasonNotAdmitted = "not_admitted" ReasonUsernameInvalid = "username_invalid" ReasonRecovery = "recovery" // auth_session_required on a recovery route ReasonReenableNeedsOtherMethod = failreason.ReenableNeedsOtherMethod ReasonTrailingData = "trailing_data" // auth_bad_request: data after the JSON value ReasonMalformedJSON = "malformed_json" // auth_bad_request: the body is not one JSON value ReasonContentType = "content_type" // auth_bad_request: the body is not application/json ReasonBody = "body" // auth_bad_request: the body is unreadable or not an object ReasonUnknownField = "unknown_field" // auth_bad_request: a key the request type lacks ReasonTokenInQuery = "token_in_query" // auth_bad_request: a token route got a token in its URL )
The Error.Reason values accesshttp assigns itself, in Reasons order.
Variables ¶
This section is empty.
Functions ¶
func Reasons ¶
func Reasons() []string
Reasons returns every fixed Error.Reason, each once, in a stable order: accesshttp's own, then access's PasswordRejections, account's PolicyReasons, UsernameReasons and TextError reasons, and webauthn's OriginRejections. Two families stay open and are not listed: "provider_error:" followed by an IdP's error code on auth_oidc_failed, and on auth_bad_request the name of the body field, path value or query key that was refused; the refusals of the body or URL as a whole are listed.
Types ¶
type AdminUsersQuery ¶
type AdminUsersQuery struct {
Key int64 `json:"key,omitempty"` // a positive decimal key ID, or absent
}
AdminUsersQuery is authAdminUsers' query.
type AuditEvent ¶
type AuditEvent struct {
Kind string // "login.success", "login.failure", "login.rate_limited", "setup.failure", ...
Username string // canonical, or "" when the input was refused; never the raw input
IP string
Method access.Method
// Reason is a code-like class: "invalid_credentials", "method_locked",
// "provider_error:access_denied", "exchange_failed".
Reason string
SessionID string
UserID int64
KeyID int64
Success bool
}
AuditEvent is one request-level outcome that changes no state: a failure, a refusal or a rate limit, and the sign-ins beside them. It carries no raw request text: no user agent, no provider error_description, no typed username that failed normalisation.
type CeremonyResponse ¶
type CeremonyResponse struct {
Ceremony string `json:"ceremony"` // echoed in X-Auth-Ceremony on finish
// PublicKey is webauthn.CredentialCreation or webauthn.CredentialAssertion
// in the browser's JSON shape ({"publicKey": …, "mediation"?}).
PublicKey json.RawMessage `json:"public_key"`
}
CeremonyResponse is a begun WebAuthn ceremony.
type Class ¶
type Class string
Class is who a route admits; its guard enforces it.
const ( ClassPublic Class = "public" ClassSession Class = "session" ClassRecentAuth Class = "recent_auth" ClassKeyScope Class = "key_scope" // Scope names the required key scope; a session also passes // ClassKeyPermission: a key carrying Scope, or a full session under // recent auth (account.Service.RequireKeyPermission). ClassKeyPermission Class = "key_permission" ClassRecovery Class = "recovery" // the restricted recovery session only )
The classes.
type Code ¶
type Code string
Code is a stable error code; Codes lists every one.
const ( CodeAuthRequired Code = "auth_required" CodeSessionExpired Code = "auth_session_expired" CodeInvalidCredentials Code = "auth_invalid_credentials" //nolint:gosec // G101: an error code, not a credential CodeKeyInvalid Code = "auth_key_invalid" CodeRecentAuthRequired Code = "auth_recent_auth_required" CodeSessionRequired Code = "auth_session_required" CodeScopeRequired Code = "auth_scope_required" CodeForbidden Code = "auth_forbidden" CodeRateLimited Code = "auth_rate_limited" CodeBusy Code = "auth_busy" CodeBadRequest Code = "auth_bad_request" CodeBodyTooLarge Code = "auth_body_too_large" CodeUsernameInvalid Code = "auth_username_invalid" CodeUsernameTaken Code = "auth_username_taken" CodePasswordRejected Code = "auth_password_rejected" CodePasswordLoginDisabled Code = "auth_password_login_disabled" CodeSetupComplete Code = "auth_setup_complete" CodeSetupTokenRequired Code = "auth_setup_token_required" //nolint:gosec // G101: an error code, not a credential CodeTokenInvalid Code = "auth_token_invalid" //nolint:gosec // G101: an error code, not a credential CodeLastMethod Code = "auth_last_method" CodeIdentityTaken Code = "auth_identity_taken" CodeAlreadyLinked Code = "auth_already_linked" CodeMethodNotLocked Code = "auth_method_not_locked" CodeCrossOrigin Code = "auth_cross_origin" CodeDuplicateCredential Code = "auth_duplicate_credential" //nolint:gosec // G101: an error code, not a credential CodeUnknownScope Code = "auth_unknown_scope" CodeOriginRefused Code = "auth_origin_refused" CodeCeremonyInvalid Code = "auth_ceremony_invalid" CodeNotDiscoverable Code = "auth_not_discoverable" CodeUnknownCredential Code = "auth_unknown_credential" //nolint:gosec // G101: an error code, not a credential CodeAssertionFailed Code = "auth_assertion_failed" CodeRegistrationFailed Code = "auth_registration_failed" CodeOIDCFailed Code = "auth_oidc_failed" CodeNotFound Code = "auth_not_found" CodeMethodNotAllowed Code = "auth_method_not_allowed" )
The codes, in Codes order.
type Config ¶
type Config struct {
// Account supplies the Authenticator, and through it the session cookie
// and timeouts; accesshttp holds no copy of either. Required.
Account *account.Service
// Errors renders every refusal. Required.
Errors ErrorWriter
// Audit receives the request-level outcomes that change no state. Optional.
Audit func(r *http.Request, e AuditEvent)
PendingSealer *access.Sealer // seals the pending-link cookie; nil: an ephemeral sealer
Logger *slog.Logger // nil: slog.Default() at each log call
Prefix string // e.g. "/api/auth"; every path not under OIDCPrefix starts with it
OIDCPrefix string // the OIDC start and callback routes' prefix
SignInPath string // where the OIDC callback sends a browser on a non-success outcome
}
Config configures the handlers.
type CurrentSessionView ¶
type CurrentSessionView struct {
AuthTime time.Time `json:"auth_time"`
IdleDeadline time.Time `json:"idle_deadline"`
AbsoluteDeadline time.Time `json:"absolute_deadline"`
ID string `json:"id"`
Method access.Method `json:"method"`
}
CurrentSessionView is the caller's own session.
type Descriptor ¶
type Descriptor struct {
Request reflect.Type // nil when there is no JSON body
Query reflect.Type // the accepted query arguments; nil when none
Response reflect.Type // nil when the 2xx body is not decoded
Name string // stable, a valid TS identifier, e.g. "authLoginPassword"
Method string
Path string // full path including the configured prefix
Class Class
Scope string // ClassKeyScope and ClassKeyPermission only
Kind Kind
Doc string
// Codes is every code this route can answer, in Codes() order: its
// class guard's, its transport's and its account operation's.
Codes []Code
Passive bool // verification does not count as activity
Array bool // Response is a JSON array of Response
}
Descriptor states one route for an app's mux, gate, census and code generator.
type Error ¶
type Error struct {
Err error // for the app's log; never sent
Code Code // stable data a client branches on
Detail string // safe to show; never a secret or a raw cause
Reason string // a stable sub-reason a client may branch on
RetryAfter time.Duration // set with 429 and 503
Status int
}
Error is one refusal, handed to the ErrorWriter.
type ErrorWriter ¶
type ErrorWriter func(w http.ResponseWriter, r *http.Request, e Error)
ErrorWriter renders one refusal in the app's own envelope. accesshttp writes no error body itself: Cache-Control and, when RetryAfter is set, Retry-After are already on w when it is called.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the access routes. Build it with New.
type InviteAcceptRequest ¶
type InviteAcceptRequest struct {
Token string `json:"token"`
Username string `json:"username"`
Password string `json:"password"`
}
InviteAcceptRequest is authInviteAcceptPassword's body.
type InviteRequest ¶
InviteRequest is authAdminInvite's body.
type KeyCreatedResponse ¶
type KeyCreatedResponse struct {
Key string `json:"key"` // the plaintext, shown once
Details KeyView `json:"details"`
}
KeyCreatedResponse is a minted key. Only writeShownOnce fills Key.
type KeyView ¶
type KeyView struct {
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at,omitzero"`
LastUsedAt time.Time `json:"last_used_at,omitzero"`
Owner string `json:"owner,omitempty"` // username; set on the admin list only
Label string `json:"label"`
Prefix string `json:"prefix"`
Suffix string `json:"suffix"`
Scopes []string `json:"scopes"`
ID int64 `json:"id"`
UserID int64 `json:"user_id"`
ParentKeyID int64 `json:"parent_key_id,omitempty"` // Key.ParentKeyID()
}
KeyView is one API key, never its secret or hash.
type LoginRequest ¶
LoginRequest is authLoginPassword's body.
type MeResponse ¶
type MeResponse struct {
Session CurrentSessionView `json:"session"`
Methods MethodsView `json:"methods"`
User UserView `json:"user"`
CanLinkOIDC bool `json:"can_link_oidc"`
}
MeResponse is the signed-in user's own view.
type MethodLockView ¶
type MethodLockView struct {
Method access.Method `json:"method"`
Untrusted bool `json:"untrusted"`
Trusted bool `json:"trusted"`
}
MethodLockView is one locked method, per trust context.
type MethodsView ¶
type MethodsView struct {
Locks []MethodLockView `json:"locks"` // [] when none
PasskeyCount int `json:"passkey_count"`
Password bool `json:"password"`
OIDCLinked bool `json:"oidc_linked"`
OIDCAvailable bool `json:"oidc_available"`
PasskeysAvailable bool `json:"passkeys_available"`
PasswordLogin bool `json:"password_login"`
}
MethodsView is what a user can sign in with.
type NameRequest ¶
type NameRequest struct {
Name string `json:"name"`
}
NameRequest renames a passkey or a session.
type NewKeyRequest ¶
type NewKeyRequest struct {
Label string `json:"label"`
Scopes []string `json:"scopes"`
ExpiresInDays int `json:"expires_in_days,omitempty"` // 0 = never
}
NewKeyRequest is authKeyCreate's body.
type NewUserRequest ¶
type NewUserRequest struct {
Username string `json:"username"`
Password string `json:"password,omitempty"` // empty: no sign-in method until a recovery link
Role access.Role `json:"role"`
}
NewUserRequest is authAdminUserCreate's body.
type OIDCCallbackQuery ¶
type OIDCCallbackQuery struct {
State string `json:"state"`
Code string `json:"code,omitempty"`
Error string `json:"error,omitempty"`
}
OIDCCallbackQuery is what the IdP sends on its redirect (RFC 6749 sections 4.1.2 and 4.1.2.1). It converts to oidc.Callback, which compiles only while the two types have the same fields.
type OIDCSignInQuery ¶
type OIDCSignInQuery struct {
Redirect string `json:"redirect,omitempty"`
}
OIDCSignInQuery is authOIDCStartSignIn's query.
type OIDCStartResponse ¶
type OIDCStartResponse struct {
URL string `json:"url"`
}
OIDCStartResponse is the link and step-up starts' answer.
type PasskeyBeginQuery ¶
type PasskeyBeginQuery struct {
Mediation string `json:"mediation,omitempty"` // "conditional" or absent
}
PasskeyBeginQuery is authLoginPasskeyBegin's query.
type PasskeyView ¶
type PasskeyView struct {
CreatedAt time.Time `json:"created_at"`
LastUsedAt time.Time `json:"last_used_at,omitzero"`
Name string `json:"name"`
// RPID is the relying-party ID the passkey was registered against; one
// that differs from the current RP's ID cannot sign in.
RPID string `json:"rp_id"`
ID int64 `json:"id"`
BackupEligible bool `json:"backup_eligible"`
BackedUp bool `json:"backed_up"`
CloneWarning bool `json:"clone_warning,omitempty"`
}
PasskeyView is one passkey.
type PasswordChangeRequest ¶
type PasswordChangeRequest struct {
CurrentPassword string `json:"current_password,omitempty"`
Password string `json:"password"`
}
PasswordChangeRequest is authPasswordSet's body. CurrentPassword is required when the user holds a password.
type PasswordRemoveRequest ¶
type PasswordRemoveRequest struct {
CurrentPassword string `json:"current_password"`
}
PasswordRemoveRequest is authPasswordRemove's body: the password being removed; empty is current_password_required.
type PasswordRequest ¶
type PasswordRequest struct {
Password string `json:"password"`
}
PasswordRequest is authStepUpPassword's body.
type PendingLinkResponse ¶
type PendingLinkResponse struct {
Issuer string `json:"issuer"`
UsernameHint string `json:"username_hint,omitempty"`
Email string `json:"email,omitempty"`
}
PendingLinkResponse is the identity a pending link would attach.
type ProfileRequest ¶
type ProfileRequest struct {
DisplayName string `json:"display_name"`
}
ProfileRequest is authProfile's body.
type RecoverPasswordRequest ¶
type RecoverPasswordRequest struct {
Password string `json:"password"`
KeepSessions bool `json:"keep_sessions,omitempty"`
KeepKeys bool `json:"keep_keys,omitempty"`
}
RecoverPasswordRequest is authRecoveryPassword's body.
type RecoveryPasskeyFinishQuery ¶
type RecoveryPasskeyFinishQuery struct {
KeepSessions bool `json:"keep_sessions,omitempty"` // "true" or absent
KeepKeys bool `json:"keep_keys,omitempty"` // "true" or absent
}
RecoveryPasskeyFinishQuery is authRecoveryPasskeyFinish's query.
type RecoveryResponse ¶
type RecoveryResponse struct {
Username string `json:"username"`
Methods MethodsView `json:"methods"`
}
RecoveryResponse is a started recovery.
type RedirectRequest ¶
type RedirectRequest struct {
Redirect string `json:"redirect,omitempty"` // the app's return path, at most oidc.MaxRedirectBytes
}
RedirectRequest is the OIDC link and step-up starts' body.
type Route ¶
type Route struct {
Handler http.Handler
Descriptor
}
Route is one descriptor and its handler, which the app mounts on its own mux at Method and Path.
type SessionView ¶
type SessionView struct {
CreatedAt time.Time `json:"created_at"`
LastActivity time.Time `json:"last_activity"`
AuthTime time.Time `json:"auth_time"`
// IdleDeadline and AbsoluteDeadline are access.SessionDeadlines of the
// session under the Authenticator's timeouts.
IdleDeadline time.Time `json:"idle_deadline"`
AbsoluteDeadline time.Time `json:"absolute_deadline"`
ID string `json:"id"`
Label string `json:"label,omitempty"`
UserAgent string `json:"user_agent,omitempty"`
LastIP string `json:"last_ip,omitempty"`
Method access.Method `json:"method"`
Current bool `json:"current"`
}
SessionView is one session.
type SetupPasskeyBeginRequest ¶
type SetupPasskeyBeginRequest struct {
Token string `json:"token,omitempty"`
Username string `json:"username"`
}
SetupPasskeyBeginRequest is authSetupPasskeyBegin's body.
type SetupPasswordRequest ¶
type SetupPasswordRequest struct {
Token string `json:"token,omitempty"` // required when the setup rule asks for one
Username string `json:"username"`
Password string `json:"password"`
}
SetupPasswordRequest is authSetupPassword's body.
type SignedInResponse ¶
type SignedInResponse struct {
SessionID string `json:"session_id"`
User UserView `json:"user"`
CloneWarning bool `json:"clone_warning,omitempty"`
}
SignedInResponse is the answer of every route that signs a user in.
type StateResponse ¶
type StateResponse struct {
SetupRequired bool `json:"setup_required"`
PasswordLogin bool `json:"password_login"`
Passkeys bool `json:"passkeys"`
OIDC bool `json:"oidc"`
}
StateResponse is authState's answer.
type TTLRequest ¶
type TTLRequest struct {
Hours int `json:"hours,omitempty"` // 0 = the default lifetime
}
TTLRequest is authAdminRecovery's body.
type TokenRequest ¶
type TokenRequest struct {
Token string `json:"token"`
}
TokenRequest is authRecoveryStart's body.
type TokenResponse ¶
type TokenResponse struct {
ExpiresAt time.Time `json:"expires_at"`
Token string `json:"token"` // the plaintext, shown once
}
TokenResponse is a minted invite or recovery token. Only writeShownOnce fills Token.
type TokenView ¶
type TokenView struct {
CreatedAt time.Time `json:"created_at"`
ExpiresAt time.Time `json:"expires_at"`
Purpose access.TokenPurpose `json:"purpose"` // "invite" or "recovery"
Role access.Role `json:"role,omitempty"` // invite only
// IssuerLineage is the issuing key's LineageIDs, root first; omitted for
// a token no key issued.
IssuerLineage []int64 `json:"issuer_lineage,omitempty"`
Subject int64 `json:"subject,omitempty"` // recovery only: the user it acts on
IssuedByKey int64 `json:"issued_by_key,omitempty"`
}
TokenView is one live invite or recovery token on authAdminTokens. It carries neither the token nor its hash.
type UserMethodsView ¶
type UserMethodsView struct {
PasskeyCount int `json:"passkey_count"`
Password bool `json:"password"`
}
UserMethodsView is a listed user's password and passkey count.
type UserUpdateRequest ¶
type UserUpdateRequest struct {
Role *access.Role `json:"role,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
}
UserUpdateRequest is authAdminUserUpdate's body.
type UserView ¶
type UserView struct {
CreatedAt time.Time `json:"created_at"`
// Methods is the user's sign-in methods; set on the admin list only.
Methods *UserMethodsView `json:"methods,omitempty"`
Username string `json:"username"`
DisplayName string `json:"display_name,omitempty"`
Role access.Role `json:"role"`
// KeyLineage is account.ListedUser.KeyLineage; set on the admin list only.
KeyLineage []int64 `json:"key_lineage,omitempty"`
ID int64 `json:"id"`
Enabled bool `json:"enabled"`
OIDCLinked bool `json:"oidc_linked"`
}
UserView is one user.