auth

type Account struct {
	// ID is the stable opaque application identifier. It must not be an email
	// address.
	ID          string
	DisplayName string
	Email       string
	// Suspended blocks session creation for an account that exists but may not
	// log in.
	Suspended bool
}

type AccountActivator func(ctx context.Context, accountID string) error

type AccountLookup func(ctx context.Context, accountID string) (Account, error)

type AccountResolver func(ctx context.Context, identity Identity, provision bool) (Account, error)

type AllowlistCandidate struct {
	Claim string
	Value string
}

type AllowlistStore interface {
	Registered(ctx context.Context, issuer string, candidates []AllowlistCandidate) (bool, error)
}

type AssuranceConfig struct {
	// Policy is an array of tables rather than a map, because configbind binds
	// statically and a map key is not a declared field:
	//
	//	[[auth.assurance.policy]]
	//	name = "admin"
	//	max_age = "15m"
	Policy   []AssurancePolicy `help:"named freshness windows a handler can require by name"`
	Hint     HintConfig        `help:"what the login screen may remember about the last user of a browser"`
	Presence PresenceConfig    `help:"end a session when nobody is at the keyboard, rather than when no request arrives"`
}

type AssurancePolicy struct {
	Name   string        `help:"name a handler passes to auth.Policy"`
	MaxAge time.Duration `help:"how old a proof may be; zero means prove again for this operation"`
	// Confirm refuses to count the login that started the session, so only a
	// re-proof this guard asked for satisfies the policy.
	//
	// Signing in and confirming an operation are different acts. Without this,
	// a window wide enough to be usable lets a sign-in stand in for the
	// confirmation: someone who signed in a minute ago to read their dashboard
	// would reach a transfer without ever being asked about it.
	Confirm bool `default:"false" help:"require a re-proof this guard asked for; a login never counts"`
}

type Backend struct {
	// OpenState opens the ceremony store of one namespace.
	OpenState func(ctx context.Context, namespace string) (authstate.RawStore, error)
	// Allowlist, Credentials, and Bootstrap are the account-side stores. Each
	// may be nil when the selected mode never reads it.
	Allowlist   AllowlistStore
	Credentials CredentialStore
	Bootstrap   BootstrapStore
}

type BackendFactory func(ctx context.Context, config Config, resources Resources) (Backend, error)

type BearerIdentity struct {
	// AccountID is the local account the identity resolved to.
	AccountID string
	// Account is the resolver's summary of that account.
	Account Account
	// Identity is the verified external identity, including its claims.
	Identity Identity
	// IssuedAt and ExpiresAt are the verified iat and exp.
	IssuedAt  time.Time
	ExpiresAt time.Time
}

type BootstrapConfig struct {
	// IssueTTL is how long an issued secret stays redeemable, measured from
	// issuance. It spans delivery, so it is the longer of the two.
	IssueTTL time.Duration `default:"24h" secret:"show" help:"how long an issued secret stays redeemable"`
	// EnrollmentTTL is how long the enrollment stays open, measured from a
	// successful redemption. It spans one ceremony, so it is short.
	//
	// It is not a session lifetime: what a redemption grants is a ticket that
	// authorizes exactly one registration, and the request stays unauthenticated
	// until that registration finishes.
	EnrollmentTTL time.Duration `default:"10m" secret:"show" help:"how long an enrollment stays open after a redemption"`
	// MaxAttempts bounds how many redemptions may be tried before the
	// credential is spent, whether or not any of them was close.
	MaxAttempts int `default:"5" secret:"show" help:"redemption attempts before the credential is spent"`
}

type BootstrapCredential struct {
	LoginID           string
	AccountID         string
	SecretDigest      []byte
	Purpose           string
	IssuedAt          time.Time
	ExpiresAt         time.Time
	AttemptsRemaining int
	ConsumedAt        time.Time
}

type BootstrapStore interface {
	Issue(ctx context.Context, credential BootstrapCredential) error
	// Find returns an unconsumed credential, or ErrUnknownBootstrap. It reports
	// nothing about why a lookup failed, so a caller cannot enumerate accounts.
	Find(ctx context.Context, loginID string) (BootstrapCredential, error)
	// RecordAttempt decrements the remaining attempts atomically and returns
	// what is left, so a parallel guess cannot spend the same budget twice.
	RecordAttempt(ctx context.Context, loginID string) (int, error)
	// Consume marks the credential spent. It participates in the transaction
	// CredentialStore.Save opened when the context carries one.
	Consume(ctx context.Context, loginID string, at time.Time) error
}

