@voltro/plugin-auth 0.80.0 → 0.82.0

package/dist/index.d.ts

@@ -25,6 +25,37 @@ export declare interface AcceptInvitationWithSignUpInput {
     readonly password: string;
 }
 
+/** What the decision can read: the app's database the plugin is bound to
+ *  (undefined before the bind, and for a handler called without the plugin). */
+export declare interface AdmissionContext {
+    readonly store: DataStore | undefined;
+}
+
+/** Why a join is refused. */
+export declare interface AdmissionRefusal {
+    /** A stable code the client can branch on, e.g. `seats`. */
+    readonly reason: string;
+    /** A sentence for the person who was refused. */
+    readonly message: string;
+}
+
+/** Decide whether a person may join a tenant — `null` to let them in. */
+export declare type AdmitJoining = (joining: Joining, context: AdmissionContext) => Effect.Effect<AdmissionRefusal | null> | Promise<AdmissionRefusal | null>;
+
+/**
+ * Keep users in the app's own database.
+ *
+ * - SQL store on postgres → `postgresUserStore` over the framework's pool. The
+ *   app registers `authTables` (from `@voltro/plugin-auth/schema`) in its
+ *   `databaseHandle` so auto-migrate creates them.
+ * - `store: 'memory'` → the in-process store: nothing else in the app is
+ *   durable either, so the two stay consistent.
+ * - Any other SQL dialect → the boot fails with the reason. There is no
+ *   user store for it yet, and silently keeping users in memory beside a
+ *   durable database would lose every account on restart.
+ */
+export declare const appUserStore: (options?: PostgresUserStoreOptions) => UserStoreResolver;
+
 export declare type AssertionOutcome = {
     readonly ok: true;
     readonly result: AssertionResult;
@@ -95,6 +126,28 @@ export declare interface AuthConfig {
      *  but any concern (unverified email, suspended tenant, …) can hook here.
      *  Absent / empty ⇒ every authenticated user proceeds unchanged. */
     readonly subjectGuards?: ReadonlyArray<SubjectGuard>;
+    /** Admission: asked before anyone JOINS a tenant — a sign-up, an invitation
+     *  accepted with a new account or an existing one — and before anything is
+     *  written (the account, the membership, the redeemed invitation). A refusal
+     *  answers 403 `not_admitted` with its `reason` and `message`. The seam for a
+     *  seat limit, an invite-only tenant, an address allow-list. Absent ⇒ every
+     *  join proceeds. Signing in is not joining: subject guards govern that. */
+    readonly admit?: AdmitJoining;
+    /**
+     * Tenants a public sign-up may name (`tenantId` in the sign-up body) besides
+     * `defaultTenantId` — a readers' tenant beside the staff one. Anything else
+     * named is refused (400 `tenant_not_open`) before an account exists: the
+     * request must not choose the tenant it joins, or anyone could sign up into
+     * a stranger's. Joining a particular organisation goes through an invitation.
+     */
+    readonly signUpTenants?: ReadonlyArray<string>;
+    /** Make sure the user has a row in the app's `actors` table before their
+     *  session exists. The `audit()` mixin stamps `createdBy` / `updatedBy`
+     *  with the user id, and those columns reference `actors`, so a user with no
+     *  row there cannot write to any audited table on an FK-enforcing database.
+     *  `authRoutesPlugin` wires this to the app store it is bound to; called by
+     *  `issueUserSession`, so every session-granting path covers it. */
+    readonly ensureActor?: (user: UserRecord) => Effect.Effect<void>;
     /** Brute-force lockout. After `maxAttempts` failed credential attempts
      *  (wrong password OR wrong MFA code) within `windowSeconds`, the account —
      *  keyed by EMAIL, so an unknown address locks exactly like a real one and
@@ -141,8 +194,12 @@ export declare interface AuthPlugin extends VoltroPlugin {
 export declare const authRoutesPlugin: (options: AuthRoutesPluginOptions) => AuthPlugin;
 
 export declare interface AuthRoutesPluginOptions extends AuthConfig {
-    /** The user store backing every handler. */
-    readonly store: UserStore;
+    /**
+     * The user store backing every handler — a `UserStore`, or a
+     * `UserStoreResolver` (e.g. `appUserStore()`) that the plugin calls once the
+     * framework has opened the app's database, so users live in that database.
+     */
+    readonly store: UserStore | UserStoreResolver;
     /** Passkey config — when omitted, the four passkey routes return 501. */
     readonly passkey?: PasskeyConfig;
     /** Challenge store for the passkey ceremonies. Defaults to an in-memory
@@ -186,6 +243,13 @@ export declare interface AuthRoutesPluginOptions extends AuthConfig {
      * on while leaving either unanswered. See `ImpersonationConfig`.
      */
     readonly impersonation?: ImpersonationConfig;
+    /**
+     * Native login for cookie-less clients (React Native, desktop shells).
+     * PRESENT mounts `/auth/native/authorize`, `/native/complete` and
+     * `/native/exchange`; ABSENT mounts nothing. `redirectUris` is exact-match —
+     * an app names the custom-scheme or universal-link URL it listens on.
+     */
+    readonly native?: NativeLoginConfig;
     /** Disambiguates multiple instances of this plugin in one app. */
     readonly name?: string;
 }
@@ -240,6 +304,14 @@ export declare const CSRF_HEADER_NAME: "x-csrf-token";
  */
 export declare const dataStoreChallengeStore: (sql: SqlClient) => ChallengeStore;
 
+/**
+ * Session rows in the app's own database — the `sessions` table from
+ * `@voltro/plugin-auth/schema`, which the app registers like any other. Reads
+ * and writes go through the store the framework opened, so there is no second
+ * pool and no second schema.
+ */
+export declare const dataStoreSessionRegistry: (store: DataStore) => SessionRegistry;
+
 /** Default set of roles allowed to invite at all. */
 export declare const DEFAULT_INVITER_ROLES: ReadonlyArray<string>;
 
@@ -559,6 +631,33 @@ export declare const handleMfaUnenroll: (input: MfaUnenrollInput, store: Identit
  */
 export declare const handleMfaVerify: (input: MfaVerifyInput, store: IdentityStore & MfaStore & MembershipStore & SessionStore & TokenStore & LockoutStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
+/**
+ * `GET /native/authorize`: validate the request, store it in the pending
+ * cookie, then either complete immediately (already signed in) or send the
+ * browser to the login page.
+ */
+export declare const handleNativeAuthorize: (query: URLSearchParams, session: {
+    readonly subject: Subject;
+    readonly sessionId: string | null;
+} | null, store: TokenStore, deps: NativeRouteDeps) => Effect.Effect<HandlerResult>;
+
+/**
+ * `GET /native/complete`: the browser is back from the login page. Without a
+ * session it goes to the login page again; without a pending cookie there is
+ * nothing to complete.
+ */
+export declare const handleNativeComplete: (cookieHeader: string | undefined, session: {
+    readonly subject: Subject;
+    readonly sessionId: string | null;
+} | null, store: TokenStore, deps: NativeRouteDeps) => Effect.Effect<HandlerResult>;
+
+/**
+ * `POST /native/exchange`: consume the one-time code, check the PKCE
+ * verifier, and hand back the session value for the row the browser login
+ * created. Every failure is the same 400 — the code is single-use either way.
+ */
+export declare const handleNativeExchange: (input: NativeExchangeInput, store: TokenStore & IdentityStore & MembershipStore & SessionStore & LockoutStore, deps: NativeRouteDeps) => Effect.Effect<HandlerResult>;
+
 /** Step 3: mint assertion options for `navigator.credentials.get`. */
 export declare const handlePasskeyAssertOptions: (input: PasskeyAssertOptionsInput, store: PasskeyStore, challenges: ChallengeStore, pk: PasskeyConfig) => Effect.Effect<HandlerResult>;
 
@@ -998,6 +1097,8 @@ export declare interface InvitationDeps {
     }) => Promise<void>;
     readonly invitations?: InvitationsConfig;
     readonly now?: () => number;
+    /** Asked before an invitation is redeemed — see `AuthConfig.admit`. */
+    readonly admit?: AdmitJoining;
 }
 
 /**
@@ -1089,6 +1190,8 @@ export declare interface InvitationStore {
     readonly supersedePendingInvitations: (tenantId: string, email: string, revokedByUserId: string, now: Date) => Effect.Effect<number>;
 }
 
+export declare const isAllowedRedirectUri: (uri: string, allowed: ReadonlyArray<string>) => boolean;
+
 /** Verify a token's own HMAC (signature integrity), independent of the
  *  cookie/header match. */
 export declare const isCsrfTokenWellFormed: (token: string, secret: string) => boolean;
@@ -1119,6 +1222,11 @@ export declare const isImpersonated: (subject: Subject) => boolean;
  */
 export declare const issueCsrfToken: (secret: string) => string;
 
+export declare interface IssuedRegisteredSession extends IssuedSession {
+    /** The row's id — what `revokeSession` takes. */
+    readonly sessionId: string;
+}
+
 export declare interface IssuedSession {
     /** The opaque cookie value — `<payload>.<sig>`. */
     readonly value: string;
@@ -1126,6 +1234,18 @@ export declare interface IssuedSession {
     readonly setCookie: string;
 }
 
+/**
+ * `issueSession` with a row behind it: writes the session to the registry,
+ * stamps its id into the cookie and signs. A cookie issued here can be killed
+ * before its `exp`; one issued with plain `issueSession` cannot.
+ */
+export declare const issueRegisteredSession: (registry: Pick<SessionRegistry, "insertSession">, subject: Subject | SubjectIdentity, secret: SessionSecretInput, options?: IssueRegisteredSessionOptions) => Promise<IssuedRegisteredSession>;
+
+export declare interface IssueRegisteredSessionOptions extends IssueSessionOptions {
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
 /**
  * Mint a signed session AND build the corresponding `Set-Cookie`
  * header in one call. Apps just attach the header to their
@@ -1144,6 +1264,8 @@ export declare interface IssueSessionOptions {
     readonly ttlSeconds?: number;
     readonly domain?: string;
     readonly secure?: boolean;
+    /** Clock override (epoch ms) — a testing seam for back-dated sessions. */
+    readonly now?: () => number;
 }
 
 /**
@@ -1159,6 +1281,11 @@ export declare interface IssueSessionOptions {
  */
 export declare const issueUserSession: (user: UserRecord, store: MembershipStore & SessionStore & LockoutStore, config: AuthConfig, meta?: IssueUserSessionOptions) => Effect.Effect<{
     readonly setCookie: string;
+    /** The signed session value itself — what a cookie-less client presents on
+     *  the `x-voltro-session` header (`/auth/native/exchange` returns it). */
+    readonly value: string;
+    /** Unix seconds the session expires. */
+    readonly expiresAt: number;
     readonly subject: ReturnType<typeof subjectFromUser>;
 }>;
 
@@ -1201,6 +1328,13 @@ export declare interface IssueUserSessionOptions {
     readonly clearLoginFailures?: boolean;
 }
 
+/** Someone about to join a tenant. */
+export declare interface Joining {
+    readonly email: string;
+    readonly tenantId: string;
+    readonly via: 'sign-up' | 'invitation';
+}
+
 export { KeyedSecret }
 
 declare interface ListSessionsInput {
@@ -1431,6 +1565,40 @@ export declare const mintSecret: (ttlSeconds: number) => Omit<MintedToken, "purp
  */
 export declare const mintToken: (purpose: TokenPurpose, ttlSeconds?: number) => MintedToken;
 
+/** Lifetime of a native-login one-time code: the app redeems it within
+ *  seconds of the browser redirect; five minutes covers a slow hand-off. */
+export declare const NATIVE_CODE_TTL_S: number;
+
+export declare const NATIVE_PENDING_COOKIE: "voltro:native";
+
+export declare interface NativeExchangeInput {
+    readonly code: string;
+    readonly codeVerifier: string;
+}
+
+export declare interface NativeLoginConfig {
+    /** Exact redirect URIs the app may name — a custom scheme
+     *  (`acme://auth/callback`) or an https universal link. No wildcards. */
+    readonly redirectUris: ReadonlyArray<string>;
+    /** The web app's sign-in page, relative to the app origin. Default `/login`.
+     *  It must honour `?next=` (the auth template does). */
+    readonly loginPath?: string;
+    /** Lifetime of the pending request cookie. Default 10 minutes. */
+    readonly pendingTtlSeconds?: number;
+    /** Cookie name for the pending request. Default `voltro:native`. */
+    readonly pendingCookieName?: string;
+}
+
+/** Where the browser goes to sign in, coming back to `/native/complete`. */
+export declare const nativeLoginRedirect: (deps: NativeRouteDeps) => string;
+
+export declare interface NativeRouteDeps {
+    readonly prefix: string;
+    readonly config: AuthConfig;
+    readonly native: NativeLoginConfig;
+    readonly now?: () => number;
+}
+
 /**
  * Does this stored hash use parameters weaker than the framework's
  * current cost? `true` means "re-hash on next successful verify". A
@@ -1586,6 +1754,19 @@ export declare interface PostgresUserStoreOptions {
  */
 export declare const readSession: (cookieHeader: string | undefined, secret: SessionSecretInput) => SubjectIdentity | null;
 
+/**
+ * Keyed read over the WHOLE header bag: the `x-voltro-session` header a
+ * cookie-less client presents (React Native, a desktop shell — the value it
+ * obtained through the native login exchange), or the session cookie a browser
+ * carries. Same verify, same keyed rotation, same renewal signal as
+ * `readSessionKeyed`; only where the value comes from differs.
+ *
+ * `readSessionKeyed` stays for the callers that hold a cookie string (an SSR
+ * layout reading `request.headers.cookie`); this is what the routes and the
+ * rpc strategy use, because they must accept both.
+ */
+export declare const readSessionFromHeaders: (headers: Readonly<Record<string, string | undefined>>, secret: SessionSecretInput, options?: VerifyOptions) => VerifyResult | null;
+
 /**
  * Keyed read: the full `VerifyResult` — subject + the `kid` that
  * verified + the sliding-window `renew` flag + `exp`/`iat`. The auth
@@ -1720,6 +1901,10 @@ export declare interface SessionRecord {
     readonly lastSeenAt: Date;
 }
 
+/** The session rows an app registers and revokes — the session half of a
+ *  `UserStore`, usable without the rest of it. */
+export declare type SessionRegistry = SessionStore;
+
 export declare interface SessionRevocationChecker {
     /** Is this session still live? `false` means the row was revoked (or
      *  is past its `expiresAt`) — the caller rejects the cookie. Verdicts
@@ -1789,6 +1974,10 @@ export declare interface SessionStore {
     /** Revoke every session for the user EXCEPT `keepSessionId` — the
      *  "sign out other devices" action. Returns the count removed. */
     readonly revokeAllOtherSessions: (userId: string, keepSessionId: string) => Effect.Effect<number>;
+    /** Revoke every session for the user — "sign out everywhere": a password
+     *  reset, a deactivation, an account deletion, a security event. Returns
+     *  the count removed. */
+    readonly revokeAllSessions: (userId: string) => Effect.Effect<number>;
 }
 
 export declare interface SignInInput {
@@ -1896,7 +2085,7 @@ export declare interface SwitchTenantInput {
     readonly metadata?: Record<string, unknown>;
 }
 
-export declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify';
+export declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify' | 'native-code';
 
 /** A single-use, hashed, expiring token (magic-link / password-reset). */
 export declare interface TokenRecord {
@@ -2023,6 +2212,15 @@ export declare interface UserRecord {
 export declare interface UserStore extends IdentityStore, MfaStore, MembershipStore, SessionStore, TokenStore, InvitationStore, ImpersonationStore, PasskeyStore, LockoutStore {
 }
 
+/** What a resolver is handed once the app's database is open. */
+export declare interface UserStoreBindContext {
+    /** The framework's open pool — absent when the app runs `store: 'memory'`. */
+    readonly sql?: SqlClient;
+}
+
+/** Builds the `UserStore` once the framework has opened the app's database. */
+export declare type UserStoreResolver = (ctx: UserStoreBindContext) => UserStore;
+
 /** Verify a passkey assertion (sign-in). */
 export declare const verifyAssertion: (input: AssertionVerifyInput) => AssertionOutcome;
 
@@ -2100,8 +2298,23 @@ export declare interface VoltroPasswordStrategyOptions {
      *  routes and the rpc auth chain. Ignored without a `store`
      *  (unless a checker is passed directly). */
     readonly revocation?: SessionRevocationOptions | SessionRevocationChecker;
+    /** Session rows to check cookies against when the app mints its own
+     *  sessions (`issueRegisteredSession`): a registry, or a factory over the
+     *  app's store (`dataStoreSessionRegistry`) — built once per store, from
+     *  the `store` the framework hands every strategy. The checker is tuned by
+     *  `revocation` (options) as for `store`. */
+    readonly sessionRegistry?: SessionRegistry | ((store: DataStore) => SessionRegistry);
+    /** Refuse a cookie that carries no `metadata.sessionId` — one minted
+     *  outside the registry. Without this such a cookie is accepted as before
+     *  (stateless); with it, nothing but a registered session authenticates,
+     *  and every session can be revoked. */
+    readonly requireSessionId?: boolean;
 }
 
 export declare type WebAuthnError = 'bad-client-data' | 'wrong-type' | 'challenge-mismatch' | 'origin-mismatch' | 'rpid-mismatch' | 'user-not-present' | 'bad-auth-data' | 'no-credential' | 'unsupported-key' | 'bad-signature' | 'counter-replay';
 
+/** The subject with a session row's id stamped into its metadata — what the
+ *  strategy reads back (`sessionIdOfSubject`) to check the row. */
+export declare const withSessionId: <S extends Subject | SubjectIdentity>(subject: S, sessionId: string) => S;
+
 export { }