embedded

func (*Client) AdminDeleteUser ¶ added in v0.98.0

func (s *Client) AdminDeleteUser(ctx context.Context, id string) error

AdminDeleteUser hard-deletes the user in ONE transaction: sessions are revoked first (for the audit trail; every AuthKit dependent table, refresh_sessions and group_user_roles included, cascades on the row delete). A host table that references profiles.users(id) without ON DELETE CASCADE aborts the whole delete with ErrUserReferenced, so a user is never left half-deleted (#304).

func (*Client) AdminGetUser ¶

func (s *Client) AdminGetUser(ctx context.Context, id string) (*AdminUser, error)

func (*Client) AdminListUsers ¶

func (s *Client) AdminListUsers(ctx context.Context, opts AdminUserListOptions) (*AdminListUsersResult, error)

AdminListUsers is the generic admin user-directory list (issue #91): generic role/status filter + search + sort + offset pagination, with optional provider-backed entitlement filtering. Each row is enriched with role slugs and (via the entitlements provider) entitlement names.

func (*Client) AdminRevokeUserSessions ¶

func (s *Client) AdminRevokeUserSessions(ctx context.Context, userID string) error

func (*Client) AdminRevokeUserSessionsAs ¶ added in v0.98.0

func (s *Client) AdminRevokeUserSessionsAs(ctx context.Context, actorUserID, userID string) error

AdminRevokeUserSessionsAs is the actor-aware AdminRevokeUserSessions.

func (*Client) AdminSetPassword ¶

func (s *Client) AdminSetPassword(ctx context.Context, userID, new string) error

AdminSetPassword force-sets a user's password (admin only, no current password required)

func (*Client) ApplyBootstrapManifest ¶

func (s *Client) ApplyBootstrapManifest(ctx context.Context, manifest BootstrapManifest, opts BootstrapReconcileOptions) (BootstrapManifestResult, error)

func (*Client) AssignGroupRole ¶

func (s *Client) AssignGroupRole(ctx context.Context, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

AssignGroupRole grants a subject a role in the group addressed by (persona, instanceSlug). The role must be a catalog role (or any role for custom-enabled types). Gated by the MFA-required-role rule (#148/root-owner-MFA); genesis callers that must run before any policy can apply use AssignGroupRoleGenesis.

func (*Client) AssignGroupRoleAs ¶

func (s *Client) AssignGroupRoleAs(ctx context.Context, actorUserID string, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

AssignGroupRoleAs is the actor-aware AssignGroupRole: it enforces the #136 capability + no-escalation rules against actorUserID before assigning. Runtime callers (HTTP role-management endpoints) use this; genesis paths (bootstrap, migration) keep using the unchecked AssignGroupRole.

func (*Client) AssignGroupRoleGenesis ¶ added in v0.98.0

func (s *Client) AssignGroupRoleGenesis(ctx context.Context, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

AssignGroupRoleGenesis grants a role with NEITHER actor-authz (#136) NOR the MFA-required-role gate (#148/root-owner-MFA). Reserved for genesis/bootstrap callers (GenesisClient, the bootstrap manifest) — the deploy-time trust root that runs before any actor-authorized request path (or any chance to enroll MFA) exists, so no runtime policy can apply yet. Never call this from a runtime request handler; use AssignGroupRole or AssignGroupRoleAs there.

func (*Client) AssignRemoteApplicationRole ¶ added in v0.98.0

func (s *Client) AssignRemoteApplicationRole(ctx context.Context, appID string, role authkit.Role) error

AssignRemoteApplicationRole grants a remote_application a role in its own controlling permission-group with NO actor check (#308): reachable only via bootstrap and embedded.Client.Genesis(). Runtime callers use AssignRemoteApplicationRoleAs.

func (*Client) AssignRemoteApplicationRoleAs ¶ added in v0.98.0

func (s *Client) AssignRemoteApplicationRoleAs(ctx context.Context, actorUserID string, group authkit.GroupRef, appSlug string, role authkit.Role) error

AssignRemoteApplicationRoleAs is the actor-aware remote-application role assignment behind PUT /<persona>/:instance_slug/remote-applications/:app/ roles/:role (#263) — the SubjectKindRemoteApp symmetric of the member-role route. The :app slug must resolve to a remote application CONTROLLED BY the addressed group (same scope rule as the remote-app delete route), and the actor must hold the persona's credentials:manage capability plus every permission the role confers (no-escalation), so nobody can grant an application authority above their own.

func (*Client) AssignRoleBySlug ¶

func (s *Client) AssignRoleBySlug(ctx context.Context, userID string, role authkit.Role) error

Exported wrappers for admin/HTTP adapters.

func (*Client) AssignRoleBySlugAs ¶

func (s *Client) AssignRoleBySlugAs(ctx context.Context, actorUserID, userID string, role authkit.Role) error

AssignRoleBySlugAs is the actor-aware root-group convenience (the runtime equivalent of assignRoleBySlug). "owner" is no longer a reserved special case: it is assignable only by an actor who already holds root:* (rule 2).

func (*Client) AssignRolesBySlugAs ¶ added in v0.80.0

func (s *Client) AssignRolesBySlugAs(ctx context.Context, actorUserID string, userIDs []string, role authkit.Role) ([]authkit.OpResult, error)

func (*Client) BanUser ¶

func (s *Client) BanUser(ctx context.Context, userID string, reason *string, until *time.Time, bannedBy string) error

BanUser disables a user account and stores ban metadata. bannedBy is the acting user and must hold every root grant the target holds (#286), so a bounded operator can never lock out a more privileged account. The ban, session revoke and device-key revoke commit together.

func (*Client) BeginDeviceKeyEnrollment ¶ added in v0.98.0

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

BeginDeviceKeyEnrollment sends an email proof and records the proposed key.

func (*Client) BeginDeviceKeyLogin ¶ added in v0.98.0

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

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

func (*Client) BeginDiscoverablePasskeyVerification ¶ added in v0.98.0

func (s *Client) BeginDiscoverablePasskeyVerification(ctx context.Context) (*protocol.CredentialAssertion, error)

BeginDiscoverablePasskeyVerification starts an identity-proof ceremony: the public response is identical for every caller, and user verification is required because the passkey is the only factor.

func (*Client) BeginPasskeyAccount ¶ added in v0.98.0

func (s *Client) BeginPasskeyAccount(ctx context.Context) (PendingPasskeyAccount, error)

BeginPasskeyAccount starts a passkey-only account: it mints the user id (no row yet), uses its bytes as the discoverable user handle, and requires user verification. Allowed only while public native registration is open.

func (*Client) BeginPasskeyLogin ¶ added in v0.98.0

func (s *Client) BeginPasskeyLogin(ctx context.Context, identifier string) (*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, so the identifier is deliberately ignored and the user is resolved at finish from the asserted credential's user handle.

func (*Client) BeginPasskeyRegistration ¶ added in v0.98.0

func (s *Client) 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 (*Client) BeginTwoFactorEnrollment ¶ added in v0.98.0

func (s *Client) BeginTwoFactorEnrollment(ctx context.Context, userID string, enrollmentToken bool, sessionID string) (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 (*Client) Can ¶

func (s *Client) Can(ctx context.Context, subject authkit.Subject, group authkit.GroupRef, perm authkit.Perm) (bool, error)

Can is the Client-level authorization check: resolve the group addressed by (persona, instanceSlug), then test perm coverage via the additive walk-up. The caller constructs perm per the two-persona rule (LT:RT:action).

func (*Client) CanOnGroup ¶ added in v0.98.0

func (s *Client) CanOnGroup(ctx context.Context, subject authkit.Subject, groupID string, perm authkit.Perm) (bool, error)

CanOnGroup evaluates live assignments for the exact resolved group. A rename or reclaimed name cannot redirect this check to a different owner.

func (*Client) ChangePassword ¶

func (s *Client) ChangePassword(ctx context.Context, userID, current, new string, keepSessionID *string) error

ChangePassword sets or changes a user's password. If the user already has a password, current must verify; otherwise current is ignored. Always Argon2id-hashes the new password and upserts it, then revokes all other sessions for the user; caller may keep one active session via keepSessionID.

func (*Client) CheckPendingRegistrationConflict ¶ added in v0.98.0

func (s *Client) 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 (*Client) CheckPhoneRegistrationConflict ¶ added in v0.98.0

func (s *Client) 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 (*Client) CheckSMSHealth ¶

func (s *Client) CheckSMSHealth(ctx context.Context) error

CheckSMSHealth probes whether the configured SMS sender can actually deliver, without sending a message, when the sender implements SMSHealthChecker. The verdict gates phone-based flows via SMSAvailable. It returns the probe error (nil = healthy) so callers can log it. When no sender is configured or the sender cannot self-check, it records healthy (delivery readiness is then governed solely by sender presence, as before).

func (*Client) CheckUserPassword ¶ added in v0.98.0

func (s *Client) 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 HashAlgoLegacyResetRequired (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 (*Client) CleanupExpiredAuthState ¶

func (s *Client) CleanupExpiredAuthState(ctx context.Context) error

CleanupExpiredAuthState removes expired transient AuthKit state that lives in postgres. Short-lived verification state — pending registrations, pending email/phone changes, email/phone verifications, and password resets — now lives entirely in the ephemeral store (Redis when multi-instance, in-memory otherwise) and expires automatically by TTL, so no database sweep is needed for it. The postgres sweep covers revoked/expired refresh sessions and their consumed-token history, long-dead invite rows (retained inviteRetention past their terminal moment), and session-event history past Config.SessionEventRetention (#245).

func (*Client) Clear2FAChallenge ¶ added in v0.98.0

func (s *Client) Clear2FAChallenge(ctx context.Context, userID string) error

Clear2FAChallenge removes the stored challenge after successful 2FA verification.

func (*Client) ClearEmailVerified ¶ added in v0.98.0

func (s *Client) ClearEmailVerified(ctx context.Context, id string) error

ClearEmailVerified marks the user's email address unverified again.

func (*Client) ClearEmailVerifyCodeAttempts ¶ added in v0.98.0

func (s *Client) ClearEmailVerifyCodeAttempts(ctx context.Context, email string)

ClearEmailVerifyCodeAttempts resets the per-email failed-attempt counter after a successful confirmation.

func (*Client) ClearPhoneVerifyCodeAttempts ¶ added in v0.98.0

func (s *Client) ClearPhoneVerifyCodeAttempts(ctx context.Context, phone string)

ClearPhoneVerifyCodeAttempts resets the per-phone failed-attempt counter after a successful confirmation.

func (*Client) CompleteExternalLogin ¶ added in v0.98.0

func (s *Client) CompleteExternalLogin(ctx context.Context, in ExternalLoginInput) (ExternalLoginOutcome, error)

CompleteExternalLogin resolves the identity to a user and signs it in. Resolution errors: ErrProviderAlreadyLinked, ErrProviderChangeRequiresUnlink, ErrAccountExistsLinkRequired, ErrRegistrationDisabled, ErrProviderLinkFailed, ErrUserCreationFailed. Session errors: ErrUserBanned, or a stage-prefixed ErrSessionIssueFailed.

func (*Client) Config ¶ added in v0.77.0

func (s *Client) Config() Config

Config returns THE configuration (#237): the host Config, normalized once at construction. Both the engine and the HTTP transport read it — there is no parallel flat options struct (#236 bug class is structurally impossible).

func (*Client) ConfirmEmailChange ¶ added in v0.98.0

func (s *Client) ConfirmEmailChange(ctx context.Context, userID, email, code string, keepSessionID *string) error

ConfirmEmailChange verifies the code and applies the new email. Every other session is revoked; keepSessionID (the confirming session) survives.

func (*Client) ConfirmEmailChangeByToken ¶ added in v0.98.0

func (s *Client) ConfirmEmailChangeByToken(ctx context.Context, token string) (string, error)

ConfirmEmailChangeByToken applies a pending email change using its high-entropy link token.

func (*Client) ConfirmEmailVerification ¶ added in v0.98.0

func (s *Client) ConfirmEmailVerification(ctx context.Context, email, code string) (userID string, err error)

ConfirmEmailVerification verifies a short typed code for a SPECIFIC email and marks email_verified = true. The record is keyed by the account that owns the address, so the code is only ever compared against that account's own record; the HTTP layer caps attempts per-identifier. For the unguessable 256-bit emailed link token use ConfirmEmailVerificationByToken instead.

func (*Client) ConfirmEmailVerificationByToken ¶ added in v0.98.0

func (s *Client) ConfirmEmailVerificationByToken(ctx context.Context, token string) (userID string, err error)

ConfirmEmailVerificationByToken verifies the 256-bit emailed link token and marks email_verified = true. The token's own entropy is the security boundary.

func (*Client) ConfirmPasswordReset ¶ added in v0.98.0

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

ConfirmPasswordReset verifies token and sets a new password.

func (*Client) ConfirmPasswordlessCode ¶

func (s *Client) ConfirmPasswordlessCode(ctx context.Context, identifier, code string) (PasswordlessConfirmResult, error)

func (*Client) ConfirmPasswordlessToken ¶

func (s *Client) ConfirmPasswordlessToken(ctx context.Context, token string) (PasswordlessConfirmResult, error)

func (*Client) ConfirmPendingPhoneRegistration ¶ added in v0.98.0

func (s *Client) ConfirmPendingPhoneRegistration(ctx context.Context, phone, code string) (userID string, err error)

ConfirmPendingPhoneRegistration finalizes a pending phone registration from the short typed code, honored only against the record issued for this phone.

func (*Client) ConfirmPendingPhoneRegistrationByToken ¶ added in v0.98.0

func (s *Client) ConfirmPendingPhoneRegistrationByToken(ctx context.Context, token string) (string, error)

ConfirmPendingPhoneRegistrationByToken finalizes a pending phone registration from the 256-bit link token.

func (*Client) ConfirmPendingRegistration ¶ added in v0.98.0

func (s *Client) ConfirmPendingRegistration(ctx context.Context, email, code string) (userID string, err error)

ConfirmPendingRegistration finalizes a pending email registration from the short typed code. The code is only honored against the record issued for this exact address (the record is keyed by it), so a guessed code can never confirm another signup; the HTTP layer caps attempts per-identifier. For the 256-bit emailed link token use ConfirmPendingRegistrationByToken instead.

func (*Client) ConfirmPendingRegistrationByToken ¶ added in v0.98.0

func (s *Client) ConfirmPendingRegistrationByToken(ctx context.Context, token string) (userID string, err error)

ConfirmPendingRegistrationByToken finalizes a pending email registration from the 256-bit emailed link token, whose entropy is the security boundary.

func (*Client) ConfirmPhoneChange ¶ added in v0.98.0

func (s *Client) ConfirmPhoneChange(ctx context.Context, userID, phone, code string, keepSessionID *string) error

ConfirmPhoneChange verifies the code and applies the new phone. Every other session is revoked; keepSessionID (the confirming session) survives.

func (*Client) ConfirmPhoneChangeByToken ¶ added in v0.98.0

func (s *Client) ConfirmPhoneChangeByToken(ctx context.Context, token string) (string, error)

ConfirmPhoneChangeByToken applies a pending phone change using its high-entropy link token.

func (*Client) ConfirmPhoneVerificationByTokenUserID ¶ added in v0.98.0

func (s *Client) ConfirmPhoneVerificationByTokenUserID(ctx context.Context, token string) (string, error)

ConfirmPhoneVerificationByTokenUserID verifies phone ownership using a one-click token and returns the user ID.

func (*Client) ConfirmPhoneVerificationUserID ¶ added in v0.98.0

func (s *Client) ConfirmPhoneVerificationUserID(ctx context.Context, phone, code string) (string, error)

ConfirmPhoneVerificationUserID verifies a token, marks phone_verified = true, and returns the user ID.

func (*Client) ConsumeAccountRegistrationInvite ¶ added in v0.98.0

func (s *Client) ConsumeAccountRegistrationInvite(ctx context.Context, email, userID, token string) error

func (*Client) Create2FAChallenge ¶ added in v0.98.0

func (s *Client) Create2FAChallenge(ctx context.Context, userID string) (string, error)

Create2FAChallenge creates a short-lived challenge to prove password verification before 2FA.

func (*Client) CreateAccountRegistrationInvite ¶ added in v0.72.0

func (s *Client) CreateAccountRegistrationInvite(ctx context.Context, req CreateAccountRegistrationInviteRequest) (AccountRegistrationInviteCreated, error)

func (*Client) CreateGroupInviteLink ¶

func (s *Client) CreateGroupInviteLink(ctx context.Context, req CreateGroupInviteLinkRequest) (GroupInviteLinkCreated, error)

CreateGroupInviteLink mints an unbound single-use invite link. Returns the plaintext code ONCE.

func (*Client) CreateInstanceForSubject ¶ added in v0.98.0

func (s *Client) CreateInstanceForSubject(ctx context.Context, group authkit.GroupRef, displayName, ownerUserID string) (CreateInstanceResult, error)

CreateInstanceForSubject is the #263 creation path: validate the slug against the persona's creation config, gate reserved slugs on the root escalation role, consult the host admission seam, then create the group with ownerUserID seeded as owner. If the slug is already held and the caller is a member of that group, it returns Created=false instead of a conflict.

func (*Client) CreatePendingPhoneRegistrationWithLanguage ¶ added in v0.98.0

func (s *Client) CreatePendingPhoneRegistrationWithLanguage(ctx context.Context, phone, username, passwordHash, preferredLanguage string) (string, error)

func (*Client) CreatePendingRegistrationWithLanguage ¶ added in v0.98.0

func (s *Client) CreatePendingRegistrationWithLanguage(ctx context.Context, email, username, passwordHash string, ttl time.Duration, preferredLanguage string) (string, error)

func (*Client) CreatePermissionGroup ¶

func (s *Client) CreatePermissionGroup(ctx context.Context, req CreatePermissionGroupRequest) (string, error)

CreatePermissionGroup validates containment against the schema, resolves the parent group, creates the group, and (atomically) seeds the owner assignment. Returns the INTERNAL group id (for the caller's own bookkeeping; never exposed over the wire).

func (*Client) CreateUser ¶

func (s *Client) CreateUser(ctx context.Context, email, username string) (*User, error)

CreateUser inserts a new user with the given email and username.

func (*Client) DefineGroupCustomRole ¶ added in v0.98.0

func (s *Client) DefineGroupCustomRole(ctx context.Context, actorUserID string, group authkit.GroupRef, def authkit.CustomRoleDef) error

DefineGroupCustomRole creates/updates a custom role in the group addressed by (persona, instanceSlug), acting as actorUserID. Requires the persona to allow custom roles; every permission must be a valid grant pattern in that persona's namespace (namespace purity) and must not collide with a catalog role name. requiresMFA mirrors RoleDef.RequiresMFA for catalog roles (#247).

#247 SECURITY: redefining an EXISTING custom role is a DEFERRED grant (a widened grant set) — and, for a narrowed one, a deferred revoke — to EVERY subject currently holding it, the same class of risk invite-minting already gates (AK2-AUTHZ-1). Without this check, a bounded admin holding <persona>:roles:manage (but not the role's own grants) could redefine a role someone else holds to the full catalog, instantly widening their OWN effective grants without ever passing AssignGroupRoleAs's no-escalation gate. The actor must hold roles:manage AND already cover every permission in BOTH the role's current grants (if it exists) and the requested ones.

func (*Client) DelegationAuthorizer ¶ added in v0.98.0

func (s *Client) DelegationAuthorizer() DelegationAuthorizer

DelegationAuthorizer returns the host-injected delegated-token authorizer (#277), nil when none was wired.

func (*Client) DeleteGroupCustomRole ¶ added in v0.98.0

func (s *Client) DeleteGroupCustomRole(ctx context.Context, actorUserID string, group authkit.GroupRef, role authkit.Role) error

DeleteGroupCustomRole removes a custom role from a group, acting as actorUserID. #247 SECURITY: deleting a role is a DEFERRED REVOKE from every subject currently holding it, gated by the same capability + no-escalation rule as DefineGroupCustomRole (covering the role's stored grants; a not-yet-defined role has nothing to revoke, so only the capability check applies).

func (*Client) DeleteGroupInstanceByID ¶ added in v0.98.0

func (s *Client) DeleteGroupInstanceByID(ctx context.Context, groupID string, opts DeletePermissionGroupOptions) error

DeleteGroupInstanceByID is the trusted host's lifecycle primitive. The host authorizes deletion before calling it; retries always target the captured UUID. ReleaseSlug releases the current name only, preserving earlier reservations.

func (*Client) DeletePasskey ¶ added in v0.98.0

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

func (*Client) DeletePendingPhoneRegistrationByPhone ¶ added in v0.98.0

func (s *Client) 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 (*Client) DeletePendingRegistrationByEmail ¶ added in v0.98.0

func (s *Client) 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 (*Client) DeletePermissionGroup ¶ added in v0.88.0

func (s *Client) DeletePermissionGroup(ctx context.Context, group authkit.GroupRef, opts DeletePermissionGroupOptions) error

DeletePermissionGroup deletes a group instance (children, role assignments, api keys, and remote applications cascade). Delete-time naming rule (#264 ruling 5): by DEFAULT the slug is TOMBSTONED to the group uuid forever — fail-safe, published references can never be re-claimed. Passing ReleaseSlug frees the name instead; that is safe ONLY for names nothing ever referenced, and the judgment is the host's. authkit itself never deletes a group — dormancy policy is entirely host-side.

func (*Client) DeleteRemoteApplication ¶

func (s *Client) DeleteRemoteApplication(ctx context.Context, issuer string) error

DeleteRemoteApplication removes a remote_application by OIDC issuer URL.

func (*Client) DeriveUsernameForOAuth ¶ added in v0.98.0

func (s *Client) DeriveUsernameForOAuth(ctx context.Context, provider, preferred, email, displayName string) string

DeriveUsernameForOAuth prefers provider-preferred usernames; falls back to email local part or display name.

func (*Client) Disable2FAFactorWithRemovedRoles ¶ added in v0.98.0

func (s *Client) Disable2FAFactorWithRemovedRoles(ctx context.Context, userID, factorID string) ([]RemovedMFARoleAssignment, error)

func (*Client) Disable2FAWithRemovedRoles ¶ added in v0.98.0

func (s *Client) Disable2FAWithRemovedRoles(ctx context.Context, userID string) ([]RemovedMFARoleAssignment, error)

Disable2FAWithRemovedRoles disables account MFA and removes active user role assignments whose catalog role requires MFA.

func (*Client) DocumentStore ¶ added in v0.98.0

func (s *Client) DocumentStore() documents.Store

DocumentStore returns the engine-owned documents.Store over the signed_documents table (migration 0005). Digest immutability is enforced by the guarded upsert: an existing digest only ever accepts a compact-JWS replacement for the SAME type + payload bytes.

func (*Client) Enable2FA ¶ added in v0.98.0

func (s *Client) Enable2FA(ctx context.Context, userID, method string, phoneNumber *string, mode FactorEnrollmentMode) ([]string, error)

Enable2FA enables two-factor authentication for a user and generates backup codes. Returns the plaintext backup codes (caller must show these to user ONCE).

func (*Client) Enable2FADefault ¶ added in v0.98.0

func (s *Client) Enable2FADefault(ctx context.Context, userID, method string, phoneNumber *string, mode FactorEnrollmentMode) ([]string, error)

func (*Client) EnableTOTP2FA ¶ added in v0.98.0

func (s *Client) EnableTOTP2FA(ctx context.Context, in TOTPEnrollment) ([]string, error)

EnableTOTP2FA verifies the pending secret and enables authenticator-app 2FA for the user, returning fresh backup codes.

func (*Client) EnrollTwoFactor ¶ added in v0.98.0

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

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

func (*Client) EnsureRootGroup ¶

func (s *Client) EnsureRootGroup(ctx context.Context) (string, error)

EnsureRootGroup creates the singleton root group if absent (idempotent) and returns its internal id. Concurrent cold boots race the singleton index; the loser adopts the winner's row instead of failing (#258).

func (*Client) EntitlementsProvider ¶

func (s *Client) EntitlementsProvider() EntitlementsProvider

func (*Client) EphemeralBackend ¶ added in v0.98.0

func (s *Client) EphemeralBackend() string

EphemeralBackend names the live ephemeral store: "redis", "memory", "custom" (a host-supplied EphemeralStore) or "none".

func (*Client) EphemeralRedisClient ¶ added in v0.98.0

func (s *Client) EphemeralRedisClient() *redis.Client

EphemeralRedisClient returns the *redis.Client backing the engine's ephemeral store when it is Redis-backed (Deps.Redis), or nil for a memory store. The HTTP transport reuses it so a host that wired Redis on the engine doesn't also have to pass it to authhttp — one Redis client, no split-brain ephemeral state (authkit #210). The type assertion is also THE redis-vs-memory discriminator.

func (*Client) ExchangeRefreshToken ¶

func (s *Client) ExchangeRefreshToken(ctx context.Context, refreshToken string, ua string, ip net.IP) (idToken string, expiresAt time.Time, newRefresh string, err error)

ExchangeRefreshToken rotates a refresh token and returns a new ID token + refresh token.

func (*Client) ExternalInvitesEnabled ¶

func (s *Client) ExternalInvitesEnabled() bool

ExternalInvitesEnabled exposes the registration-mode gate for HTTP adapters (so a closed-registration deployment can omit/zero the invite-link routes).

func (*Client) FinishDeviceKeyEnrollment ¶ added in v0.98.0

func (s *Client) FinishDeviceKeyEnrollment(ctx context.Context, enrollmentID, code, signature, secondFactor string) (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 it (secondFactor: a factor code or backup code) — email possession alone never enrolls a standing credential on an MFA-protected account (#293).

func (*Client) FinishDeviceKeyLogin ¶ added in v0.98.0

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

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

func (*Client) FinishDiscoverablePasskeyVerification ¶ added in v0.98.0

func (s *Client) FinishDiscoverablePasskeyVerification(ctx context.Context, response []byte) (VerifiedPasskey, error)

FinishDiscoverablePasskeyVerification validates the assertion and returns the verified user/credential without minting any session or token.

func (*Client) FinishPasskeyAccount ¶ added in v0.98.0

func (s *Client) FinishPasskeyAccount(ctx context.Context, response []byte) (*User, Passkey, error)

FinishPasskeyAccount consumes the ceremony once, validates the credential, then inserts the user (no email/username/password), its handle and the passkey in one transaction. A replayed or concurrent finish cannot create a second user because the ceremony consume is atomic.

func (*Client) FinishPasskeyLogin ¶ added in v0.98.0

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

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

func (*Client) FinishPasskeyRegistration ¶ added in v0.98.0

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

func (*Client) FinishPasskeyReplacement ¶ added in v0.98.0

func (s *Client) FinishPasskeyReplacement(ctx context.Context, userID string, response []byte) (Passkey, error)

FinishPasskeyReplacement registers the new credential and tombstones every other active passkey of the user in the same transaction, for hosts with a single-passkey policy. Any failure leaves the prior passkeys active.

func (*Client) GenerateAvailableUsername ¶ added in v0.98.0

func (s *Client) GenerateAvailableUsername(ctx context.Context, base string) string

GenerateAvailableUsername tries base, then minimal numeric suffixes, then a short fallback.

func (*Client) GenerateSIWSChallenge ¶ added in v0.98.0

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

GenerateSIWSChallenge creates a new SIWS challenge for the given address. The challenge is stored in the cache and must be verified within 15 minutes.

func (*Client) Genesis ¶ added in v0.79.0

func (s *Client) Genesis() GenesisClient

Genesis returns the unchecked bootstrap/migration sub-client. See GenesisClient.

func (*Client) Get2FASettings ¶ added in v0.98.0

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

Get2FASettings retrieves a user's 2FA settings

func (*Client) GetPendingPhoneRegistrationByPhone ¶ added in v0.98.0

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

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

func (*Client) GetPendingRegistrationByEmail ¶ added in v0.98.0

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

GetPendingRegistrationByEmail looks up a pending registration by email.

func (*Client) GetPreferredLanguage ¶ added in v0.98.0

func (s *Client) GetPreferredLanguage(ctx context.Context, userID string) (PreferredLanguage, error)

func (*Client) GetProviderLinkByIssuer ¶ added in v0.98.0

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

Issuer-based provider link helpers (preferred)

func (*Client) GetRemoteApplication ¶

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

GetRemoteApplication returns a remote_application by OIDC issuer URL.

func (*Client) GetRemoteApplicationBySlug ¶ added in v0.98.0

func (s *Client) GetRemoteApplicationBySlug(ctx context.Context, slug string) (*RemoteApplication, error)

GetRemoteApplicationBySlug returns a remote_application by slug.

func (*Client) GetSolanaAddress ¶ added in v0.98.0

func (s *Client) GetSolanaAddress(ctx context.Context, userID string) (string, error)

GetSolanaAddress retrieves the Solana wallet address linked to a user, if any.

func (*Client) GetSolanaLinkedAccount ¶ added in v0.98.0

func (s *Client) GetSolanaLinkedAccount(ctx context.Context, userID string) (*SolanaLinkedAccount, error)

GetSolanaLinkedAccount retrieves the SIWS-linked wallet and its AuthKit-owned metadata.

func (*Client) GetUserByEmail ¶

func (s *Client) GetUserByEmail(ctx context.Context, email string) (*User, error)

GetUserByEmail looks up a user by email.

func (*Client) GetUserByPhone ¶

func (s *Client) GetUserByPhone(ctx context.Context, phone string) (*User, error)

GetUserByPhone looks up a user by phone number.

func (*Client) GetUserByUsername ¶

func (s *Client) GetUserByUsername(ctx context.Context, username string) (*User, error)

GetUserByUsername looks up a user by username.

func (*Client) GetUserMetadata ¶

func (s *Client) GetUserMetadata(ctx context.Context, userID string) (map[string]any, error)

GetUserMetadata returns a user's arbitrary metadata (internal/admin flags).

func (*Client) GroupInstanceByID ¶ added in v0.98.0

func (s *Client) GroupInstanceByID(ctx context.Context, groupID string) (GroupInstance, error)

GroupInstanceByID reads the identity already resolved by a host. It never interprets the UUID as a mutable name.

func (*Client) GroupInstanceForSlug ¶ added in v0.93.0

func (s *Client) GroupInstanceForSlug(ctx context.Context, group authkit.GroupRef) (GroupInstance, error)

GroupInstanceForSlug reads one instance's own identity — id, persona, slug, display name (#269). This is the read behind GET /<persona>/:instance_slug: the id is a JOIN KEY a host needs for its own ledger rows, never an address. Authorization is the caller's job (the route gates on <persona>:settings:read).

func (*Client) GroupNamingState ¶ added in v0.98.0

func (s *Client) GroupNamingState(ctx context.Context, id string) (authkit.NamingState, error)

func (*Client) HardDeleteUser ¶

func (s *Client) HardDeleteUser(ctx context.Context, userID string) error

HardDeleteUser permanently deletes the user row and dependent AuthKit rows via ON DELETE CASCADE.

func (*Client) HardDeleteUserAs ¶ added in v0.98.0

func (s *Client) HardDeleteUserAs(ctx context.Context, actorUserID, userID string) error

HardDeleteUserAs is the actor-aware HardDeleteUser.

func (*Client) HardDeleteUsers ¶ added in v0.80.0

func (s *Client) HardDeleteUsers(ctx context.Context, userIDs []string) ([]authkit.OpResult, error)

func (*Client) HasEmailSender ¶

func (s *Client) HasEmailSender() bool

HasEmailSender returns true if an email sender is configured.

func (*Client) HasPassword ¶ added in v0.98.0

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

HasPassword reports whether the user has a local password set.

func (*Client) HasProviderLink ¶ added in v0.98.0

func (s *Client) 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 (*Client) HasSMSSender ¶

func (s *Client) HasSMSSender() bool

HasSMSSender returns true if an SMS sender is configured.

func (*Client) ImportUnverifiedSolanaLinks ¶ added in v0.97.1

func (s *Client) ImportUnverifiedSolanaLinks(ctx context.Context, inputs []ImportUnverifiedSolanaLinkInput) (ImportUnverifiedSolanaLinksResult, error)

ImportUnverifiedSolanaLinks imports legacy wallet claims with one outcome per input row. It never verifies a wallet: only a successful SIWS proof may promote an imported claim. Migration tooling only; runtime request handlers must use the normal proof-aware Solana link flow.

func (*Client) ImportUser ¶ added in v0.98.0

func (s *Client) ImportUser(ctx context.Context, input ImportUserInput) (*User, error)

func (*Client) ImportUsers ¶

func (s *Client) ImportUsers(ctx context.Context, inputs []ImportUserInput) (ImportUsersResult, error)

ImportUsers bulk-imports users for fast legacy migration (target: 500k+). It is the sole import API: validate/normalize happens in Go (identical to the legacy single-row path) so accuracy is preserved, then clean rows load via chunked multi-row INSERTs — no per-row round-trips.

Semantics are INSERT-OR-SKIP (not upsert): a row whose username/email/phone already exists, or which duplicates an earlier row in the same batch, is skipped and reported, never overwritten. This makes a re-run idempotent (resume a partial import) without clobbering changes a user made after they were imported. Invalid rows are rejected individually and never abort the batch.

Each input may carry an optional pre-hashed PasswordHash; for inserted rows it is stored verbatim (the verify-time hash whitelist still governs login).

func (*Client) IsUserReserved ¶ added in v0.98.0

func (s *Client) IsUserReserved(ctx context.Context, userID string) (bool, error)

IsUserReserved reports whether a user is a reserved, non-loginable placeholder (the `reserved` metadata flag). The login gate (ensureUserAccess) consults it so reserved placeholders cannot authenticate. The owner-namespace reservation FLOW that set this flag was removed in the permission-group hard cut (#111); the read gate stays as defense-in-depth for any externally-set flag.

func (*Client) IssueAuthenticatedSession ¶ added in v0.98.0

func (s *Client) IssueAuthenticatedSession(ctx context.Context, userID, userAgent string, ip net.IP, authMethods []string, extra map[string]any) (sessionID, refreshToken, accessToken string, accessExpiresAt time.Time, refreshExpiresAt *time.Time, err error)

IssueAuthenticatedSession creates a refresh session AND mints its paired access token for an ALREADY-AUTHENTICATED user in one shot (#227). It loads + gates the user row (ensureUserAccess) and computes MFAStatus ONCE, threading both through the session-creation gate and the access-token mint — instead of the 2× user-read / 2× MFA-read that the separate IssueRefreshSession* + MintAccessToken calls incurred on the password-login and 2FA-verify paths.

authMethods records how the session was established (e.g. []string{"pwd"} for password login, []string{"pwd","otp","mfa"} after a verified second factor). extra is merged into the access token; the freshly-created session id is added as "sid". The banned/deleted/reserved gate and the MFA gate behave exactly as they do for the separate calls (same ErrUserBanned / ErrTwoFAEnrollmentRequired at the same point). Returns the session id so the caller can emit its own session-created audit log.

func (*Client) IssueLoginSession ¶ added in v0.98.0

func (s *Client) IssueLoginSession(ctx context.Context, in LoginSessionInput) (IssuedSession, error)

IssueLoginSession creates the refresh session, mints its access token and writes the session-created audit event — the shared tail of every login. The liveness and MFA gates fire exactly as IssueAuthenticatedSession does (ErrUserBanned, ErrTwoFAEnrollmentRequired).

func (*Client) IssueRefreshSession ¶ added in v0.98.0

func (s *Client) IssueRefreshSession(ctx context.Context, userID, userAgent string, ip net.IP) (sessionID, refreshToken string, expiresAt *time.Time, err error)

IssueRefreshSession creates a session row and returns a new refresh token string.

func (*Client) IssueRefreshSessionWithAuthMethods ¶ added in v0.98.0

func (s *Client) IssueRefreshSessionWithAuthMethods(ctx context.Context, userID, userAgent string, ip net.IP, authMethods []string) (sessionID, refreshToken string, expiresAt *time.Time, err error)

IssueRefreshSessionWithAuthMethods creates a refresh session and records the authentication methods that established it. Callers minting a session after MFA should pass e.g. []string{"pwd", "otp", "mfa"}.

func (*Client) JWKS ¶

func (s *Client) JWKS() jwtkit.JWKS

JWKS returns a JWKS built from the CURRENT public keys — read fresh from the KeySource on every call, so a rotation is reflected on the very next request (#238).

func (*Client) LinkProviderByIssuer ¶

func (s *Client) LinkProviderByIssuer(ctx context.Context, userID, issuer, providerSlug, subject string, email *string) error

func (*Client) LinkSolanaWallet ¶ added in v0.98.0

func (s *Client) LinkSolanaWallet(ctx context.Context, cache siws.ChallengeCache, userID string, output siws.SignInOutput) error

LinkSolanaWallet links a Solana wallet to an existing user account.

func (*Client) List2FAFactors ¶ added in v0.98.0

func (s *Client) List2FAFactors(ctx context.Context, userID string) ([]TwoFactorFactor, error)

func (*Client) ListAPIKeys ¶

func (s *Client) ListAPIKeys(ctx context.Context, group authkit.GroupRef) ([]APIKey, error)

ListAPIKeys returns metadata for every API key of the permission-group addressed by (persona, instanceSlug), including revoked/expired ones. The secret is never returned.

func (*Client) ListDeviceKeys ¶ added in v0.98.0

func (s *Client) ListDeviceKeys(ctx context.Context, userID, currentID string) ([]DeviceKey, error)

ListDeviceKeys returns the user's machine credentials after proving that the device which minted the caller's token is still active.

func (*Client) ListEffectivePermissions ¶

func (s *Client) ListEffectivePermissions(ctx context.Context, subject authkit.Subject, group authkit.GroupRef) ([]string, error)

ListEffectivePermissions returns the subject's effective grant PATTERNS in the group addressed by (persona, instanceSlug) — the de-duplicated union of every perm its roles grant, with globs (e.g. `root:*`) returned VERBATIM. This is the read primitive behind a "what can I do here" introspection endpoint (#421): a client fetches it once and gates UI on the strings (glob-matching with the same authkit.Perm.Matches the server enforces with) instead of re-deriving authority from role slugs. Scoped per group instance BY DESIGN — perms are persona- namespaced, so a global union would be both large and meaningless. An unknown group ⇒ empty (no authority), not an error; real lookup failures propagate (fail-closed — never a partial set returned as if complete).

func (*Client) ListEnabledRemoteApplications ¶ added in v0.98.0

func (s *Client) ListEnabledRemoteApplications(ctx context.Context) ([]RemoteApplication, error)

ListEnabledRemoteApplications returns only the enabled remote_applications: the verification-facing snapshot a Verifier trusts issuers from.

func (*Client) ListEntitlements ¶

func (s *Client) ListEntitlements(ctx context.Context, userID string) []string

ListEntitlements returns current entitlement names for a user (fresh from the provider — a one-element batch, #221). A provider failure is logged and returned as none — callers (admin user views) degrade rather than fail.

func (*Client) ListGroupInviteLinks ¶

func (s *Client) ListGroupInviteLinks(ctx context.Context, group authkit.GroupRef) ([]GroupInviteLink, error)

ListGroupInviteLinks lists the group's invite links (active and inactive), newest first. Never returns the code or its hash.

func (*Client) ListGroupMembers ¶

func (s *Client) ListGroupMembers(ctx context.Context, group authkit.GroupRef) ([]GroupMember, error)

ListGroupMembers returns the role-assignments in the group addressed by (persona, instanceSlug).

func (*Client) ListPasskeys ¶ added in v0.98.0

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

func (*Client) ListRemoteApplications ¶

func (s *Client) ListRemoteApplications(ctx context.Context) ([]RemoteApplication, error)

ListRemoteApplications returns every registered remote_application, enabled or not (the admin read).

func (*Client) ListRemoteApplicationsForGroup ¶ added in v0.98.0

func (s *Client) ListRemoteApplicationsForGroup(ctx context.Context, group authkit.GroupRef) ([]RemoteApplication, error)

ListRemoteApplicationsForGroup returns the remote_applications whose controlling permission_group_id is the group addressed by (persona, instanceSlug) (#111). It resolves the group via the store, then filters remote_applications by permission_group_id so a per-persona management caller sees only the issuers it controls (ListRemoteApplications lists ALL groups').

func (*Client) ListSessionEvents ¶ added in v0.98.0

func (s *Client) ListSessionEvents(ctx context.Context, userID string, eventTypes ...SessionEventType) ([]AuthSessionEvent, error)

ListSessionEvents returns a user's recent session events, most recent first (capped at listSessionEventsLimit). No eventTypes means all event types.

func (*Client) ListSubjectGroups ¶

func (s *Client) ListSubjectGroups(ctx context.Context, subject authkit.Subject) ([]SubjectGroupMembership, error)

ListSubjectGroups returns every group membership a subject holds (the cross-persona discovery behind /me/groups).

func (*Client) ListUserSessions ¶

func (s *Client) ListUserSessions(ctx context.Context, userID string) ([]Session, error)

ListUserSessions lists active sessions for a user and issuer.

func (*Client) ListUsersDeletedBefore ¶

func (s *Client) ListUsersDeletedBefore(ctx context.Context, cutoff time.Time, limit int) ([]string, error)

ListUsersDeletedBefore returns user IDs for users soft-deleted before the cutoff. It is intended for retention/purge workflows in the host application.

func (*Client) LogPasswordChanged ¶ added in v0.98.0

func (s *Client) LogPasswordChanged(ctx context.Context, userID string, sessionID string, ip *string, ua *string)

LogPasswordChanged records a password change event for a user (best-effort).

func (*Client) LogPasswordRecovery ¶ added in v0.98.0

func (s *Client) LogPasswordRecovery(ctx context.Context, userID string, method, sessionID string, ip *string, ua *string)

LogPasswordRecovery records a password recovery event for a user (best-effort).

func (*Client) LogSessionCreated ¶ added in v0.98.0

func (s *Client) LogSessionCreated(ctx context.Context, userID string, method string, sessionID string, ip *string, ua *string)

LogSessionCreated records a session creation event (best-effort).

func (*Client) LogSessionFailed ¶ added in v0.98.0

func (s *Client) 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 (*Client) MFAStatus ¶ added in v0.98.0

func (s *Client) MFAStatus(ctx context.Context, userID string) (MFAStatus, error)

func (*Client) MFAStatusWith ¶ added in v0.98.0

func (s *Client) MFAStatusWith(settings *TwoFactorSettings, settingsErr error) (MFAStatus, error)

MFAStatusWith derives MFAStatus from an ALREADY-loaded Get2FASettings result (and its lookup error) instead of re-reading 2FA settings here (#228), so a caller that already read them — e.g. GET /me, which threads one Get2FASettings through MFAStatus, the step-up methods, and the step-up 2FA options — does not recompute the read. Behaviour matches MFAStatus exactly: a "no 2FA row" lookup (pgx.ErrNoRows) is the empty/disabled status, any other error propagates.

func (*Client) MarkEmailVerified ¶ added in v0.98.0

func (s *Client) MarkEmailVerified(ctx context.Context, id string) error

MarkEmailVerified records that the user's email address is verified.

func (*Client) MarkSessionAuthenticated ¶ added in v0.98.0

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

func (*Client) MarkSessionAuthenticatedWithMethods ¶ added in v0.98.0

func (s *Client) 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 (*Client) MayCreateInstance ¶ added in v0.98.0

func (s *Client) MayCreateInstance(ctx context.Context, group authkit.GroupRef, subject string) error

MayCreateInstance consults the host admission seam (#263). A nil predicate allows; a predicate error is wrapped as ErrGroupCreationRefused. The seam sees the normalized slug (#269) so a host can refuse a specific namespace outright, not merely price the attempt.

func (*Client) Mint2FAEnrollmentToken ¶ added in v0.98.0

func (s *Client) Mint2FAEnrollmentToken(ctx context.Context, userID string) (token string, expiresAt time.Time, err error)

func (*Client) MintAPIKeyWithOptions ¶

func (s *Client) MintAPIKeyWithOptions(ctx context.Context, group authkit.GroupRef, opts APIKeyMintOptions) (APIKey, string, error)

MintAPIKeyWithOptions inserts a new API key. The key references exactly ONE role (opts.Role) valid for the owning group's persona; its effective permissions are resolved from the role at use time.

func (*Client) MintAccessToken ¶ added in v0.80.0

func (s *Client) MintAccessToken(ctx context.Context, userID string, extra map[string]any) (token string, expiresAt time.Time, err error)

MintAccessToken builds and signs an access token (JWT) for the given user. Includes core registered claims plus: - entitlements (authoritative short-lived snapshot) Extra claims in `extra` are merged into the token body (e.g., sid).

func (*Client) MintDelegatedAccessToken ¶

func (s *Client) MintDelegatedAccessToken(ctx context.Context, p DelegatedAccessParams) (string, error)

MintDelegatedAccessToken signs a canonical delegated access token using the Client's internal signer. The host passes claims/params only and NEVER touches the private key. When p.Issuer is empty it defaults to the Client's configured Issuer. See the package-level MintDelegatedAccessToken for the claim contract.

func (*Client) MintRemoteApplicationAccessToken ¶

func (s *Client) MintRemoteApplicationAccessToken(ctx context.Context, p RemoteApplicationAccessParams) (string, error)

MintRemoteApplicationAccessToken signs a remote application access token using the Client's internal signer. When p.Issuer is empty it defaults to the Client's configured Issuer.

func (*Client) MintServiceJWT ¶

func (s *Client) MintServiceJWT(ctx context.Context, opts ServiceJWTMintOptions) (string, ServiceJWTClaims, error)

MintServiceJWT creates a short-lived signed service JWT from AuthKit's active signing key. It defaults to a 15-minute lifetime and stamps `token_use=service`; it does not grant host permissions by itself.

func (*Client) NamingPolicy ¶ added in v0.98.0

func (s *Client) NamingPolicy() authkit.NamingPolicy

NamingPolicy returns the normalized site policy for users and groups.

func (*Client) PasskeysEnabled ¶ added in v0.98.0

func (s *Client) 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 (*Client) PasswordLogin ¶ added in v0.98.0

func (s *Client) PasswordLogin(ctx context.Context, in PasswordLoginInput) (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 (*Client) PatchUserMetadata ¶

func (s *Client) PatchUserMetadata(ctx context.Context, userID string, patch map[string]any) error

PatchUserMetadata merges patch into a user's metadata.

func (*Client) PermissionGroupSchema ¶ added in v0.98.0

func (s *Client) PermissionGroupSchema() *GroupSchema

PermissionGroupSchema returns the validated schema this Client was built with (the intrinsic root-only schema if constructed without Config groups).

func (*Client) Postgres ¶

func (s *Client) Postgres() *pgxpool.Pool

Postgres returns the attached pgx pool (may be nil).

func (*Client) ProviderSlugs ¶ added in v0.98.0

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

ProviderSlugs returns the distinct provider slugs linked to userID.

func (*Client) PublicKeysByKID ¶

func (s *Client) 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 (*Client) PublicNativeUserRegistrationEnabled ¶ added in v0.98.0

func (s *Client) PublicNativeUserRegistrationEnabled() bool

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

func (*Client) PublicUsersByIDs ¶ added in v0.92.0

func (s *Client) PublicUsersByIDs(ctx context.Context, ids []string) (map[string]authkit.PublicUserRef, error)

PublicUsersByIDs resolves many user IDs to the PUBLIC-safe display projection in ONE query (#268): the batch read for "render N comment authors" that is safe to nest directly into a response body, because authkit.PublicUserRef has no email field at all.

Deleted/banned policy, decided once here so three hosts stop each inventing it:

• A SOFT-DELETED user resolves to a TOMBSTONE — present in the map with Deleted set and every display field blanked. Existing references (a comment, a gallery) therefore still render something stable (PublicUserRef.DisplayName → "user-<id8>") instead of silently disappearing, and a caller cannot accidentally publish a deleted account's old name.
• A BANNED user is returned normally. A ban is an ACCESS decision (see UserLivenessByIDs), not a visibility one; suppressing bans here would retroactively rewrite public history and would leak moderation state to anyone who diffed the page.
• An id that matches no row at all is ABSENT from the map, like UsersByIDs. authkit.PublicDisplayName covers that case for callers that want one branch-free lookup.

func (*Client) RBACDriftReport ¶ added in v0.72.0

func (s *Client) RBACDriftReport(ctx context.Context) (RBACDriftReport, error)

func (*Client) RecordFailedDeviceKeyEnrollment ¶ added in v0.98.0

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

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

func (*Client) RecordFailedEmailVerifyCode ¶ added in v0.98.0

func (s *Client) RecordFailedEmailVerifyCode(ctx context.Context, email string)

RecordFailedEmailVerifyCode increments the per-email failed-attempt counter for the typed email-verification code. After maxEmailVerifyCodeAttempts failures it invalidates every outstanding code/pending-registration for that address so the short numeric code cannot be brute-forced within its TTL (AK security audit F1). No-op without an ephemeral store.

func (*Client) RecordFailedPasswordlessCode ¶

func (s *Client) RecordFailedPasswordlessCode(ctx context.Context, identifier string)

func (*Client) RecordFailedPhoneVerifyCode ¶ added in v0.98.0

func (s *Client) RecordFailedPhoneVerifyCode(ctx context.Context, phone string)

RecordFailedPhoneVerifyCode is the phone twin of RecordFailedEmailVerifyCode: after maxPhoneVerifyCodeAttempts wrong guesses the outstanding code(s) for the number are invalidated. No-op without an ephemeral store.

func (*Client) RedeemGroupInviteLink ¶

func (s *Client) RedeemGroupInviteLink(ctx context.Context, code, redeemerUserID string) (RedeemGroupInviteLinkResult, error)

RedeemGroupInviteLink redeems code on behalf of the authenticated redeemerUserID: it validates the link (live, not expired/revoked, unredeemed), assigns the role in the same transaction, and stamps redeemed_at. Idempotent: if the redeemer already holds that role, it succeeds without consuming the link.

func (*Client) RedisKeyPrefix ¶ added in v0.98.0

func (s *Client) RedisKeyPrefix() string

RedisKeyPrefix is the namespace every Redis key of this deployment is written under (ephemeral store, OIDC/SIWS caches, rate-limit counters).

func (*Client) RegenerateBackupCodes ¶ added in v0.98.0

func (s *Client) 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 (*Client) Register ¶ added in v0.98.0

func (s *Client) Register(ctx context.Context, in RegisterInput) (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 / ErrEmailRegistrationUnavailable / ErrPhoneRegistrationUnavailable; engine failures carry a stage prefix and, for sends, the delivery sentinel.

func (*Client) RegisterApplicationFromDomain ¶ added in v0.88.0

func (s *Client) RegisterApplicationFromDomain(ctx context.Context, domain string) (*RegisteredApplication, error)

RegisterApplicationFromDomain is the create-or-reprove registration flow (#264): fetch + validate the domain's application.json (the domain-control proof), then atomically create the remote_application row + its SERVICE-OWNED org (the application principal is the org's owner) — or, when the slug already exists as a domain-rooted application, refresh its issuer/keys/config from the re-fetched document. Re-registration is the boot-time self-heal AND the rotation-from-root path: the old keypair may be gone entirely, the fresh domain proof adopts whatever the document declares now.

func (*Client) RegisterRemoteAppAttributeDef ¶ added in v0.98.0

func (s *Client) RegisterRemoteAppAttributeDef(ctx context.Context, appID, key string, version int32, definition json.RawMessage) (*RemoteAppAttributeDef, error)

RegisterRemoteAppAttributeDef stores (or updates) a definition for the remote_application. version defaults to 1 when zero. The caller authority is the remote_application itself (it owns its users' restrictions); the http layer enforces that.

func (*Client) RegistrationAllowedForEmailWithInvite ¶ added in v0.98.0

func (s *Client) RegistrationAllowedForEmailWithInvite(ctx context.Context, email, token string) (bool, error)

func (*Client) RegistrationVerificationEnabled ¶ added in v0.98.0

func (s *Client) RegistrationVerificationEnabled() bool

func (*Client) RegistrationVerificationPolicy ¶ added in v0.98.0

func (s *Client) RegistrationVerificationPolicy() RegistrationVerificationPolicy

RegistrationVerificationPolicy returns the effective registration verification policy ("none" when unset/invalid).

func (*Client) RegistrationVerificationRequired ¶ added in v0.98.0

func (s *Client) RegistrationVerificationRequired() bool

func (*Client) RemoveGroupSubjectAs ¶

func (s *Client) RemoveGroupSubjectAs(ctx context.Context, actorUserID string, group authkit.GroupRef, subject authkit.Subject) error

RemoveGroupSubjectAs strips every role a subject holds in a group. It enforces the #136 capability + no-escalation rules for EVERY role the subject currently holds before stripping them, so a bounded admin cannot remove a member whose authority it does not itself hold (e.g. a non-owner cannot remove an owner).

func (*Client) RemoveRoleBySlug ¶

func (s *Client) RemoveRoleBySlug(ctx context.Context, userID string, role authkit.Role) error

func (*Client) RemoveRoleBySlugAs ¶

func (s *Client) RemoveRoleBySlugAs(ctx context.Context, actorUserID, userID string, role authkit.Role) error

RemoveRoleBySlugAs is the actor-aware root-group revoke.

func (*Client) RemoveRolesBySlugAs ¶ added in v0.80.0

func (s *Client) RemoveRolesBySlugAs(ctx context.Context, actorUserID string, userIDs []string, role authkit.Role) ([]authkit.OpResult, error)

func (*Client) RenamePasskey ¶ added in v0.98.0

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

func (*Client) RequestEmailChange ¶ added in v0.98.0

func (s *Client) 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 via ConfirmEmailChange. The old address is not notified by AuthKit (only a security log line); a host that wants that notification sends it itself.

func (*Client) RequestEmailVerification ¶ added in v0.98.0

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

RequestEmailVerification creates a verification code and dispatches an email.

func (*Client) RequestPasswordReset ¶ added in v0.98.0

func (s *Client) 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 (*Client) RequestPhoneChange ¶ added in v0.98.0

func (s *Client) 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 (*Client) RequestPhonePasswordReset ¶ added in v0.98.0

func (s *Client) 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 (*Client) RequestPhoneVerification ¶ added in v0.98.0

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

RequestPhoneVerification looks up the user by phone number and sends a verification code. This mirrors the RequestEmailVerification pattern - caller only needs to provide the phone number.

func (*Client) Require2FAForLoginFactor ¶ added in v0.98.0

func (s *Client) Require2FAForLoginFactor(ctx context.Context, userID, factorID string) (destination, method string, factor TwoFactorFactor, err error)

func (*Client) Require2FAForStepUpMethod ¶ added in v0.98.0

func (s *Client) Require2FAForStepUpMethod(ctx context.Context, userID, sessionID, method string) (destination, selectedMethod string, factor TwoFactorFactor, err error)

func (*Client) ResolveAPIKey ¶

func (s *Client) ResolveAPIKey(ctx context.Context, keyID, secret string) (groupRef string, permissions []string, err error)

ResolveAPIKey validates a presented API key (key_id + secret) and returns the owning permission-group id and the key's effective permissions resolved from its role at verify time (a role edit is reflected immediately — perms are never frozen into the key).

func (*Client) ResolveAPIKeyDetailed ¶ added in v0.72.0

func (s *Client) ResolveAPIKeyDetailed(ctx context.Context, keyID, secret string) (ResolvedAPIKey, error)

ResolveAPIKeyDetailed validates a presented API key and returns the full resolution result (id, key_id, owning group, role, and role-resolved permissions).

func (*Client) ResolveExternalIdentity ¶ added in v0.98.0

func (s *Client) ResolveExternalIdentity(ctx context.Context, in ExternalLoginInput) (userID string, created bool, err error)

ResolveExternalIdentity maps a verified provider identity to a local user without issuing a session: the explicit link target, the already-linked account, or a newly registered one (created reports the last case).

func (*Client) ResolveGroupIDForSlug ¶

func (s *Client) ResolveGroupIDForSlug(ctx context.Context, group authkit.GroupRef) (string, error)

ResolveGroupIDForSlug maps the API addressing key (persona, instanceSlug) to the group's INTERNAL id, for IN-PROCESS callers that must thread the controlling permission_group_id into a sibling resource (e.g. a remote_application's permission_group_id, #111). ErrGroupNotFound if no live group matches. Out-of-process callers use GroupInstanceForSlug, which the HTTP descriptor route exposes under an authorization gate (#269).

func (*Client) ResolveGroupSlug ¶ added in v0.98.0

func (s *Client) ResolveGroupSlug(ctx context.Context, group authkit.GroupRef) (authkit.NameResolution, error)

func (*Client) ResolveRemoteAppAttributeDef ¶

func (s *Client) ResolveRemoteAppAttributeDef(ctx context.Context, appID, key string, version int32) (*RemoteAppAttributeDef, error)

ResolveRemoteAppAttributeDef returns the definition for (appID, key, version). version <= 0 resolves the LATEST version. The returned Definition is opaque.

func (*Client) ResolveRemoteApplicationAuthority ¶

func (s *Client) ResolveRemoteApplicationAuthority(ctx context.Context, appID string) (authkit.RemoteApplicationAuthority, error)

ResolveRemoteApplicationAuthority resolves a remote_application's effective permissions — the additive walk-up of every role it holds across its controlling permission-group's parent chain (#111) — plus the owning group instance the authority is bound to (#248). Permissions is an empty slice (no error) when the app holds no roles.

func (*Client) ResolveUsername ¶ added in v0.98.0

func (s *Client) ResolveUsername(ctx context.Context, name string) (authkit.NameResolution, error)

ResolveUsername resolves current names and unexpired aliases directly to UUID.

func (*Client) RevokeAPIKey ¶

func (s *Client) RevokeAPIKey(ctx context.Context, group authkit.GroupRef, tokenID string) (bool, error)

RevokeAPIKey marks the API key revoked. It is scoped to the group so a token cannot be revoked from a different group. Returns false if no matching, not-already-revoked token exists.

func (*Client) RevokeAllSessions ¶

func (s *Client) RevokeAllSessions(ctx context.Context, userID string, keepSessionID *string) error

func (*Client) RevokeDeviceKey ¶ added in v0.98.0

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

RevokeDeviceKey idempotently revokes one key owned by the caller. The token's own key is checked live in the same transaction first, so a revoked machine cannot use the remainder of its access-token lifetime to revoke a replacement machine.

func (*Client) RevokeGroupInviteLink ¶

func (s *Client) RevokeGroupInviteLink(ctx context.Context, group authkit.GroupRef, linkID string) error

RevokeGroupInviteLink revokes a link by id, scoped to the group addressed by (persona, instanceSlug) so a manager cannot revoke another group's link.

func (*Client) RevokeOtherDeviceKeys ¶ added in v0.98.0

func (s *Client) 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 (*Client) RevokeSessionByIDForUser ¶ added in v0.98.0

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

RevokeSessionByIDForUser revokes a session by id ensuring it belongs to the user.

func (*Client) RoleSlugsByUsers ¶ added in v0.80.0

func (s *Client) RoleSlugsByUsers(ctx context.Context, userIDs []string) (map[string][]string, error)

RoleSlugsByUsers returns each user's LIVE configured root permission-group role slugs in ONE call (#220 — replaces ListRoleSlugsByUser and the error-propagating ListRoleSlugsByUserErr). The map is keyed by user id; users holding no live roles are absent. A failure resolving roles is RETURNED, not swallowed into an empty result, so authz callers can FAIL CLOSED instead of treating a backend outage as "no roles" (#136). A missing root group is genuinely empty (not an error). Root has no parent groups, so direct root-group assignments ARE the effective set. Roles that have drifted out of the configured catalog are excluded (splitConfiguredRootRoles), which is also the correct authz reading: an unconfigured role confers nothing.

func (*Client) SMSAvailable ¶

func (s *Client) SMSAvailable() bool

SMSAvailable reports whether phone-based flows should be offered: a sender is configured and (if a health check has run) it was found able to deliver.

func (*Client) SMSHealthy ¶ added in v0.98.0

func (s *Client) SMSHealthy() bool

SMSHealthy reports the last CheckSMSHealth verdict; true until a check has run.

func (*Client) Schema ¶

func (s *Client) Schema() string

Schema returns the Postgres schema AuthKit's tables live in ("profiles" unless configured otherwise via Config.Schema).

func (*Client) SeedPermissionGroupContainment ¶

func (s *Client) SeedPermissionGroupContainment(ctx context.Context) error

SeedPermissionGroupContainment writes the declared containment schema into group_persona_parents so the DB trigger can enforce tree shape. Idempotent; call once at bootstrap.

func (*Client) SendPhone2FASetupCode ¶ added in v0.98.0

func (s *Client) SendPhone2FASetupCode(ctx context.Context, userID, phone, code string) error

SendPhone2FASetupCode generates and sends a 6-digit code for 2FA setup to the user's phone.

func (*Client) SendPhoneVerificationToUser ¶ added in v0.98.0

func (s *Client) SendPhoneVerificationToUser(ctx context.Context, phone, userID string, ttl time.Duration) error

SendPhoneVerificationToUser creates a verification code and sends it via SMS to a known user. Use RequestPhoneVerification if you only have a phone number and need to look up the user. Always returns nil for security.

func (*Client) SendWelcome ¶ added in v0.98.0

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

SendWelcome triggers the welcome email if an EmailSender is configured.

func (*Client) SessionFreshness ¶ added in v0.98.0

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

func (*Client) SetDefault2FAFactor ¶ added in v0.98.0

func (s *Client) SetDefault2FAFactor(ctx context.Context, userID, factorID string) error

func (*Client) SetEntitlementsProvider ¶

func (s *Client) SetEntitlementsProvider(p EntitlementsProvider)

SetEntitlementsProvider installs the entitlements provider AFTER construction.

This is the ONE sanctioned post-construction setter — #108 otherwise removed every mutating builder in favor of constructor options. It exists for a genuine initialization CYCLE: an embedded billing engine (e.g. OpenRails) authenticates through this Client — it needs the Verifier/Core, so the Client must exist first — yet that same engine is the SOURCE of the entitlements provider, so the provider cannot exist at construction time. The host builds the Client, builds the engine with it, then installs the engine's provider here. Safe because entitlements are read LAZILY at token-mint time; call it during wiring, before serving requests. Hosts WITHOUT this cycle should set Deps.Entitlements instead.

func (*Client) SetPasswordAfterFreshAuth ¶ added in v0.98.0

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

SetPasswordAfterFreshAuth sets a new password without verifying a current one, for flows that already proved freshness (e.g. step-up). It still revokes other sessions, keeping keepSessionID if provided.

func (*Client) SetPermissionGroupDisplayName ¶ added in v0.88.0

func (s *Client) SetPermissionGroupDisplayName(ctx context.Context, group authkit.GroupRef, displayName string) error

SetPermissionGroupDisplayName updates a group's free-form, non-unique display name (#264 naming doctrine: vanity naming lives here, renameable at will; the slug stays the unique handle). Callers gate authorization.

func (*Client) SetPreferredLanguage ¶ added in v0.98.0

func (s *Client) SetPreferredLanguage(ctx context.Context, userID, language string) error

func (*Client) SetProviderUsername ¶ added in v0.98.0

func (s *Client) SetProviderUsername(ctx context.Context, userID, provider, subject, username string) error

func (*Client) SignDocument ¶ added in v0.86.0

func (s *Client) SignDocument(ctx context.Context, envelope documents.Envelope) (documents.SignedDocument, error)

SignDocument signs through the Client's live key source, so normal AuthKit key rotation applies without exposing private key material to the host.

func (*Client) SoftDeleteUser ¶

func (s *Client) SoftDeleteUser(ctx context.Context, id string) error

SoftDeleteUser marks the user deleted without dropping rows. Sessions and device keys are revoked in the same transaction.

func (*Client) SoftDeleteUserAs ¶ added in v0.98.0

func (s *Client) SoftDeleteUserAs(ctx context.Context, actorUserID, userID string) error

SoftDeleteUserAs is the actor-aware SoftDeleteUser.

func (*Client) SoftDeleteUsers ¶ added in v0.80.0

func (s *Client) SoftDeleteUsers(ctx context.Context, userIDs []string) ([]authkit.OpResult, error)

func (*Client) StartPasswordless ¶

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

func (*Client) StartTOTPEnrollment ¶ added in v0.98.0

func (s *Client) StartTOTPEnrollment(ctx context.Context, userID string) (secret, otpauthURI string, err error)

StartTOTPEnrollment creates a short-lived pending authenticator-app secret.

func (*Client) TwoFactorAllowedMethods ¶ added in v0.98.0

func (s *Client) TwoFactorAllowedMethods() []string

TwoFactorAllowedMethods is the set of currently-usable methods, in stable order. Empty when 2FA is disabled or no method's dependency is satisfied — what status and enrollment-required responses report to clients.

func (*Client) TwoFactorEnabled ¶ added in v0.98.0

func (s *Client) TwoFactorEnabled() bool

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

func (*Client) TwoFactorMethodAvailable ¶ added in v0.98.0

func (s *Client) TwoFactorMethodAvailable(method string) bool

TwoFactorMethodAvailable reports whether a second-factor method can be enrolled/used right now: enabled by policy AND its delivery dependency present.

func (*Client) UnassignGroupRole ¶ added in v0.98.0

func (s *Client) UnassignGroupRole(ctx context.Context, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

UnassignGroupRole revokes a subject's role in a group.

func (*Client) UnassignGroupRoleAs ¶

func (s *Client) UnassignGroupRoleAs(ctx context.Context, actorUserID string, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

UnassignGroupRoleAs is the actor-aware UnassignGroupRole. Revoking is gated the same way (you cannot strip a role whose authority you do not hold — e.g. a non-owner cannot remove an owner).

func (*Client) UnbanUser ¶

func (s *Client) UnbanUser(ctx context.Context, userID string) error

UnbanUser clears ban metadata and re-enables the account.

func (*Client) UnlinkProviderUnlessLast ¶ added in v0.98.0

func (s *Client) UnlinkProviderUnlessLast(ctx context.Context, userID, provider string) (bool, error)

UnlinkProviderUnlessLast atomically removes the provider link only if the user retains a login method afterward (a password, or another provider). Returns (false, nil) when removal would strip the last login method. The check and the delete run in one transaction, and UserProviderCountForUpdate locks the user's provider rows so two concurrent unlinks of different providers cannot both pass the "not last" check and leave the user with zero login methods.

func (*Client) UpdateAvatarURL ¶ added in v0.90.0

func (s *Client) UpdateAvatarURL(ctx context.Context, id string, avatarURL *string) error

UpdateAvatarURL sets (nil clears) a user's avatar URL/key string (#262). Blob storage and content validation are host-owned; authkit stores the string verbatim (trimmed) and serves it on GET /me.

func (*Client) UpdateEmail ¶

func (s *Client) UpdateEmail(ctx context.Context, id, email string) error

UpdateEmail updates a user's email and re-triggers email verification.

func (*Client) UpdateGroupInstanceAs ¶ added in v0.98.0

func (s *Client) UpdateGroupInstanceAs(ctx context.Context, actorUserID, groupID string, update authkit.GroupInstanceUpdate) (authkit.GroupInstance, error)

UpdateGroupInstanceAs applies settings to one captured UUID. It authorizes before even a no-op and never resolves a mutable spelling after authorization.

func (*Client) UpdateImportedUser ¶

func (s *Client) UpdateImportedUser(ctx context.Context, userID string, input ImportUserInput) (*User, error)

func (*Client) UpdateUsername ¶

func (s *Client) UpdateUsername(ctx context.Context, id, username string) error

UpdateUsername applies the deployment policy to an account rename.

func (*Client) UpsertPasswordHash ¶

func (s *Client) UpsertPasswordHash(ctx context.Context, userID, hash, algo string, params []byte) error

UpsertPasswordHash stores a precomputed password hash for a user.

func (*Client) UpsertRemoteApplication ¶

func (s *Client) UpsertRemoteApplication(ctx context.Context, in RemoteApplication) (*RemoteApplication, error)

UpsertRemoteApplication registers or updates a remote_application keyed by its issuer. An existing issuer can only be updated by its controlling group.

func (*Client) UpsertRoleBySlug ¶

func (s *Client) UpsertRoleBySlug(ctx context.Context, name string, role authkit.Role, description *string) error

func (*Client) UserLivenessByIDs ¶ added in v0.92.0

func (s *Client) UserLivenessByIDs(ctx context.Context, ids []string) (map[string]authkit.UserLiveness, error)

UserLivenessByIDs resolves many user IDs to their account-liveness verdict plus fresh identity fields in ONE query (#267) — the read behind verify's per-request liveness gate, and the reason a host never needs an admin-privileged user lookup to refresh a display name onto a request.

The verdict is the SAME gate that guards token mint at login and refresh (ensureUserAccess): deleted, reserved and banned accounts are denied, and an expired temporary ban is cleared and allowed. Both paths evaluate livenessAllowed, so they cannot drift.

Errors PROPAGATE. Callers are authorization gates and must fail CLOSED on a lookup failure rather than read an outage as "allowed" — the same contract RoleSlugsByUsers carries. IDs that match no row are absent from the map, which a gate must also treat as a denial.

func (*Client) UserNamingState ¶ added in v0.98.0

func (s *Client) UserNamingState(ctx context.Context, id string) (authkit.NamingState, error)

func (*Client) UserProfile ¶ added in v0.98.0

func (s *Client) UserProfile(ctx context.Context, in ProfileInput) (authkit.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_2fa").

func (*Client) UserProfileLinks ¶ added in v0.98.0

func (s *Client) UserProfileLinks(ctx context.Context, userID string) (providerSlugs []string, aliases []string, err error)

UserProfileLinks returns the user's linked provider slugs (non-null) and username aliases — the two extra lists GET /me needs beyond AdminGetUser. Keeps raw db.Queries out of the HTTP layer, which previously built its own db handle inline.

func (*Client) UsersByIDs ¶ added in v0.66.0

func (s *Client) UsersByIDs(ctx context.Context, ids []string) (map[string]authkit.UserRef, error)

UsersByIDs resolves many user IDs to slim display projections (username/email) in ONE query — the batch read behind "resolve N authors for display" without N+1 single fetches. IDs that don't exist are simply absent from the result.

PRIVILEGED: the projection carries Email. For anything rendered to other users, call PublicUsersByIDs instead (#268).

This replaces the removed authkit/identity store's batch reads. Mutations are NOT exposed here on purpose: username/email writes go through UpdateUsername/ UpdateEmail, which enforce the rename cooldown + validation that raw table writes (the old identity.Store) silently skipped.

func (*Client) ValidateUsernameForRegistration ¶ added in v0.98.0

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

func (*Client) ValidateVerificationConfiguration ¶

func (s *Client) ValidateVerificationConfiguration() error

ValidateVerificationConfiguration ensures registration verification policy can be satisfied by currently configured delivery senders.

func (*Client) Verify2FAChallenge ¶ added in v0.98.0

func (s *Client) Verify2FAChallenge(ctx context.Context, userID, challenge string) (bool, error)

Verify2FAChallenge verifies the challenge created during the password step.

func (*Client) Verify2FACode ¶ added in v0.98.0

func (s *Client) Verify2FACode(ctx context.Context, userID, code string) (bool, error)

Verify2FACode verifies a 2FA code entered by the user during login. Returns true if code is valid, false otherwise.

func (*Client) Verify2FAFactorCode ¶ added in v0.98.0

func (s *Client) Verify2FAFactorCode(ctx context.Context, userID, factorID, code string) (bool, error)

func (*Client) Verify2FAStepUpMethodCode ¶ added in v0.98.0

func (s *Client) Verify2FAStepUpMethodCode(ctx context.Context, userID, sessionID, method, code string) (bool, error)

func (*Client) VerifyBackupCode ¶ added in v0.98.0

func (s *Client) 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 (*Client) VerifyPendingPassword ¶ added in v0.98.0

func (s *Client) 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 (*Client) VerifyPendingPhonePassword ¶ added in v0.98.0

func (s *Client) 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 (*Client) VerifyPhone2FASetupCode ¶ added in v0.98.0

func (s *Client) VerifyPhone2FASetupCode(ctx context.Context, userID, phone, code string) (bool, error)

VerifyPhone2FASetupCode checks the code for 2FA phone setup.

func (*Client) VerifySIWSAndLogin ¶ added in v0.98.0

func (s *Client) VerifySIWSAndLogin(ctx context.Context, cache siws.ChallengeCache, output siws.SignInOutput, extra map[string]any) (accessToken string, expiresAt time.Time, refreshToken, userID string, created bool, err error)

VerifySIWSAndLogin verifies a SIWS signature and logs in or creates a user. Returns access token, expiry, refresh token, user ID, and whether a new user was created.

func (*DeviceKeySecondFactorRequired) Error ¶ added in v0.98.0

func (e *DeviceKeySecondFactorRequired) Error() string

func (GenesisClient) AssignGroupRole ¶ added in v0.79.0

func (g GenesisClient) AssignGroupRole(ctx context.Context, group authkit.GroupRef, subject authkit.Subject, role authkit.Role) error

AssignGroupRole grants a role to a subject in a permission group with NO actor check and NO no-escalation enforcement. The MFA-required-role enrollment gate still applies (see GenesisClient). Bootstrap/migration only. Runtime callers use AssignGroupRoleAs.

func (GenesisClient) AssignRemoteApplicationRole ¶ added in v0.98.0

func (g GenesisClient) AssignRemoteApplicationRole(ctx context.Context, appID string, role authkit.Role) error

AssignRemoteApplicationRole grants a remote application (by id) a role in its controlling group with NO actor check and NO no-escalation enforcement (#308). Bootstrap/migration only — see GenesisClient. Runtime callers use AssignRemoteApplicationRoleAs.

func (GenesisClient) AssignRoleBySlug ¶ added in v0.79.0

func (g GenesisClient) AssignRoleBySlug(ctx context.Context, userID string, role authkit.Role) error

AssignRoleBySlug grants userID the named root-persona role with NO actor check and NO no-escalation enforcement. The MFA-required-role enrollment gate still applies (see GenesisClient). Bootstrap/migration only. Runtime callers use AssignRoleBySlugAs.

func (GenesisClient) RemoveRoleBySlug ¶ added in v0.79.0

func (g GenesisClient) RemoveRoleBySlug(ctx context.Context, userID string, role authkit.Role) error

RemoveRoleBySlug revokes userID's named root-persona role with NO actor check and NO no-escalation enforcement. Bootstrap/migration only — see GenesisClient. Runtime callers use RemoveRoleBySlugAs.

func (*GroupDirectory) GroupInstanceByID ¶ added in v0.98.0

func (d *GroupDirectory) GroupInstanceByID(ctx context.Context, id string) (authkit.GroupInstance, error)

func (*GroupDirectory) GroupInstanceForSlug ¶ added in v0.98.0

func (d *GroupDirectory) GroupInstanceForSlug(ctx context.Context, group authkit.GroupRef) (authkit.GroupInstance, error)

func (*GroupDirectory) SearchGroupInstances ¶ added in v0.98.0

func (d *GroupDirectory) SearchGroupInstances(ctx context.Context, persona authkit.Persona, query, afterSlug, afterID string, limit int) ([]authkit.GroupInstance, error)

SearchGroupInstances returns canonical slugs containing query (case insensitive, literal substring), ordered by (slug,id). Empty cursor starts the search; later pages use the last row's slug/id. Limit defaults to50 and is capped at200.