type ClaimConfig struct {
	// Path is a JSON Pointer into the verified ID Token claims.
	Path   string `help:"JSON Pointer into verified claims"`
	Values []string
	Match  string `default:"any" help:"any or all"`
}

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

type Config struct {
	Enabled bool `default:"false"`
	// Backend names the storage of the four stores this package owns: the
	// ceremony records, the admission allowlist, the passkey credentials, and
	// the issued bootstrap credentials. They move together, because they are
	// one deployment's authentication state and splitting them across two
	// engines gains nothing.
	Backend string `default:"rdb" enum:"rdb,dynamo" dependon:".enabled" help:"storage backend of the authentication tables: rdb or dynamo"`
	// Mode selects which login methods this deployment offers, and with them
	// which of the OIDC, Passkey, and JWT sections below are in force. The enum
	// is what makes those sections' conditions checkable: a mistyped mode there
	// would hide a whole subtree from the startup summary silently and forever,
	// and generation rejects a value that is not listed here.
	Mode string `` /* 172-byte string literal not displayed */
	// LoginPath starts the provider flow.
	LoginPath    string `default:"/auth/login" dependon:".enabled" help:"path that starts the provider flow"`
	CallbackPath string `default:"/auth/callback" dependon:".enabled"`
	LogoutPath   string `default:"/auth/logout" dependon:".enabled"`
	// PostLoginPath is the local path a completed login lands on.
	PostLoginPath string `default:"/" dependon:".enabled" help:"path a completed login lands on"`
	// RecentAuthMaxAge bounds how long a completed authentication still counts
	// as recent enough to add or remove a login method.
	RecentAuthMaxAge time.Duration `` /* 126-byte string literal not displayed */
	// SharedDevice declares that the browsers reaching this deployment are
	// shared, which couples the settings that would otherwise leave one user
	// visible to the next. It fixes the logout scope to global and withholds
	// the select_account prompt, because that prompt exists to surface exactly
	// what this mode hides.
	//
	// Any one of those alone achieves nothing: with the local hint disabled
	// but the provider session alive, the next visitor still sees the previous
	// account in the provider's own account picker.
	//
	// It reduces disclosure and does not eliminate it. The common end of a
	// session on a shared device is abandonment rather than logout, and no
	// relying party can end a provider session it was not asked to end.
	SharedDevice bool               `` /* 131-byte string literal not displayed */
	Assurance    AssuranceConfig    `dependon:".enabled"`
	Protection   ProtectionConfig   `dependon:".enabled"`
	Registration RegistrationConfig `dependon:".enabled"`
	Recovery     RecoveryConfig     `dependon:".enabled"`
	Bootstrap    BootstrapConfig    `dependon:".enabled" summary:"omit"`
	// The three login-method sections name the modes they belong to, so a
	// summary reports the methods this deployment offers rather than all of
	// them. The lists restate usesOIDC, usesPasskey, and usesJWT below; those
	// predicates decide what is built, and these decide what is reported, so
	// the two have to agree. The enabled switch is not repeated: Mode answers
	// to it, and a condition on Mode inherits that gate transitively.
	OIDC OIDCConfig `` /* 462-byte string literal not displayed */
	// The key tag is load-bearing. Generation derives a TOML key from the field
	// name and splits it at every lower-to-upper boundary, which turns OAuth
	// into o_auth — OIDC survives only because it is all caps. The setting a
	// deployment writes is [auth.oauth].
	OAuth   OAuthConfig   `` /* 298-byte string literal not displayed */
	Passkey PasskeyConfig `dependon:".mode=oidc_passkey,passkey_only"`
	JWT     JWTConfig     `dependon:".mode=jwt_only"`
}

