accesshttp

package
v1.0.0-dev.19 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

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 access.ErrorWriter.

Index

Constants

View Source
const (
	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"
	ReasonExchangeFailed           = "exchange_failed"
	ReasonTokenInvalid             = "token_invalid"
	ReasonNonceMismatch            = "nonce_mismatch"
	ReasonProvisioningDisabled     = "provisioning_disabled"
	ReasonNotAdmitted              = "not_admitted"
	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
	ReasonEnrolNeedsKnownDevice    = "enrol_needs_known_device" // auth_second_factor_required at a password sign-in
	ReasonNoUsableMethod           = "no_usable_method"         // auth_forbidden: the app allows no next step
	// ReasonSecondFactorProofRequired is auth_bad_request: a change that
	// needs a current second factor carried none.
	ReasonSecondFactorProofRequired = "second_factor_proof_required"
	ReasonLastSecondFactor          = "last_second_factor"  // auth_last_method: the rule needs the factor kept
	ReasonSecondFactorHeld          = "second_factor_held"  // auth_second_factor_required: step up with the factor
	ReasonTOTPNeedsPassword         = "totp_needs_password" // auth_forbidden: TOTP protects only a password
	// ReasonEnableWithoutSecondFactor is auth_second_factor_required: an
	// admin turning the rule on holds no usable second factor.
	ReasonEnableWithoutSecondFactor = "enable_without_second_factor"
	ReasonLinked                    = "linked" // auth_sso_only: a temporary password for a linked account
	// ReasonTemporaryPasswordExposed is auth_https_required: a temporary
	// password sent over plain HTTP where it could not finish, now cancelled.
	ReasonTemporaryPasswordExposed = failreason.TemporaryPasswordExposed
)

The access.Error Reason values accesshttp assigns itself, in Reasons order.

Variables

This section is empty.

Functions

func Reasons

func Reasons() []string

Reasons returns every fixed access.Error Reason, each once, in a stable order: accesshttp's own, then access's ErrorReasons and PasswordRejections, account's PolicyReasons, CodeReasons, UsernameReasons, TextErrors and LogFilterReasons, 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 AdminSecurityLogQuery

type AdminSecurityLogQuery struct {
	Kinds       string `json:"kinds,omitempty"`        // LogFilter.Kinds, split on ","
	User        int64  `json:"user,omitempty"`         // LogFilter.UserID
	Actor       int64  `json:"actor,omitempty"`        // LogFilter.ActorUserID
	ActorKey    int64  `json:"actor_key,omitempty"`    // LogFilter.ActorKeyID
	After       int64  `json:"after,omitempty"`        // LogFilter.AfterSeq
	Before      int64  `json:"before,omitempty"`       // LogFilter.BeforeSeq
	Limit       int64  `json:"limit,omitempty"`        // LogFilter.Limit
	OldestFirst bool   `json:"oldest_first,omitempty"` // LogFilter.OldestFirst
}

AdminSecurityLogQuery is authAdminSecurityLog's query. Kinds is a comma-separated list of kinds, OldestFirst is "true" or absent, and every other key is a positive decimal.

type AdminUsersQuery

type AdminUsersQuery struct {
	Key int64 `json:"key,omitempty"` // a positive decimal key ID, or absent
}

AdminUsersQuery is authAdminUsers' query.

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 session under
	// recent auth (account.Service.RequireKeyPermission).
	ClassKeyPermission Class = "key_permission"
)

The classes.

type CodeRequest

type CodeRequest struct {
	Ticket string `json:"ticket"`
	Code   string `json:"code"`
}

CodeRequest is a pending sign-in step's body: its ticket and a code, six digits once spaces are removed, or authLoginRecoveryCode's 16 symbols.

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 access.ErrorWriter
	// Audit receives the request-level outcomes that change no state. Optional.
	Audit         func(r *http.Request, e access.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 is where the OIDC callback sends a browser on a non-success
	// outcome. A value access.ValidateRedirectURI refuses, empty included, is "/".
	SignInPath string
}

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"`
	Secure           bool          `json:"secure"`
}

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 // one present-tense sentence saying what the route does
	// Codes is every code this route can answer, in [access.Codes] order: its
	// class guard's, its transport's and its account operation's.
	Codes   []access.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.

func Descriptors

func Descriptors(cfg DescriptorConfig) []Descriptor

Descriptors returns every route's Descriptor, in Routes order, with no Account: for the same values it equals the Descriptors of New's Routes.

type DescriptorConfig

type DescriptorConfig struct {
	Prefix           string
	OIDCPrefix       string
	AdminScope       string
	ManageUsersScope string
	CreateKeysScope  string
}

