@absolutejs/auth 0.65.1 → 0.65.3

package/dist/types.d.ts

@@ -0,0 +1,438 @@
+import { CredentialsFor, CustomProviderCredentials, NonEmptyArray, OAuth2Client, OAuth2TokenResponse, ProviderConfig, ProviderOption, ProvidersMap } from 'citra';
+import { Cookie, status as statusType, redirect as redirectType } from 'elysia';
+import { ElysiaCustomStatusResponse } from 'elysia/error';
+import type { StatusMap } from 'elysia/utils';
+import type { ApiKeysConfig } from './apikeys/config';
+import type { AgentAuthConfig } from './agents/config';
+import type { AuditConfig } from './audit/config';
+import type { AuthorizationConfig } from './authorization/config';
+import type { ComplianceConfig } from './compliance/config';
+import type { CredentialsConfig } from './credentials/config';
+import type { AuthIdentityConflict } from './errors';
+import type { AuthHtmxConfig, AuthHtmxUser } from './htmx/types';
+import type { LockoutConfig } from './lockout/config';
+import type { MfaConfig } from './mfa/config';
+import type { VerificationProvider } from './verification/types';
+import type { OidcProviderConfig } from './oidc/config';
+import type { OrganizationsConfig } from './organizations/config';
+import type { PasswordlessConfig } from './passwordless/config';
+import type { PortalConfig } from './portal/config';
+import type { RolesConfig } from './roles/config';
+import type { ScimConfig } from './scim/config';
+import type { SessionsConfig } from './session/sessionsConfig';
+import type { AuthSessionStore } from './session/types';
+import type { SSOConfig } from './sso/config';
+import type { TracingConfig } from './telemetry/tracing';
+import type { WebAuthnConfig } from './webauthn/config';
+import type { WebhooksConfig } from './webhooks/config';
+export type AuthIntent = 'login' | 'link_identity' | 'link_connector';
+export type OAuth2ProviderClientConfiguration<Provider extends ProviderOption> = {
+    credentials: CredentialsFor<Provider>;
+    searchParams?: [string, string][];
+} & (ProvidersMap[Provider]['scopeRequired'] extends true ? {
+    scope: NonEmptyArray<string>;
+} : {
+    scope?: string[];
+});
+export type OAuth2ProviderConfiguration<Provider extends ProviderOption> = OAuth2ProviderClientConfiguration<Provider> | Record<string, OAuth2ProviderClientConfiguration<Provider>>;
+export type OAuth2ConfigurationOptions = {
+    [Provider in ProviderOption]?: OAuth2ProviderConfiguration<Provider>;
+};
+/** One client of a caller-defined (custom) OAuth provider: the full citra
+ *  ProviderConfig plus this app's credentials. Same optional scope /
+ *  searchParams knobs as built-in provider clients. */
+export type CustomProviderClientConfiguration = {
+    credentials: CustomProviderCredentials;
+    providerConfig: ProviderConfig;
+    scope?: string[];
+    searchParams?: [string, string][];
+};
+/** Caller-defined providers keyed by YOUR provider name (any key that isn't a
+ *  built-in citra provider). Single client or named client variants — the same
+ *  shape as providersConfiguration. Registered providers get the full route
+ *  set (authorize/callback/refresh/revoke/linked-providers) like built-ins. */
+export type CustomProvidersConfiguration = Record<string, CustomProviderClientConfiguration | Record<string, CustomProviderClientConfiguration>>;
+export type UserSessionId = `${string}-${string}-${string}-${string}-${string}`;
+/** Stamped on a session created via admin impersonation (`startImpersonation`). RFC 8693
+ *  actor semantics: `actorId`/`actorEmail` are the admin acting as the user, `reason` is
+ *  required and audited, `returnToSessionId` is the admin's own session to restore on exit.
+ *  Surfaced by userStatus so your UI can show an "impersonating" banner.
+ *
+ *  `readOnly` is the RFC 8693 §6 "down-scope the delegated session" lever, surfaced for the
+ *  app to enforce: when true this is a GHOST/observe-only session — the app should reject
+ *  writes (and suppress side-effects) so an admin can watch a member's account without
+ *  disturbing them. The package only CARRIES the flag (it can't know your routes); enforce
+ *  it in your own request guard. Absent/false = full-access acting session. */
+export type Impersonator = {
+    actorEmail?: string;
+    actorId: string;
+    readOnly?: boolean;
+    reason: string;
+    returnToSessionId?: UserSessionId;
+    startedAt: number;
+    /** Sandbox lever, surfaced for the app to enforce: when true, the app should
+     *  suppress outbound side-effects (emails / SMS / push / notifications)
+     *  triggered while acting as the member — so an admin can run a flow and watch
+     *  the behavior WITHOUT the member or their partners being contacted. Like
+     *  `readOnly`, the package only carries it; enforce it at your emitters.
+     *  Independent of `readOnly` (a session can act AND suppress = "sandbox"). */
+    suppressSideEffects?: boolean;
+};
+export type SessionData<UserType> = {
+    /** Snapshot of your user, serialized into the session at login and handed to
+     *  `protectRoute`/`userStatus` as-is — it is NOT re-read from your user table per
+     *  request. Mutations made after login (role grants, bans, tier changes) stay
+     *  invisible to existing sessions until you rewrite the snapshot with
+     *  `refreshUserSessions`. */
+    user: UserType;
+    /** OAuth provider access token. Optional: credential / SSO sessions are not backed
+     *  by a provider token, so they omit it. Only the OAuth routes (profile, refresh,
+     *  revoke) read it, and they are all gated on an `auth_provider`. */
+    accessToken?: string;
+    refreshToken?: string;
+    /** Normalized OAuth subject retained for provider operations that target an
+     *  account identifier instead of a token, such as Withings revocation. */
+    oauthSubject?: string | number;
+    expiresAt: number;
+    /** When the session was last established by an actual authentication (login, OAuth
+     *  callback, or MFA challenge — NOT a token refresh). Drives step-up `requireRecentAuth`. */
+    authenticatedAt?: number;
+    /** SAML SP-initiated Single Logout context, captured at the SAML ACS. Lets
+     *  `{ssoRoute}/saml/:org/logout` build a signed LogoutRequest (the IdP needs the original
+     *  NameID + SessionIndex) for the connection the session was created from. */
+    samlLogout?: {
+        connectionId: string;
+        nameId: string;
+        sessionIndex?: string;
+    };
+    /** Present only when this session was created via admin impersonation. */
+    impersonator?: Impersonator;
+    /** True for a guest/anonymous session (createAnonymousSession) that can later be
+     *  upgraded by a real login. */
+    anonymous?: boolean;
+};
+export type SessionRecord<UserType> = Record<UserSessionId, SessionData<UserType>>;
+export type UnregisteredSessionData = {
+    userIdentity?: JsonObject;
+    sessionInformation?: JsonObject;
+    expiresAt: number;
+    accessToken?: string;
+    refreshToken?: string;
+    oauthSubject?: string | number;
+};
+export type UnregisteredSessionRecord = Record<UserSessionId, UnregisteredSessionData>;
+export type ResolvedOAuthAuthorization = {
+    userIdentity: JsonObject;
+    accessToken: string;
+    oauthSubject?: string | number;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType?: string;
+};
+export type StatusReturn = Pick<ElysiaCustomStatusResponse<number | keyof StatusMap, unknown>, 'code' | 'response'>;
+export type OnNewUser<UserType> = (userIdentity: JsonObject) => UserType | StatusReturn | Response | Promise<UserType | StatusReturn | Response>;
+export type GetUser<UserType> = (userIdentity: JsonObject) => UserType | StatusReturn | Response | null | undefined | Promise<UserType | StatusReturn | Response | null | undefined>;
+export type CallbackCookie = Record<string, Cookie<unknown>> & {
+    auth_client: Cookie<string | undefined>;
+    auth_intent: Cookie<AuthIntent | undefined>;
+    user_session_id: Cookie<UserSessionId | undefined>;
+};
+export type CallbackContext<UserType> = {
+    providerInstance: OAuth2Client<ProviderOption>;
+    /** Configured provider name — a built-in citra key or a customProviders key. */
+    authProvider: string;
+    /** The provider's citra config — pass to instantiateUserSession so identity
+     *  extraction works for custom providers too. */
+    providerConfiguration: ProviderConfig;
+    authClient?: string;
+    authIntent: AuthIntent;
+    tokenResponse: OAuth2TokenResponse;
+    session: SessionRecord<UserType>;
+    unregisteredSession: UnregisteredSessionRecord;
+    userSessionId: UserSessionId;
+    originUrl: string;
+    cookie: CallbackCookie;
+    currentUser?: UserType;
+    status: typeof statusType;
+    redirect: typeof redirectType;
+};
+export type ResolveAuthIntent<UserType> = (({ authProvider, authClient, originUrl, session, userSessionId, currentUser }: {
+    authProvider: string;
+    authClient?: string;
+    originUrl: string;
+    session: SessionRecord<UserType>;
+    userSessionId?: UserSessionId;
+    currentUser?: UserType;
+}) => AuthIntent | Promise<AuthIntent>) | undefined;
+export type OnCallbackSuccess<UserType> = ((context: CallbackContext<UserType>) => void | Response | StatusReturn | Promise<void | Response | StatusReturn>) | undefined;
+export type OnLinkIdentity<UserType> = ((context: CallbackContext<UserType>) => void | Response | StatusReturn | Promise<void | Response | StatusReturn>) | undefined;
+export type OnLinkIdentityConflict<UserType> = ((context: CallbackContext<UserType> & {
+    conflict: AuthIdentityConflict;
+}) => void | Response | StatusReturn | Promise<void | Response | StatusReturn>) | undefined;
+export type OnLinkConnector<UserType> = ((context: CallbackContext<UserType>) => void | Response | StatusReturn | Promise<void | Response | StatusReturn>) | undefined;
+export type OnCallbackError = (({ error, authProvider, originUrl }: {
+    authProvider: string;
+    authClient?: string;
+    error: unknown;
+    originUrl: string;
+}) => void | Promise<void>) | undefined;
+export type OnAuthorizeSuccess = (({ authProvider, authClient, authIntent, authorizationUrl }: {
+    authProvider: string;
+    authClient?: string;
+    authIntent?: AuthIntent;
+    authorizationUrl: URL;
+}) => void | Promise<void>) | undefined;
+export type OnAuthorizeError = (({ error, authProvider }: {
+    authProvider: string;
+    authClient?: string;
+    error: unknown;
+}) => void | Promise<void>) | undefined;
+export type OnRefreshSuccess = (({ tokenResponse, authProvider }: {
+    tokenResponse: OAuth2TokenResponse;
+    authProvider: string;
+    authClient?: string;
+}) => void | Promise<void>) | undefined;
+export type OnRefreshError = (({ error, authProvider }: {
+    authProvider: string;
+    authClient?: string;
+    error: unknown;
+}) => void | Promise<void>) | undefined;
+export type OnProfileSuccess = (({ userProfile, authProvider }: {
+    userProfile: Record<string, unknown>;
+    authProvider: string;
+    authClient?: string;
+}) => void | Promise<void>) | undefined;
+export type OnProfileError = (({ error, authProvider }: {
+    authProvider: string;
+    authClient?: string;
+    error: unknown;
+}) => void | Promise<void>) | undefined;
+export type OnRevocationSuccess = (({ tokenToRevoke, authProvider }: {
+    tokenToRevoke: string | number;
+    authProvider: string;
+    authClient?: string;
+}) => void | Promise<void>) | undefined;
+export type OnRevocationError = (({ error, authProvider }: {
+    authProvider: string;
+    authClient?: string;
+    error: unknown;
+}) => void | Promise<void>) | undefined;
+export type OnStatus<UserType> = (({ impersonator, user }: {
+    impersonator?: Impersonator;
+    user: UserType | null;
+}) => void | Promise<void>) | undefined;
+export type OnSignOut<UserType> = (({ authProvider, userSessionId, session }: {
+    /** Set only when the session was minted by the OAuth2 `/authorize` flow —
+     *  credentials, MFA, passwordless, SSO, WebAuthn, and impersonation-minted
+     *  sessions sign out without one. Use it to revoke the upstream provider
+     *  token when present; ignore when undefined. */
+    authProvider: string | undefined;
+    userSessionId: UserSessionId;
+    session: SessionRecord<UserType>;
+}) => void | Promise<void>) | undefined;
+export type OnSessionCleanup<UserType> = (({ removedSessionCount, removedSessions, removedUnregisteredSessionCount, removedUnregisteredSessions }: {
+    /** Total removed, including SQL fast-path rows whose values were never loaded. */
+    removedSessionCount: number;
+    removedSessions: Map<UserSessionId, SessionData<UserType>>;
+    /** Total unregistered sessions removed, including SQL fast-path rows. */
+    removedUnregisteredSessionCount: number;
+    removedUnregisteredSessions: Map<UserSessionId, UnregisteredSessionData>;
+}) => void | Promise<void>) | undefined;
+export type RouteString = `/${string}`;
+export type AuthorizeRoute = `${string}/:provider${'' | `/${string}`}`;
+export type AuthConfig<UserType> = {
+    /** Canonical user resolver: load the application user for a session subject
+     *  (`sub`). REQUIRED, and the single source of truth for `UserType` — every
+     *  other user-typed callback (`credentials.getUserByEmail`,
+     *  `sso.getSsoUser`, `onCallbackSuccess`, …) is checked against the shape
+     *  `getUser` returns (via `NoInfer`), so they cannot disagree. This is also
+     *  the resolver the package uses to hydrate the typed `user` in
+     *  `protectRoute`'s context. */
+    getUser: (sub: string) => UserType | null | Promise<UserType | null>;
+    providersConfiguration: OAuth2ConfigurationOptions;
+    /** Bring-your-own OAuth providers (citra createCustomOAuth2Client) — keys
+     *  must not collide with built-in provider names. */
+    customProviders?: CustomProvidersConfiguration;
+    /** Override the `Secure` attribute on every cookie the package sets (session, OAuth state,
+     *  code_verifier, SSO nonce, ring, etc.). When omitted, defaults to
+     *  `process.env.NODE_ENV === 'production'` — matching the convention used by
+     *  express-session / iron-session / lucia / better-auth, and the only way non-browser
+     *  HTTP clients (curl, SSR fetch, test runners) can round-trip cookies on a plain-HTTP
+     *  dev server. If you run prod without setting `NODE_ENV=production`, set
+     *  `cookieSecure: true` explicitly. */
+    cookieSecure?: boolean;
+    /** OpenTelemetry instrumentation. Pass your configured `TracerProvider` (from
+     *  `@opentelemetry/sdk-trace-node` / `-web` / `-bun`) and the package emits spans for
+     *  every key flow: `auth.credentials.login`, `auth.oauth.callback`, `auth.mfa.challenge`,
+     *  `auth.webhook.deliver`, etc. Pipe the spans into Datadog / Honeycomb / Grafana Tempo /
+     *  Sentry / Jaeger / whichever APM you already pay for. `@opentelemetry/api` is an
+     *  OPTIONAL peer dep — consumers that leave `tracing` unset never load it. */
+    tracing?: TracingConfig;
+    authorizeRoute?: AuthorizeRoute;
+    profileRoute?: RouteString;
+    callbackRoute?: RouteString;
+    refreshRoute?: RouteString;
+    revokeRoute?: RouteString;
+    signoutRoute?: RouteString;
+    statusRoute?: RouteString;
+    cleanupIntervalMs?: number;
+    maxSessions?: number;
+    sessionDurationMs?: number;
+    authSessionStore?: AuthSessionStore<NoInfer<UserType>>;
+    /** Append-only audit logging. When present, `auth()` emits structured events
+     *  (register, login, mfa_*, password_reset, logout, …) from every flow into the
+     *  `auditStore` and/or `onAuditEvent` hook. SOC 2 prerequisite. */
+    audit?: AuditConfig<NoInfer<UserType>>;
+    /** Local email/password (credentials) block. Additive and optional — when present,
+     *  mounts register / verify-email / login / reset-password routes that produce the
+     *  same `SessionData<UserType>` as OAuth, transparent to `protectRoute`. */
+    credentials?: CredentialsConfig<NoInfer<UserType>>;
+    /** Passwordless login: magic links + email OTP. When present, mounts the magic-link flow
+     *  (if `onSendMagicLink` is set) and/or the OTP flow (if `onSendOtp` is set) under
+     *  `{passwordlessRoute}`; each verify route resolves the email to a user and mints the same
+     *  `SessionData<UserType>` as every other flow. */
+    passwordless?: PasswordlessConfig<NoInfer<UserType>>;
+    /** Multi-factor auth (TOTP + backup codes). When present alongside `credentials`,
+     *  `auth()` auto-wires the login MFA gate, mounts the enroll/challenge routes, and
+     *  promotes the parked session once a factor is verified. */
+    mfa?: MfaConfig<NoInfer<UserType>>;
+    /** Provider-managed phone verification (Twilio Verify, etc.). When absent,
+     * MFA can use the built-in locally generated code flow through onSendSmsCode. */
+    verificationProvider?: VerificationProvider;
+    /** Per-identity attempt throttling + account lockout on the credential login route
+     *  (progressive: locks after `maxAttempts` failures within `windowMs`). */
+    lockout?: LockoutConfig;
+    /** Self-service session management: `GET /auth/sessions` (list the caller's active
+     *  sessions) and `DELETE /auth/sessions/:id` (remote revoke). Requires an
+     *  `authSessionStore` that can enumerate sessions. */
+    sessions?: SessionsConfig<NoInfer<UserType>>;
+    /** Per-organization enterprise SSO (the WorkOS-style model). When present, mounts
+     *  `GET {ssoRoute}/oidc/:organizationId/authorize` + `.../callback`, resolves the org's
+     *  OIDC connection from `ssoConnectionStore`, verifies the id_token in-house against the
+     *  issuer's JWKS, and mints the same `SessionData<UserType>` as every other flow. */
+    sso?: SSOConfig<NoInfer<UserType>>;
+    /** SCIM 2.0 auto-provisioning for enterprise directory sync (Okta / Azure AD). When present,
+     *  mounts `{scimRoute}/Users` (+ `/ServiceProviderConfig`) with per-org bearer-token auth via
+     *  `scimTokenStore`, and maps SCIM resources to the consumer's user store through hooks. */
+    scim?: ScimConfig;
+    /** Machine-to-machine authentication: static API keys (`sk_…`) + the OAuth2
+     *  client_credentials grant. When `apiClientStore` + `accessTokenStore` are set,
+     *  mounts `{tokenRoute}` (defaults `/oauth2/token`) so registered clients can
+     *  exchange `client_id`/`client_secret` for short-lived `at_…` access tokens.
+     *  Pair with the exported `createApiKey` / `resolveApiPrincipal` / `hasScopes`
+     *  helpers to issue and guard with static keys. */
+    apikeys?: ApiKeysConfig;
+    /** Standards-first delegated agent authorization. Mounts RFC 9728 protected-resource
+     * metadata and contributes `protectAgent`, while protocol adapters normalize verified
+     * credentials into durable agent registrations + user delegations. */
+    agentAuth?: AgentAuthConfig;
+    /** OAuth2 / OIDC provider — makes your app an identity provider ("Sign in with
+     *  <yourapp>"). Mounts `{oidcRoute}/authorize` + `/token` + `/jwks` and
+     *  `/.well-known/openid-configuration`: authorization_code + mandatory PKCE, ES256
+     *  JWTs signed by a key you own (self-hosted JWKS), refresh-token rotation, and
+     *  optional DPoP (RFC 9449) sender-constrained tokens. The authorize endpoint reuses
+     *  the package session, so the IdP login gets passkeys / MFA / SSO for free. */
+    oidc?: OidcProviderConfig<NoInfer<UserType>>;
+    /** First-class multi-tenancy (the WorkOS model). When present, mounts organization +
+     *  membership + invitation routes under `{organizationsRoute}`: list the caller's orgs, create
+     *  one (caller becomes owner), invite/accept/revoke by email, and list/remove members. Ties the
+     *  bare `organizationId` used by SSO/SCIM/RBAC into a real tenant model with org-scoped roles. */
+    organizations?: OrganizationsConfig<NoInfer<UserType>>;
+    /** Admin portal — the WorkOS self-serve "setup link" model, headless. When present, mounts
+     *  `{portalRoute}` endpoints a customer's IT admin (holding a scoped setup token from
+     *  `createSetupSession`) calls to read the service-provider URLs and configure their own SSO
+     *  connection / SCIM token. JSON contract, so the portal UI can be built in any framework. */
+    portal?: PortalConfig;
+    /** Org-scoped roles & permissions (builds on `organizations`). When present, mounts routes to
+     *  list an org's role definitions and set a member's roles. Pair with
+     *  `createMembershipPermissionResolver` to make `authorization.hasPermission` turnkey. */
+    roles?: RolesConfig<NoInfer<UserType>>;
+    /** Role-based / attribute-based access control (E4). When present, `auth()` exposes a
+     *  `protectPermission(check, handler)` derive (alongside `protectRoute`) that delegates the
+     *  decision to your `hasPermission` hook — the package stays schema-agnostic about roles. */
+    authorization?: AuthorizationConfig<NoInfer<UserType>>;
+    /** GDPR/CCPA self-service compliance (E5). When present, mounts `GET {complianceRoute}/export`
+     *  (right to access) and `DELETE {complianceRoute}` (right to erasure — runs your delete hook,
+     *  revokes the user's sessions, clears the cookie). Pair with `audit.redact` for PII redaction. */
+    compliance?: ComplianceConfig<NoInfer<UserType>>;
+    /** Passwordless / passkey auth (WebAuthn). When present, mounts the registration ceremony
+     *  (`{webauthnRoute}/register/options` + `/verify`, adds a passkey to the authenticated caller)
+     *  and the authentication ceremony (`.../authenticate/options` + `/verify`, passwordless sign-in
+     *  → mints the same `SessionData<UserType>`). A `webauthnAdapter` wraps a vetted library (e.g.
+     *  `@simplewebauthn/server`); the package never bundles the WebAuthn crypto. */
+    webauthn?: WebAuthnConfig<NoInfer<UserType>>;
+    /** Signed outbound webhooks. When present, every emitted auth event (the audit taxonomy) is
+     *  HMAC-signed (Standard Webhooks scheme) and POSTed to each endpoint. Delivery is best-effort
+     *  and isolated per endpoint; configuring this alone (without `audit`) is enough to turn on
+     *  event emission. PII redaction (`audit.redact`) applies before delivery. */
+    webhooks?: WebhooksConfig;
+    /** Enable the built-in HTMX fragment routes (login, identities, connectors,
+     *  account, signout, delete-account). Supply provider display data + the
+     *  identity/connector data actions; the package owns the route wiring and
+     *  renderers. See @absolutejs/auth/ui to override individual fragments.
+     *
+     *  Only available when `UserType` has the fields the fragments render
+     *  (`sub` + optional email/name); users that don't enable HTMX are never
+     *  constrained. */
+    htmx?: NoInfer<UserType> extends AuthHtmxUser ? AuthHtmxConfig : never;
+    unregisteredSessionDurationMs?: number;
+    resolveAuthIntent?: ResolveAuthIntent<NoInfer<UserType>>;
+    onAuthorizeSuccess?: OnAuthorizeSuccess;
+    onAuthorizeError?: OnAuthorizeError;
+    onCallbackSuccess?: OnCallbackSuccess<NoInfer<UserType>>;
+    onLinkIdentity?: OnLinkIdentity<NoInfer<UserType>>;
+    onLinkIdentityConflict?: OnLinkIdentityConflict<NoInfer<UserType>>;
+    onLinkConnector?: OnLinkConnector<NoInfer<UserType>>;
+    onCallbackError?: OnCallbackError;
+    onStatus?: OnStatus<NoInfer<UserType>>;
+    onRefreshSuccess?: OnRefreshSuccess;
+    onRefreshError?: OnRefreshError;
+    onSignOut?: OnSignOut<NoInfer<UserType>>;
+    onRevocationSuccess?: OnRevocationSuccess;
+    onRevocationError?: OnRevocationError;
+    onProfileSuccess?: OnProfileSuccess;
+    onProfileError?: OnProfileError;
+    onSessionCleanup?: OnSessionCleanup<NoInfer<UserType>>;
+};
+/** The serializable subset of `AuthConfig` — the route paths, session durations, and
+ *  limits that can live in a data file (`auth.config.ts` via `defineAuthSettings`) and
+ *  be edited from tooling, separate from the code wiring (stores, hooks, callbacks)
+ *  that stays in the `auth()` call. Spread alongside the rest:
+ *  `auth({ ...defineAuthSettings({...}), authSessionStore, providersConfiguration })`. */
+export type AuthSettings = Pick<AuthConfig<unknown>, 'authorizeRoute' | 'callbackRoute' | 'cleanupIntervalMs' | 'maxSessions' | 'profileRoute' | 'refreshRoute' | 'revokeRoute' | 'sessionDurationMs' | 'signoutRoute' | 'statusRoute' | 'unregisteredSessionDurationMs'>;
+export type ClientProviderEntry = {
+    providerConfiguration: ProviderConfig;
+    requiresPKCE: boolean;
+    clientName?: string;
+    providerInstance: OAuth2Client<ProviderOption>;
+    scope?: string[];
+    searchParams?: [string, string][];
+};
+export type ClientProviderGroup = {
+    entries: Record<string, ClientProviderEntry>;
+    isSingleClient: boolean;
+};
+export type ClientProviders = Record<string, ClientProviderGroup>;
+export type InsantiateUserSessionProps<UserType> = {
+    authProvider: string;
+    /** Required for custom providers (names outside the citra registry). */
+    providerConfiguration?: ProviderConfig;
+    tokenResponse: OAuth2TokenResponse;
+    session: SessionRecord<UserType>;
+    unregisteredSession: UnregisteredSessionRecord;
+    providerInstance: OAuth2Client<ProviderOption>;
+    user_session_id: Cookie<UserSessionId | undefined>;
+    onNewUser: OnNewUser<NoInfer<UserType>>;
+    getUser: GetUser<NoInfer<UserType>>;
+    cookieSecure?: boolean;
+    resolvedAuthorization?: ResolvedOAuthAuthorization;
+    sessionDurationMs?: number;
+    unregisteredSessionDurationMs?: number;
+};
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare function isJsonValue(value: unknown): value is JsonValue;
+export declare const parseJsonObject: (value: unknown) => JsonObject;