type Credential struct {
	CredentialID []byte
	AccountID    string
	UserHandle   []byte
	// PublicKey is the normalized COSE key. PublicKeyX and PublicKeyY are the
	// same key as curve points: the relying party verifies with the points and
	// cross-checks them against the COSE blob, so a corrupted row fails closed
	// instead of verifying against something else.
	PublicKey      []byte
	PublicKeyX     []byte
	PublicKeyY     []byte
	Algorithm      int
	SignCount      uint32
	BackupEligible bool
	BackupState    bool
	Transports     []string
	Label          string
	CreatedAt      time.Time
	LastUsedAt     time.Time
}

type CredentialStore interface {
	// Find returns the credential of an ID, or ErrUnknownCredential.
	Find(ctx context.Context, credentialID []byte) (Credential, error)
	// ListByAccount supplies excludeCredentials and allowCredentials.
	ListByAccount(ctx context.Context, accountID string) ([]Credential, error)
	// Save persists a new credential and runs within in the same transaction,
	// so a first enrollment can also activate the account and consume the
	// bootstrap credential as one unit. within may be nil.
	Save(ctx context.Context, credential Credential, within func(ctx context.Context) error) error
	// UpdateOnAssertion persists the accepted counter and backup state of a
	// completed assertion.
	//
	// An implementation moves the stored counter forward or changes nothing,
	// in one conditional statement rather than a read and a write, and
	// tolerates an incoming count of zero from an authenticator that keeps
	// none. It reports ErrUnknownCredential when nothing was updated, which
	// covers both a missing credential and a counter that did not advance.
	UpdateOnAssertion(ctx context.Context, credentialID []byte, signCount uint32, backupState bool, usedAt time.Time) error
	// Delete removes one credential of an account.
	Delete(ctx context.Context, accountID string, credentialID []byte) error
}

type Exchange interface {
	// Cookies, SetCookie, and Context are the session's three, and a login is a
	// session, so the endpoints reach the manager through this value directly.
	session.Carrier

	// Method is the request method.
	Method() string
	// Path is the request path with percent-encoding decoded.
	Path() string
	// RawPath is the path as it arrived, before decoding. It is read only to
	// refuse an encoded separator, which is invisible in the decoded form.
	RawPath() string
	// Target is the path and query as sent, which is what a return path records
	// so a completed login lands back on the whole request.
	Target() string
	// Query returns one query parameter, or the empty string.
	Query(name string) string
	// FormValue returns one submitted form field, or the empty string.
	FormValue(name string) string
	// Header returns one request header, or the empty string.
	Header(name string) string
	// HeaderValues returns every value of one request header.
	//
	// It exists for Authorization alone, and only because a second one is
	// refused rather than merged: which of two a proxy forwards is not this
	// application's decision to guess, and a reader that saw only the first
	// could not tell there had been two.
	HeaderValues(name string) []string
	// Body reads the request body, refusing one longer than limit. The refusal
	// is an error rather than a truncation, so an oversized document is
	// answered as one rather than as malformed JSON.
	Body(limit int64) ([]byte, error)

	// IsTLS reports whether this hop arrived over TLS, which is the fact
	// internal/requestorigin outranks every forwarded header with.
	IsTLS() bool
	// RemoteAddress is the peer, which decides whether a forwarded header is
	// evidence of anything.
	RemoteAddress() string
	// Host is the authority the request named, which the origin is built from.
	Host() string

	// SetHeader sets one response header.
	SetHeader(name, value string)
	// Write commits a status and a body.
	Write(status int, body []byte)
	// Problem answers with the framework's problem document, rendered through
	// whatever error page this deployment registered.
	Problem(err error)
	// Redirect sends the browser elsewhere, through the framework's own helper
	// rather than the transport's: an update request is a fetch, so a 303 would
	// be followed and its target applied as a region set for the wrong page.
	Redirect(location string, status int)

	// RecordAuthentication publishes the verified authentication result, so
	// everything after this frame reads it from the request.
	RecordAuthentication(pwruntime.Authentication)
	// AttachSession publishes a session the endpoints resolved themselves,
	// which is what a caller with no session middleware above it needs.
	AttachSession(session.Resolved)
}

type FirstEnrollmentStore interface {
	// SaveFirstCredential applies the enrollment. spend consumes the bootstrap
	// credential that authorized it and activate promotes the provisional
	// account; either may be nil.
	SaveFirstCredential(ctx context.Context, credential Credential, spend, activate func(context.Context) error) error
}

