embedded

type APIKey = authkit.APIKey

type APIKeyMintOptions = authkit.APIKeyMintOptions

type APIKeysConfig struct {
	// Prefix is the issuing application's brand prefix for generated API keys
	// (single value per deployment). Empty defaults to the bare `st_` marker.
	// Must be lowercase alphanumeric, 1-16 chars.
	Prefix string
	// MaxTTL caps how far in the future a minted API key may expire. 0 (default)
	// means no cap (keys may be non-expiring); when set, a requested expiry
	// beyond now+MaxTTL (incl. no-expiry) is capped at mint time.
	MaxTTL time.Duration
}

type AccountRecoveryConfirmation struct {
	Token     string    `json:"token"`
	ExpiresAt time.Time `json:"expires_at"`
	PurgeAt   time.Time `json:"purge_at"`
}

type AccountRegistrationInvite = authkit.AccountRegistrationInvite

type AccountRegistrationInviteCreated = authkit.AccountRegistrationInviteCreated

type AdminListUsersResult = authkit.AdminListUsersResult

type AdminUser = authkit.AdminUser

type AdminUserListOptions = authkit.AdminUserListOptions

type AdminUserSort = authkit.AdminUserSort

type AdminUserStatus = authkit.AdminUserStatus

type ApplicationDocument = authkit.ApplicationDocument

type ApplicationsConfig struct {
	// SelfRegistration enables the POST /applications/register surface (and
	// the signed rotate/repoint routes). Off by default.
	SelfRegistration bool
	// AllowPrivateNetworkJWKS permits http and private/loopback addresses for
	// every remote-application fetch — jwks_uri values, application documents
	// and their domain proofs — and turns off the SSRF guard on the verifier's
	// JWKS client. Local federation rigs only; the default (false) refuses
	// anything that is not a public https endpoint.
	AllowPrivateNetworkJWKS bool
	// OrgPersona is the declared RBAC persona under which each self-registered
	// application's SERVICE-OWNED org is created (instance_slug = the
	// application slug; the application principal is seeded as its owner).
	// Required when SelfRegistration is set; must be a declared non-root
	// persona whose Parent is the root persona.
	OrgPersona authkit.Persona
}

type AuthSessionEvent struct {
	OccurredAt time.Time
	Issuer     string
	UserID     string
	SessionID  string
	Event      SessionEventType
	Method     *string
	Reason     *string
	IPAddr     *string
	UserAgent  *string
}

type BootstrapManifest = authkit.BootstrapManifest

type BootstrapManifestRemoteApplication = authkit.BootstrapManifestRemoteApplication

type BootstrapManifestResult = authkit.BootstrapManifestResult

type BootstrapManifestUser = authkit.BootstrapManifestUser

type BootstrapReconcileOptions = authkit.BootstrapReconcileOptions

type BootstrapUserPassword = authkit.BootstrapUserPassword

type Config struct {
	// HTTP configures the optional runtime-owned HTTP surface during New.
	// Pass authhttp.Config. Nil keeps the runtime headless; hosts that must
	// provision first may call ConfigureHTTP before obtaining routes instead.
	HTTP HTTPConfiguration

	// River configures mandatory PostgreSQL cleanup; in-memory TTL stays local.
	River RiverConfig

	// Naming is the shared user/group rename policy, normalized at construction.
	Naming authkit.NamingConfig

	// Token is the JWT issuing/verification contract and session limits.
	Token TokenConfig
	// Frontend describes host-owned frontend routes used for absolute-URL and
	// full-page OIDC callback construction.
	Frontend FrontendConfig
	// Registration controls verification policy and public self-registration.
	Registration RegistrationConfig
	// Password is the length policy every password write enforces; zero fields
	// default to 8..128 characters. Published by GET {api}/capabilities.
	Password password.Policy
	// Username bounds username length; zero fields default to 4..30. The
	// character rule is fixed (authkit.UsernamePattern). Published by
	// GET {api}/capabilities.
	Username authkit.UsernamePolicy
	// Keys controls signing-key resolution (or verify-only mode).
	Keys KeysConfig
	// Ephemeral governs the short-lived state backend (2FA codes, pending
	// registrations, reset tokens, rate-limit counters).
	Ephemeral EphemeralConfig
	// Identity declares external OAuth2/OIDC identity providers.
	Identity IdentityConfig
	// APIKeys configures opaque permission-group-owned machine credentials.
	APIKeys APIKeysConfig
	// TwoFactor configures optional MFA features.
	TwoFactor TwoFactorConfig
	// Passkeys configures WebAuthn/FIDO2 passkey ceremonies.
	Passkeys PasskeyConfig
	// DeviceKeys enables the refreshless native-client device-key surface
	// (#278). Off by default: enrollment is an email-code login, so hosts opt
	// in explicitly before RouteDeviceKeys is mounted or the engine issues
	// enrollment/login challenges (#293).
	DeviceKeys DeviceKeysConfig
	// RBAC declares the app's permission-group personas (#111): containment
	// schema plus per-persona role catalogs. Empty yields root-only.
	RBAC []PersonaDef

	// Applications configures application self-registration (#264): domain-
	// proven remote applications with service-owned orgs. Zero value = disabled
	// (the manual/bootstrap registration paths are unaffected).
	Applications ApplicationsConfig

	// Delegated configures the delegated-token mint route (#261): the audience
	// allowlist and the TTL floor/default/ceiling. Zero value = the route is
	// not mounted. An internally inconsistent triple refuses at construction —
	// never a silent clamp of the configuration itself (request-time TTLs ARE
	// clamped into the validated bounds).
	Delegated DelegatedConfig

	// Documents configures the published signed-document surface (#260):
	// which remote-application reader slugs may fetch published documents from
	// GET|HEAD /.well-known/authkit/documents/{digest}. Publication is never
	// public — an empty list with a mounted documents surface refuses at
	// construction (authhttp.New), fail-closed like the publisher itself.
	Documents DocumentsConfig

	// Schema is the Postgres schema AuthKit's tables live in. Empty defaults to
	// "profiles" (the historical hard-coded name). Set it when multiple apps
	// embed AuthKit against the same database and must not share auth tables
	// (authkit issue 69). The name must match ^[a-z_][a-z0-9_]*$ (max 63 bytes);
	// NewFromConfig rejects anything else. Hosts must call ApplyMigrations with
	// the same schema before constructing the Runtime.
	Schema string

	// SolanaNetwork is the SIWS chain selector ("mainnet"/"testnet"/"devnet").
	// Empty defaults to mainnet. Solana Name Runtime (SNS)
	// resolution is AuthKit-owned: it uses the built-in keyless resolver, with a
	// fixed 3s lookup timeout and 24h cache TTL. There is no host override.
	SolanaNetwork string

	// SessionEventRetention is how long session-event history rows
	// (sign-ins/revocations, incl. IP + user-agent — personal data) are kept
	// before CleanupExpiredAuthState prunes them. 0 (unset) defaults to 365
	// days — the deliberate ceiling; any negative value keeps events forever.
	SessionEventRetention time.Duration
	// contains filtered or unexported fields
}