package/dist/utils.d.ts

@@ -0,0 +1,45 @@
+import { OAuth2Client, OAuth2TokenResponse, ProviderConfig, ProviderOption } from 'citra';
+import { Cookie } from 'elysia';
+import { AuthHtmxConfig } from './htmx/types';
+import { AuthConfig, AuthSettings, InsantiateUserSessionProps, OAuth2ConfigurationOptions, ResolvedOAuthAuthorization, SessionRecord, UnregisteredSessionRecord, UserSessionId } from './types';
+export declare const defineAuthConfig: <UserType>(configuration: AuthConfig<UserType>) => AuthConfig<UserType>;
+export declare const defineAuthHtmxConfig: (htmxConfig: AuthHtmxConfig) => AuthHtmxConfig;
+export declare const defineAuthSettings: (settings: AuthSettings) => AuthSettings;
+export declare const defineProvidersConfiguration: (providersConfiguration: OAuth2ConfigurationOptions) => OAuth2ConfigurationOptions;
+export declare const getStatus: <UserType>(session: SessionRecord<UserType>, user_session_id: Cookie<UserSessionId | undefined>) => Promise<{
+    error: {
+        readonly code: "Bad Request";
+        readonly message: "Cookies are missing";
+    };
+    user: null;
+} | {
+    error: null;
+    user: NonNullable<UserType> | null;
+}>;
+export declare const instantiateUserSession: <UserType>({ authProvider, providerConfiguration, cookieSecure, session, user_session_id, unregisteredSession, tokenResponse, providerInstance, getUser, onNewUser, resolvedAuthorization, sessionDurationMs, unregisteredSessionDurationMs }: InsantiateUserSessionProps<UserType>) => Promise<Response | import("./types").StatusReturn | undefined>;
+export declare const resolveCookieSecure: (override?: boolean) => boolean;
+export declare const resolveOAuthAuthorization: ({ authProvider, providerConfiguration, providerInstance, tokenResponse, now }: {
+    authProvider: string;
+    providerConfiguration?: ProviderConfig;
+    providerInstance: OAuth2Client<ProviderOption>;
+    tokenResponse: OAuth2TokenResponse;
+    now?: number;
+}) => Promise<ResolvedOAuthAuthorization>;
+export declare const resolveOAuthTokenExpiresAt: (tokenResponse: OAuth2TokenResponse, now?: number) => number | undefined;
+type ValidateSessionProps<SessionType extends Record<string, unknown> & {
+    expiresAt: number;
+}> = {
+    user_session_id: Cookie<UserSessionId | undefined>;
+    session: Record<UserSessionId, SessionType>;
+};
+export declare const validateSession: <SessionType extends Record<string, unknown> & {
+    expiresAt: number;
+}>({ user_session_id, session }: ValidateSessionProps<SessionType>) => SessionType | undefined;
+type GetUserSessionIdProps<UserType> = {
+    cookieSecure?: boolean;
+    user_session_id: Cookie<UserSessionId | undefined>;
+    session?: SessionRecord<UserType>;
+    unregisteredSession?: UnregisteredSessionRecord;
+};
+export declare const getUserSessionId: <UserType>({ cookieSecure, user_session_id, session, unregisteredSession }: GetUserSessionIdProps<UserType>) => `${string}-${string}-${string}-${string}-${string}`;
+export {};