type HintConfig struct {
	Enabled bool   `default:"false" help:"remember who last signed in, to shorten the next sign-in"`
	Name    string `default:"pw_hint" dependon:".enabled" help:"cookie name"`
	// Secret seals the cookie. The contents never reach the client, so the
	// hint may hold a login identifier; what must not leak is what the login
	// screen renders, which is masked instead.
	Secret string `secret:"mask" env:"AUTH_HINT_SECRET" dependon:".enabled" help:"base64 secret of at least 256 bits that seals the hint"`
	// PreviousSecrets keep a rotation readable.
	PreviousSecrets []string `secret:"mask" dependon:".enabled" help:"retired secrets kept readable during a rotation"`
	// TTL is the absolute bound and IdleTimeout the one measured from the last
	// successful login. The pair is the session's own shape, for the same
	// reasons, and is deliberately not inherited from it: a hint outlives a
	// session by design.
	//
	// Setting TTL to zero is a valid answer. It means this browser may
	// remember nothing, which is what a shared terminal wants and what
	// SharedDevice sets for a whole deployment.
	TTL         time.Duration `default:"720h" dependon:".enabled" help:"how long a hint may live at all"`
	IdleTimeout time.Duration `default:"336h" dependon:".enabled" help:"how long since the last successful login a hint survives"`
}

type Identity struct {
	Issuer  string
	Subject string
	// KeyClaim names the claim a deployment identifies accounts by, and Key is
	// its verified value. They default to the "sub" claim and the subject.
	//
	// A directory that issues its own stable identifier, such as an employee
	// number, usually knows that value before anyone logs in, which the
	// subject never is. auth.oidc.identity_claim selects it.
	KeyClaim string
	Key      string
	Claims   Claims
	// TokenID is the verified jti of a bearer access token, and empty for a
	// browser login. It names one token, which is what the token form of
	// policy:token-revocation withdraws.
	TokenID string
	// IssuedAt and ExpiresAt are the verified iat and exp of a bearer access
	// token, and zero for a browser login.
	//
	// IssuedAt is what a subject-form revocation compares against: a token
	// minted after the identity was revoked is admitted, so revoking an
	// identity ends its outstanding tokens without ending the identity.
	IssuedAt  time.Time
	ExpiresAt time.Time
}