DescriptorConfig is what a route's Path and access level read: Config's two prefixes and account.Config's three key scopes.

type EnrolmentOutcome

type EnrolmentOutcome struct {
	SignedIn *SignedInResponse `json:"signed_in,omitempty"`
	// RecoveryCode is the recovery code the waiting account's binding
	// issued, shown once; absent when it issued none.
	RecoveryCode string `json:"recovery_code,omitempty" arm:"waiting_approval"`
	// WaitingApproval is always true in its arm.
	WaitingApproval bool `json:"waiting_approval,omitempty" arm:"waiting_approval"`
}

EnrolmentOutcome is a pending enrolment finish's and a passkey registration's answer, in which exactly one arm is set: signed_in, or waiting_approval for an account a registration made wait for approval, which holds no session.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler serves the access routes. Build it with New.

func New

func New(cfg Config) (*Handler, error)

New refuses a nil Account or Errors.

func (*Handler) Routes

func (h *Handler) Routes() []Route

Routes returns a copy of the routes; the app mounts any subset on its own mux.

type InviteAcceptRequest

type InviteAcceptRequest struct {
	Token    string `json:"token"`
	Username string `json:"username"`
	Password string `json:"password"`
}

InviteAcceptRequest is authInviteAcceptPassword's body.

type InviteRequest

type InviteRequest struct {
	Role  access.Role `json:"role"`
	Hours int         `json:"hours,omitempty"`
}

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.

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"`
	// PreviousUntil is the overlap's bound, set only while the superseded
	// secret still verifies at the response's now.
	PreviousUntil time.Time `json:"previous_until,omitzero"`
	Username      string    `json:"username,omitempty"` // 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 Kind

type Kind string

Kind is how a route answers: JSON bodies, or a redirect.

const (
	KindJSON     Kind = "json"
	KindRedirect Kind = "redirect"
)

The kinds.

type LogActorView

type LogActorView struct {
	SessionID string `json:"session_id,omitempty"`
	OutOfBand string `json:"out_of_band,omitempty"`
	Label     string `json:"label,omitempty"`
	UserAgent string `json:"user_agent,omitempty"`
	KeySuffix string `json:"key_suffix,omitempty"`
	UserID    int64  `json:"user_id,omitempty"`
	KeyID     int64  `json:"key_id,omitempty"`
}

LogActorView is who made a logged change, with the display data the change's Update snapshotted.

type LogClassView

type LogClassView struct {
	Class   account.LogClass `json:"class"`
	Count   int64            `json:"count"`
	Evicted int64            `json:"evicted"` // removed by the size limit, ever
}

LogClassView is one log class's entry count and cap evictions.

type LogEntryView

type LogEntryView struct {
	At         time.Time        `json:"at"`
	OccurredAt time.Time        `json:"occurred_at"` // Event.At
	Class      account.LogClass `json:"class"`
	Kind       string           `json:"kind"`
	IP         string           `json:"ip,omitempty"`
	Method     access.Method    `json:"method,omitempty"`
	Role       access.Role      `json:"role,omitempty"`
	Detail     string           `json:"detail,omitempty"`
	// SSOMode and PreviousSSOMode are an sso_mode_changed entry's new and
	// old mode; absent on every other kind.
	SSOMode         account.SSOModeName `json:"sso_mode,omitempty"`
	PreviousSSOMode account.SSOModeName `json:"previous_sso_mode,omitempty"`
	SessionIDs      []string            `json:"session_ids,omitempty"`
	Actor           LogActorView        `json:"actor"`
	Seq             int64               `json:"seq"`
	UserID          int64               `json:"user_id,omitempty"`
	KeyID           int64               `json:"key_id,omitempty"`
	PasskeyID       int64               `json:"passkey_id,omitempty"`
	// IssuerUserID is the issuing user of a withdrawn temporary password or
	// of one an admin link spent.
	IssuerUserID int64 `json:"issuer_user_id,omitempty"`
	Trusted      bool  `json:"trusted,omitempty"`
	// Plain is a temporary_password_used entry whose secret crossed plain
	// HTTP.
	Plain bool `json:"plain,omitempty"`
}

LogEntryView is one security-log entry.

type LoginRequest