package/dist/vault/config.d.ts

@@ -0,0 +1,20 @@
+import { type SecretCipher } from '../compliance/cipher';
+import type { VaultStore } from './types';
+export type Vault = {
+    delete: (ownerId: string, name: string) => Promise<void>;
+    get: (ownerId: string, name: string) => Promise<string | undefined>;
+    list: (ownerId: string) => Promise<string[]>;
+    put: (ownerId: string, name: string, value: string) => Promise<void>;
+};
+export declare const createVault: ({ cipher, store }: {
+    cipher: SecretCipher;
+    store: VaultStore;
+}) => Vault;
+export type VaultKeyRotationResult = {
+    rotated: number;
+};
+export declare const rotateVaultKey: ({ newKey, oldKey, store }: {
+    newKey: string;
+    oldKey: string;
+    store: VaultStore;
+}) => Promise<VaultKeyRotationResult>;

package/dist/vault/inMemoryVaultStore.d.ts

@@ -0,0 +1,2 @@
+import type { VaultStore } from './types';
+export declare const createInMemoryVaultStore: () => VaultStore;

package/dist/vault/index.d.ts

@@ -0,0 +1,5 @@
+export { createSecretCipher, createVersionedSecretCipher, type SecretCipher } from '../compliance/cipher';
+export { createVault, rotateVaultKey, type Vault } from './config';
+export { createInMemoryVaultStore } from './inMemoryVaultStore';
+export { createNeonVaultStore, createPostgresVaultStore, vaultEntriesTable } from './postgresVaultStore';
+export type { VaultEntry, VaultStore } from './types';