type JWTConfig struct {
	// Issuer is the exact iss claim this deployment accepts. Key discovery
	// starts here, so it is also where the trust in a signing key comes from.
	Issuer string `env:"AUTH_JWT_ISSUER" help:"exact iss claim value this deployment accepts"`
	// Audience is what this API is called by the authorization server. It has
	// no default: a token verified without an audience check was minted for
	// some other service and would be accepted here anyway.
	Audience []string `help:"aud value naming this API; required"`
	// AudienceMatch decides how a multi-valued aud is compared. any is
	// ordinary, because an access token names every resource it may reach.
	AudienceMatch string `default:"any" enum:"any,all" key:"audience_match" help:"any or all"`
	// Algorithms is the exact verification allowlist. It never comes from the
	// token header. An HMAC algorithm is refused outright: the verification key
	// arrives from a public JWKS, so accepting one would let a published key be
	// used as a shared secret.
	//
	// It is required rather than defaulted. Which signatures this deployment
	// trusts is not a question to inherit an answer to, and the answer is one
	// line: algorithms = ["RS256"].
	Algorithms []string `help:"exact verification algorithm allowlist; required, e.g. [\"RS256\"]"`
	// RequiredTokenType is the typ header this deployment demands. RFC 9068
	// names at+jwt, and demanding it is what keeps an ID Token from being
	// replayed here as an access token.
	//
	// Setting it empty accepts an absent typ, for an issuer predating RFC 9068.
	// That is an explicit act with a cost: the audience becomes the only thing
	// separating the two token kinds, so it must be one the issuer does not put
	// in its ID Tokens.
	RequiredTokenType string `default:"at+jwt" key:"required_token_type" help:"typ header to demand; empty accepts an absent typ"`
	// RequiredScopes are the scope values every request must carry. It is its
	// own field rather than a claim rule because scope is a space-delimited
	// string and a generic claim comparison would match the whole value.
	RequiredScopes []string `key:"required_scopes" help:"scope values every request must carry"`
	// Discovery selects where the signing keys are found.
	Discovery string `default:"oidc" enum:"oidc,oauth,manual" help:"oidc, oauth, or manual"`
	// JWKSURI is read only under DiscoveryManual.
	JWKSURI string `key:"jwks_uri" help:"signing key set, for manual discovery"`
	// Leeway absorbs clock skew between this host and the issuer.
	Leeway time.Duration `default:"30s" help:"clock skew allowance"`
	// MaxTokenLifetime bounds exp minus iat. It is required, because it is also
	// how long a subject-form revocation entry must be kept: this application
	// cannot know how long the issuer mints for, so the deployment says.
	MaxTokenLifetime time.Duration `key:"max_token_lifetime" help:"longest exp-minus-iat accepted; required"`
	// MaxTokenBytes bounds the compact token before it is decoded.
	MaxTokenBytes int `default:"8192" key:"max_token_bytes" help:"largest compact token accepted"`
	// JWKSRefreshCooldown bounds how often an unknown kid may cause a refresh,
	// so a stream of forged kid values cannot be amplified into traffic against
	// the issuer.
	JWKSRefreshCooldown time.Duration `default:"1m" key:"jwks_refresh_cooldown" help:"shortest interval between unknown-kid refreshes"`
	// AllowLoopbackHTTP permits an http issuer on loopback and relaxes the
	// same-origin rule on the discovered key set. Development only.
	AllowLoopbackHTTP bool `default:"false" key:"allow_loopback_http" help:"permit an http loopback issuer during development"`
	// IdentityClaim names the verified claim that identifies a local account.
	IdentityClaim string `default:"sub" key:"identity_claim" help:"verified claim that identifies a local account"`
	// Admission decides whether a verified identity may enter this application.
	// Verification proves who the caller is; this decides whether they belong.
	Admission string `help:"authenticated, claim, registered, or existing; required"`
	// AutoProvision permits an unknown verified identity to create an account.
	// It defaults false here and true under OIDC, because a browser login is a
	// person arriving and a bearer request is a machine already running.
	AutoProvision bool `default:"false" key:"auto_provision" help:"permit an unknown verified identity to create an account"`
	// Claim is the admission rule applied when Admission is claim.
	Claim ClaimConfig `help:"admission rule applied when admission is claim"`
	// RegisteredClaims names the claims compared against the allowlist table
	// under AdmissionRegistered.
	RegisteredClaims []string `key:"registered_claims" help:"claims compared against the allowlist; defaults to identity_claim"`
	Revocation       JWTRevocationConfig
	Dev              JWTDevConfig
}

type JWTDevConfig struct {
	TrustUnverifiedTokens bool `default:"false" key:"trust_unverified_tokens" help:"development only: admit a token without verifying it"`
}

type JWTRevocationConfig struct {
	// Mode is off, token, subject, or both, and carries no default. Selecting a
	// form is what turns its requirements on: the token form makes jti
	// mandatory, rather than a second switch that can disagree with it.
	Mode string `help:"off, token, subject, or both; required in jwt_only"`
	// OnUnavailable is refuse or admit. It defaults to refuse, because a store
	// that cannot answer has not said the token is valid.
	OnUnavailable string `default:"refuse" enum:"refuse,admit" key:"on_unavailable" help:"refuse or admit when the store cannot answer"`
	// MaxPropagationDelay bounds a per-process cache of revocation answers. It
	// defaults to zero, which is no cache: a revocation that takes effect at
	// the next request is the answer nobody has to reason about.
	MaxPropagationDelay time.Duration `key:"max_propagation_delay" help:"how stale a cached revocation answer may be; zero disables the cache"`
}