type ContactChange struct {
	// Field is "email" or "phone".
	Field string
	// NewValue is the replacement address as stored.
	NewValue string
}

type CreateAccountRegistrationInviteRequest = authkit.CreateAccountRegistrationInviteRequest

type CreateGroupInviteLinkRequest = authkit.CreateGroupInviteLinkRequest

type CreateInstanceResult struct {
	// GroupID is the new (or idempotently returned) instance's uuid (#269). It
	// is populated on BOTH outcomes: the idempotent re-run is the bootstrap
	// path, so an id only on Created=true would leave the re-runner with
	// nothing. Empty only on error.
	GroupID      string
	InstanceSlug string
	Created      bool
}

type CreatePermissionGroupRequest = authkit.CreatePermissionGroupRequest

type CustomRoleResolver func(groupID string, role authkit.Role) ([]string, bool)

type DelegatedAccessParams = authkit.DelegatedAccessParams

type DelegatedConfig struct {
	// AllowDPoP allows browser-key binding. The authorizer must handle requests
	// with ConfirmationJWKThumbprintSHA256 set and DelegateCertificate nil.
	AllowDPoP bool `json:"allow_dpop" yaml:"allow_dpop"`
	// Audiences is the allowlist. Requested audiences must be a subset; an
	// empty request receives the full list. Empty = the route is disabled.
	Audiences []string
	// TTLFloor/TTLDefault/TTLCeiling bound the minted token TTL. Unset fields
	// default to 60s / 15m / 1h. After defaulting, the triple must satisfy
	// 0 < floor <= default <= ceiling or construction refuses (#231 house
	// style: an impossible configuration never boots).
	TTLFloor   time.Duration
	TTLDefault time.Duration
	TTLCeiling time.Duration
}

type DelegationAuthorizer = authkit.DelegationAuthorizer

type DelegationGrant = authkit.DelegationGrant

type DelegationRequest = authkit.DelegationRequest

type DeletePermissionGroupOptions = authkit.DeletePermissionGroupOptions

type Deps struct {
	// River is nil for managed maintenance, or RiverFromHost for a shared fleet.
	River *RiverOwnership

	// Postgres is the durable store. Required by every host-facing constructor.
	Postgres *pgxpool.Pool
	// Redis backs the ephemeral store, namespaced by Ephemeral.KeyPrefix
	// (#307). Nil selects the per-process memory store, which construction
	// refuses unless Config.Ephemeral.AllowMemory is set (#305).
	// Redis-compatible servers must provide atomic Lua execution (EVAL/EVALSHA)
	// for conditional proof claims and counters, as well as atomic GETDEL.
	Redis *redis.Client
	// EphemeralStore is a host-supplied store; mutually exclusive with Redis.
	EphemeralStore EphemeralStore
	Email          EmailSender
	SMS            SMSSender
	Entitlements   EntitlementsProvider
	// Deletion hooks run durably through River, never inside the request's
	// transaction. Soft deletion must preserve recoverable host data; hard
	// deletion is finalization work after 30 days and before identity purge.
	// Hooks must be idempotent and honor context cancellation. Nil means no
	// application work for that stage. OnRestore undoes reversible soft work.
	OnSoftDelete func(context.Context, authkit.UserDeletion) error
	OnHardDelete func(context.Context, authkit.UserDeletion) error
	OnRestore    func(context.Context, authkit.UserDeletion) error
	// DelegatedAuthorization is the host's delegation authorizer for the
	// delegated-token mint route (#261/#277); its grant is the complete
	// authority AuthKit signs. Required when Delegated.Audiences is set.
	DelegatedAuthorization DelegationAuthorizer
	// ApplicationAdmission is consulted before any application
	// self-registration fetch (#264): a non-nil error refuses the attempt.
	ApplicationAdmission func(ctx context.Context, domain string) error
	// InstanceAdmission is consulted before any generated persona-instance
	// creation (#263) with the normalized slug; a non-nil error refuses.
	InstanceAdmission func(ctx context.Context, group authkit.GroupRef, subject string) error
	// NameAdmission is the host's side-effect-free namespace policy for
	// creation and rename.
	NameAdmission func(context.Context, authkit.NameAdmissionRequest) error
	// SolanaSNSResolver replaces the SNS primary-name resolver used after a
	// verified Solana link.
	SolanaSNSResolver SolanaSNSResolver
	// OutboundHTTP overrides the client for application-document and JWKS
	// fetches (#264); nil builds the timeout-bounded, redirect-refusing,
	// SSRF-guarded default.
	OutboundHTTP *http.Client
	// Clock replaces the engine clock for TTL and grace-window decisions.
	Clock func() time.Time
}