type LoginRequest struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

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"`
	// SSOOnly is account.Me.SSOOnly: the stored SSO mode keeps this user's
	// local methods dormant.
	SSOOnly    bool `json:"sso_only"`
	Owner      bool `json:"owner"`
	SingleUser bool `json:"single_user"`
}

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 {
	TOTP              TOTPView         `json:"totp"`
	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"`
	RecoveryCode      bool             `json:"recovery_code"` // a recovery code is stored
	// SecondFactorHeld is account.Methods.SecondFactorHeld: adding or
	// removing a passkey needs a current second factor.
	SecondFactorHeld bool `json:"second_factor_held"`
	PasswordStepUp   bool `json:"password_step_up"` // step-up may offer the password
}

MethodsView is what a user can sign in with.

type NameRequest

type NameRequest struct {
	Name string `json:"name"`
}

NameRequest renames a passkey, a session or an API key.

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
	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, step-up and invite starts' answer.

type OwnerRequest

type OwnerRequest struct {
	Owner bool `json:"owner"`
}

OwnerRequest is authAdminOwner's body.

type PasskeyBeginQuery

type PasskeyBeginQuery struct {
	Mediation string `json:"mediation,omitempty"` // "conditional" or absent
}

PasskeyBeginQuery is authLoginPasskeyBegin's query.

type PasskeyRegisteredResponse

type PasskeyRegisteredResponse struct {
	RecoveryCode string      `json:"recovery_code,omitempty"`
	Passkey      PasskeyView `json:"passkey"`
}

PasskeyRegisteredResponse is authPasskeyRegisterFinish's answer: the new passkey, and the recovery code its registration issued, shown once; absent when it issued none.

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"`
	// Removable is whether authPasskeyRemove would remove it; false where
	// the last-method or the second-factor guard would refuse.
	Removable bool `json:"removable"`
}

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 PasswordLengthView

type PasswordLengthView struct {
	Min int `json:"min"`
	Max int `json:"max"`
}

PasswordLengthView is a password's least and greatest length in Unicode code points after NFC.

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 Pending

type Pending struct {
	Ticket    string          `json:"ticket"`
	Next      account.Next    `json:"next"`
	Methods   []PendingMethod `json:"methods"`             // what Next accepts on this transport
	Recovered bool            `json:"recovered,omitempty"` // the enrolment's finish completes a recovery
}

Pending is account.Pending: the client continues with the newest ticket, which this body alone carries.

type PendingCreateRequest

type PendingCreateRequest struct {
	Username string `json:"username"`
}

PendingCreateRequest is authOIDCCreatePending's body.

type PendingLinkByAdminRequest

type PendingLinkByAdminRequest struct {
	Username          string `json:"username"`
	TemporaryPassword string `json:"temporary_password"`
}

PendingLinkByAdminRequest is authOIDCLinkByAdmin's body: the account's name and the temporary password an admin issued it.

type PendingLinkResponse

type PendingLinkResponse struct {
	Issuer       string `json:"issuer"`
	UsernameHint string `json:"username_hint,omitempty"`
	Email        string `json:"email,omitempty"`
	// SuggestedUsername is set only with CanCreate, and may be absent then.
	SuggestedUsername string `json:"suggested_username,omitempty"`
	CanCreate         bool   `json:"can_create"`
}

PendingLinkResponse is the identity a pending link would attach.

type PendingMethod

type PendingMethod string

PendingMethod is an access.Method a pending sign-in's step accepts; no other method, app-defined ones included, is ever one.

const (
	PendingTOTP         PendingMethod = "totp"
	PendingPasskey      PendingMethod = "passkey"
	PendingRecoveryCode PendingMethod = "recovery_code"
	PendingPassword     PendingMethod = "password"
)

The pending methods, each the access.Method of its name.

type PendingTOTPBeginResponse

type PendingTOTPBeginResponse struct {
	URI  string `json:"uri"`
	Text string `json:"text"`
}

PendingTOTPBeginResponse is a TOTP enrolment begun inside a pending sign-in, shown once: the otpauth URI and the secret as text. The ticket keeps the secret for authPendingTOTPFinish.

type PlainSessionView

type PlainSessionView struct {
	IdleSeconds     int64 `json:"idle_seconds"`
	AbsoluteSeconds int64 `json:"absolute_seconds"`
}

PlainSessionView is account.State.PlainSession in whole seconds.

type ProfileRequest

type ProfileRequest struct {
	DisplayName string `json:"display_name"`
}

ProfileRequest is authProfile's body.

type Readiness

type Readiness struct {
	// Refusal is the state refusal authAdminSSOApply would answer, as its
	// error body would carry it; absent when the change would be made.
	Refusal                     *ReadinessRefusal `json:"refusal,omitempty"`
	LockedOut                   int               `json:"locked_out"`
	MethodsMadeDormant          int               `json:"methods_made_dormant"`
	MethodsRestored             int               `json:"methods_restored"`
	TemporaryPasswordsWithdrawn int               `json:"temporary_passwords_withdrawn"`
}