type OAuthConfig struct {
	// Provider names the built-in definition. It has no default: a provider is
	// the one thing this mode cannot infer, and defaulting to whichever one
	// happened to be written first would make the choice for a deployment that
	// never made it.
	Provider     string `enum:"x" help:"OAuth login provider; x is X, formerly Twitter"`
	ClientID     string `env:"AUTH_OAUTH_CLIENT_ID"`
	ClientSecret string `secret:"mask" env:"AUTH_OAUTH_CLIENT_SECRET"`
	// RedirectURL is the absolute callback URL registered with the provider.
	RedirectURL string `help:"RedirectURL is the absolute callback URL registered with the provider"`
	// Scopes replaces the provider's own defaults rather than adding to them,
	// so a deployment that states this list owns it. Empty asks for exactly
	// what the provider needs to report an account and nothing more, which is
	// what a login should ask for.
	Scopes []string `help:"scopes to request; empty asks for the provider's minimum login set"`
	// IdentityClaim names the claim of the fetched profile that identifies a
	// local account, and defaults to "sub", which every provider definition
	// fills with that provider's own stable identifier.
	//
	// A handle is the tempting alternative and the wrong one. X lets a handle
	// be renamed, and lets a released one be claimed by somebody else, so an
	// account linked to a handle eventually becomes somebody else's account.
	// Only a name the provider definition actually emits is accepted, so a
	// claim copied out of the provider's own API reference is refused at
	// startup rather than at every login.
	IdentityClaim string `default:"sub" help:"profile claim that identifies a local account; sub is the provider's own identifier"`
	Admission     string `default:"authenticated" help:"authenticated, claim, registered, or existing"`
	// AutoProvision permits an unknown profile to create an account through the
	// registered account resolver.
	AutoProvision bool `default:"true" help:"permit an unknown profile to create an account through the registered account resolver"`
	// Claim is the admission rule applied when Admission is claim.
	Claim ClaimConfig `help:"admission rule applied when admission is claim"`
	// RegisteredClaims names the profile claims compared against the allowlist
	// table under AdmissionRegistered, and defaults to IdentityClaim alone.
	RegisteredClaims []string `help:"claims compared against the allowlist; defaults to identity_claim"`
	// AllowLoopbackHTTP permits a request-relative redirect URL on loopback, so
	// a developer can run the login against the real provider from localhost
	// without registering a URL per machine. The provider endpoints themselves
	// stay https whatever this says.
	AllowLoopbackHTTP bool `default:"false" help:"permit an http loopback redirect URL during development"`
}

type OIDCConfig struct {
	Issuer       string `env:"AUTH_OIDC_ISSUER"`
	ClientID     string `env:"AUTH_OIDC_CLIENT_ID"`
	ClientSecret string `secret:"mask" env:"AUTH_OIDC_CLIENT_SECRET"`
	RedirectURL  string
	Scopes       []string
	// EndpointHosts restricts which hosts the issuer's discovery document may
	// point its endpoints at. Empty accepts whatever the document names.
	//
	// The document decides where this deployment sends the authorization code
	// and its client secret, and the only value checked against configuration is
	// the issuer field the document reports about itself. Naming the hosts turns
	// that into something the deployment asserts.
	//
	// It is empty by default because federated endpoints are ordinary rather than
	// suspicious — Google's issuer is accounts.google.com while its token
	// endpoint is oauth2.googleapis.com — so a same-origin rule would refuse a
	// working provider. The issuer's own host never needs listing, and a host is
	// matched exactly, without wildcards.
	EndpointHosts []string `help:"hosts the discovery document may point endpoints at; empty accepts any"`
	// IdentityClaim names the verified claim that identifies a local account.
	// It defaults to "sub".
	//
	// A deployment that provisions users in advance usually cannot know a
	// subject yet, and instead adds its own stable identifier to the
	// directory, such as an employee number. That claim must be stable for the
	// life of the account and unique within the issuer: it becomes the account
	// link, so a reissued or reused value hands one person another person's
	// account.
	IdentityClaim string `default:"sub" help:"verified claim that identifies a local account"`
	Admission     string `default:"authenticated" help:"authenticated, claim, registered, or existing"`
	// AutoProvision permits an unknown verified identity to create an account
	// through the registered account resolver.
	AutoProvision bool `` /* 133-byte string literal not displayed */
	// Claim is the admission rule applied when Admission is claim.
	Claim ClaimConfig `help:"admission rule applied when admission is claim"`
	// RegisteredClaims names the verified claims compared against the
	// allowlist table under AdmissionRegistered. It defaults to IdentityClaim
	// alone, because that is the value a deployment registers in advance.
	RegisteredClaims []string `help:"claims compared against the allowlist; defaults to identity_claim"`
	// LogoutScope decides what a logout does to the session the provider
	// holds, which is not the session this application owns.
	//
	// reconfirm revokes the local session, sends the provider nothing, and
	// marks the next authorization to carry prompt, so the provider still
	// demands proof while every other relying party sharing it is untouched.
	//
	// global additionally ends the provider session through the discovered end
	// session endpoint, which signs the user out of every application sharing
	// that provider. It is what a shared device wants and what a personal one
	// rarely does.
	//
	// There is no local-only value: revoking only the local session leaves the
	// next login silent, so the sign-out looks like it did nothing. That was
	// the failure reconfirm exists to fix.
	LogoutScope string `default:"reconfirm" enum:"reconfirm,global" help:"what a logout does to the provider session: reconfirm or global"`
	// ProviderLogout is removed and survives only to fail loudly. configbind
	// ignores a key no field declares, so deleting the field outright would
	// leave every scaffolded project silently running reconfirm while its
	// configuration still read as a global sign-out.
	//
	// The default is inverted to false so presence is detectable: an untouched
	// project binds false and starts, and one carrying provider_logout = true
	// is refused with LogoutScope named. A leftover false meant the rejected
	// local scope, whose nearest surviving behavior is the new default.
	//
	// Delete this once no configuration in the wild carries the key.
	ProviderLogout bool `default:"false" help:"removed; use auth.oidc.logout_scope"`
	// AllowGlobalLogoutRequest lets the logout request escalate to global, for
	// a deployment offering both a sign-out and a sign-out-everywhere control.
	// A request may only escalate: a forced downgrade would leave the provider
	// session alive after the user asked to leave it.
	AllowGlobalLogoutRequest bool `default:"false" help:"permit a logout request to escalate to a global sign-out"`
	// AllowLoopbackHTTP permits an http issuer on localhost. It exists for
	// local development against a loopback identity provider and must stay
	// false everywhere else.
	AllowLoopbackHTTP bool `default:"false" help:"permit an http loopback issuer during development"`
}