type DeviceKey struct {
	ID         string     `json:"id"`
	Label      string     `json:"label,omitempty"`
	CreatedAt  time.Time  `json:"created_at"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
	RevokedAt  *time.Time `json:"revoked_at,omitempty"`
}

type DeviceKeyAuthResult struct {
	AccessToken string
	ExpiresAt   time.Time
	DeviceKey   DeviceKey
}

type DeviceKeyChallenge struct {
	ID        string
	Challenge string
	ExpiresAt time.Time
}

type DeviceKeyNotice struct {
	Label     string
	CreatedAt time.Time
}

type DeviceKeySecondFactorRequired struct{ Method string }

type DeviceKeysConfig struct {
	// Enabled mounts RouteDeviceKeys and lets the engine run enrollment and
	// login ceremonies.
	Enabled bool
}

type DocumentReader struct {
	ID     string
	Domain string
	Issuer string
}

type DocumentsConfig struct {
	// Readers are the remote applications allowed to fetch published
	// documents. Authorization is config, not a host callback, and it keys on
	// an identity nobody else can claim — never on the slug, which is a
	// claimable handle. Empty + a mounted documents surface is a construction
	// error, never a public route.
	Readers []DocumentReader
	// AllowRegisteredTier admits readers still at the registered tier
	// (self-registered, not yet approved by an admin). Default: approved only.
	AllowRegisteredTier bool
}

type EmailSender interface {
	SendVerification(ctx context.Context, email, username string, msg VerificationMessage) error
	SendPasswordResetLink(ctx context.Context, email, username, resetURL string) error
	SendAccountRegistrationInvite(ctx context.Context, email, inviteURL string) error
	SendLoginCode(ctx context.Context, email, username, code string) error
	SendWelcome(ctx context.Context, email, username string) error
	// SendContactChanged goes to the address that was just REPLACED.
	SendContactChanged(ctx context.Context, email, username string, change ContactChange) error
	// SendDeviceKeyEnrolled tells the account's address that a new device key
	// can now sign in as it.
	SendDeviceKeyEnrolled(ctx context.Context, email, username string, notice DeviceKeyNotice) error
}

type EntitlementFilterProvider interface {
	ListSubjectsWithEntitlement(ctx context.Context, entitlement string) ([]string, error)
}

type EntitlementsProvider interface {
	ListEntitlements(ctx context.Context, userIDs []string) (map[string][]string, error)
}

type EphemeralConfig struct {
	// AllowMemory permits the in-memory ephemeral store and rate limiter
	// (single-instance deployments and local development only).
	AllowMemory bool
	// KeyPrefix namespaces every Redis key this deployment writes (ephemeral
	// store, OIDC/SIWS caches, rate-limit counters) so several AuthKit
	// deployments can share one Redis database (#307). Empty derives
	// "authkit:<schema>:"; a trailing ':' is added when missing. Must match
	// ^[a-z0-9_.:-]{1,64}$.
	KeyPrefix string
}

type EphemeralStore interface {
	Get(ctx context.Context, key string) ([]byte, bool, error)
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
	Del(ctx context.Context, key string) error
	// Consume atomically returns AND deletes a key in a single operation, so the
	// value is delivered to AT MOST ONE caller even under concurrent reads
	// (Redis GETDEL / a single locked get-delete). Single-use credentials whose
	// KEY is the secret — a WebAuthn/passkey challenge, a password-reset token —
	// MUST be read via Consume, never Get+Del: a non-atomic read-then-delete lets
	// two concurrent requests both observe the value before either deletes it,
	// defeating the single-use guarantee (replay). Missing key => (nil, false, nil).
	Consume(ctx context.Context, key string) ([]byte, bool, error)
	// CompareAndConsume deletes a live key only while it still holds expected.
	// OTP/link representations use one canonical record; an old reader can
	// neither win twice nor consume a newer issuance. Missing/mismatch => false.
	CompareAndConsume(ctx context.Context, key string, expected []byte) (bool, error)
	// Incr atomically increments the integer at key and returns the new value,
	// creating it as 1 with ttl when absent (the TTL is set once, not on every
	// increment). Attempt caps MUST use it: a Get+Set counter lets K concurrent
	// wrong guesses all read the same n and the cap never fires (#306).
	Incr(ctx context.Context, key string, ttl time.Duration) (int64, error)
}

type ExternalIdentity struct {
	Provider          string // provider slug (the configured name)
	Issuer            string
	Subject           string
	Email             string
	EmailVerified     bool
	PreferredUsername string
	DisplayName       string
}

type ExternalLinkAuthorization struct {
	UserID          string
	SessionID       string
	AuthenticatedAt time.Time
}

type ExternalLoginInput struct {
	Identity ExternalIdentity
	// Link authorizes a provider mutation only; it never creates a session.
	Link               *ExternalLinkAuthorization
	AccountInviteToken string
	Event              string // session-created audit event, e.g. "oidc_login"
	UserAgent          string
	IP                 string
}

type FactorEnrollmentMode string

type FrontendConfig struct {
	// BaseURL, if set, is used for building absolute URLs (e.g. password
	// reset/verify links). If empty and Token.Issuer is a well-formed URL,
	// NewFromConfig defaults it to the issuer.
	BaseURL string
	// OIDCReturnPath is the host SPA landing route AuthKit redirects to after it
	// finishes an OIDC/social login flow (the browser is sent to
	// BaseURL + OIDCReturnPath with the login result). This is NOT the backend
	// OAuth/OIDC provider callback URL — AuthKit owns that. Empty defaults to
	// "/login/callback".
	OIDCReturnPath string
	// VerifyPath is the host-owned frontend route that receives scanner-safe
	// verification link landings. Empty defaults to "/verify".
	VerifyPath string
	// PasswordResetPath is the host-owned frontend route that receives
	// scanner-safe password reset link landings. Empty defaults to "/reset".
	PasswordResetPath string
	// PasswordlessPath is the host-owned frontend route that receives
	// passwordless login magic links. Empty defaults to "/passwordless".
	PasswordlessPath string
	// InvitePath is the host-owned frontend route that receives permission-group
	// invite links (`?code=…`); the SPA reads the code and POSTs it to the redeem
	// endpoint. Empty defaults to "/accept-invite". (#134)
	InvitePath string
}

type GeneratedRoute struct {
	Persona authkit.Persona
	Method  string
	Path    string // e.g. /merchant/:instance_slug/members
	Perm    authkit.Perm
}

type GroupAssignment struct {
	Persona           authkit.Persona
	PermissionGroupID string // opaque group id; used ONLY to scope custom-role lookups
	Role              authkit.Role
}

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

type GroupInstance = authkit.GroupInstance

type GroupInviteLink = authkit.GroupInviteLink

type GroupInviteLinkCreated = authkit.GroupInviteLinkCreated

type GroupMember = authkit.GroupMember

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

type HTTPBackend interface {
	authkit.Client
	verify.Enricher
	AssignGroupRoleFromClaims(ctx context.Context, claims verify.Claims, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error
	RemoveGroupSubjectFromClaims(ctx context.Context, claims verify.Claims, group authkit.GroupRef, subject authkit.Subject) error
	AdminRevokeAccountSessionsAs(ctx context.Context, actorUserID, userID string) (authkit.AccountSessionRevocation, error)
	AssignRemoteApplicationRoleAs(ctx context.Context, actorUserID string, group authkit.GroupRef, appSlug string, role authkit.Role) error
	BeginDeviceKeyEnrollment(ctx context.Context, email, publicKey, label string) (DeviceKeyChallenge, error)
	BeginDeviceKeyLogin(ctx context.Context, deviceKeyID string) (DeviceKeyChallenge, error)
	BeginPasskeyLogin(ctx context.Context) (*protocol.CredentialAssertion, error)
	BeginPasskeyRegistration(ctx context.Context, userID string) (*protocol.CredentialCreation, error)
	BeginTwoFactorEnrollment(ctx context.Context, userID string, enrollmentToken bool, sessionID string) (TwoFactorEnrollmentScope, error)
	ChangePassword(ctx context.Context, userID, current, new string, keepSessionID *string) error
	CheckPendingRegistrationConflict(ctx context.Context, email, username string) (bool, bool, error)
	CheckPhoneRegistrationConflict(ctx context.Context, phone, username string) (bool, bool, error)
	CheckSMSHealth(ctx context.Context) error
	CheckUserPassword(ctx context.Context, userID, pass string) error
	ClaimDPoPProof(ctx context.Context, key string, ttl time.Duration) (bool, error)
	CompleteExternalLogin(ctx context.Context, in ExternalLoginInput) (LoginOutcome, error)
	CompleteLoginChallenge(ctx context.Context, in LoginChallengeInput) (LoginOutcome, error)
	Config() Config
	ConfirmPasswordReset(ctx context.Context, token, newPassword string) (string, error)
	ConfirmVerification(ctx context.Context, in VerificationInput) (LoginOutcome, error)
	ContinueRefreshMFA(ctx context.Context, userID, sessionID string) (LoginOutcome, error)
	CreateAccountRegistrationInvite(ctx context.Context, req CreateAccountRegistrationInviteRequest) (AccountRegistrationInviteCreated, error)
	CreateInstanceForSubject(ctx context.Context, group authkit.GroupRef, displayName, ownerUserID string) (CreateInstanceResult, error)
	DefineGroupCustomRole(ctx context.Context, actorUserID string, group authkit.GroupRef, def authkit.CustomRoleDef) error
	DelegationAuthorizer() DelegationAuthorizer
	DeleteGroupCustomRole(ctx context.Context, actorUserID string, group authkit.GroupRef, role authkit.Role) error
	DeletePasskey(ctx context.Context, userID, id string) error
	DeletePendingPhoneRegistrationByPhone(ctx context.Context, phone string) error
	DeletePendingRegistrationByEmail(ctx context.Context, email string) error
	DeleteRemoteApplication(ctx context.Context, issuer string) error
	Disable2FAFactorWithRemovedRoles(ctx context.Context, userID, factorID string) ([]RemovedMFARoleAssignment, error)
	Disable2FAWithRemovedRoles(ctx context.Context, userID string) ([]RemovedMFARoleAssignment, error)
	EnrollTwoFactor(ctx context.Context, in TwoFactorEnrollInput) (TwoFactorEnrollOutcome, error)
	EphemeralRedisClient() *redis.Client
	ExchangeRefreshToken(ctx context.Context, refreshToken string, ua string, ip net.IP) (idToken string, expiresAt time.Time, newRefresh string, err error)
	FinishDeviceKeyEnrollment(ctx context.Context, enrollmentID, code, signature, secondFactor string) (DeviceKeyAuthResult, error)
	FinishDeviceKeyLogin(ctx context.Context, challengeID, signature string) (DeviceKeyAuthResult, error)
	FinishPasskeyLogin(ctx context.Context, response []byte, userAgent string, ip net.IP) (LoginOutcome, error)
	ConfirmAccountRecovery(ctx context.Context, token string) error
	FinishPasskeyRegistration(ctx context.Context, userID string, response []byte) (Passkey, error)
	GenerateSIWSChallenge(ctx context.Context, cache siws.ChallengeCache, domain, address, username string) (siws.SignInInput, error)
	Get2FASettings(ctx context.Context, userID string) (*TwoFactorSettings, error)
	GetPendingPhoneRegistrationByPhone(ctx context.Context, phone string) (*PendingRegistration, error)
	GetPendingRegistrationByEmail(ctx context.Context, email string) (*PendingRegistration, error)
	GetPreferredLanguage(ctx context.Context, userID string) (PreferredLanguage, error)
	GetProviderLinkByIssuer(ctx context.Context, issuer, subject string) (string, *string, error)
	GetRemoteApplicationBySlug(ctx context.Context, slug string) (*RemoteApplication, error)
	GroupNamingState(ctx context.Context, id string) (authkit.NamingState, error)
	HasEmailSender() bool
	HasPassword(ctx context.Context, userID string) (bool, error)
	HasProviderLink(ctx context.Context, userID, issuer, providerSlug string) (bool, error)
	JWKS() jwtkit.JWKS
	LinkSolanaWallet(ctx context.Context, cache siws.ChallengeCache, userID string, output siws.SignInOutput) error
	ListDeviceKeys(ctx context.Context, userID, currentID string) ([]DeviceKey, error)
	ListPasskeys(ctx context.Context, userID string) ([]Passkey, error)
	ListRemoteApplicationsForGroup(ctx context.Context, group authkit.GroupRef) ([]RemoteApplication, error)
	ListSessionEvents(ctx context.Context, userID string, eventTypes ...SessionEventType) ([]AuthSessionEvent, error)
	ListUserSessions(ctx context.Context, userID string) ([]Session, error)
	LogSessionFailed(ctx context.Context, userID string, sessionID string, reason *string, ip *string, ua *string)
	MarkSessionAuthenticated(ctx context.Context, userID, sessionID string) error
	MarkSessionAuthenticatedWithMethods(ctx context.Context, userID, sessionID string, authMethods []string) error
	MintDelegatedAccessToken(ctx context.Context, p DelegatedAccessParams) (string, error)
	NamingPolicy() authkit.NamingPolicy
	PasskeysEnabled() bool
	PasswordLogin(ctx context.Context, in PasswordLoginInput) (LoginOutcome, error)
	PasswordlessLogin(ctx context.Context, in PasswordlessLoginInput) (LoginOutcome, error)
	PermissionGroupSchema() *GroupSchema
	Postgres() *pgxpool.Pool
	ProviderSlugs(ctx context.Context, userID string) ([]string, error)
	PublicKeysByKID() map[string]crypto.PublicKey
	PublicNativeUserRegistrationEnabled() bool
	RecordFailedDeviceKeyEnrollment(ctx context.Context, enrollmentID string)
	RedeemGroupInviteLink(ctx context.Context, code, redeemerUserID string) (RedeemGroupInviteLinkResult, error)
	RedisKeyPrefix() string
	RegenerateBackupCodes(ctx context.Context, userID string) ([]string, error)
	Register(ctx context.Context, in RegisterInput) (RegisterOutcome, error)
	RegisterApplicationFromDomain(ctx context.Context, domain string) (*RegisteredApplication, error)
	RegistrationVerificationEnabled() bool
	RenamePasskey(ctx context.Context, userID, id, label string) error
	RequestEmailChange(ctx context.Context, userID, newEmail string) error
	RequestEmailVerification(ctx context.Context, email string, ttl time.Duration) error
	RequestPasswordReset(ctx context.Context, email string, ttl time.Duration, ip *string, ua *string) error
	RequestPhoneChange(ctx context.Context, userID, newPhone string) error
	RequestPhonePasswordReset(ctx context.Context, phone string, ttl time.Duration, ip *string, ua *string) error
	RequestPhoneVerification(ctx context.Context, phone string, ttl time.Duration) error
	Require2FAForStepUpMethod(ctx context.Context, userID, sessionID, method string) (destination, selectedMethod string, factor TwoFactorFactor, err error)
	ResendLoginChallenge(ctx context.Context, userID, nonce, factorID string) (*TwoFactorChallenge, error)
	ResendRegistration(ctx context.Context, identifier string) (bool, error)
	RevokeDeviceKey(ctx context.Context, userID, currentID, targetID string) error
	RevokeIssuerSessions(ctx context.Context, userID string, keepSessionID *string) error
	RevokeOtherDeviceKeys(ctx context.Context, userID, currentID string) error
	RevokeSessionByIDForUser(ctx context.Context, userID, sessionID string) error
	SMSAvailable() bool
	SMSHealthy() bool
	Schema() string
	SendWelcome(ctx context.Context, userID string)
	SessionFreshness(ctx context.Context, userID, sessionID string, now time.Time) (SessionFreshness, error)
	SetPasswordAfterFreshAuth(ctx context.Context, userID, new string, keepSessionID *string) error
	SetPreferredLanguage(ctx context.Context, userID, language string) error
	SoftDeleteUser(ctx context.Context, id string) error
	SoftDeleteUserAs(ctx context.Context, actorUserID, userID string) error
	RestoreUserAs(ctx context.Context, actorUserID, userID string) error
	StartPasswordless(ctx context.Context, req PasswordlessStartRequest) (PasswordlessStartResult, error)
	TwoFactorAllowedMethods() []string
	TwoFactorEnabled() bool
	UnlinkProviderUnlessLast(ctx context.Context, userID, provider string) (bool, error)
	UpdateGroupInstanceAs(ctx context.Context, actorUserID, groupID string, update authkit.GroupInstanceUpdate) (authkit.GroupInstance, error)
	UserNamingState(ctx context.Context, id string) (authkit.NamingState, error)
	UserProfile(ctx context.Context, in ProfileInput) (authkit.UserProfile, error)
	ValidatePassword(value string, identifiers ...string) error
	ValidateUsername(username string) error
	ValidateUsernameForRegistration(ctx context.Context, username string) (string, error)
	ValidateVerificationConfiguration() error
	Verify2FAStepUpMethodCode(ctx context.Context, userID, sessionID, method, code string) (bool, error)
	VerifyBackupCode(ctx context.Context, userID, backupCode string) (bool, error)
	VerifyPendingPassword(ctx context.Context, email, pass string) bool
	VerifyPendingPhonePassword(ctx context.Context, phone, pass string) bool
	VerifySIWSAndLogin(ctx context.Context, cache siws.ChallengeCache, output siws.SignInOutput, extra map[string]any) (LoginOutcome, error)
}

type HTTPConfiguration interface {
	BuildHTTP(HTTPBackend) (HTTPSurface, error)
}

type HTTPRoute struct {
	Method  string
	Path    string
	Handler http.Handler
}

type HTTPSurface interface {
	Routes() []HTTPRoute
	Verifier() *verify.Verifier
	Close()
}

type IdentityConfig struct {
	// Providers are the external identity providers: authprovider.Google/
	// Apple/Discord/GitHub for the built-ins, authprovider.OIDC/OAuth2 for any
	// other IdP. Each provider owns its quirks and carries its own Name.
	Providers []authprovider.Provider
}

type ImportUnverifiedSolanaLinkInput = authkit.ImportUnverifiedSolanaLinkInput

type ImportUnverifiedSolanaLinkResult = authkit.ImportUnverifiedSolanaLinkResult

type ImportUnverifiedSolanaLinkStatus = authkit.ImportUnverifiedSolanaLinkStatus

type ImportUnverifiedSolanaLinksResult = authkit.ImportUnverifiedSolanaLinksResult

type ImportUserInput = authkit.ImportUserInput

type ImportUserResult = authkit.ImportUserResult

type ImportUserStatus = authkit.ImportUserStatus

type ImportUsersResult = authkit.ImportUsersResult

type InstanceCreationDef = authkit.InstanceCreationDef

type IssuedSession struct {
	SessionID       string
	RefreshToken    string
	AccessToken     string
	AccessExpiresAt time.Time
}

type KeysConfig struct {
	// Source can be nil — if nil, authkit resolves keys from the filesystem:
	// <Path>/keys.json (default /vault/auth), hot-reloaded on rotation. When no
	// keys.json exists, construction FAILS unless AllowEphemeralDevKeys is set.
	// Hosts NEVER handle the private key — they delegate the signing OPERATION
	// to authkit; there is no API that returns a private key or PEM (a future
	// Vault-Transit backend, authkit future #72, drops in behind the same
	// Signer seam).
	Source jwtkit.KeySource
	// Path overrides the filesystem DIRECTORY the local key resolver scans for
	// keys.json (and totp.key, #148) when Source is nil. Empty defaults to
	// /vault/auth. There is no env fallback (#231; AUTHKIT_KEYS_PATH is read by
	// cmd/authkit-server only).
	Path string
	// AllowEphemeralDevKeys opts in to auto-generating an RSA dev signing
	// keypair when Source is nil and no <Path>/keys.json exists. It lives in
	// memory, unless Path is explicit — then it is written to <Path>/keys.json
	// so restarts reuse it. DEVELOPMENT ONLY — the default (false) is
	// fail-closed: with no keys configured, NewFromConfig returns a hard error
	// instead of silently minting dev keys (#231). This flag is deliberately
	// NOT derived from Environment.
	AllowEphemeralDevKeys bool
	// VerifyOnly constructs the Runtime with NO active signer (#87): token
	// MINTING returns ErrMissingSigner, while VERIFICATION and all RBAC reads
	// work fully and the JWKS endpoint serves an empty key set. When true, key
	// resolution is SKIPPED. Ignored when Source is non-nil. Use it for a
	// pure resource-server / control-plane deployment that only verifies inbound
	// tokens.
	VerifyOnly bool
}

type Keyset struct {
	Active     jwtkit.Signer
	PublicKeys map[string]crypto.PublicKey // kid -> pub
}

type LoginChallengeInput struct {
	UserID     string
	Challenge  string
	FactorID   string
	Code       string
	BackupCode bool
	UserAgent  string
	IP         string
}

type LoginOutcome struct {
	Recovery       *AccountRecoveryConfirmation
	Enrollment     *authkit.TokenSet
	AllowedMethods []string
	ReturnTo       string
	Created        bool
	Kind           LoginOutcomeKind
	UserID         string
	Reason         error
	Session        *IssuedSession
	Verification   *VerificationRequired
	Challenge      *TwoFactorChallenge
}

type LoginOutcomeKind string

type LoginSessionInput struct {
	UserID      string
	AuthMethods []string       // how the session was established, e.g. {"pwd"}
	Event       string         // session-created audit event, e.g. "password_login"
	Extra       map[string]any // extra access-token claims
	UserAgent   string
	IP          string
}

type MFAContinuationRequiredError struct {
	UserID    string
	SessionID string
	Reason    error
}

type MFAStatus = authkit.MFAStatus

type MigrationOptions struct {
	River       *RiverOwnership
	RiverSchema string
	// RuntimePool identifies the existing database user that will run AuthKit.
	// When supplied, initialization grants that user runtime access directly.
	// Both pools must connect to the same database and remain host-owned.
	// Nil applies migrations without provisioning runtime privileges.
	RuntimePool *pgxpool.Pool
}

type Passkey struct {
	ID                      string     `json:"id"`
	UserID                  string     `json:"user_id,omitempty"`
	Label                   *string    `json:"label,omitempty"`
	Transports              []string   `json:"transports,omitempty"`
	AuthenticatorAttachment string     `json:"authenticator_attachment,omitempty"`
	BackupEligible          bool       `json:"backup_eligible"`
	BackupState             bool       `json:"backup_state"`
	CreatedAt               time.Time  `json:"created_at"`
	LastUsedAt              *time.Time `json:"last_used_at,omitempty"`
}

type PasskeyConfig struct {
	RPID             string
	RPDisplayName    string
	Origins          []string
	UserVerification string
}

type PasswordLoginInput struct {
	Identifier string
	Password   string
	UserAgent  string
	IP         string
}

type PasswordlessLoginInput struct {
	Identifier string
	Code       string
	Token      string
	UserAgent  string
	IP         string
}

type PasswordlessStartRequest = authkit.PasswordlessStartRequest

type PasswordlessStartResult = authkit.PasswordlessStartResult

type PendingChangeKind string

type PendingPasskeyAccount struct {
	UserID   string
	Creation *protocol.CredentialCreation
}

type PendingRegistration struct {
	Email             string
	Username          string
	PasswordHash      string
	PreferredLanguage string
}

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

type PersonaCapabilities = authkit.PersonaCapabilities

type PersonaDef struct {
	Name         authkit.Persona
	Roles        []RoleDef       // app-declared; owner (=<persona>:*) is injected if absent
	Parent       authkit.Persona // declared persona; empty only for root. Non-root must name exactly one parent.
	Capabilities PersonaCapabilities
	Catalog      []string
	// Creation opts the persona into the generated instance-creation route
	// (#263): POST /<persona>, owner seeded from the authenticated user. Only
	// root-parented personas may enable it (validated at schema build).
	Creation InstanceCreationDef
}

type PreferredLanguage = authkit.PreferredLanguage

type ProfileInput struct {
	UserID          string
	ClaimsUsername  string // fallback when the row carries no username
	AuthTime        time.Time
	StepUpSatisfied bool // the presented token is fresh enough for sensitive actions
	// EnabledProviders lists the deployment's login providers;
	// ProviderSupportsStepUp reports which linked providers can re-authenticate.
	EnabledProviders       []string
	ProviderSupportsStepUp func(provider string) bool
}

type RBACDriftReport struct {
	GroupUserRoles int `json:"group_user_roles"`
	CustomRoles    int `json:"group_custom_roles"`
	APIKeys        int `json:"api_keys"`
}

type RedeemGroupInviteLinkResult = authkit.RedeemGroupInviteLinkResult

type RegisterInput struct {
	Identifier         string
	Username           string
	Password           string
	PreferredLanguage  string
	AccountInviteToken string
	UserAgent          string
	IP                 string
}

type RegisterOutcome struct {
	Login    *LoginOutcome
	Kind     RegisterOutcomeKind
	Username string
	Email    *string
	Phone    *string
	Session  *IssuedSession
}

type RegisterOutcomeKind string

type RegisteredApplication = authkit.RegisteredApplication

type RegistrationConfig struct {
	// Verification controls registration verification: "none"|"optional"|
	// "required". Empty defaults to "none".
	Verification RegistrationVerificationPolicy
	// NativeUserMode controls public native-user self-registration. Empty
	// defaults to "open". Non-open modes disable every public user-creation path
	// while leaving embedded admin/bootstrap core APIs available.
	NativeUserMode RegistrationMode
	// PasswordlessLogin enables contact-based passwordless sessions. Off by
	// default; hosts must opt in before /passwordless/start sends challenges.
	PasswordlessLogin bool
	// PasswordlessAutoRegistration lets a verified unknown contact create a
	// no-password user during passwordless confirmation. Off by default.
	PasswordlessAutoRegistration bool
	// AllowMissingSenders lets verification, contact-change, password-reset and
	// login-code flows proceed when no email/SMS sender is wired: nothing is
	// delivered and the engine hands the code back to its caller (dev rigs read
	// it from there). The default (false) makes a missing sender an error.
	AllowMissingSenders bool
	// VerificationSendTimeout bounds each in-line email/SMS provider send
	// (registration/verification codes, password-reset links, passwordless login
	// codes) so a misconfigured/unreachable provider cannot hang the request that
	// triggered it. 0 (unset) defaults to 15 seconds.
	VerificationSendTimeout time.Duration
}

type RegistrationMode = authkit.RegistrationMode

type RegistrationVerificationPolicy = authkit.RegistrationVerificationPolicy

type RemoteAppKey = authkit.RemoteAppKey

type RemoteApplication = authkit.RemoteApplication

type RemoteApplicationAccessParams = authkit.RemoteApplicationAccessParams

type RemovedMFARoleAssignment struct {
	PermissionGroupID string
	Persona           authkit.Persona
	InstanceSlug      string
	Role              authkit.Role
	RemovedAt         time.Time
}

type ResolvedAPIKey = authkit.ResolvedAPIKey

type RiverConfig struct {
	Schema          string
	CleanupInterval time.Duration
}

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

type RoleDef struct {
	Name        authkit.Role
	Permissions []string
	RequiresMFA bool
}

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

type SMSHealthChecker interface {
	CheckHealth(ctx context.Context) error
}

type SMSSender interface {
	SendVerification(ctx context.Context, phone string, msg VerificationMessage) error
	SendPasswordResetLink(ctx context.Context, phone, resetURL string) error
	SendLoginCode(ctx context.Context, phone, code string) error
	// SendContactChanged goes to the number that was just REPLACED.
	SendContactChanged(ctx context.Context, phone string, change ContactChange) error
}

type ServiceJWTClaims = authkit.ServiceJWTClaims

type ServiceJWTMintOptions = authkit.ServiceJWTMintOptions

type Session = authkit.Session

type SessionEventType string

type SessionFreshness struct {
	LastAuthenticatedAt           time.Time
	TimeUntilStepUpRequired       time.Duration
	StepUpRequiredForSensitiveOps bool
	AuthMethods                   []string
}

type SessionRevokeReason string

type SolanaLinkedAccount = authkit.SolanaLinkedAccount

type SolanaSNSResolver interface {
	ResolvePrimaryName(ctx context.Context, address string) (string, error)
}

type SubjectGroupMembership = authkit.SubjectGroupMembership

type TOTPEnrollment struct {
	UserID      string
	Code        string
	MakeDefault bool
	Mode        FactorEnrollmentMode
}

type TokenConfig struct {
	// EntitlementAllowlist selects coarse provider-granted names for native
	// access-token snapshots. Empty skips the mint-time provider lookup and
	// omits the claim. Selection never grants an entitlement by itself.
	EntitlementAllowlist []string
	Issuer               string
	IssuedAudiences      []string // tokens issued will contain ALL of these audiences
	ExpectedAudiences    []string // audiences accepted at verification; empty defaults to IssuedAudiences
	AccessTokenDuration  time.Duration
	RefreshTokenDuration time.Duration
	// SessionMaxPerUser caps concurrent refresh sessions per user. 0 (unset)
	// applies the default of 3; any negative value (e.g. -1) means unlimited.
	// Eviction is always evict-oldest.
	SessionMaxPerUser int
	// RefreshRotationGrace is how long a just-rotated refresh token keeps being
	// answered with the successor it rotated into, instead of being read as
	// reuse and revoking the family (ak#274). It exists for the race in which
	// two holders of ONE token refresh at once — a shared credential file, a
	// retried request, a response lost in flight — which is otherwise
	// indistinguishable from theft and is punished as theft. 0 (unset) applies
	// the default of 30s; any negative value disables the window and restores
	// strictly single-use rotation.
	RefreshRotationGrace time.Duration
	// AccountIssuers lists every issuer whose deployment shares this account
	// store (same database schema), e.g. two sites with separate logins over
	// one set of accounts. Account-level revocations — admin emergency revoke,
	// password/contact changes, ban and deletion — cover refresh sessions on
	// all of them. Logout and a user's own session management stay on Issuer.
	// Issuer is always included; empty means Issuer alone. Every deployment
	// sharing the store should configure the same set.
	AccountIssuers []string
}

type TrustSourcePolicy struct {
	AllowPrivateNetworkJWKS bool
}

type TwoFactorChallenge struct {
	Method      string
	Destination string // where the code went (email/phone), unmasked
	Challenge   string
	Factor      TwoFactorFactor
	Factors     []TwoFactorFactor
}

type TwoFactorConfig struct {
	// Mode is the account-wide 2FA policy: Disabled (no enroll/challenge/verify
	// routes usable), Optional (users may enroll), or Required (every user must
	// enroll before normal session use; existing un-enrolled users are challenged
	// on their next authenticated request). Empty defaults to Optional; other
	// values fail construction. Per-role
	// RoleDef.RequiresMFA remains available for narrower enforcement.
	Mode TwoFactorMode

	// Methods is the set of second-factor channels the host enables
	// (Email/SMS/TOTP). Empty defaults to all three. A method whose dependency is
	// missing (e.g. SMS with no SMS sender) fails closed regardless of this list.
	Methods []TwoFactorMethod

	// TOTPSecretKey encrypts persisted authenticator-app shared secrets. It must
	// be 16, 24, or 32 RAW bytes (not base64/hex). This is an OVERRIDE for
	// tests/custom key management; the normal path loads the key from
	// <Keys.Path>/totp.key (vault-mounted key material, same model as JWT
	// signing keys; wired in NewFromConfig, #232). An override of any other
	// length is a hard construction error. Without either, TOTP enrollment
	// fails closed.
	TOTPSecretKey []byte
}

type TwoFactorEnrollInput struct {
	LoginChallenge string
	// SessionID is the caller's session; a confirmed code marks it 2FA-verified.
	SessionID   string
	UserAgent   string
	IP          string
	UserID      string
	Mode        FactorEnrollmentMode
	Method      string // "email" | "sms" | "totp"; empty with FactorID+MakeDefault re-points the default
	Code        string // email/SMS setup code or TOTP code; empty starts the method's setup
	PhoneNumber string
	MakeDefault bool
	FactorID    string
}

type TwoFactorEnrollKind string

type TwoFactorEnrollOutcome struct {
	Login           *LoginOutcome
	Kind            TwoFactorEnrollKind
	Method          string
	Secret          string
	OTPAuthURI      string
	BackupCodes     []string
	SessionVerified bool
}

type TwoFactorEnrollmentScope struct {
	Mode       FactorEnrollmentMode
	HasFactors bool
}

type TwoFactorFactor struct {
	ID           string
	UserID       string
	Method       string
	PhoneNumber  *string
	TOTPSecret   []byte
	LastTOTPStep *int64
	IsDefault    bool
	Enabled      bool
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type TwoFactorMethod = authkit.TwoFactorMethod

type TwoFactorMode = authkit.TwoFactorMode

type TwoFactorSettings struct {
	UserID       string
	Enabled      bool
	Method       string // "email", "sms", or "totp"
	PhoneNumber  *string
	TOTPSecret   []byte
	LastTOTPStep *int64
	BackupCodes  []string // Hashed backup codes
	Factors      []TwoFactorFactor
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type User = authkit.User

type VerificationInput struct {
	Identifier string
	Code       string
	Token      string
	UserID     string
	SessionID  string
	UserAgent  string
	IP         string
}

type VerificationMessage struct {
	// Fixed-length numeric code for manual entry (optional).
	Code string
	// AuthKit-built scanner-safe verification link (optional).
	LinkURL string
	// Purpose lets senders vary copy without adding new sender methods.
	Purpose string
}

type VerificationRequired struct {
	Identifier string
	Channel    string // "email" | "phone"
}

type VerifiedPasskey struct {
	UserID         string
	PasskeyID      string
	CredentialID   string
	BackupEligible bool
	BackupState    bool
	// contains filtered or unexported fields
}