Readiness is account.Readiness: what a change of the SSO mode would do.

type ReadinessRefusal

type ReadinessRefusal struct {
	Code   access.Code `json:"code"`
	Reason string      `json:"reason,omitempty"`
}

ReadinessRefusal is a state refusal's code and reason.

type RecoveryCodeIssuedResponse

type RecoveryCodeIssuedResponse struct {
	RecoveryCode string `json:"recovery_code,omitempty"`
}

RecoveryCodeIssuedResponse is the answer of an Account change that may issue a recovery code, authTOTPFinish and authPasswordSet: the code, shown once; absent when it issued none.

type RecoveryCodeResponse

type RecoveryCodeResponse struct {
	RecoveryCode string `json:"recovery_code"`
}

RecoveryCodeResponse is authRecoveryCodeRegenerate's answer: the new recovery code, shown once.

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 RegisterPasskeyBeginRequest

type RegisterPasskeyBeginRequest struct {
	Username string `json:"username"`
}

RegisterPasskeyBeginRequest is authRegisterPasskeyBegin's body.

type RegisterPasswordRequest

type RegisterPasswordRequest struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

RegisterPasswordRequest is authRegisterPassword's body.

type RegistrationOutcome

type RegistrationOutcome struct {
	SignedIn        *SignedInResponse `json:"signed_in,omitempty"`
	Pending         *Pending          `json:"pending,omitempty"`
	WaitingApproval bool              `json:"waiting_approval,omitempty" arm:"waiting_approval"`
}

RegistrationOutcome is a password registration's answer, in which exactly one arm is set: signed_in, pending under Rules.RequireSecondFactor, or waiting_approval, true, for an account that waits for approval with no session. A recovery code needs a second factor, which this answer never binds, so its waiting arm carries none.

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 SSOReadinessQuery

type SSOReadinessQuery struct {
	Mode account.SSOModeName `json:"mode"`
}

SSOReadinessQuery is authAdminSSOReadiness's query.

type SSORequest

type SSORequest struct {
	Mode account.SSOModeName `json:"mode"`
}

SSORequest is authAdminSSOApply's body.

type SecondFactorProof

type SecondFactorProof struct {
	Code      string          `json:"code,omitempty" arm:"code"`
	Ceremony  string          `json:"ceremony,omitempty" arm:"passkey"`
	Assertion json.RawMessage `json:"assertion,omitempty" arm:"passkey"`
}

SecondFactorProof is a current second factor sent with a change that needs one, in which exactly one arm is set: a code, or a ceremony from authStepUpPasskeyBegin with its assertion. An absent body, or {}, is no proof.

type SecurityLogView

type SecurityLogView struct {
	Entries []LogEntryView `json:"entries"` // never null: an empty page is []
	Classes []LogClassView `json:"classes"` // one per account.LogClasses() value, in order
}

SecurityLogView is one authAdminSecurityLog page.

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"`
	Secure           bool          `json:"secure"`
}

SessionView is one session.

type SetPasswordRequest

type SetPasswordRequest struct {
	Ticket   string `json:"ticket"`
	Password string `json:"password"`
}

SetPasswordRequest is authLoginSetPassword's body: a set_credential ticket and the password its holder chose.

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 SignInOutcome

type SignInOutcome struct {
	SignedIn *SignedInResponse `json:"signed_in,omitempty"`
	Pending  *Pending          `json:"pending,omitempty"`
}

SignInOutcome is a sign-in step's answer, in which exactly one arm is set.

type SignedInResponse