package/dist/vault/postgresVaultStore.d.ts

@@ -0,0 +1,86 @@
+import { type AnyPgDatabase } from '../stores/postgres';
+import type { VaultStore } from './types';
+export declare const vaultEntriesTable: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "auth_vault_entries";
+    schema: undefined;
+    columns: {
+        created_at_ms: import("drizzle-orm/pg-core").PgBuildColumn<"auth_vault_entries", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgBigInt53Builder>, {
+            name: string;
+            tableName: "auth_vault_entries";
+            dataType: "number int53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        encrypted_value: import("drizzle-orm/pg-core").PgBuildColumn<"auth_vault_entries", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "auth_vault_entries";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        name: import("drizzle-orm/pg-core").PgBuildColumn<"auth_vault_entries", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "auth_vault_entries";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        owner_id: import("drizzle-orm/pg-core").PgBuildColumn<"auth_vault_entries", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgVarcharBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "auth_vault_entries";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        updated_at_ms: import("drizzle-orm/pg-core").PgBuildColumn<"auth_vault_entries", import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgBigInt53Builder>, {
+            name: string;
+            tableName: "auth_vault_entries";
+            dataType: "number int53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+    };
+    dialect: "pg";
+}>;
+export declare const createNeonVaultStore: (databaseUrl: string) => VaultStore;
+export declare const createPostgresVaultStore: <DB extends AnyPgDatabase>(db: DB) => VaultStore;

package/dist/vault/types.d.ts

@@ -0,0 +1,14 @@
+export type VaultEntry = {
+    createdAt: number;
+    encryptedValue: string;
+    name: string;
+    ownerId: string;
+    updatedAt: number;
+};
+export type VaultStore = {
+    deleteEntry: (ownerId: string, name: string) => Promise<void>;
+    getEntry: (ownerId: string, name: string) => Promise<VaultEntry | undefined>;
+    listAllEntries: () => Promise<VaultEntry[]>;
+    listEntries: (ownerId: string) => Promise<VaultEntry[]>;
+    saveEntry: (entry: VaultEntry) => Promise<void>;
+};

package/dist/vc/inMemoryVpStores.d.ts

@@ -0,0 +1,2 @@
+import type { PresentationRequestStore } from './openid4vp';
+export declare const createInMemoryPresentationRequestStore: () => PresentationRequestStore;