type PasskeyConfig struct {
	// Path is the base path of the ceremony endpoints. The five endpoints hang
	// off it, so one setting keeps them consistent and keeps them all reachable
	// past the guard.
	Path string `default:"/auth/passkey" help:"base path of the ceremony endpoints"`
	// RPID scopes every credential. It is a domain, never an IP literal,
	// because an IP address cannot be an RP ID.
	RPID    string   `key:"rp_id" help:"relying party domain; localhost during development"`
	RPName  string   `key:"rp_name" help:"relying party display name"`
	Origins []string `help:"origin the browser reaches this deployment on"`
	// UserVerification and Discoverable are the ceremony requirements the
	// relying party asks the authenticator for.
	UserVerification string `default:"required" help:"required, preferred, or discouraged"`
	Discoverable     string `default:"preferred" help:"required or preferred"`
}

type PresenceConfig struct {
	Enabled bool `default:"false" help:"accept presence reports from the browser"`
	// Interval is how often the browser is expected to report. It bounds the
	// endpoint's rate and sets the pace the scaffolded script ticks at.
	Interval time.Duration `default:"1m" dependon:".enabled" help:"how often a browser reports"`
	// AbsentAfter ends the session once no interaction has been reported for
	// this long. It measures a person rather than a request, which is the whole
	// point of the signal.
	AbsentAfter time.Duration `default:"30m" dependon:".enabled" help:"end the session after this long with no interaction"`
}

type ProtectionConfig struct {
	Include []string `help:"protected path pattern"`
	Exclude []string `help:"public path pattern"`
	// Unauthenticated is redirect or unauthorized.
	Unauthenticated string `default:"redirect" help:"redirect or unauthorized"`
}

type RecoveryConfig struct {
	Policy string `help:"oidc, administrator, or application"`
}

type RegistrationConfig struct {
	Policy string `help:"disabled, oidc, invite, administrator, or open"`
}

type Requirement interface {
	// contains filtered or unexported methods
}

type Resources struct {
	// DB is the session-group database handle, or nil when middleware.rdb is
	// not enabled.
	DB *sql.DB
	// DBDriver is the engine the DSN resolved to, empty when DB is nil.
	DBDriver string
}

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