type SignedInResponse struct {
	SessionID string `json:"session_id"`
	// RecoveryCode is the recovery code this sign-in's binding issued,
	// shown once; absent when it issued none.
	RecoveryCode string   `json:"recovery_code,omitempty"`
	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 {
	PlainSession *PlainSessionView   `json:"plain_session,omitempty"`
	HTTPSOrigin  string              `json:"https_origin,omitempty"`
	SSO          account.SSOModeName `json:"sso"` // the stored SSO mode
	// Registration is account.State's: "off" in a single-user app and
	// under the stored mode SSOOnly.
	Registration  account.RegistrationModeName `json:"registration"`
	HTTPSRequired []account.HTTPSFeature       `json:"https_required"`
	// PasswordLength is the bounds [access.ValidatePasswordLength] enforces.
	PasswordLength PasswordLengthView `json:"password_length"`
	SetupRequired  bool               `json:"setup_required"`
	PasswordLogin  bool               `json:"password_login"`
	Passkeys       bool               `json:"passkeys"`
	OIDC           bool               `json:"oidc"`
	Secure         bool               `json:"secure"`
	TOTP           bool               `json:"totp"` // the app offers TOTP
	// TemporaryPasswordHTTPSOnly is account.State's; absent when false, as
	// on every secure request.
	TemporaryPasswordHTTPSOnly bool `json:"temporary_password_https_only,omitempty"`
}

StateResponse is authState's answer: account.State on the wire, and the password length bounds.

type StepUpCodeRequest

type StepUpCodeRequest struct {
	Code string `json:"code"`
}

StepUpCodeRequest is authStepUpCode's body.

type TOTPBeginResponse

type TOTPBeginResponse struct {
	URI    string `json:"uri"`
	Text   string `json:"text"`
	Ticket string `json:"ticket"`
}

TOTPBeginResponse is a begun TOTP enrolment, shown once: the otpauth URI for a QR code, the secret as text, and the ticket authTOTPFinish takes.

type TOTPFinishRequest

type TOTPFinishRequest struct {
	Ticket      string `json:"ticket"`
	Code        string `json:"code"`
	CurrentCode string `json:"current_code,omitempty"`
}

TOTPFinishRequest is authTOTPFinish's body. CurrentCode is the replaced authenticator's code, required when the user holds one.

type TOTPView

type TOTPView struct {
	Since     time.Time `json:"since,omitzero"` // set while enrolled
	Enrolled  bool      `json:"enrolled"`
	Usable    bool      `json:"usable"`    // enrolled, and the app has authenticator apps on
	Removable bool      `json:"removable"` // authTOTPRemove would remove it
}

TOTPView is account.TOTPState: the user's authenticator app.

type TemporaryPasswordOptions

type TemporaryPasswordOptions struct {
	TTLHours       int  `json:"ttl_hours,omitempty"` // 0 is 24 hours; at most 168
	RevokePasskeys bool `json:"revoke_passkeys,omitempty"`
	KeepKeys       bool `json:"keep_keys,omitempty"`
}

TemporaryPasswordOptions is authAdminTemporaryPassword's and authAdminOIDCRelink's body, account.TemporaryPasswordOptions on the wire.

type TemporaryPasswordResponse

type TemporaryPasswordResponse struct {
	ExpiresAt   time.Time `json:"expires_at"`
	Password    string    `json:"password"` // XXXX-XXXX-XXXX-XXXX, shown once
	HTTPSOrigin string    `json:"https_origin,omitempty"`
	// HTTPSOnly is account.Service.TemporaryPasswordHTTPSOnly, read after
	// the issue committed.
	HTTPSOnly    bool `json:"https_only"`
	Dormant      bool `json:"dormant"`
	PasswordKept bool `json:"password_kept"`
}

TemporaryPasswordResponse is account.IssuedTemporaryPassword on the wire.

type TemporaryPasswordView

type TemporaryPasswordView struct {
	ExpiresAt time.Time `json:"expires_at"`
}

TemporaryPasswordView is a listed user's live temporary password.

type TicketRequest

type TicketRequest struct {
	Ticket string `json:"ticket"`
}

TicketRequest is the body of a pending sign-in's begin route.

type TokenRequest

type TokenRequest struct {
	Token string `json:"token"`
}

TokenRequest is authInviteAcceptOIDC'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 token.

type TokenView

type TokenView struct {
	CreatedAt time.Time           `json:"created_at"`
	ExpiresAt time.Time           `json:"expires_at"`
	Purpose   access.TokenPurpose `json:"purpose"`        // "invite"
	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"`
	IssuedByKey   int64   `json:"issued_by_key,omitempty"`
}

TokenView is one live invite token on authAdminTokens. It carries neither the token nor its hash.

type UserMethodsView

type UserMethodsView struct {
	// TemporaryPassword is the user's live temporary password; absent when
	// they hold none.
	TemporaryPassword   *TemporaryPasswordView `json:"temporary_password,omitempty"`
	PasskeyCount        int                    `json:"passkey_count"`
	Password            bool                   `json:"password"`
	LocalMethodsDormant bool                   `json:"local_methods_dormant"`
	RoleFromProvider    bool                   `json:"role_from_provider"`
	TOTP                bool                   `json:"totp"` // the user holds a TOTP record
	// WaitingApproval marks a registration no admin has approved; enabling
	// the user approves it.
	WaitingApproval bool `json:"waiting_approval"`
}

UserMethodsView is a listed user's sign-in methods and the facts about them the admin list reads with the page.

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"`
	Owner      bool    `json:"owner"`
}

UserView is one user.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL