engine

func (*Authenticator) Verify ¶

func (a *Authenticator) Verify(ctx context.Context, token string) (verify.Claims, error)

Verify is VerifyRequest for a token detached from any request.

func (*Authenticator) VerifyRequest ¶

func (a *Authenticator) VerifyRequest(r *http.Request) (verify.Claims, error)

VerifyRequest authenticates r: an API key is resolved and never tried as a JWT; a JWT is this deployment's.

func (*Engine) AcceptAgreements ¶ added in v1.20.0

func (s *Engine) AcceptAgreements(ctx context.Context, userID string, refs []iam.AgreementRef, opts ...ops.Option) error

AcceptAgreements records userID's acceptance of refs, each a declared document at its current version.

func (*Engine) AcceptRemoteInvitation ¶ added in v1.18.0

func (s *Engine) AcceptRemoteInvitation(ctx context.Context, v auth.Verified, id string) (iam.Role, error)

AcceptRemoteInvitation redeems one of v's RemoteInvitations: v's user (recorded in the group's directory) holds its role in the group from now on, replacing any it held. iam.ErrInvitationNotFound for an id that is not one of them.

func (*Engine) AddMFAEnrollmentExemptRoutes ¶

func (s *Engine) AddMFAEnrollmentExemptRoutes(paths []string)

AddMFAEnrollmentExemptRoutes registers the anchored paths (mount prefix and route path) of the 2FA enrollment routes, matched exactly: the only paths a 2FA-enrollment-only token, or a user a Required policy has yet to enroll, may reach. A host route replacing one (HTTPConfig.Exclude) keeps the exemption; one that merely ends in the same path does not (ak#324).

func (*Engine) Agreements ¶ added in v1.20.0

func (s *Engine) Agreements() []iam.Agreement

Agreements are the declared documents at their current versions.

func (*Engine) AgreementsDue ¶ added in v1.20.0

func (s *Engine) AgreementsDue(ctx context.Context, userID string) ([]iam.Agreement, error)

AgreementsDue are the documents userID is asked to accept now: one Registration.Agreements names that the account never accepted (created before it was required, or by the host), and one marked Reaccept whose earlier version it accepted.

func (*Engine) ApplyBootstrapManifest ¶

func (s *Engine) ApplyBootstrapManifest(ctx context.Context, manifest iam.BootstrapManifest, opts iam.BootstrapOptions, options ...ops.Option) (iam.BootstrapResult, error)

ApplyBootstrapManifest applies seed data and its StartupOnly receipt in one authority transaction, as a host operation. It never adopts an account through a username, an alias or an unverified contact, and never changes an existing account's identity or marks its contacts verified (see iam.BootstrapManifestUser). Role changes run the credential sweep.

func (*Engine) ApproveOAuthAuthorization ¶ added in v1.5.0

func (s *Engine) ApproveOAuthAuthorization(ctx context.Context, userID, sessionID, id string, consented bool) (string, error)

ApproveOAuthAuthorization answers a pending request for the signed-in user of sessionID: it issues a one-time authorization code and returns the client redirect carrying it. A request asking for a fresh sign-in (prompt=login, max_age) that this one does not meet is StepUpRequired, and stays pending for the retry.

func (*Engine) Authenticate ¶ added in v1.18.0

func (s *Engine) Authenticate(r *http.Request) (auth.Verified, error)

Authenticate is r's helpers/auth Verified request for AuthKit's own routes that admit every credential (SCIM): an access token for Config.Resource.ID, else this deployment's own credentials (verify.AuthenticateSession).

func (*Engine) AuthenticateClientAssertion ¶ added in v1.20.0

func (s *Engine) AuthenticateClientAssertion(ctx context.Context, client authflow.OAuthClient, assertion string) error

AuthenticateClientAssertion checks a private_key_jwt client's assertion: signed by its keys, iss and sub its id, aud this issuer or its token endpoint, at most five minutes to live, its jti spent once.

func (*Engine) AuthenticateResource ¶ added in v1.18.0

func (s *Engine) AuthenticateResource(r *http.Request) (auth.Verified, error)

AuthenticateResource is r's helpers/auth Verified request for an access token minted for Config.Resource.ID (resourceVerified).

func (*Engine) AuthorizeSCIM ¶ added in v1.12.0

func (s *Engine) AuthorizeSCIM(_ context.Context, accessToken, jkt string) error

AuthorizeSCIM accepts a client-credentials access token this deployment issued for its SCIM resource with scope scim:read, from a client still allowed it; jkt is the DPoP key the request proved, if any.

func (*Engine) Ban ¶

func (s *Engine) Ban(ctx context.Context, a auth.Identity, userID string, b iam.Ban, opts ...ops.Option) error

Ban bans an account under ACCT(root:users:ban) and revokes its sessions, device keys and every credential it issued, in one transaction. Nobody bans themselves, and the last usable owner of a group cannot be banned.

func (*Engine) BeginDeviceKeyEnrollment ¶

func (s *Engine) BeginDeviceKeyEnrollment(ctx context.Context, email, publicKey, label string) (authflow.DeviceKeyChallenge, error)

BeginDeviceKeyEnrollment sends an email proof and records the proposed key.

func (*Engine) BeginDeviceKeyLogin ¶

func (s *Engine) BeginDeviceKeyLogin(ctx context.Context, deviceKeyID string) (authflow.DeviceKeyChallenge, error)

BeginDeviceKeyLogin returns an indistinguishable challenge for active, revoked, and unknown ids.

func (*Engine) BeginOAuthAuthorization ¶ added in v1.5.0

func (s *Engine) BeginOAuthAuthorization(ctx context.Context, a authflow.OAuthAuthorization) (string, error)

BeginOAuthAuthorization stores a validated authorization request for its user and returns its id: a secret the SPA approves or declines it by.

func (*Engine) BeginPasskeyLogin ¶

func (s *Engine) BeginPasskeyLogin(ctx context.Context) (*protocol.CredentialAssertion, error)

BeginPasskeyLogin always issues a discoverable assertion with an empty allowCredentials list (AK2-PK-002): scoping it to a known identifier would leak account existence and credential ids to an unauthenticated caller. The asserted credential's user handle resolves the user at finish.

func (*Engine) BeginPasskeyRegistration ¶

func (s *Engine) BeginPasskeyRegistration(ctx context.Context, userID string) (*protocol.CredentialCreation, error)

BeginPasskeyRegistration starts adding a passkey to an already identified user. The same ceremony finishes as either FinishPasskeyRegistration (add) or FinishPasskeyReplacement (replace all).

func (*Engine) BeginPasskeyStepUp ¶ added in v1.1.0

func (s *Engine) BeginPasskeyStepUp(ctx context.Context, userID, sessionID string) (*protocol.CredentialAssertion, error)

BeginPasskeyStepUp starts an assertion by one of the account's passkeys, bound to the session.

func (*Engine) BeginSolanaStepUp ¶ added in v1.1.0

func (s *Engine) BeginSolanaStepUp(ctx context.Context, userID, sessionID, domain string) (siws.SignInInput, error)

BeginSolanaStepUp issues a SIWS challenge for the account's linked wallet, bound to the session.

func (*Engine) BeginTwoFactorEnrollment ¶

func (s *Engine) BeginTwoFactorEnrollment(ctx context.Context, userID string, enrollmentToken bool, sessionID string) (authflow.TwoFactorEnrollmentScope, error)

BeginTwoFactorEnrollment decides the enrollment scope for a caller. An enrollment-only token (issued at login when a factor is mandatory) may fill the FIRST factor only, and only while no session or factor exists — ErrTwoFAFactorExists otherwise. A full session may add further factors.

func (*Engine) Can ¶

func (s *Engine) Can(ctx context.Context, a auth.Identity, ref iam.GroupRef, perm iam.Perm) (bool, error)

Can reports whether a covers perm in the group ref addresses, live: a dead identity, an unknown group or an identity bound to another group is false, and an identity whose bound session was revoked is ErrSessionRevoked. The system is always true. An unregistered perm is ErrUnknownPermission.

func (*Engine) CheckPendingRegistrationConflict ¶

func (s *Engine) CheckPendingRegistrationConflict(ctx context.Context, email, username string) (bool, bool, error)

CheckPendingRegistrationConflict checks if email or username exists in users or pending registration cache. Returns (emailTaken, usernameTaken, error)

func (*Engine) CheckPhoneRegistrationConflict ¶

func (s *Engine) CheckPhoneRegistrationConflict(ctx context.Context, phone, username string) (bool, bool, error)

CheckPhoneRegistrationConflict checks if phone or username exists in users OR pending tables. Returns (phoneTaken, usernameTaken, error)

func (*Engine) CheckRecentSignIn ¶

func (s *Engine) CheckRecentSignIn(ctx context.Context, cl verify.Claims) error

CheckRecentSignIn is the sensitive-action gate, for AuthKit's own credential routes and verify.Sensitive alike: CheckSession, then a sign-in of the user's own token within authflow.SensitiveActionFreshAuthWindow, with a second factor when the account has one (checked live, so a token minted before enrollment cannot hide it). A stale sign-in is StepUpRequired; any other credential is forbidden.

func (*Engine) CheckSession ¶

func (s *Engine) CheckSession(ctx context.Context, cl verify.Claims) error

CheckSession is the session check (#412) for verified claims: the refresh session or device key the token was minted from is still active and its account usable. A user's token names one; so does this issuer's jwt-bearer resource token, the device key that signed its capability (#437). A token that names none, such as one the host minted, is refused too, since nothing proves it still stands. Every refusal is ErrSessionRevoked; any other credential (an API key, a 2FA-enrollment token, another resource token) is forbidden. Permission checks run the same query through the identity's session binding.

func (*Engine) CheckUserPassword ¶

func (s *Engine) CheckUserPassword(ctx context.Context, userID, pass string) error

CheckUserPassword is the error-returning form of VerifyUserPassword: nil on success, ErrPasswordResetRequired when the stored hash is flagged iam.HashLegacyResetRequired (no plaintext can verify; the user must reset), and a generic unauthorized error otherwise. Callers that need to route reset-required users (step-up, change-password) should use this form.

func (*Engine) CheckUsername ¶

func (s *Engine) CheckUsername(ctx context.Context, name string) error

CheckUsername reports whether a new account could take name: the username policy, then any claim on it (a canonical name, a live alias, a purged account's reservation, a pending registration), then NameAdmission. A claim answers ErrUsernameInUse and nothing about its owner.

func (*Engine) Close ¶

func (s *Engine) Close(ctx context.Context) error

Close stops what Start started and releases AuthKit-owned resources, including its schema-bound pool. ctx bounds stopping AuthKit's own River. Injected dependencies, including the host pool, a host River fleet, stores and keys, stay host-owned.

func (*Engine) CompleteExternalLogin ¶

func (s *Engine) CompleteExternalLogin(ctx context.Context, in authflow.ExternalLoginInput) (authflow.LoginOutcome, error)

CompleteExternalLogin resolves the identity to a user and signs it in. Resolution errors: ErrProviderAlreadyLinked, ErrProviderChangeRequiresUnlink, ErrAccountExistsLinkRequired, ErrRegistrationDisabled, ErrProviderLinkFailed, ErrUserCreationFailed. Session and MFA errors come from the shared login workflow.

func (*Engine) CompleteLoginChallenge ¶

func (s *Engine) CompleteLoginChallenge(ctx context.Context, in authflow.LoginChallengeInput) (authflow.LoginOutcome, error)

CompleteLoginChallenge gives one current first-factor grant one successful second-factor completion and commits its session while holding the account lock.

func (*Engine) Config ¶

func (s *Engine) Config() config.Config

Config is the normalized configuration the engine runs with.

func (*Engine) ConfirmAccountRecovery ¶

func (s *Engine) ConfirmAccountRecovery(ctx context.Context, token string) error

func (*Engine) ConfirmDeviceVerification ¶ added in v1.3.0

func (s *Engine) ConfirmDeviceVerification(ctx context.Context, in authflow.DeviceVerificationInput) (authflow.LoginOutcome, error)

ConfirmDeviceVerification checks the device code, makes the device known to the account and continues the sign-in: a session, or its second factor. ErrInvalidCode is a wrong code; ErrCodeExpired, no live one.

func (*Engine) ConfirmPasswordReset ¶

func (s *Engine) ConfirmPasswordReset(ctx context.Context, token, newPassword string) (string, error)

ConfirmPasswordReset verifies token and sets a new password.

func (*Engine) ConfirmVerification ¶

func (s *Engine) ConfirmVerification(ctx context.Context, in authflow.VerificationInput) (authflow.LoginOutcome, error)

ConfirmVerification is the shared registration/contact-verification workflow. Verification that authenticates a user returns the same MFA/session outcome as password and provider login; a contact mutation returns contact_changed.

func (*Engine) ConsumeOIDCResult ¶ added in v0.149.0

func (s *Engine) ConsumeOIDCResult(ctx context.Context, code string) (json.RawMessage, bool, error)

ConsumeOIDCResult trades a one-time code for its result, once.

func (*Engine) ConsumeOIDCState ¶

func (s *Engine) ConsumeOIDCState(ctx context.Context, state string) (oidcstate.StateData, bool, error)

ConsumeOIDCState claims a pending browser login once; concurrent callbacks cannot both win it.

func (*Engine) ContinueRefreshMFA ¶

func (s *Engine) ContinueRefreshMFA(ctx context.Context, userID, sessionID string) (authflow.LoginOutcome, error)

ContinueRefreshMFA is called only after validating the refresh credential. An old session must repeat a first factor before sensitive factor enrollment.

func (*Engine) CreateAPIKey ¶

func (s *Engine) CreateAPIKey(ctx context.Context, a auth.Identity, ref iam.GroupRef, k iam.NewAPIKey, opts ...ops.Option) (iam.APIKeyCreated, error)

CreateAPIKey issues a key holding role in ref: CAP(<p>:credentials:manage) plus COVER(role). Only a user or the system issues credentials. The token is returned once.

func (*Engine) CreateDirectoryUser ¶ added in v1.18.0

func (s *Engine) CreateDirectoryUser(ctx context.Context, t scim.Tenant, u scim.User) (scim.User, error)

CreateDirectoryUser creates u in the tenant (RFC 7644 §3.3). A user its token claims recorded becomes provisioned; one already provisioned, or a userName another holds, is 409 uniqueness.

func (*Engine) CreateGroup ¶

func (s *Engine) CreateGroup(ctx context.Context, ng iam.NewGroup, opts ...ops.Option) (iam.Group, error)

CreateGroup creates a group of a declared persona. ng.Owner, when set, must be a live account; it is seeded with the owner role. With ng.ID, creating an existing live group of the same persona returns it unchanged; a deleted group or another persona under that id is iam.ErrGroupConflict.

func (*Engine) CreateGroupOAuthClient ¶ added in v1.20.0

func (s *Engine) CreateGroupOAuthClient(ctx context.Context, who auth.Identity, ref iam.GroupRef, n iam.NewOAuthClient, opts ...ops.Option) (iam.OAuthClientCreated, error)

CreateGroupOAuthClient registers an OAuth client in ref under CAP <p>:credentials:manage. A client_secret_basic client's secret is returned this once; AuthKit keeps its hash.

func (*Engine) CreateGroupRole ¶ added in v1.19.0

func (s *Engine) CreateGroupRole(ctx context.Context, who auth.Identity, ref iam.GroupRef, n iam.NewGroupRole, opts ...ops.Option) (iam.GroupRole, error)

CreateGroupRole defines a custom role in ref: CAP(<p>:roles:manage) and COVER of every grant. A name the group already uses is iam.ErrRoleExists; past iam.MaxGroupRoles, iam.ErrRoleLimitReached.

func (*Engine) CreateInvitation ¶

func (s *Engine) CreateInvitation(ctx context.Context, a auth.Identity, ref iam.GroupRef, n iam.NewInvitation, opts ...ops.Option) (iam.InvitationCreated, error)

CreateInvitation creates an invite link (n.Email empty), or emails an invitation to n.Email. A link, and an email invitation carrying a role, need CAP(<p>:members:manage) plus COVER(role) in ref; a plain email invitation (no role) is issued in the root group and needs CAP(root:users:invite). Only a user or the system issues credentials. The code is returned once. ops.InTx applies to links only: an email is sent at once.

func (*Engine) CreateUser ¶

func (s *Engine) CreateUser(ctx context.Context, n iam.NewUser, opts ...ops.Option) (iam.User, error)

CreateUser creates a native account: a host operation.

func (*Engine) DeclareRemoteApplications ¶ added in v1.18.0

func (s *Engine) DeclareRemoteApplications(ctx context.Context, ref iam.GroupRef, apps []iam.RemoteApplication, opts ...ops.Option) error

DeclareRemoteApplications makes apps the group ref's declared remote applications (Issuer, JWKSURI or PublicKeys, Enabled and Role are read): each is registered by the system in ref with Role, its role there (none when zero), and the applications this deployment declared in ref before and no longer lists are disabled.

func (*Engine) DeclineOAuthAuthorization ¶ added in v1.5.0

func (s *Engine) DeclineOAuthAuthorization(ctx context.Context, id, code string) (string, error)

DeclineOAuthAuthorization ends a pending request without a code and returns the client redirect carrying the error: access_denied when the user refused, login_required or interaction_required when prompt=none could not be met without the user.

func (*Engine) DeleteDirectoryUser ¶ added in v1.18.0

func (s *Engine) DeleteDirectoryUser(ctx context.Context, t scim.Tenant, id string) error

DeleteDirectoryUser deletes the tenant's user id and everything kept of it (RFC 7644 §3.6).

func (*Engine) DeleteGroup ¶

func (s *Engine) DeleteGroup(ctx context.Context, ref iam.GroupRef, opts ...ops.Option) error

DeleteGroup soft-deletes a group: it stops resolving and granting, while its rows stay until PurgeGroup. Deleting a deleted group is a no-op; the root group cannot be deleted.

func (*Engine) DeleteGroupOAuthClient ¶ added in v1.20.0

func (s *Engine) DeleteGroupOAuthClient(ctx context.Context, who auth.Identity, ref iam.GroupRef, clientID string, opts ...ops.Option) error

DeleteGroupOAuthClient deletes a client of ref and every consent to it: its tokens are refused at their next use.

func (*Engine) DeleteGroupRole ¶ added in v1.19.0

func (s *Engine) DeleteGroupRole(ctx context.Context, who auth.Identity, ref iam.GroupRef, role iam.Role, opts ...ops.Option) error

DeleteGroupRole deletes a custom role of ref after taking it from every holder: members, applications and remote users lose it, and the API keys and invitations carrying it are revoked, under UpdateGroupRole's authority over its current grants. Deleting a role the group does not define is a no-op.

func (*Engine) DeletePasskey ¶

func (s *Engine) DeletePasskey(ctx context.Context, userID, id string) error

DeletePasskey deletes the account's passkey id; ErrPasskeyNotFound when the account holds no such passkey.

func (*Engine) DeletePendingPhoneRegistrationByPhone ¶

func (s *Engine) DeletePendingPhoneRegistrationByPhone(ctx context.Context, phone string) error

DeletePendingPhoneRegistrationByPhone removes a pending phone registration for the given phone, if one exists. No-op when none exists.

func (*Engine) DeletePendingRegistrationByEmail ¶

func (s *Engine) DeletePendingRegistrationByEmail(ctx context.Context, email string) error

DeletePendingRegistrationByEmail removes a pending email registration for the given email, if one exists. No-op when none exists.

func (*Engine) DeleteRemoteApplication ¶

func (s *Engine) DeleteRemoteApplication(ctx context.Context, who auth.Identity, ref iam.GroupRef, id string, opts ...ops.Option) error

DeleteRemoteApplication deletes the application id that group ref controls; an id unknown in the group is iam.ErrRemoteApplicationNotFound. Any identity but the system needs the same authority as re-keying it, and never deletes a system-registered application.

func (*Engine) DeleteUsers ¶

func (s *Engine) DeleteUsers(ctx context.Context, a auth.Identity, ids []string, opts ...ops.Option) ([]iam.OpResult, error)

DeleteUsers soft-deletes accounts under ACCT(root:users:delete), starting the fixed recovery window; an account may delete itself, and only then can signing in undo it. Sessions, device keys and every credential the account issued are revoked. A repeat call keeps the original window. Per-item results; the error is a whole-call failure.

func (*Engine) DeviceKeys ¶

func (s *Engine) DeviceKeys(ctx context.Context, userID string) ([]iam.DeviceKey, error)

DeviceKeys returns the account's device keys in enrollment order, revoked ones included. ErrDeviceKeysDisabled without Config.DeviceKeys.Enabled.

func (*Engine) DirectoryUser ¶ added in v1.18.0

func (s *Engine) DirectoryUser(ctx context.Context, t scim.Tenant, id string) (scim.User, error)

DirectoryUser is the tenant's provisioned user id.

func (*Engine) DirectoryUsers ¶ added in v1.18.0

func (s *Engine) DirectoryUsers(ctx context.Context, t scim.Tenant, filter string, startIndex, count int) (scim.ListResponse[scim.User], error)

DirectoryUsers answers a query of the tenant's provisioned users: those filter matches (scim.ParseFilter), or all, in id order, from the 1-based startIndex (RFC 7644 §3.4.2).

func (*Engine) Disable2FA ¶ added in v0.149.0

func (s *Engine) Disable2FA(ctx context.Context, userID string) error

Disable2FA removes every second factor of the account, and the roles that require MFA it held.

func (*Engine) Disable2FAFactor ¶ added in v0.149.0

func (s *Engine) Disable2FAFactor(ctx context.Context, userID, factorID string) error

Disable2FAFactor removes one second factor; the last one disables MFA as Disable2FA does, and a removed default passes to another factor. A factor the account does not hold is not_found.

func (*Engine) EffectivePermissions ¶

func (s *Engine) EffectivePermissions(ctx context.Context, a auth.Identity, refs []iam.GroupRef) (map[string][]iam.Perm, error)

EffectivePermissions returns a's effective grant patterns per group id, for clients that gate UI on permission strings (glob-matching with iam.Perm.Matches). Globs are returned verbatim; a ceiling narrows them. Unknown and deleted groups and groups granting nothing are absent; a dead identity has none, and one whose bound session was revoked is ErrSessionRevoked. The system gets each persona's owner grant. A user's grants on many groups are read together, not group by group.

func (*Engine) EmailAvailable ¶ added in v0.149.0

func (s *Engine) EmailAvailable() bool

EmailAvailable reports whether email flows are offered: Deps.Email is set and its latest health check, if any, passed.

func (*Engine) EmailHealth ¶ added in v0.149.0

func (s *Engine) EmailHealth() (time.Time, error)

EmailHealth is the latest Deps.Email health verdict and when that check started; a zero time means no check has run.

func (*Engine) EndOAuthSession ¶ added in v1.5.0

func (s *Engine) EndOAuthSession(ctx context.Context, in authflow.OAuthEndSession) (string, error)

EndOAuthSession ends the sign-in an ID token names (OIDC RP-Initiated Logout) and returns where to send the browser: the client's registered post-logout redirect, with state, or "" when there is none.

func (*Engine) EnrollTwoFactor ¶

func (s *Engine) EnrollTwoFactor(ctx context.Context, in authflow.TwoFactorEnrollInput) (authflow.TwoFactorEnrollOutcome, error)

EnrollTwoFactor runs the enrollment decision tree. Input problems: ErrInvalidTwoFAMethod, ErrPhoneNumberRequired, ErrPhoneNumberMustBeE164, ErrInvalidCode, ErrCodeExpired, ErrTwoFAFactorExists; engine failures carry a stage prefix wrapping ErrSMSUnavailable / ErrTwoFASetupCodeSendFailed (with the delivery sentinel) / ErrTwoFAEnableFailed.

func (*Engine) EnsureUserRole ¶

func (s *Engine) EnsureUserRole(ctx context.Context, ref iam.GroupRef, u iam.UserRef, role iam.Role, opts ...ops.Option) (iam.User, error)

EnsureUserRole makes the account u names hold role in ref, under the system, and is idempotent on every boot. ops.InTx runs it in the host's transaction.

u is an id, an email or a phone; a username proves nothing and is refused. With no account for the contact, one is created without credentials and with the contact unverified: only a proof of that contact can ever sign in, and that proof verifies it. An existing account is used when u is its id or the contact is verified on it; one that already holds role, the group's owner role, or a role covering role is left as it is (a re-run, including on the unverified account an earlier call created). Any other account is refused with ErrContactNotVerified: a pre-registered account is never adopted, and nothing here marks a contact verified.

func (*Engine) ExchangeOAuthCode ¶ added in v1.5.0

func (s *Engine) ExchangeOAuthCode(ctx context.Context, in authflow.OAuthCodeExchange) (authflow.OAuthTokens, error)

ExchangeOAuthCode redeems an authorization code once (RFC 6749 §4.1.3, RFC 7636 §4.6): the client, redirect URI and PKCE verifier must match the approval, and the user's sign-in must still stand.

func (*Engine) ExchangeOAuthToken ¶ added in v1.5.0

func (s *Engine) ExchangeOAuthToken(ctx context.Context, in authflow.OAuthTokenExchange) (authflow.OAuthTokens, error)

ExchangeOAuthToken is RFC 8693 token exchange: the user's own AuthKit access token (a sign-in of this deployment) for an access token to one of the client's resources, standing on the same sign-in. With no actor_token it is impersonation (RFC 8693 §1.1): the token carries no act claim.

func (*Engine) ExchangeRefreshToken ¶

func (s *Engine) ExchangeRefreshToken(ctx context.Context, refreshToken string, ua string, ip net.IP) (userID string, session authflow.IssuedSession, err error)

ExchangeRefreshToken rotates a refresh token: the session's user, and its new access and refresh tokens.

func (*Engine) FinishDeviceKeyEnrollment ¶

func (s *Engine) FinishDeviceKeyEnrollment(ctx context.Context, enrollmentID, code, signature, secondFactor string) (authflow.DeviceKeyAuthResult, error)

FinishDeviceKeyEnrollment consumes both proofs, enrolls the key, and mints no refresh session. An existing account with a usable second factor must also present one independent of the emailed code (secondFactor: a TOTP or SMS code, or a backup code) — email possession alone never enrolls a standing credential on an MFA-protected account (#293, P1). A revoked key, or one bound to another account, is refused before any second factor is asked for, and a backup code is spent only by the enrollment that commits (R4).

func (*Engine) FinishDeviceKeyLogin ¶

func (s *Engine) FinishDeviceKeyLogin(ctx context.Context, challengeID, signature string) (authflow.DeviceKeyAuthResult, error)

FinishDeviceKeyLogin atomically consumes a challenge and issues only a short access token.

func (*Engine) FinishPasskeyLogin ¶

func (s *Engine) FinishPasskeyLogin(ctx context.Context, response []byte, userAgent string, ip net.IP) (authflow.LoginOutcome, error)

FinishPasskeyLogin composes the verification primitive with the browser session issuance; it is the only passkey path that mints a session.

func (*Engine) FinishPasskeyRegistration ¶

func (s *Engine) FinishPasskeyRegistration(ctx context.Context, userID string, response []byte) (iam.Passkey, error)

func (*Engine) GenerateSIWSChallenge ¶

func (s *Engine) GenerateSIWSChallenge(ctx context.Context, domain, address, username string) (siws.SignInInput, error)

GenerateSIWSChallenge creates a new SIWS challenge for the given address. The challenge must be verified within 15 minutes.

func (*Engine) Get2FASettings ¶

func (s *Engine) Get2FASettings(ctx context.Context, userID string) (*authflow.TwoFactorSettings, error)

Get2FASettings retrieves a user's 2FA settings

func (*Engine) GetPendingPhoneRegistrationByPhone ¶

func (s *Engine) GetPendingPhoneRegistrationByPhone(ctx context.Context, phone string) (*authflow.PendingRegistration, error)

GetPendingPhoneRegistrationByPhone looks up a pending phone registration by phone number. (PendingRegistration.Email carries the phone for phone registrations, preserving prior behavior.)

func (*Engine) GetPendingRegistrationByEmail ¶

func (s *Engine) GetPendingRegistrationByEmail(ctx context.Context, email string) (*authflow.PendingRegistration, error)

GetPendingRegistrationByEmail looks up a pending registration by email.

func (*Engine) GetProviderLinkByIssuer ¶

func (s *Engine) GetProviderLinkByIssuer(ctx context.Context, issuer, subject string) (string, *string, error)

Issuer-based provider link helpers (preferred)

func (*Engine) GetRemoteApplication ¶

func (s *Engine) GetRemoteApplication(ctx context.Context, issuer string) (*iam.RemoteApplication, error)

GetRemoteApplication returns a remote_application by OIDC issuer URL.

func (*Engine) Group ¶

func (s *Engine) Group(ctx context.Context, ref iam.GroupRef) (iam.Group, error)

Group reads one group, a soft-deleted one included, with DeletedAt set. Absence is ErrGroupNotFound.

func (*Engine) GroupName ¶ added in v1.20.0

func (s *Engine) GroupName(ctx context.Context, groupID string) *string

GroupName is groupName for the HTTP layer.

func (*Engine) GroupOAuthClient ¶ added in v1.20.0

func (s *Engine) GroupOAuthClient(ctx context.Context, ref iam.GroupRef, clientID string) (iam.OAuthClient, error)

GroupOAuthClient returns one of ref's clients.

func (*Engine) GroupOAuthClients ¶ added in v1.20.0

func (s *Engine) GroupOAuthClients(ctx context.Context, ref iam.GroupRef) ([]iam.OAuthClient, error)

GroupOAuthClients returns ref's clients, oldest first.

func (*Engine) GroupRole ¶ added in v1.19.0

func (s *Engine) GroupRole(ctx context.Context, ref iam.GroupRef, role iam.Role) (iam.GroupRole, error)

GroupRole returns one role assignable in the group, iam.ErrRoleNotFound for any other.

func (*Engine) GroupRoles ¶

func (s *Engine) GroupRoles(ctx context.Context, ref iam.GroupRef, subjects []iam.Subject) (map[iam.Subject]iam.Role, error)

GroupRoles returns the direct role of each subject that holds one in the group. Roles no longer defined (catalog or custom) confer nothing and are omitted.

func (*Engine) Groups ¶

func (s *Engine) Groups(ctx context.Context, ids []string) (map[string]iam.Group, error)

Groups reads many groups by id, soft-deleted ones included. Unknown ids are absent.

func (*Engine) HasPassword ¶

func (s *Engine) HasPassword(ctx context.Context, userID string) (bool, error)

HasPassword reports whether the user has a local password set.

func (*Engine) HasProviderLink ¶

func (s *Engine) HasProviderLink(ctx context.Context, userID, issuer, providerSlug string) (bool, error)

HasProviderLink reports whether userID holds a link to subject-issuer under providerSlug — the step-up gate's "is this the user's own provider" check.

func (*Engine) HasUsableMFA ¶

func (s *Engine) HasUsableMFA(ctx context.Context, userID string) (bool, error)

HasUsableMFA reports whether the account has 2FA enabled with a factor.

func (*Engine) ImportSolanaLinks ¶

func (s *Engine) ImportSolanaLinks(ctx context.Context, rows []iam.ImportSolanaLink, opts ...ops.Option) (iam.ImportSolanaLinksResult, error)

ImportSolanaLinks imports legacy wallet claims as a host operation, one outcome per row. It never verifies a wallet: only a successful SIWS proof promotes an imported claim.

func (*Engine) ImportUsers ¶

func (s *Engine) ImportUsers(ctx context.Context, rows []iam.ImportUser, opts iam.ImportOptions, options ...ops.Option) (iam.ImportResult, error)

ImportUsers bulk-imports accounts (target: 500k+ rows) as a host operation. Rows are validated in Go, then each chunk runs in one transaction: find the accounts its rows name, insert the rest with one multi-row INSERT, store their password hashes, and merge where asked. A row sharing an identifier with an earlier row of the batch is that row's account. A row whose identifiers name two accounts is rejected. Matching is never proof: only an id binds a row for a merge. Addresses import unverified.

func (*Engine) JWKS ¶

func (s *Engine) JWKS() keys.JWKS

JWKS publishes the CURRENT public keys, read from the KeySource on every call, so a rotation shows on the very next request (#238).

func (*Engine) KnownPermission ¶

func (s *Engine) KnownPermission(perm iam.Perm) bool

KnownPermission reports whether perm is registered in a persona catalog.

func (*Engine) LinkProvider ¶

func (s *Engine) LinkProvider(ctx context.Context, userID string, l iam.ProviderLink, opts ...ops.Option) error

LinkProvider links an external identity to a live account as a login method, as a host operation. Browser flows use ExternalLoginInput.Link, whose initiating session is checked at commit.

func (*Engine) LinkSolanaWallet ¶

func (s *Engine) LinkSolanaWallet(ctx context.Context, userID string, output siws.SignInOutput) (authflow.SolanaLinkedAccount, error)

LinkSolanaWallet links the Solana wallet a SIWS output proves to an existing account and returns the account's linked wallet.

func (*Engine) ListAPIKeys ¶

func (s *Engine) ListAPIKeys(ctx context.Context, ref iam.GroupRef, p iam.PageRequest) (iam.ListPage[iam.APIKey], error)

ListAPIKeys lists the group's keys, newest first, including revoked and expired ones (terminal keys are purged after 90 days). Never the secret.

func (*Engine) ListGroupMembers ¶

func (s *Engine) ListGroupMembers(ctx context.Context, ref iam.GroupRef, q iam.MemberQuery) (iam.ListPage[iam.GroupMember], error)

ListGroupMembers lists the subjects holding a role in a live group, ordered by subject kind, then id.

func (*Engine) ListGroupRoles ¶ added in v1.19.0

func (s *Engine) ListGroupRoles(ctx context.Context, ref iam.GroupRef) ([]iam.GroupRole, error)

ListGroupRoles returns the roles assignable in the group: those its persona declares, then the custom roles it defines, by name.

func (*Engine) ListGroups ¶

func (s *Engine) ListGroups(ctx context.Context, q iam.GroupQuery) (iam.ListPage[iam.Group], error)

ListGroups lists groups oldest first. The root group is never listed. q.Ownerless keeps live groups with no owner that counts toward the last-owner rule (requireRemainingOwner).

func (*Engine) ListInvitations ¶

func (s *Engine) ListInvitations(ctx context.Context, ref iam.GroupRef, p iam.PageRequest) (iam.ListPage[iam.Invitation], error)

ListInvitations lists the group's invitations, links and email invitations, newest first, active or not; never a code. Root's include the plain email invitations.

func (*Engine) ListMemberships ¶

func (s *Engine) ListMemberships(ctx context.Context, subject iam.Subject, p iam.PageRequest) (iam.ListPage[iam.Membership], error)

ListMemberships lists the live groups a subject holds a role in, ordered by persona, then id.

func (*Engine) ListPasskeys ¶

func (s *Engine) ListPasskeys(ctx context.Context, userID string) ([]iam.Passkey, error)

func (*Engine) ListRemoteApplications ¶

func (s *Engine) ListRemoteApplications(ctx context.Context, ref iam.GroupRef, page iam.PageRequest) (iam.ListPage[iam.RemoteApplication], error)

ListRemoteApplications lists the applications group ref controls, newest first, with their roles.

func (*Engine) ListSessionEvents ¶

func (s *Engine) ListSessionEvents(ctx context.Context, userID string, q iam.SessionEventQuery) (iam.ListPage[iam.SessionEvent], error)

SessionEvents pages an account's session history, newest first.

func (*Engine) ListUsers ¶

func (s *Engine) ListUsers(ctx context.Context, q iam.UserQuery) (iam.ListPage[iam.UserEntry], error)

ListUsers is the user directory: search, status, root-role and entitlement filters, keyset-paged. NULL sort values come last in either direction. Each entry carries its root role and, with q.WithEntitlements, its entitlements; q.Total counts every match.

func (*Engine) LogSessionFailed ¶

func (s *Engine) LogSessionFailed(ctx context.Context, userID string, sessionID string, reason *string, ip *string, ua *string)

LogSessionFailed records a failed session event for a user (best-effort).

func (*Engine) MarkSessionAuthenticated ¶

func (s *Engine) MarkSessionAuthenticated(ctx context.Context, userID, sessionID string) error

func (*Engine) MarkSessionAuthenticatedWithMethods ¶

func (s *Engine) MarkSessionAuthenticatedWithMethods(ctx context.Context, userID, sessionID string, authMethods []string) error

MarkSessionAuthenticatedWithMethods refreshes the session's sensitive-action auth window and records how the user re-proved identity.

func (*Engine) MintAccessToken ¶

func (s *Engine) MintAccessToken(ctx context.Context, userID string, o iam.AccessTokenOptions, opts ...ops.Option) (iam.Token, error)

MintAccessToken mints an access token for a live account outside any login flow; a host operation. o.Claims naming one of AuthKit's own claims is invalid_request (param claims.<name>); o.SessionID becomes sid.

func (*Engine) MintSessionAccessToken ¶

func (s *Engine) MintSessionAccessToken(ctx context.Context, userID, sessionID string) (string, time.Time, error)

MintSessionAccessToken re-mints the access token of the caller's own session (step-up and provider-link responses).

func (*Engine) NewAuthenticator ¶

func (s *Engine) NewAuthenticator(audiences []string, opts ...verify.VerifierOption) (*Authenticator, error)

NewAuthenticator builds an authenticator for a host resource server in this process: this deployment's API keys and tokens, for audiences. DPoP proofs are spent in this deployment's replay store and checked against the issuer's origin unless opts say otherwise (verify.WithPublicURL). It applies no 2FA policy.

func (*Engine) OAuthAuthorization ¶ added in v1.5.0

func (s *Engine) OAuthAuthorization(ctx context.Context, id string) (authflow.OAuthAuthorization, error)

OAuthAuthorization reads a pending authorization request.

func (*Engine) OAuthClient ¶ added in v1.20.0

func (s *Engine) OAuthClient(ctx context.Context, clientID string) (authflow.OAuthClient, bool, error)

OAuthClient resolves clientID for the authorization and resource servers: a declared client, else a live group client. ok is false for neither.

func (*Engine) OAuthClientCredentials ¶ added in v1.5.0

func (s *Engine) OAuthClientCredentials(ctx context.Context, in authflow.OAuthClientCredentials) (authflow.OAuthTokens, error)

OAuthClientCredentials mints a client's own access token: sub is its client_id and its permissions are its grants within the resource's ceiling.

func (*Engine) OAuthClientOrigin ¶ added in v1.20.0

func (s *Engine) OAuthClientOrigin(ctx context.Context, origin string) (bool, error)

OAuthClientOrigin reports whether a live group client redirects to origin, so a browser client there may call the token endpoint.

func (*Engine) OAuthConsents ¶ added in v1.20.0

func (s *Engine) OAuthConsents(ctx context.Context, userID string) ([]iam.OAuthConsent, error)

OAuthConsents lists userID's consents, newest change first.

func (*Engine) OAuthJWTBearer ¶ added in v1.10.0

func (s *Engine) OAuthJWTBearer(ctx context.Context, in authflow.OAuthJWTBearer) (authflow.OAuthTokens, error)

OAuthJWTBearer redeems a workload's assertion and the capability it carries for an access token to the capability's resource: for its user, bound to the workload key, carrying its operations (as the grant authorizer narrows them) until it expires. Nothing is spent until the token is minted, so a failure may be retried with the same capability.

func (*Engine) OAuthRemoteAssertion ¶ added in v1.18.0

func (s *Engine) OAuthRemoteAssertion(ctx context.Context, in authflow.OAuthJWTBearer) (authflow.OAuthTokens, error)

OAuthRemoteAssertion is the RFC 7523 §2.1 JWT-bearer grant for a trusted issuer's backend, with no authorization server of its own: it signs a short assertion with its registered remote application's key (iss its issuer, sub its user, aud the token endpoint, a jti spent once), and its frontend redeems it for an access token to Config.Resource.ID acting for that user in the application's group. The token holds no permissions; its client_id is the application's issuer, the namespace of its sub. A DPoP proof binds it, as the frontend chooses.

func (*Engine) OAuthUserInfo ¶ added in v1.5.0

func (s *Engine) OAuthUserInfo(ctx context.Context, accessToken, jkt string) (map[string]any, error)

OAuthUserInfo answers the userinfo endpoint (OIDC Core §5.3) for one of this server's access tokens granted the openid scope. jkt is the request's proven DPoP key: a DPoP-bound token needs its own, and a bearer token none.

func (*Engine) PasskeysEnabled ¶

func (s *Engine) PasskeysEnabled() bool

PasskeysEnabled reports whether passkey (WebAuthn) support is configured. Passkeys require a Relying Party ID (PasskeyConfig.RPID); without it every WebAuthn ceremony fails closed (the origin must match the RPID). The HTTP transport uses this to skip mounting the /passkeys/* routes entirely rather than exposing endpoints that can only error.

func (*Engine) PasswordLogin ¶

func (s *Engine) PasswordLogin(ctx context.Context, in authflow.PasswordLoginInput) (authflow.LoginOutcome, error)

PasswordLogin runs the whole password-login decision tree. It returns an error only when the engine itself failed (a send, the challenge store, the session insert — each prefixed with its stage and, for sends, the delivery sentinel); every policy result is a LoginOutcome.

func (*Engine) PasswordlessLogin ¶

func (s *Engine) PasswordlessLogin(ctx context.Context, in authflow.PasswordlessLoginInput) (authflow.LoginOutcome, error)

func (*Engine) PatchDirectoryUser ¶ added in v1.18.0

func (s *Engine) PatchDirectoryUser(ctx context.Context, t scim.Tenant, id string, req scim.PatchRequest) (scim.User, error)

PatchDirectoryUser applies req to the tenant's user id (RFC 7644 §3.5.2), all operations or none.

func (*Engine) PatchPublicMetadata ¶ added in v1.2.0

func (s *Engine) PatchPublicMetadata(ctx context.Context, a auth.Identity, userID string, patch map[string]any, opts ...ops.Option) error

PatchPublicMetadata applies patch to the account's public metadata as an RFC 7396 JSON Merge Patch under ACCT(root:users:manage), never on oneself: objects merge recursively, a nil value deletes its key, and any other value (arrays included) replaces the one it names.

func (*Engine) Permission ¶

func (s *Engine) Permission(text string) (iam.Perm, error)

Permission resolves a registered concrete permission.

func (*Engine) PermissionGroupSchema ¶

func (s *Engine) PermissionGroupSchema() *rbac.Schema

PermissionGroupSchema returns the compiled Config.Roles.

func (*Engine) Persona ¶

func (s *Engine) Persona(name string) (iam.Persona, error)

Persona resolves a persona name declared in Config.Roles (root always is).

func (*Engine) ProviderSlugs ¶

func (s *Engine) ProviderSlugs(ctx context.Context, userID string) ([]string, error)

ProviderSlugs returns the distinct provider slugs linked to userID.

func (*Engine) ProvisioningTargets ¶ added in v1.12.0

func (s *Engine) ProvisioningTargets(ctx context.Context) ([]iam.ProvisioningTarget, error)

ProvisioningTargets reports each configured target's delivery.

func (*Engine) PublicKeysByKID ¶

func (s *Engine) PublicKeysByKID() map[string]crypto.PublicKey

PublicKeysByKID returns the CURRENT public keys indexed by key ID, read fresh from the KeySource on every call (#238).

func (*Engine) PublicNativeUserRegistrationEnabled ¶

func (s *Engine) PublicNativeUserRegistrationEnabled() bool

PublicNativeUserRegistrationEnabled reports whether public native-user self-registration / auto-registration is allowed.

func (*Engine) PublicUsers ¶

func (s *Engine) PublicUsers(ctx context.Context, ids []string) (map[string]iam.PublicUser, error)

PublicUsers returns what others may see of ids. A deleted account is a tombstone; a banned one is returned normally (a ban is an access decision, not a visibility one); unknown ids are absent.

func (*Engine) PurgeGroup ¶

func (s *Engine) PurgeGroup(ctx context.Context, ref iam.GroupRef, opts ...ops.Option) error

PurgeGroup permanently deletes a group, live or soft-deleted, with every role, key and link in it. Purging an unknown group is a no-op.

func (*Engine) PurgeUsers ¶

func (s *Engine) PurgeUsers(ctx context.Context, ids []string, opts ...ops.Option) ([]iam.OpResult, error)

PurgeUsers closes the recovery window of accounts now, soft-deleting live ones first: a host operation. The account row goes once the host deletion callbacks complete, exactly as at the end of the window.

func (*Engine) PutOIDCResult ¶ added in v0.149.0

func (s *Engine) PutOIDCResult(ctx context.Context, code string, result json.RawMessage) error

PutOIDCResult keeps a browser OIDC result for its one-time code; the key is the code's hash, so the store never holds a usable code.

func (*Engine) PutOIDCState ¶

func (s *Engine) PutOIDCState(ctx context.Context, state string, data oidcstate.StateData) error

PutOIDCState records a pending browser login for the provider callback.

func (*Engine) RecordAgreements ¶ added in v1.20.0

func (s *Engine) RecordAgreements(ctx context.Context, userID string, refs []iam.AgreementRef, channel iam.AgreementChannel, ip, userAgent string) error

RecordAgreements is AcceptAgreements on channel, with the client that gave it.

func (*Engine) RecordFailedDeviceKeyEnrollment ¶

func (s *Engine) RecordFailedDeviceKeyEnrollment(ctx context.Context, enrollmentID string)

RecordFailedDeviceKeyEnrollment bounds online guessing without consuming a valid ceremony on one typo.

func (*Engine) RecordRemoteUserClaims ¶ added in v1.18.0

func (s *Engine) RecordRemoteUserClaims(ctx context.Context, groupID, issuer, subject string, c RemoteUserClaims) error

RecordRemoteUserClaims records a verified token's contact claims for the group's user of issuer known by subject: a new user's at once; a held one's only when c.UpdatedAt is after what it holds and something changed, so a token that repeats them writes nothing. An email counts only when verified; a claim that is empty or too long is absent and keeps the held value.

func (*Engine) RedeemInvitation ¶

func (s *Engine) RedeemInvitation(ctx context.Context, a auth.Identity, code string) (authflow.InviteRedemption, error)

RedeemInvitation redeems code for the signed-in user a: a link must be live (not revoked, expired or used) and its issuer live, and the redeemer live. The role is assigned in the same transaction and the link consumed. Idempotent: a redeemer already holding the role succeeds without using it. code may also be a role-carrying account invitation (an add by email): only the account that has verified the invited address accepts it.

func (*Engine) RefreshOAuthTokens ¶ added in v1.5.0

func (s *Engine) RefreshOAuthTokens(ctx context.Context, in authflow.OAuthRefresh) (authflow.OAuthTokens, error)

RefreshOAuthTokens redeems a refresh token (RFC 6749 §6) once: it rotates the family and mints fresh tokens with live permissions while the sign-in stands. A replayed token revokes the family.

func (*Engine) RegenerateBackupCodes ¶

func (s *Engine) RegenerateBackupCodes(ctx context.Context, userID string) ([]string, error)

RegenerateBackupCodes generates new backup codes for a user (invalidating old ones). Returns the plaintext codes (caller must show these to user ONCE).

func (*Engine) Register ¶

func (s *Engine) Register(ctx context.Context, in authflow.RegisterInput) (authflow.RegisterOutcome, error)

Register runs the registration decision tree. Input problems come back as the validation errors (ValidationErrorCode) and the sentinels ErrInvalidIdentifier / ErrEmailInUse / ErrPhoneInUse / ErrUsernameInUse / ErrRegistrationDisabled / ErrEmailUnavailable / ErrSMSUnavailable; engine failures carry a stage prefix and, for sends, the delivery sentinel.

func (*Engine) RegistrationVerificationEnabled ¶

func (s *Engine) RegistrationVerificationEnabled() bool

func (*Engine) RelabelDeviceKey ¶ added in v0.149.0

func (s *Engine) RelabelDeviceKey(ctx context.Context, userID, id, label string) (iam.DeviceKey, error)

RelabelDeviceKey sets the label of the account's live key id (empty clears it); not_found when the account holds no such live key.

func (*Engine) RemoteApplication ¶

func (s *Engine) RemoteApplication(ctx context.Context, ref iam.AppRef) (iam.RemoteApplication, error)

RemoteApplication is the management read of an application, by id or by issuer, disabled or in a retired group included, with its role and the permissions it confers now.

func (*Engine) RemoteInvitations ¶ added in v1.18.0

func (s *Engine) RemoteInvitations(ctx context.Context, v auth.Verified) ([]iam.Invitation, error)

RemoteInvitations are the email invitations with a role pending in the group v's issuer is trusted by, for v's verified email. A credential that is no trusted issuer's user with a verified email has none.

func (*Engine) RemoteUser ¶ added in v1.18.0

func (s *Engine) RemoteUser(ctx context.Context, groupID, issuer, subject string) (RemoteUser, error)

RemoteUser is the group's user of issuer known by subject, provisioned or recorded from claims; iam.ErrUserNotFound when there is none.

func (*Engine) RemoteUserInfo ¶ added in v1.18.0

func (s *Engine) RemoteUserInfo(ctx context.Context, groupID, issuer string, subjects []string) (map[string]userinfo.User, error)

RemoteUserInfo returns the active users among subjects of the group's directory of issuer, keyed by subject; an inactive or unknown one is absent.

func (*Engine) RemoteUserRoles ¶ added in v1.18.0

func (s *Engine) RemoteUserRoles(ctx context.Context, ref iam.GroupRef) ([]iam.RemoteUserRole, error)

RemoteUserRoles are the roles trusted issuers' users hold in the group ref, oldest first.

func (*Engine) RemoveGroupMember ¶

func (s *Engine) RemoveGroupMember(ctx context.Context, a auth.Identity, ref iam.GroupRef, subject iam.Subject, opts ...ops.Option) error

RemoveGroupMember strips subject's role in ref: CAP by subject kind, COVER of the role it holds (none for a removed role), then the last-owner check. A non-member is a no-op, as is a subject holding another role than ops.IfRole names.

func (*Engine) RemovePhone ¶ added in v0.149.0

func (s *Engine) RemovePhone(ctx context.Context, a auth.Identity, userID string) error

RemovePhone clears the account's phone number under ACCT(root:users:manage), the account's own included. It is refused (ErrCannotRemoveLastContact) unless a proven email remains, so the account keeps an address to sign in and recover with, and an MFA holder keeps a proven contact. An account without a phone is unchanged.

func (*Engine) RemoveRemoteUserRole ¶ added in v1.18.0

func (s *Engine) RemoveRemoteUserRole(ctx context.Context, who auth.Identity, ref iam.GroupRef, remoteUserID string, opts ...ops.Option) error

RemoveRemoteUserRole ends the role a trusted issuer's user holds in the group ref. who needs <persona>:members:manage there and coverage of the role; iam.ErrUserNotFound when the user holds none.

func (*Engine) RenamePasskey ¶

func (s *Engine) RenamePasskey(ctx context.Context, userID, id, label string) error

RenamePasskey sets the label of the account's live passkey id (empty clears it); ErrPasskeyNotFound when the account holds no such passkey.

func (*Engine) ReplaceDirectoryUser ¶ added in v1.18.0

func (s *Engine) ReplaceDirectoryUser(ctx context.Context, t scim.Tenant, id string, u scim.User) (scim.User, error)

ReplaceDirectoryUser replaces the tenant's user id with u (RFC 7644 §3.5.1): what u omits is cleared, id and meta are ignored.

func (*Engine) RequestEmailChange ¶

func (s *Engine) RequestEmailChange(ctx context.Context, userID, newEmail string) error

RequestEmailChange initiates an email change by sending a verification code to the new email. The current email is NOT changed until the user confirms it (ConfirmVerification). The old address is not notified by AuthKit (only a security log line); a host that wants that notification sends it itself.

func (*Engine) RequestEmailVerification ¶

func (s *Engine) RequestEmailVerification(ctx context.Context, email string, ttl time.Duration) error

RequestEmailVerification sends a verification code to an account or pending registration whose address is unproven. An unknown or already verified address gets the same nil, so the answer reveals neither.

func (*Engine) RequestPasswordReset ¶

func (s *Engine) RequestPasswordReset(ctx context.Context, email string, ttl time.Duration, ip *string, ua *string) error

RequestPasswordReset creates a password reset token and dispatches a reset link via email. Returns nil for unknown emails to prevent user enumeration (202-like behavior).

func (*Engine) RequestPhoneChange ¶

func (s *Engine) RequestPhoneChange(ctx context.Context, userID, newPhone string) error

RequestPhoneChange initiates a phone number change by sending a verification code to the new phone. The current phone is NOT changed until the user confirms via ConfirmPhoneChange.

func (*Engine) RequestPhonePasswordReset ¶

func (s *Engine) RequestPhonePasswordReset(ctx context.Context, phone string, ttl time.Duration, ip *string, ua *string) error

RequestPhonePasswordReset creates a password reset token and sends a reset link via SMS. Always returns nil for unknown phone numbers to prevent user enumeration (202-like behavior).

func (*Engine) RequestPhoneVerification ¶

func (s *Engine) RequestPhoneVerification(ctx context.Context, phone string, ttl time.Duration) error

RequestPhoneVerification is RequestEmailVerification for a phone number.

func (*Engine) RequireProvenContact ¶

func (s *Engine) RequireProvenContact(ctx context.Context, userID string) error

RequireProvenContact is the pre-flight form of the login-method gate.

func (*Engine) ResendLoginChallenge ¶

func (s *Engine) ResendLoginChallenge(ctx context.Context, userID, nonce, factorID string) (*authflow.TwoFactorChallenge, error)

ResendLoginChallenge changes the selected independent factor while retaining the first-factor proof and its original expiry.

func (*Engine) ResetAccountMFA ¶

func (s *Engine) ResetAccountMFA(ctx context.Context, userID string, opts ...ops.Option) error

ResetAccountMFA is the system's recovery for an account that lost its second factors (a lost passkey answers passkey_required): it deletes the account's passkeys, 2FA factors and backup codes, revokes its device keys and its sessions on every account issuer, and tells its address. Roles stay: when one needs MFA, or 2FA is Required, the next sign-in enrolls a factor: a host operation.

func (*Engine) ResolveAPIKey ¶

func (s *Engine) ResolveAPIKey(ctx context.Context, token string) (iam.ResolvedAPIKey, error)

ResolveAPIKey authenticates a presented token: the key must exist with a matching secret, be neither revoked nor expired, belong to a live group, and have a live creator (a banned or deleted creator's keys are refused even before any sweep revokes them). Permissions are the role's now. It is verify's API-key resolver.

func (*Engine) ResolveUsername ¶

func (s *Engine) ResolveUsername(ctx context.Context, name string) (iam.NameResolution, error)

ResolveUsername resolves a current username or live alias of a live account.

func (*Engine) ResourceEnabled ¶ added in v1.18.0

func (s *Engine) ResourceEnabled() bool

ResourceEnabled reports whether Config.Resource admits access tokens.

func (*Engine) RestoreUsers ¶

func (s *Engine) RestoreUsers(ctx context.Context, a auth.Identity, ids []string, opts ...ops.Option) ([]iam.OpResult, error)

RestoreUsers restores soft-deleted accounts within their recovery window under ACCT(root:users:delete), re-checked against every group role the account resumes. Old sessions, device keys and credentials stay revoked.

func (*Engine) RevokeAPIKey ¶

func (s *Engine) RevokeAPIKey(ctx context.Context, a auth.Identity, ref iam.GroupRef, id string, opts ...ops.Option) error

RevokeAPIKey revokes the group's key id. It needs the authority to issue the key's role: CAP(<p>:credentials:manage) plus COVER(role). A revoked key is a no-op; an id unknown in the group is iam.ErrAPIKeyNotFound.

func (*Engine) RevokeAccountSessions ¶

func (s *Engine) RevokeAccountSessions(ctx context.Context, a auth.Identity, userID string, opts ...ops.Option) (iam.AccountSessionRevocation, error)

RevokeAccountSessions revokes the account's refresh sessions on every account issuer and all its device keys, under ACCT(root:users:manage) with peers allowed; an account may revoke its own. Issued access tokens expire on their TTL.

func (*Engine) RevokeConsent ¶ added in v1.20.0

func (s *Engine) RevokeConsent(ctx context.Context, userID, clientID string, opts ...ops.Option) error

RevokeConsent withdraws userID's consent to clientID as the host (OpenRails unlinking a merchant).

func (*Engine) RevokeDeviceKey ¶

func (s *Engine) RevokeDeviceKey(ctx context.Context, userID, currentID, targetID string) error

RevokeDeviceKey revokes the account's key targetID; a revoked key stays revoked, and a key the account does not hold is not_found. currentID is the key behind the caller's token ("" for a browser session): it is checked live in the same transaction, so a revoked machine cannot use the rest of its access token to revoke a replacement.

func (*Engine) RevokeInvitation ¶

func (s *Engine) RevokeInvitation(ctx context.Context, a auth.Identity, ref iam.GroupRef, id string, opts ...ops.Option) error

RevokeInvitation revokes the group's invitation id. It needs the authority to issue it: CAP(<p>:members:manage) plus COVER of its role, or CAP(root:users:invite) for a plain email invitation. A revoked or redeemed invitation is a no-op; an id unknown in the group is iam.ErrInvitationNotFound.

func (*Engine) RevokeIssuerSessions ¶

func (s *Engine) RevokeIssuerSessions(ctx context.Context, userID string, keepSessionID *string) error

RevokeIssuerSessions revokes the user's refresh sessions on this issuer only, optionally keeping one: a user's own "sign out my other sessions" here.

func (*Engine) RevokeOAuthToken ¶ added in v1.5.0

func (s *Engine) RevokeOAuthToken(ctx context.Context, clientID, token string) error

RevokeOAuthToken is RFC 7009 revocation for clientID: a refresh token ends its family. Anything else (an access token, which expires on its own, or an unknown token) is accepted and ignored, as the RFC requires.

func (*Engine) RevokeOtherDeviceKeys ¶

func (s *Engine) RevokeOtherDeviceKeys(ctx context.Context, userID, currentID string) error

RevokeOtherDeviceKeys atomically revokes every key except the live key that minted the caller's email-proven token.

func (*Engine) RevokeSession ¶

func (s *Engine) RevokeSession(ctx context.Context, a auth.Identity, userID, sessionID string, opts ...ops.Option) error

RevokeSession revokes one refresh session of the account on this issuer, under ACCT(root:users:manage) with peers allowed; an account may revoke its own. An unknown or already revoked session is a no-op.

func (*Engine) RevokeSessionByIDForUser ¶

func (s *Engine) RevokeSessionByIDForUser(ctx context.Context, userID, sessionID string) error

RevokeSessionByIDForUser revokes a session by id ensuring it belongs to the user; an unknown or revoked session is left as it is.

func (*Engine) RiverJobs ¶

func (s *Engine) RiverJobs() riverhelpers.Contribution

RiverJobs contributes AuthKit's jobs to one fleet: the host's, which it passes to Start with WithRiverClient, or the one Start builds itself. It neither constructs nor starts a client. Compose once; a failed composition needs a new Client.

func (*Engine) Role ¶

func (s *Engine) Role(text string) (iam.Role, error)

Role resolves role text `<persona>:<name>`: a declared role, a persona's owner role, or a custom role name of a persona whose groups define them (whether a group does is checked where it is used), else iam.ErrRoleNotAssignable (iam.ErrUnknownGroupPersona for an undeclared persona).

func (*Engine) RolePermissions ¶ added in v0.148.0

func (s *Engine) RolePermissions(role iam.Role) ([]iam.Perm, error)

RolePermissions returns role's grants in the catalog, includes flattened: permissions and patterns, in declaration order. A custom role is a group's: GroupRole reads it.

func (*Engine) RootGroupID ¶ added in v1.7.0

func (s *Engine) RootGroupID(ctx context.Context) (string, error)

RootGroupID is the root group's id.

func (*Engine) RotateGroupOAuthClientSecret ¶ added in v1.20.0

func (s *Engine) RotateGroupOAuthClientSecret(ctx context.Context, who auth.Identity, ref iam.GroupRef, clientID string, opts ...ops.Option) (string, error)

RotateGroupOAuthClientSecret replaces a client_secret_basic client's secret, returning the new one this once; the old one stops at once.

func (*Engine) SCIMTenant ¶ added in v1.18.0

func (s *Engine) SCIMTenant(ctx context.Context, who auth.Identity, boundGroup string) (scim.Tenant, error)

SCIMTenant is the directory who provisions (RFC 7644 §6.1: the tenant follows from the credential): an API key's, bound to a remote application of its group (iam.NewAPIKey.ProvisionsFor), or a remote application's own token's, whose group is boundGroup. The application must be enabled. Anything else is scim.ErrNoTenant.

func (*Engine) SCIMUser ¶ added in v1.12.0

func (s *Engine) SCIMUser(ctx context.Context, id string) (scim.User, error)

SCIMUser is the account id as a SCIM User; iam.ErrUserNotFound for none.

func (*Engine) SCIMUsers ¶ added in v1.12.0

func (s *Engine) SCIMUsers(ctx context.Context, filter string, startIndex, count int) (scim.ListResponse[scim.User], error)

SCIMUsers answers a query: the accounts filter matches (scim.ParseFilter), or every account, in id order, from the 1-based startIndex.

func (*Engine) SMSAvailable ¶

func (s *Engine) SMSAvailable() bool

SMSAvailable is EmailAvailable for Deps.SMS and phone flows.

func (*Engine) SMSHealth ¶

func (s *Engine) SMSHealth() (time.Time, error)

SMSHealth is EmailHealth for Deps.SMS.

func (*Engine) ScopeDescriptions ¶ added in v1.20.0

func (s *Engine) ScopeDescriptions(scopes []string) []errmodel.ScopeDescription

ScopeDescriptions is scopeDescriptions for the HTTP layer.

func (*Engine) SearchRemoteUserInfo ¶ added in v1.18.0

func (s *Engine) SearchRemoteUserInfo(ctx context.Context, groupID, issuer, query string, limit int) ([]userinfo.User, error)

SearchRemoteUserInfo returns up to limit active users of the group's directory of issuer whose username, email or name contains query, ignoring case.

func (*Engine) SearchUserInfo ¶ added in v1.15.0

func (s *Engine) SearchUserInfo(ctx context.Context, query string, limit int) ([]userinfo.User, error)

SearchUserInfo returns up to limit live accounts whose verified email or username contains query, ignoring case.

func (*Engine) Send2FAStepUpCode ¶ added in v1.1.0

func (s *Engine) Send2FAStepUpCode(ctx context.Context, userID, sessionID, factorID string) error

Send2FAStepUpCode sends a step-up code to the account's factor factorID (its default factor when empty); an authenticator app needs none.

func (*Engine) SendDeviceVerification ¶ added in v1.3.0

func (s *Engine) SendDeviceVerification(ctx context.Context, userID, challenge, channel string) (*authflow.DeviceChallenge, error)

SendDeviceVerification sends the waiting sign-in a new code, on channel ("email" or "sms"; empty: the first available).

func (*Engine) SendStepUpCode ¶ added in v1.1.0

func (s *Engine) SendStepUpCode(ctx context.Context, userID, sessionID, channel string) error

SendStepUpCode sends a code to the account's proven address on channel ("email" or "sms"). It replaces any code the session holds.

func (*Engine) SendWelcome ¶

func (s *Engine) SendWelcome(ctx context.Context, userID string)

SendWelcome sends the welcome email when Deps.Email is set.

func (*Engine) SessionFreshness ¶

func (s *Engine) SessionFreshness(ctx context.Context, userID, sessionID string, now time.Time) (authflow.SessionFreshness, error)

func (*Engine) Sessions ¶

func (s *Engine) Sessions(ctx context.Context, userID string) ([]iam.Session, error)

Sessions lists the account's live refresh sessions on this issuer.

func (*Engine) SetClock ¶ added in v1.1.0

func (s *Engine) SetClock(now func() time.Time)

SetClock replaces the engine clock of TTL and grace-window decisions, for AuthKit's own tests (internal/testclock); call it before the engine serves. Ephemeral state (codes, claims, counters) keeps the database clock.

func (*Engine) SetDefault2FAFactor ¶ added in v0.149.0

func (s *Engine) SetDefault2FAFactor(ctx context.Context, userID, factorID string) (authflow.MFAFactor, error)

SetDefault2FAFactor makes the account's factor factorID its default and returns it; not_found when the account holds no such factor.

func (*Engine) SetGroupRole ¶

func (s *Engine) SetGroupRole(ctx context.Context, a auth.Identity, ref iam.GroupRef, subject iam.Subject, role iam.Role, opts ...ops.Option) (iam.GroupMember, error)

SetGroupRole makes subject hold role in ref, replacing the role it holds: CAP by subject kind, COVER(role), and when replacing, COVER(old) (none for a removed role) and the last-owner check. An application subject must be controlled by the group. Holding role already changes nothing.

func (*Engine) SetPasswordAfterFreshAuth ¶

func (s *Engine) SetPasswordAfterFreshAuth(ctx context.Context, userID, new string, keepSessionID *string) error

SetPasswordAfterFreshAuth sets or replaces the password of an account whose session recently signed in, invalidates recovery grants and revokes its other sessions atomically. keepSessionID may preserve one.

func (*Engine) SetSMSLimiter ¶ added in v1.20.0

func (s *Engine) SetSMSLimiter(rl ratelimit.Limiter)

SetSMSLimiter spends text messages' send limits in rl, the HTTP surface's limiter (Deps.Redis, else memory). A headless Client sends only for its host and applies none.

func (*Engine) Start ¶

func (s *Engine) Start(ctx context.Context, fleet *river.Client[pgx.Tx]) error

Start starts the senders' health checks and River. Without a fleet it builds and starts AuthKit's own River client in RiverSchema; with one it requires the fleet RiverJobs is bound to and leaves its start to the host. It runs no DDL. A client without PostgreSQL (for example verify-only tests) has no jobs. The client running its issuer's fleet sets whether the issuer records account events (Deps.OnEvent).

func (*Engine) StartPasswordless ¶

func (s *Engine) StartPasswordless(ctx context.Context, req authflow.PasswordlessStartRequest) (authflow.PasswordlessStartResult, error)

func (*Engine) StepUpRequired ¶

func (s *Engine) StepUpRequired(ctx context.Context, userID string) error

StepUpRequired is the step_up_required error for userID, carrying how the account can step up: its methods, the window, and its second factors.

func (*Engine) StepUpWithCode ¶ added in v1.1.0

func (s *Engine) StepUpWithCode(ctx context.Context, userID, sessionID, code string) error

StepUpWithCode re-authenticates the session with the code SendStepUpCode sent it, while the address it went to is still the account's, proven. ErrInvalidCode is a wrong code; ErrCodeExpired, no live one.

func (*Engine) StepUpWithPasskey ¶ added in v1.1.0

func (s *Engine) StepUpWithPasskey(ctx context.Context, userID, sessionID string, response []byte) error

StepUpWithPasskey re-authenticates the session with the assertion BeginPasskeyStepUp asked for. A user-verified passkey is multi-factor, so it clears the gate on an account with a second factor too.

func (*Engine) StepUpWithSolana ¶ added in v1.1.0

func (s *Engine) StepUpWithSolana(ctx context.Context, userID, sessionID string, output siws.SignInOutput) error

StepUpWithSolana re-authenticates the session with the linked wallet's signature over the challenge BeginSolanaStepUp issued it.

func (*Engine) TwoFactorEnabled ¶

func (s *Engine) TwoFactorEnabled() bool

TwoFactorEnabled reports whether any 2FA flow is usable (Mode != Disabled).

func (*Engine) TwoFactorMethods ¶ added in v0.148.0

func (s *Engine) TwoFactorMethods() []iam.TwoFactorMethod

TwoFactorMethods are the second factors a user can enroll now, in stable order: enabled by TwoFactor.Mode and Methods, with their dependency present (Deps.Email and Deps.SMS while healthy, the TOTP key). Empty when 2FA is disabled.

func (*Engine) Unban ¶

func (s *Engine) Unban(ctx context.Context, a auth.Identity, userID string, opts ...ops.Option) error

Unban lifts a ban under ACCT(root:users:ban). Lifting a ban restores the account's authority, so it needs the same coverage as imposing one; nobody lifts their own ban.

func (*Engine) UnlinkProvider ¶ added in v1.1.0

func (s *Engine) UnlinkProvider(ctx context.Context, userID, provider string) error

UnlinkProvider removes the account's link to provider unless it is the account's last way to sign in: provider_not_linked when nothing is linked under that name, cannot_unlink_last_login_method when no other sign-in method would remain. An imported claim not yet verified signs nobody in, so it always goes. The check and the delete hold the account lock every credential change takes, so two unlinks cannot each leave the other last.

func (*Engine) UpdateGroupOAuthClient ¶ added in v1.20.0

func (s *Engine) UpdateGroupOAuthClient(ctx context.Context, who auth.Identity, ref iam.GroupRef, clientID string, u iam.OAuthClientUpdate, opts ...ops.Option) (iam.OAuthClient, error)

UpdateGroupOAuthClient changes a client of ref under CAP <p>:credentials:manage. Disabling it refuses its sign-ins and every token it holds at its next use.

func (*Engine) UpdateGroupRole ¶ added in v1.19.0

func (s *Engine) UpdateGroupRole(ctx context.Context, who auth.Identity, ref iam.GroupRef, role iam.Role, u iam.GroupRoleUpdate, opts ...ops.Option) (iam.GroupRole, error)

UpdateGroupRole replaces what a custom role of ref grants. Every holder gets the change at its next request, so beyond CAP(<p>:roles:manage) and COVER of the grants before and after, it takes <p>:members:manage while members or invitations hold the role and <p>:credentials:manage while API keys or applications do. A change that needs MFA is refused while an API key or application holds the role (iam.ErrRoleNotAssignable) or a holder has no second factor (iam.ErrSubjectMFARequired). Afterwards every credential in the group (root: everywhere) whose issuer no longer covers its role is revoked (rule CRED).

func (*Engine) UpdateUser ¶

func (s *Engine) UpdateUser(ctx context.Context, a auth.Identity, userID string, u iam.UserUpdate, opts ...ops.Option) (iam.User, error)

UpdateUser changes an account under ACCT(root:users:manage). An account may change its own Username and PreferredLanguage (the rename policy applies to itself, not to staff renaming it); Password, PasswordHash and the verified flags are system-only (staff send a reset to the proven address instead). Setting a verified flag is the proof transition: on an account with no proven contact it first retires every pre-proof credential, and every address the flags set don't cover. Never set one on another system's word (see ImportUsers). A contact change never leaves an account with a second factor or MFA-required roles without a proven contact, since the next proof would retire its MFA, and never moves its email factor, which stays bound to the address it was proven for. Nothing is sent to the new address.

func (*Engine) UpsertRemoteApplication ¶

func (s *Engine) UpsertRemoteApplication(ctx context.Context, who auth.Identity, ref iam.GroupRef, in iam.RemoteApplication, opts ...ops.Option) (iam.RemoteApplication, error)

UpsertRemoteApplication registers the application app.Issuer in the group ref, or updates it there. The system may set Mode and TrustRoot (new applications default to manual); a user registers at trust root user. Machine identities cannot register.

func (*Engine) User ¶

func (s *Engine) User(ctx context.Context, ref iam.UserRef, opts ...ops.Option) (iam.User, error)

User returns one account. Soft-deleted accounts are excluded unless opts include ops.IncludeDeleted(); a miss is iam.ErrUserNotFound.

func (*Engine) UserAgreements ¶ added in v1.20.0

func (s *Engine) UserAgreements(ctx context.Context, userID string) ([]iam.AgreementAcceptance, error)

UserAgreements returns userID's acceptances, every version, by key.

func (*Engine) UserEntry ¶

func (s *Engine) UserEntry(ctx context.Context, userID string) (iam.UserEntry, error)

UserEntry is one account, deleted ones included, as the user directory lists it, entitlements included.

func (*Engine) UserInfo ¶ added in v1.15.0

func (s *Engine) UserInfo(ctx context.Context, ids []string) (map[string]userinfo.User, error)

UserInfo returns the live accounts among ids, keyed by id; a deleted, purged, unknown or malformed id is absent.

func (*Engine) UserNamingState ¶

func (s *Engine) UserNamingState(ctx context.Context, id string) (naming.State, error)

func (*Engine) UserProfile ¶

func (s *Engine) UserProfile(ctx context.Context, in authflow.ProfileInput) (authflow.UserProfile, error)

UserProfile builds the caller's profile. Errors: the user row is missing (stage "load_user"), or a store failure (stage "load_password", "load_providers").

func (*Engine) UserSecurity ¶ added in v0.149.0

func (s *Engine) UserSecurity(ctx context.Context, in authflow.ProfileInput) (authflow.UserSecurity, error)

UserSecurity builds the caller's security view: the presented token's freshness, the step-up methods and the second factors, from one 2FA-settings read.

func (*Engine) Users ¶

func (s *Engine) Users(ctx context.Context, ids []string) (map[string]iam.User, error)

Users returns the accounts among ids, deleted ones included; unknown ids are absent. It is privileged: it carries contact details.

func (*Engine) ValidatePassword ¶

func (s *Engine) ValidatePassword(value string, identifiers ...string) error

ValidatePassword applies the configured password policy. identifiers are the account's username and email address when known. Length failures carry min_length/max_length; requirement failures carry the missing classes.

func (*Engine) ValidateUsername ¶

func (s *Engine) ValidateUsername(username string) error

ValidateUsername applies the configured username rule.

func (*Engine) ValidateUsernameForRegistration ¶

func (s *Engine) ValidateUsernameForRegistration(ctx context.Context, username string) (string, error)

func (*Engine) Verify ¶

func (s *Engine) Verify(ctx context.Context, token string) (verify.Claims, error)

Verify is VerifyRequest for a token detached from any request.

func (*Engine) Verify2FAStepUpCode ¶ added in v1.1.0

func (s *Engine) Verify2FAStepUpCode(ctx context.Context, userID, sessionID, factorID, code string) (bool, error)

Verify2FAStepUpCode checks a step-up code from the account's factor factorID (its default factor when empty).

func (*Engine) VerifyBackupCode ¶

func (s *Engine) VerifyBackupCode(ctx context.Context, userID, backupCode string) (bool, error)

VerifyBackupCode verifies a 2FA backup code for account recovery. On success, removes the used backup code from the user's backup codes.

func (*Engine) VerifyIDToken ¶ added in v1.20.0

func (s *Engine) VerifyIDToken(ctx context.Context, raw string) (iam.IDToken, error)

VerifyIDToken verifies an ID token this deployment's authorization server issued, in process: its signature, issuer, single audience (its azp), lifetime, a client still registered and enabled, and a sign-in that still stands (its user neither deleted nor banned). Anything else is iam.ErrInvalidIDToken; a store failure stays an error.

func (*Engine) VerifyPendingPassword ¶

func (s *Engine) VerifyPendingPassword(ctx context.Context, email, pass string) bool

VerifyPendingPassword checks if the provided password matches the pending registration's hash. Returns true if password is correct, false otherwise.

func (*Engine) VerifyPendingPhonePassword ¶

func (s *Engine) VerifyPendingPhonePassword(ctx context.Context, phone, pass string) bool

VerifyPendingPhonePassword checks if the provided password matches the pending phone registration's hash. Returns true if password is correct, false otherwise.

func (*Engine) VerifyRequest ¶

func (s *Engine) VerifyRequest(r *http.Request) (verify.Claims, error)

VerifyRequest authenticates the engine's own requests (verify.Authenticator).

func (*Engine) VerifyResourceRequest ¶ added in v1.18.0

func (s *Engine) VerifyResourceRequest(r *http.Request) (ResourceAccess, error)

VerifyResourceRequest verifies r's access token for Config.Resource.ID. Its errors are verify's, for verify.Refusal.

func (*Engine) VerifySIWSAndLogin ¶

func (s *Engine) VerifySIWSAndLogin(ctx context.Context, output siws.SignInOutput, extra map[string]any) (authflow.LoginOutcome, error)

VerifySIWSAndLogin verifies a SIWS signature and logs in or creates a user. It shares the normal MFA/recovery/session tail with other first factors.

func (*Engine) WithdrawConsent ¶ added in v1.20.0

func (s *Engine) WithdrawConsent(ctx context.Context, who auth.Identity, userID, clientID string) error

WithdrawConsent withdraws userID's consent to clientID, as who: the consent goes, the client's refresh tokens for the user end at their next use, its back-channel logout is sent, and oauth_consent.revoked recorded.

func (ResourceAccess) Group ¶ added in v1.18.0

func (a ResourceAccess) Group() string

Group is the group the token is bound to: its application's, or its group client's.