type Rules struct {
	// Protected reports whether a path requires an authenticated caller. A nil
	// value protects nothing.
	Protected func(path string) bool
	// LoginURL is where an unauthenticated browser is sent, carrying a
	// validated local return path. An empty result answers 401 instead.
	LoginURL func(path string) string
	// Redirect sends a browser to LoginURL; without it an unauthenticated
	// request is answered 401 whatever it accepts.
	Redirect bool
	// BearerRealm names the scheme a 401 asks for, per RFC 6750. Empty sends no
	// challenge.
	BearerRealm string
}

type SessionData struct {
	AccountID string `json:"account_id"`
	Issuer    string `json:"iss"`
	Subject   string `json:"sub"`
	// AuthenticatedAt is when the current authentication strength was
	// established. A rotation after a login or a re-proof refreshes it.
	AuthenticatedAt time.Time `json:"authenticated_at"`
	// Method is the unordered label of what proved this session, such as oidc
	// or passkey. Nothing ranks one above another: the framework cannot order
	// the methods it mounts, so an ordering would be a deployment claim.
	Method string `json:"method,omitempty"`
	// KeyClaim and Key record which verified claim identified the account and
	// its value, so a handler can show or audit the link without repeating the
	// configuration.
	KeyClaim    string `json:"key_claim,omitempty"`
	Key         string `json:"key,omitempty"`
	DisplayName string `json:"name,omitempty"`
	Email       string `json:"email,omitempty"`
	// Provider is the OAuth login provider that authenticated this session,
	// such as "x". It is empty for every other login method, which is what
	// makes the three fields below readable without a second flag: they are
	// present exactly when this one is.
	//
	// Subject is that provider's own account identifier — the X user id, for
	// the x provider — and Issuer is the provider's namespace.
	Provider string `json:"provider,omitempty"`
	// Username is the handle the provider reported, such as an X @name without
	// the @. It is stored for display and support, and is not the account link:
	// a handle can be renamed, and on X a released one can be claimed by
	// somebody else, so it identifies nobody durably. It is a copy taken at
	// login and goes stale the moment the user renames themselves.
	Username string `json:"username,omitempty"`
	// AvatarURL is the profile image the provider reported, when it reported
	// one. Like Username it is a copy taken at login.
	AvatarURL string `json:"avatar_url,omitempty"`
	// ProviderAuthTime is the verified auth_time of the identity provider: the
	// moment it last actively authenticated this person, which is not the
	// moment the login landed here. A provider may satisfy an authorization
	// request from a single sign-on session established much earlier, so
	// freshness is measured from this and only falls back to the session's own
	// AuthenticatedAt when the provider reported nothing.
	//
	// It lives here rather than on the session record because it is an OpenID
	// Connect concept: a passkey-only deployment has no provider at all, and
	// the generic session package must not learn what an issuer is.
	ProviderAuthTime int64 `json:"provider_auth_time,omitempty"`
	// StepUpAt records that a zero-window re-proof completed, which is the only
	// thing that can satisfy a per-operation requirement.
	//
	// It lives in the session rather than in a cookie so it cannot be forged. It
	// is spent by the guard that accepts it, under one lock with the read that
	// accepted it, so two operations arriving together cannot share one proof —
	// see zeroWindowAdmission. The short window is the backstop for a proof
	// nobody spent, such as one the user abandoned, rather than the mechanism.
	StepUpAt int64 `json:"step_up_at,omitempty"`
}

type SessionLifetimeConfig = sessionconfig.SessionLifetimeConfig

type SignInHint struct {
	// DisplayName and LoginID are for rendering. Mask what you render: the
	// disclosure risk is what the next person on the device reads, not what
	// the sealed cookie holds.
	DisplayName string `json:"name,omitempty"`
	LoginID     string `json:"login_id,omitempty"`
	// Issuer is the provider of the last successful login, so a login screen
	// offering several can skip its picker.
	Issuer string `json:"iss,omitempty"`
	// LastLoginAt bounds the hint by inactivity, independently of the absolute
	// bound the cookie itself carries.
	LastLoginAt int64 `json:"at,omitempty"`
}

type Step func(x Exchange, next func())