@voltro/plugin-auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1114 @@
+import { AuthStrategy } from '@voltro/protocol';
+import { Effect } from 'effect';
+import { KeyedSecret } from '@voltro/protocol/session';
+import { SessionSecrets } from '@voltro/protocol/session';
+import { SqlClient } from '@effect/sql/SqlClient';
+import { Subject } from '@voltro/protocol';
+import { VerifyOptions } from '@voltro/protocol/session';
+import { VerifyResult } from '@voltro/protocol/session';
+import { VoidIfEmpty } from 'effect/Types';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare type AssertionOutcome = {
+    readonly ok: true;
+    readonly result: AssertionResult;
+} | {
+    readonly ok: false;
+    readonly error: WebAuthnError;
+};
+
+export declare interface AssertionResult {
+    /** The new signature counter to persist. */
+    readonly newCounter: number;
+}
+
+export declare interface AssertionVerifyInput {
+    readonly clientDataJSON: string;
+    readonly authenticatorData: string;
+    /** base64url signature over `authenticatorData ‖ sha256(clientDataJSON)`. */
+    readonly signature: string;
+    readonly expectedChallenge: string;
+    readonly expectedOrigin: string;
+    readonly rpId: string;
+    /** The stored COSE public key (base64url) for the asserted credential. */
+    readonly storedPublicKey: string;
+    /** The stored signature counter for the credential. */
+    readonly storedCounter: number;
+}
+
+export declare interface AuthConfig {
+    readonly secret: string;
+    /** Explicit keyed secret set for zero-downtime rotation. When absent,
+     *  the set is derived from `secret` (current) + the
+     *  `VOLTRO_SESSION_SECRET_PREVIOUS` / `VOLTRO_SESSION_KID*` env vars —
+     *  so env-var rotation works without setting this. Cookies are always
+     *  SIGNED with the current key; verification also accepts `previous`. */
+    readonly secrets?: SessionSecrets;
+    readonly defaultTenantId: string;
+    readonly cookieDomain?: string;
+    readonly cookieSecure?: boolean;
+    /** Where to redirect on successful sign-in / sign-up. Default: '/'. */
+    readonly successRedirect?: string;
+    /** Injected email transport for magic-link + password-reset. When
+     *  absent, those handlers still mint + persist the token but cannot
+     *  deliver it (they return 202 so existence isn't leaked). The
+     *  documented default forwards to `@voltro/plugin-mail` via
+     *  `mailSender(mailService)`. */
+    readonly sendEmail?: SendEmail;
+    /** Absolute base URL used to build the links inside emails, e.g.
+     *  `https://app.example.com`. Defaults to '' (relative links). */
+    readonly appBaseUrl?: string;
+    /** Post-authentication subject guards. After a login path resolves the
+     *  authenticated user (credentials verified) but BEFORE a session is
+     *  issued, every guard runs against that `UserRecord`; the first to veto
+     *  (`{ ok: false }`) aborts the login with a 403 carrying its `code` and
+     *  NO session cookie. General-purpose: `@voltro/plugin-deactivation`'s
+     *  `deactivationGuard()` is the canonical one ("account deactivated"),
+     *  but any concern (unverified email, suspended tenant, …) can hook here.
+     *  Absent / empty ⇒ every authenticated user proceeds unchanged. */
+    readonly subjectGuards?: ReadonlyArray<SubjectGuard>;
+}
+
+/**
+ * The auth plugin instance also carries a pre-wired session
+ * `AuthStrategy` (keyed verify + the SAME revocation cache the HTTP
+ * routes use) so the framework's serve pipeline can slot it into the
+ * per-app auth chain — the rpc/WS path then rejects revoked sessions
+ * exactly like the `/auth/*` routes. Read it via
+ * `getAuthSessionStrategy`.
+ */
+export declare interface AuthPlugin extends VoltroPlugin {
+    readonly auth: {
+        readonly sessionStrategy: AuthStrategy;
+    };
+}
+
+export declare const authRoutesPlugin: (options: AuthRoutesPluginOptions) => AuthPlugin;
+
+export declare interface AuthRoutesPluginOptions extends AuthConfig {
+    /** The user store backing every handler. */
+    readonly store: UserStore;
+    /** Passkey config — when omitted, the four passkey routes return 501. */
+    readonly passkey?: PasskeyConfig;
+    /** Challenge store for the passkey ceremonies. Defaults to an in-memory
+     *  single-node store. */
+    readonly challengeStore?: ChallengeStore;
+    /** MFA (TOTP) enrolment config. When set, the `/auth/mfa/enroll/*`
+     *  routes are mounted so an authenticated user can enrol a second
+     *  factor; `issuer` is the label shown in their authenticator app.
+     *  Sign-in enforcement (the `/auth/mfa/verify` challenge) is ALWAYS
+     *  active for enrolled users regardless of this — it only gates the
+     *  enrolment routes. */
+    readonly mfa?: MfaConfig;
+    /** Rebind hook for switch-tenant on the live WS path — pass
+     *  `bindConnectionSubject` from `@voltro/runtime`. */
+    readonly rebind?: RebindConnection;
+    /** Route prefix. Default `/auth`. */
+    readonly prefix?: string;
+    /** Tuning for the request-time session-revocation check (TTL cache
+     *  window, default 30s; `now` is a testing seam). */
+    readonly sessionRevocation?: SessionRevocationOptions;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/** Single-use challenge storage. `key` is `<userId>:<ceremony>`. */
+export declare interface ChallengeStore {
+    readonly put: (key: string, challenge: string, ttlSeconds: number) => Effect.Effect<void>;
+    /** Read AND delete (single-use). Returns null when absent/expired. */
+    readonly take: (key: string) => Effect.Effect<string | null>;
+}
+
+/**
+ * Build a `Set-Cookie` value that clears the session cookie. Send
+ * this on logout.
+ */
+export declare const clearSessionCookie: (options?: IssueSessionOptions) => string;
+
+/** The keyed secret set a handler signs/verifies with — the explicit
+ *  `config.secrets` when set, else `config.secret` widened with the
+ *  rotation env vars. */
+export declare const configSessionSecrets: (config: AuthConfig) => SessionSecrets;
+
+export declare const CSRF_COOKIE_NAME: "voltro:csrf";
+
+export declare const CSRF_HEADER_NAME: "x-csrf-token";
+
+/**
+ * Shared-store `ChallengeStore` over the `passkeyChallenges` table (see
+ * `./schema`). Use this in ANY deployment running more than one replica:
+ * the `register/options` and `assert/options` requests may land on a
+ * different node than their matching `verify`, and a memory challenge
+ * would be missing there. Rows are:
+ *
+ *   - single-use — `take` is a single `DELETE … RETURNING` statement, so
+ *     two concurrent verifies can't both redeem the same challenge (the
+ *     loser gets zero rows); and
+ *   - short-lived — `put` stamps `expiresAt`, and `take` treats an expired
+ *     row as absent (while still deleting it). A background reaper is
+ *     optional; abandoned rows are tiny and self-invalidate.
+ *
+ * The caller owns the `SqlClient` lifecycle (same contract as
+ * `postgresUserStore`).
+ */
+export declare const dataStoreChallengeStore: (sql: SqlClient) => ChallengeStore;
+
+/** Mint a fresh WebAuthn challenge (base64url, 32 random bytes). The
+ *  server stashes it (keyed by user / ceremony) and hands it to the
+ *  browser; `verifyRegistration` / `verifyAssertion` check it back. */
+export declare const generateChallenge: () => string;
+
+/** Generate N base32 recovery codes (5 chars each, 5 groups separated
+ *  by '-'). 25-character codes, ~125 bits of entropy — enough that
+ *  brute-forcing the recovery surface is unrealistic, short enough
+ *  the user can type them. Each code is single-use; the caller must
+ *  persist them hashed (same as passwords) + mark them consumed on
+ *  use. */
+export declare const generateRecoveryCodes: (count?: number) => ReadonlyArray<string>;
+
+/** Generate the current TOTP code for a secret. Caller controls the
+ *  clock to make this testable — pass `Date.now()` in production. */
+export declare const generateTotpCode: (secretBase32: string, nowMs?: number) => string;
+
+/** Generate a fresh TOTP secret (160-bit, base32-encoded). Hand this
+ *  to the user via an otpauth URL — `otpauthUrl()` below builds it. */
+export declare const generateTotpSecret: () => string;
+
+/**
+ * Pull the pre-wired session strategy off a plugin list (the framework's
+ * serve pipeline calls this when composing the auth chain). Returns the
+ * FIRST auth plugin's strategy, or null when no auth plugin is present.
+ */
+export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugin>) => AuthStrategy | null;
+
+/**
+ * Run the config's post-authentication subject guards against a resolved
+ * user. Returns a 403 `HandlerResult` (carrying the vetoing guard's `code`
+ * as `error`) when a guard rejects the login, or `null` to let it proceed.
+ *
+ * Every login path that grants a session to a PRE-EXISTING user calls this
+ * after the credential check and before issuing the session — so a guarded
+ * account (e.g. deactivated) is turned away uniformly across password,
+ * MFA, magic-link, and passkey sign-in. Sign-up is exempt: it creates a
+ * brand-new user that no guard could yet reject.
+ */
+export declare const guardSubject: (user: UserRecord, config: AuthConfig) => Effect.Effect<HandlerResult | null>;
+
+/**
+ * Issue a CSRF token. Returns the token in the JSON body AND sets a
+ * readable (non-HttpOnly) `voltro:csrf` cookie. The SPA reads the cookie
+ * and echoes the value in the `x-csrf-token` header on every mutation;
+ * the server verifies the two match + the HMAC.
+ */
+export declare const handleCsrf: (config: AuthConfig) => HandlerResult;
+
+export declare const handleListMemberships: (input: {
+    readonly userId: string;
+}, store: UserStore) => Effect.Effect<HandlerResult>;
+
+export declare const handleListSessions: (input: ListSessionsInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+/**
+ * Consume a magic-link token: validate (single-use, unexpired) and, on
+ * success, issue a session for the bound user. Writes a session row +
+ * loads memberships, same as password sign-in.
+ */
+export declare const handleMagicLinkConsume: (input: MagicLinkConsumeInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+/**
+ * Request a magic-link. Always returns 202 regardless of whether the
+ * email exists (no account-enumeration). When the user exists we mint a
+ * single-use token, persist its hash, and call `config.sendEmail`.
+ */
+export declare const handleMagicLinkRequest: (input: MagicLinkRequestInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+export declare const handleMfaEnrollStart: (input: MfaEnrollStartInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+export declare const handleMfaEnrollVerify: (input: MfaEnrollVerifyInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+/** Regenerate the user's recovery codes — wipes the prior set and returns
+ *  a fresh plaintext batch (shown once). Only valid for an enrolled user. */
+export declare const handleMfaRegenerateRecoveryCodes: (input: MfaRegenerateRecoveryCodesInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+export declare const handleMfaUnenroll: (input: MfaUnenrollInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+/**
+ * Complete an MFA sign-in: redeem the single-use pending token, verify the
+ * submitted TOTP code (or a recovery code) against the user's stored
+ * secret, and ONLY THEN issue the real session — through the same
+ * `issueUserSession` path as password sign-in, so rotation + revocation
+ * apply. A wrong code (or missing enrolment) is a 401; the pending token is
+ * consumed on redemption regardless, so a guessed code can't be retried
+ * against the same challenge.
+ */
+export declare const handleMfaVerify: (input: MfaVerifyInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+/** Step 3: mint assertion options for `navigator.credentials.get`. */
+export declare const handlePasskeyAssertOptions: (input: PasskeyAssertOptionsInput, store: UserStore, challenges: ChallengeStore, pk: PasskeyConfig) => Effect.Effect<HandlerResult>;
+
+/** Step 4: verify the assertion (signature + strictly-increasing counter)
+ *  and issue a session. */
+export declare const handlePasskeyAssertVerify: (input: PasskeyAssertVerifyInput, store: UserStore, challenges: ChallengeStore, pk: PasskeyConfig, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+/** Step 1: mint registration options for `navigator.credentials.create`. */
+export declare const handlePasskeyRegisterOptions: (input: PasskeyRegisterOptionsInput, store: UserStore, challenges: ChallengeStore, pk: PasskeyConfig) => Effect.Effect<HandlerResult>;
+
+/** Step 2: verify the registration and persist the credential. */
+export declare const handlePasskeyRegisterVerify: (input: PasskeyRegisterVerifyInput, store: UserStore, challenges: ChallengeStore, pk: PasskeyConfig) => Effect.Effect<HandlerResult>;
+
+/** Confirm a password reset: validate the token, set the new (hashed)
+ *  password, and revoke ALL existing sessions for the user (a reset
+ *  invalidates every prior login). */
+export declare const handlePasswordResetConfirm: (input: PasswordResetConfirmInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+/** Request a password reset. Uniform 202 (no enumeration); mints + emails
+ *  a single-use reset token when the user exists. */
+export declare const handlePasswordResetRequest: (input: PasswordResetRequestInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+export declare const handleRevokeAllOtherSessions: (input: RevokeOtherSessionsInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+export declare const handleRevokeSession: (input: RevokeSessionInput, store: UserStore) => Effect.Effect<HandlerResult>;
+
+export declare interface HandlerResult {
+    readonly status: number;
+    readonly body: string;
+    readonly contentType?: string;
+    readonly setCookie?: string;
+    readonly location?: string;
+}
+
+/**
+ * Sign-in handler. Accepts either form-encoded OR JSON input with
+ * `email` + `password`. Returns:
+ *   - 200 JSON `{ ok: true, mfaRequired: true, pendingToken }` when the
+ *     user has MFA enrolled — NO session cookie is issued; the caller must
+ *     complete `POST /auth/mfa/verify` with the pending token + a TOTP (or
+ *     recovery) code before a real session is granted.
+ *   - 200 JSON with subject + Set-Cookie (for fetch-based callers) when the
+ *     user has NO MFA enrolled.
+ *   - 302 redirect when `redirectAfter` is true (form post path, non-MFA).
+ *
+ * Always runs `verifyPassword` even when the user is missing, so
+ * sign-in latency doesn't leak existence (timing-oracle defence).
+ *
+ * On the non-MFA success path it ALSO: (a) loads the user's tenant
+ * memberships and carries them on the Subject, (b) writes a `sessions` row
+ * for the device list + revocation, and (c) rehashes the stored password
+ * when it's below the current scrypt cost (rehash-on-verify).
+ */
+export declare const handleSignIn: (input: SignInInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+/**
+ * Sign-out handler. Clears the session cookie. Synchronous so it
+ * stays callable as a plain function from non-Effect call sites; no
+ * error channel because there's nothing to fail.
+ */
+export declare const handleSignOut: (config: AuthConfig) => HandlerResult;
+
+/**
+ * Sign-up handler. Creates a new user with the hashed password +
+ * issues a session immediately (auto sign-in after sign-up).
+ *
+ * Inputs failing validation collapse to 4xx HandlerResults. Storage
+ * errors (`UserAlreadyExistsError`, `PasswordHashError`) propagate
+ * via the Effect's error channel — callers either map them to 5xx or
+ * pattern-match for finer-grained responses.
+ */
+export declare const handleSignUp: (input: SignUpInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
+
+/**
+ * Switch the active tenant. Validates the user is actually a member of
+ * `targetTenantId` (the switch-tenant guard), re-issues the session
+ * cookie with the new active tenant, and — when a `clientId` + `rebind`
+ * are supplied — rebinds the live connection's Subject in place (the
+ * dispatcher re-scopes subscriptions on rebind).
+ */
+export declare const handleSwitchTenant: (input: SwitchTenantInput, store: UserStore, config: AuthConfig, rebind?: RebindConnection) => Effect.Effect<HandlerResult>;
+
+/**
+ * Hash a password. Returns a self-describing string that
+ * `verifyPassword` can re-parse without external config. Don't
+ * truncate this string — the parameters are encoded inline.
+ */
+export declare const hashPassword: (plaintext: string) => Effect.Effect<string, PasswordEmptyError | PasswordHashError>;
+
+/** Hash a plaintext token for storage / lookup. SHA-256 is sufficient —
+ *  the token is high-entropy (32 random bytes), so there's no
+ *  brute-force surface that would need a slow KDF. */
+export declare const hashToken: (plaintext: string) => string;
+
+/** Verify a token's own HMAC (signature integrity), independent of the
+ *  cookie/header match. */
+export declare const isCsrfTokenWellFormed: (token: string, secret: string) => boolean;
+
+/**
+ * Issue a fresh CSRF token: `<randomB64url>.<hmacB64url>`. Set this as a
+ * readable (non-HttpOnly) cookie AND hand it to the SPA so it can echo
+ * it in the `x-csrf-token` header.
+ */
+export declare const issueCsrfToken: (secret: string) => string;
+
+export declare interface IssuedSession {
+    /** The opaque cookie value — `<payload>.<sig>`. */
+    readonly value: string;
+    /** Ready-to-Set-Cookie header string with sane defaults. */
+    readonly setCookie: string;
+}
+
+/**
+ * Mint a signed session AND build the corresponding `Set-Cookie`
+ * header in one call. Apps just attach the header to their
+ * response. Pass a `SessionSecrets` set to sign with the current
+ * rotation key (its `kid` is stamped into the payload).
+ */
+export declare const issueSession: (subject: Subject, secret: SessionSecretInput, options?: IssueSessionOptions) => IssuedSession;
+
+export declare interface IssueSessionOptions {
+    readonly ttlSeconds?: number;
+    readonly domain?: string;
+    readonly secure?: boolean;
+}
+
+/**
+ * Issue a real session for a fully-authenticated user: load memberships,
+ * write the `sessions` row (so device-list + revocation cover it), and
+ * mint the signed cookie. Shared by password sign-in (post-MFA), sign-up,
+ * magic-link, MFA verify, and passkey assertion so rotation + revocation
+ * apply uniformly on every path that grants a session.
+ */
+export declare const issueUserSession: (user: UserRecord, store: UserStore, config: AuthConfig, meta?: {
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}) => Effect.Effect<{
+    readonly setCookie: string;
+    readonly subject: ReturnType<typeof subjectFromUser>;
+}>;
+
+export { KeyedSecret }
+
+declare interface ListSessionsInput {
+    readonly userId: string;
+}
+
+/** Default magic-link lifetime — short, since it's an inbox round-trip. */
+export declare const MAGIC_LINK_TTL_S: number;
+
+declare interface MagicLinkConsumeInput {
+    readonly token: string;
+    readonly redirectAfter?: boolean;
+}
+
+declare interface MagicLinkRequestInput {
+    readonly email: string;
+    /** Path the email link points at (the consume endpoint). Default
+     *  `/auth/magic-link/callback`. */
+    readonly callbackPath?: string;
+}
+
+/** The slice of `@voltro/plugin-mail`'s `MailService` we depend on. */
+export declare interface MailLike {
+    readonly send: (message: {
+        readonly to: string;
+        readonly subject: string;
+        readonly html: string;
+        readonly text?: string;
+    }) => Effect.Effect<unknown, unknown>;
+}
+
+/**
+ * Build a `SendEmail` hook backed by `@voltro/plugin-mail`. Wire it into
+ * `authRoutesPlugin({ sendEmail: mailSender(mail) })` where `mail` is the
+ * yielded `MailService`.
+ *
+ * ```ts
+ * const mail = yield* MailService
+ * authRoutesPlugin({ store, secret, sendEmail: mailSender(mail) })
+ * ```
+ */
+export declare const mailSender: (mail: MailLike) => SendEmail;
+
+/**
+ * Build the revocation checker over a `UserStore`'s session rows.
+ * `authRoutesPlugin` constructs one internally (options via
+ * `sessionRevocation`); `voltroPasswordStrategy({ store })` builds or
+ * accepts one so the framework's rpc auth chain enforces the same
+ * revocations the HTTP routes do.
+ */
+export declare const makeSessionRevocationChecker: (store: Pick<UserStore, "findSession">, options?: SessionRevocationOptions) => SessionRevocationChecker;
+
+/** One tenant a user belongs to. The active tenant lives on the Subject;
+ *  the full set drives the switch-tenant menu + the switch-tenant guard. */
+export declare interface MembershipRecord {
+    readonly userId: string;
+    readonly tenantId: string;
+    readonly role: string;
+    readonly joinedAt: Date;
+}
+
+/** In-memory challenge store. Single-node only — a challenge minted on one
+ *  replica is invisible to another, so this is the DEV / single-node
+ *  default. Multi-replica deployments pass `dataStoreChallengeStore`. */
+export declare const memoryChallengeStore: () => ChallengeStore;
+
+/**
+ * Build a UserStore backed by in-memory Maps. Useful for tests +
+ * dev scenarios that don't want to spin up Postgres. NOT for
+ * production — restart wipes everything.
+ */
+export declare const memoryUserStore: (seed?: ReadonlyArray<UserRecord>) => UserStore;
+
+/** Lifetime of the short-lived MFA pending token (the second-factor
+ *  challenge). Long enough for the user to fetch a TOTP code, short enough
+ *  that a leaked challenge is near-useless. */
+export declare const MFA_PENDING_TTL_S: number;
+
+/** MFA (TOTP) enrolment config. */
+export declare interface MfaConfig {
+    /** Issuer label shown in the user's authenticator app (typically your
+     *  product name, e.g. "Voltro Cloud"). */
+    readonly issuer: string;
+}
+
+export declare interface MfaEnrollStartInput {
+    readonly userId: string;
+    /** Issuer for the otpauth URL — typically your product name
+     *  ("Voltro Cloud"). Shown in the user's authenticator app. */
+    readonly issuer: string;
+    /** Account name shown in the authenticator app under the issuer.
+     *  Email is the conventional pick. */
+    readonly accountName: string;
+}
+
+export declare interface MfaEnrollVerifyInput {
+    readonly userId: string;
+    readonly code: string;
+}
+
+export declare interface MfaRegenerateRecoveryCodesInput {
+    readonly userId: string;
+}
+
+export declare interface MfaUnenrollInput {
+    readonly userId: string;
+}
+
+export declare interface MfaVerifyInput {
+    /** The pending token returned by `handleSignIn` when MFA was required. */
+    readonly pendingToken: string;
+    /** A 6-digit TOTP code. Provide this OR `recoveryCode`. */
+    readonly code?: string;
+    /** A single-use recovery (backup) code — the fallback when the
+     *  authenticator is unavailable. Provide this OR `code`. */
+    readonly recoveryCode?: string;
+    readonly redirectAfter?: boolean;
+    readonly ipAddress?: string;
+    readonly userAgent?: string;
+}
+
+export declare interface MintedToken {
+    /** The plaintext — put this in the emailed link. Never stored. */
+    readonly token: string;
+    /** SHA-256 of the plaintext — store this. */
+    readonly tokenHash: string;
+    /** Unix-ms expiry. */
+    readonly expiresAt: Date;
+    readonly purpose: TokenPurpose;
+}
+
+/**
+ * Mint a fresh single-use token. The caller persists `{ tokenHash,
+ * userId, purpose, expiresAt }` via `UserStore.insertToken` and emails
+ * the plaintext `token` in a link.
+ */
+export declare const mintToken: (purpose: TokenPurpose, ttlSeconds?: number) => MintedToken;
+
+/**
+ * Does this stored hash use parameters weaker than the framework's
+ * current cost? `true` means "re-hash on next successful verify". A
+ * malformed hash also returns `true` (it should be replaced).
+ */
+export declare const needsRehash: (stored: string) => boolean;
+
+export declare const newAuthId: (prefix: string) => string;
+
+/** Build the `otpauth://totp/...` URL the user's authenticator app
+ *  scans / imports. Both label + issuer are URL-encoded. */
+export declare const otpauthUrl: (params: {
+    readonly issuer: string;
+    readonly accountName: string;
+    readonly secret: string;
+}) => string;
+
+declare interface ParsedHash {
+    readonly N: number;
+    readonly r: number;
+    readonly p: number;
+    readonly keyLen: number;
+}
+
+/** Parse the scrypt parameters out of a stored hash. Returns null when the
+ *  string isn't a well-formed `scrypt$N$r$p$salt$derived`. */
+export declare const parseScryptParams: (stored: string) => ParsedHash | null;
+
+declare interface PasskeyAssertOptionsInput {
+    /** Optional — for a usernameless flow leave it undefined. When present
+     *  we scope `allowCredentials` to that user's registered passkeys. */
+    readonly userId?: string;
+}
+
+declare interface PasskeyAssertVerifyInput {
+    readonly credentialId: string;
+    readonly clientDataJSON: string;
+    readonly authenticatorData: string;
+    readonly signature: string;
+    /** Echo back the userId used at options time, when the flow knew it. */
+    readonly userId?: string;
+}
+
+export declare interface PasskeyConfig {
+    /** Relying-party id — the registrable domain (e.g. `example.com`). */
+    readonly rpId: string;
+    /** Human-readable RP name shown in the OS prompt. */
+    readonly rpName: string;
+    /** The exact origin ceremonies must run on (e.g. `https://app.example.com`). */
+    readonly origin: string;
+}
+
+/** A registered WebAuthn credential. */
+export declare interface PasskeyRecord {
+    readonly id: string;
+    readonly credentialId: string;
+    readonly userId: string;
+    readonly publicKey: string;
+    readonly counter: number;
+    readonly transports?: string | null;
+    readonly createdAt: Date;
+    readonly lastUsedAt: Date | null;
+}
+
+declare interface PasskeyRegisterOptionsInput {
+    readonly userId: string;
+    readonly userName: string;
+}
+
+declare interface PasskeyRegisterVerifyInput {
+    readonly userId: string;
+    readonly credentialId: string;
+    readonly clientDataJSON: string;
+    readonly authenticatorData: string;
+    readonly transports?: string;
+}
+
+/** Default password-reset lifetime — a bit longer. */
+export declare const PASSWORD_RESET_TTL_S: number;
+
+export declare class PasswordEmptyError extends PasswordEmptyError_base<{
+    readonly message: string;
+}> {
+}
+
+declare const PasswordEmptyError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "PasswordEmptyError";
+} & Readonly<A>;
+
+export declare class PasswordHashError extends PasswordHashError_base<{
+    readonly message: string;
+    readonly cause: unknown;
+}> {
+}
+
+declare const PasswordHashError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "PasswordHashError";
+} & Readonly<A>;
+
+declare interface PasswordResetConfirmInput {
+    readonly token: string;
+    readonly newPassword: string;
+}
+
+declare interface PasswordResetRequestInput {
+    readonly email: string;
+    readonly callbackPath?: string;
+}
+
+/**
+ * Build a UserStore that reads + writes the auth tables via the provided
+ * `SqlClient`. The caller owns the client's lifecycle.
+ *
+ * Find* flatten database-error channels to `never` (we treat connection
+ * issues as "not found" — surfacing lets a brute-forcer tell flaky DB
+ * from missing user). `insert` surfaces `UserAlreadyExistsError`.
+ */
+export declare const postgresUserStore: (sql: SqlClient) => UserStore;
+
+/**
+ * Read + verify the session cookie from a Cookie header string.
+ * Returns the decoded Subject or null when the cookie is missing,
+ * malformed, tampered, or expired. Never throws — callers branch
+ * on the boolean.
+ *
+ * Verification is keyed: the given secret is widened via
+ * `sessionSecretsOf`, so a cookie signed with the previous rotation
+ * key keeps verifying while `VOLTRO_SESSION_SECRET_PREVIOUS` is set.
+ */
+export declare const readSession: (cookieHeader: string | undefined, secret: SessionSecretInput) => Subject | null;
+
+/**
+ * Keyed read: the full `VerifyResult` — subject + the `kid` that
+ * verified + the sliding-window `renew` flag + `exp`/`iat`. The auth
+ * routes plugin re-issues the cookie when `renew` is set or when the
+ * value verified under the previous key.
+ */
+export declare const readSessionKeyed: (cookieHeader: string | undefined, secret: SessionSecretInput, options?: VerifyOptions) => VerifyResult | null;
+
+/** Injected rebinder — the app passes `bindConnectionSubject` from
+ *  `@voltro/runtime` so the plugin stays runtime-agnostic. */
+export declare type RebindConnection = (clientId: number, subject: ReturnType<typeof subjectFromUser>) => void;
+
+/** A hashed, single-use MFA recovery (backup) code. Minted alongside
+ *  enrolment; accepted at sign-in as an alternative to a TOTP code when
+ *  the authenticator is lost. Stored hashed (SHA-256), like tokens. */
+export declare interface RecoveryCodeRecord {
+    readonly id: string;
+    readonly userId: string;
+    readonly codeHash: string;
+    readonly consumedAt: Date | null;
+    readonly createdAt: Date;
+}
+
+export declare type RegistrationOutcome = {
+    readonly ok: true;
+    readonly result: RegistrationResult;
+} | {
+    readonly ok: false;
+    readonly error: WebAuthnError;
+};
+
+export declare interface RegistrationResult {
+    /** base64url credential id to store. */
+    readonly credentialId: string;
+    /** base64url COSE public key to store. */
+    readonly publicKey: string;
+    /** Initial signature counter. */
+    readonly counter: number;
+}
+
+export declare interface RegistrationVerifyInput {
+    /** base64url clientDataJSON from `navigator.credentials.create`. */
+    readonly clientDataJSON: string;
+    /** base64url authenticatorData (or attestationObject's authData — see
+     *  the client helper, which forwards the raw authenticatorData). */
+    readonly authenticatorData: string;
+    /** The challenge the server issued for this ceremony (base64url). */
+    readonly expectedChallenge: string;
+    /** The exact origin the ceremony must have run on (e.g.
+     *  `https://app.example.com`). */
+    readonly expectedOrigin: string;
+    /** The relying-party id (registrable domain, e.g. `example.com`). */
+    readonly rpId: string;
+}
+
+export declare const resolveSessionSecret: () => string;
+
+export declare const resolveSessionSecrets: () => SessionSecrets;
+
+declare interface RevokeOtherSessionsInput {
+    readonly userId: string;
+    /** The session to KEEP — typically the caller's current session id. */
+    readonly keepSessionId: string;
+}
+
+declare interface RevokeSessionInput {
+    readonly userId: string;
+    readonly sessionId: string;
+}
+
+/**
+ * Run the guards in order against `user`, short-circuiting on the FIRST
+ * rejection. With no guards (or all allowing) it resolves `{ ok: true }`.
+ * The login handlers call this once, just before issuing a session.
+ */
+export declare const runSubjectGuards: (guards: ReadonlyArray<SubjectGuard>, user: UserRecord) => Effect.Effect<SubjectGuardVerdict>;
+
+export declare type SendEmail = (input: SendEmailInput) => Promise<void>;
+
+/** The email hook the plugin calls for magic-link + password-reset. Inject
+ *  it on the config. The documented default wiring forwards to
+ *  `@voltro/plugin-mail`'s `MailService.send` (see `mailSender`). */
+export declare interface SendEmailInput {
+    readonly to: string;
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    /** Discriminates the flow so a custom sender can branch. */
+    readonly kind: 'magic-link' | 'password-reset';
+    /** The action URL embedded in the email (also present inside `html`). */
+    readonly actionUrl: string;
+}
+
+export declare const SESSION_COOKIE_NAME: "voltro:session";
+
+/** Read the server-side session id carried on a Subject (stamped by the
+ *  sign-in/sign-up/magic-link handlers as `metadata.sessionId`). Returns
+ *  null for non-user subjects and for cookies minted without a session
+ *  row (e.g. a hand-rolled `issueSession` call) — those can't be checked
+ *  against the sessions table. */
+export declare const sessionIdOfSubject: (subject: Subject) => string | null;
+
+/** A server-side session row — enumerated so apps can list active
+ *  devices + revoke them. Written on sign-in; deleted on revoke. */
+export declare interface SessionRecord {
+    readonly id: string;
+    readonly userId: string;
+    readonly tenantId: string;
+    readonly expiresAt: Date;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+    readonly createdAt: Date;
+    readonly lastSeenAt: Date;
+}
+
+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
+     *  are cached for `ttlMs`. */
+    readonly isLive: (sessionId: string) => Effect.Effect<boolean>;
+    /** Drop the cached verdict for one session — called inline by
+     *  sign-out / revoke handlers so the kill is immediate on THIS
+     *  process (other replicas converge within `ttlMs`). */
+    readonly invalidate: (sessionId: string) => void;
+    /** The effective cache window in milliseconds. */
+    readonly ttlMs: number;
+}
+
+export declare interface SessionRevocationOptions {
+    /** Cache window in milliseconds. A revocation performed elsewhere
+     *  takes effect on this process within this window. Default 30s.
+     *  `0` disables caching (every verify hits the store). */
+    readonly ttlMs?: number;
+    /** Upper bound on cached session ids. When exceeded, expired entries
+     *  are swept; if still over, the oldest entries are dropped. Default
+     *  10 000. */
+    readonly maxEntries?: number;
+    /** Clock override (epoch milliseconds). Defaults to `Date.now`. A
+     *  testing seam — lets suites cross the cache window without
+     *  wall-clock sleeps. */
+    readonly now?: () => number;
+}
+
+/** Every session helper takes either a bare secret string (single-key)
+ *  or the keyed `{ current, previous? }` rotation set. */
+export declare type SessionSecretInput = string | SessionSecrets;
+
+export { SessionSecrets }
+
+/**
+ * Normalise a secret input into the keyed set VERIFICATION runs against.
+ *
+ *   - A `SessionSecrets` set passes through unchanged.
+ *   - A bare string becomes `current` and is widened with the env-driven
+ *     `previous` key (`VOLTRO_SESSION_SECRET_PREVIOUS` +
+ *     `VOLTRO_SESSION_KID_PREVIOUS`) so env-var rotation works without
+ *     the app switching its config to the keyed shape. When the string
+ *     IS the env secret (`VOLTRO_SESSION_SECRET`), it inherits the env
+ *     `kid`; otherwise the default kid applies. The comparison is
+ *     constant-time — secrets never go through `===`.
+ */
+export declare const sessionSecretsOf: (secret: SessionSecretInput) => SessionSecrets;
+
+export declare interface SignInInput {
+    readonly email: string;
+    readonly password: string;
+    readonly redirectAfter?: boolean;
+    /** Recorded on the session row for the device list. */
+    readonly ipAddress?: string;
+    readonly userAgent?: string;
+}
+
+export declare interface SignUpInput {
+    readonly email: string;
+    readonly password: string;
+    readonly tenantId?: string;
+    readonly redirectAfter?: boolean;
+}
+
+/**
+ * Convert a UserRecord into the protocol Subject the framework
+ * carries around per-request. Tenant id flows through; user type
+ * is locked to 'user'.
+ *
+ * The user's tenant memberships, when supplied, are carried in
+ * `metadata.memberships` (the protocol Subject's metadata slot — the
+ * framework never reads it, but app code + the switch-tenant menu do).
+ * Pass an explicit `tenantId` to make the ACTIVE tenant differ from the
+ * user's home tenant (post switch-tenant rebind).
+ */
+export declare const subjectFromUser: (user: UserRecord, options?: {
+    readonly tenantId?: string;
+    readonly memberships?: ReadonlyArray<MembershipRecord>;
+}) => Subject;
+
+/**
+ * A post-authentication subject guard: given the authenticated user,
+ * decide whether the login may proceed. Runs after the credential check,
+ * before the session is issued. Effect-native so a guard can do IO (e.g.
+ * read a fresh flag) without a Promise bridge.
+ */
+export declare type SubjectGuard = (user: UserRecord) => Effect.Effect<SubjectGuardVerdict>;
+
+/** A guard's decision. Allow, or reject with a stable machine `code`
+ *  (surfaced as the 403 body's `error`) plus a human `message`. */
+export declare type SubjectGuardVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+
+/** Read the memberships carried on a Subject (set by `subjectFromUser`).
+ *  Returns [] when none are present. */
+export declare const subjectMemberships: (subject: Subject) => ReadonlyArray<{
+    tenantId: string;
+    role: string;
+}>;
+
+declare interface SwitchTenantInput {
+    readonly userId: string;
+    /** The connection (clientId) whose subject to rebind, when invoked over
+     *  the live WS path. Absent on the pure HTTP path (cookie re-issue only). */
+    readonly clientId?: number;
+    readonly targetTenantId: string;
+    /** The caller's current server-side session id — carried onto the
+     *  re-issued cookie so the request-time revocation check keeps
+     *  covering the session after a tenant switch. */
+    readonly sessionId?: string;
+}
+
+export declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+
+/** A single-use, hashed, expiring token (magic-link / password-reset). */
+export declare interface TokenRecord {
+    readonly id: string;
+    readonly tokenHash: string;
+    readonly userId: string;
+    readonly purpose: TokenPurpose;
+    readonly expiresAt: Date;
+    readonly consumedAt: Date | null;
+    readonly createdAt: Date;
+}
+
+export declare class TotpVerifyError extends TotpVerifyError_base<{
+    readonly reason: 'invalidCode' | 'malformedSecret' | 'replay';
+}> {
+}
+
+declare const TotpVerifyError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "TotpVerifyError";
+} & Readonly<A>;
+
+export declare class UserAlreadyExistsError extends UserAlreadyExistsError_base<{
+    readonly email: string;
+}> {
+}
+
+declare const UserAlreadyExistsError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "UserAlreadyExistsError";
+} & Readonly<A>;
+
+export declare class UserNotFoundError extends UserNotFoundError_base<{
+    readonly userId: string;
+}> {
+}
+
+declare const UserNotFoundError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "UserNotFoundError";
+} & Readonly<A>;
+
+export declare interface UserRecord {
+    readonly id: string;
+    readonly email: string;
+    readonly passwordHash: string;
+    readonly tenantId: string;
+    readonly createdAt: Date;
+    /** Base32-encoded TOTP secret. `null` = MFA not enrolled. Set by
+     *  `setMfaSecret()` from the enrolment handler. Stored as plaintext. */
+    readonly mfaSecret?: string | null;
+    /** Timestamp the user completed TOTP enrolment (first successful
+     *  verify). Distinct from the secret being set — a half-completed
+     *  enrolment leaves `mfaSecret` populated but this null. */
+    readonly mfaEnrolledAt?: Date | null;
+    /** Optional lifecycle flag read by post-authentication subject guards.
+     *  Set (a `Date`) means the account is DEACTIVATED — `@voltro/plugin-
+     *  deactivation`'s `deactivationGuard()` vetoes login when it's non-null.
+     *  `null` / absent means active. A store populates it from the app's
+     *  `deactivatedAt` column (added by the `deactivation()` mixin) when that
+     *  column exists; stores without the column simply leave it undefined and
+     *  the guard treats the account as active. */
+    readonly deactivatedAt?: Date | null;
+}
+
+export declare interface UserStore {
+    readonly findByEmail: (email: string) => Effect.Effect<UserRecord | null>;
+    readonly findById: (id: string) => Effect.Effect<UserRecord | null>;
+    readonly insert: (user: Omit<UserRecord, 'createdAt'>) => Effect.Effect<UserRecord, UserAlreadyExistsError>;
+    /** Replace a user's stored password hash. Used by password-reset AND
+     *  by rehash-on-verify (silently upgrading an under-cost hash on a
+     *  successful sign-in). */
+    readonly updatePassword: (userId: string, newHash: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Stash a freshly-generated TOTP secret on the user. Called by
+     *  the MFA enrolment handler before the user verifies the first
+     *  code. */
+    readonly setMfaSecret: (userId: string, secret: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Mark MFA as fully enrolled (called after the first successful
+     *  TOTP verify completes the enrolment ceremony). */
+    readonly markMfaEnrolled: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Wipe the secret + enrolledAt. Used by /account/security's
+     *  "remove MFA" action. */
+    readonly clearMfa: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+    /** Every tenant the user belongs to. */
+    readonly listMemberships: (userId: string) => Effect.Effect<ReadonlyArray<MembershipRecord>>;
+    /** Idempotent grant: inserts the [userId, tenantId] membership or
+     *  updates its role if it already exists. The DB-level composite
+     *  UNIQUE on `[userId, tenantId]` (see `membershipsTable`) is the
+     *  source of truth; this upsert converges to it. */
+    readonly addMembership: (membership: Omit<MembershipRecord, 'joinedAt'>) => Effect.Effect<MembershipRecord>;
+    /** Resolve the role for a [userId, tenantId] pair, or null when the
+     *  user is NOT a member. The switch-tenant handler calls this to
+     *  validate the requested tenant before rebinding the connection. */
+    readonly membershipRole: (userId: string, tenantId: string) => Effect.Effect<string | null>;
+    /** Active sessions for a user (most recent first). */
+    readonly listSessions: (userId: string) => Effect.Effect<ReadonlyArray<SessionRecord>>;
+    /** Record a session on sign-in. */
+    readonly insertSession: (session: Omit<SessionRecord, 'createdAt' | 'lastSeenAt'>) => Effect.Effect<SessionRecord>;
+    /** Look up one session row by id. The request-time revocation check
+     *  (`makeSessionRevocationChecker`) calls this — a missing row means
+     *  the session was revoked. */
+    readonly findSession: (sessionId: string) => Effect.Effect<SessionRecord | null>;
+    /** Slide a session row forward: bump `expiresAt` + `lastSeenAt`. Called
+     *  when the sliding-window renewal re-issues the cookie, so the row
+     *  outlives the renewed cookie and the revocation check keeps passing. */
+    readonly touchSession: (sessionId: string, expiresAt: Date) => Effect.Effect<void>;
+    /** Revoke a single session — only if it belongs to `userId` (so a
+     *  caller can't revoke another user's session by id-guessing). Returns
+     *  whether a row was removed. */
+    readonly revokeSession: (userId: string, sessionId: string) => Effect.Effect<boolean>;
+    /** 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>;
+    /** Persist a single-use token (already hashed). */
+    readonly insertToken: (token: Omit<TokenRecord, 'consumedAt' | 'createdAt'>) => Effect.Effect<TokenRecord>;
+    /** Atomically redeem a token by its hash + purpose: returns the row
+     *  only when it exists, matches the purpose, is unexpired, and was not
+     *  already consumed — and marks it consumed in the same step. Returns
+     *  null otherwise (single-use guard). */
+    readonly consumeToken: (tokenHash: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
+    /** Replace the user's recovery codes with a fresh (already hashed) set.
+     *  Called at enrolment / regeneration — wipes any prior codes so the
+     *  displayed set is the only valid one. */
+    readonly replaceRecoveryCodes: (userId: string, codeHashes: ReadonlyArray<string>) => Effect.Effect<void>;
+    /** Atomically redeem one recovery code by its hash: returns true only
+     *  when an unconsumed row for `userId` matched — and marks it consumed
+     *  in the same step (single-use). false otherwise. */
+    readonly consumeRecoveryCode: (userId: string, codeHash: string) => Effect.Effect<boolean>;
+    /** Count the user's remaining (unconsumed) recovery codes — surfaced so
+     *  the UI can warn when the user is running low. */
+    readonly countRecoveryCodes: (userId: string) => Effect.Effect<number>;
+    readonly listPasskeys: (userId: string) => Effect.Effect<ReadonlyArray<PasskeyRecord>>;
+    readonly findPasskey: (credentialId: string) => Effect.Effect<PasskeyRecord | null>;
+    readonly insertPasskey: (passkey: Omit<PasskeyRecord, 'createdAt' | 'lastUsedAt'>) => Effect.Effect<PasskeyRecord>;
+    /** Atomically bump the stored signature counter, guarding against a
+     *  cloned authenticator (WebAuthn §6.1.1): the update only applies when
+     *  `newCounter` strictly exceeds the stored counter. Returns whether a
+     *  row was advanced. `false` with an unchanged stored counter is the
+     *  clone/replay signal the assertion handler rejects on — the check and
+     *  the write are ONE atomic statement at the store, so two replicas
+     *  racing the same counter can't both succeed. */
+    readonly advancePasskeyCounter: (credentialId: string, newCounter: number) => Effect.Effect<boolean>;
+}
+
+/** Verify a passkey assertion (sign-in). */
+export declare const verifyAssertion: (input: AssertionVerifyInput) => AssertionOutcome;
+
+/**
+ * Verify a state-changing request's CSRF protection. Both the header
+ * value and the cookie value must (a) be the SAME token and (b) carry a
+ * valid HMAC. Returns true only when both hold.
+ */
+export declare const verifyCsrf: (headerToken: string | undefined, cookieToken: string | undefined, secret: string) => boolean;
+
+/**
+ * Verify a plaintext password against a stored hash.
+ *
+ * Uses `timingSafeEqual` for the comparison so attackers can't
+ * fingerprint correct prefixes via response-time analysis.
+ *
+ * Returns `Effect<boolean, never>` — parse errors or scrypt errors
+ * collapse to `false` because surfacing them lets attackers
+ * fingerprint malformed-vs-mismatched, which leaks structural info.
+ */
+export declare const verifyPassword: (plaintext: string, stored: string) => Effect.Effect<boolean>;
+
+/**
+ * Verify a password and, when it matches an under-cost hash, return a
+ * freshly-minted replacement. The caller wires `rehash` into
+ * `UserStore.updatePassword(userId, rehash)`. Never throws — parse /
+ * scrypt failures collapse to `{ valid: false }`.
+ */
+export declare const verifyPasswordWithRehash: (plaintext: string, stored: string) => Effect.Effect<VerifyWithRehashResult>;
+
+/** Verify a passkey registration. Attestation is intentionally NOT
+ *  checked (90% path); everything binding the credential to this
+ *  origin/rpId IS. */
+export declare const verifyRegistration: (input: RegistrationVerifyInput) => RegistrationOutcome;
+
+export { VerifyResult }
+
+/** Verify a TOTP code against the user's secret. Returns an Effect
+ *  that fails with `TotpVerifyError` on mismatch / malformed secret.
+ *  Accepts ±`TOTP_SKEW` steps (default ±1 → ±30s window) to tolerate
+ *  clock drift. */
+export declare const verifyTotpCode: (secretBase32: string, code: string, nowMs?: number) => Effect.Effect<true, TotpVerifyError>;
+
+export declare interface VerifyWithRehashResult {
+    /** Whether the password matched the stored hash. */
+    readonly valid: boolean;
+    /** A freshly-minted hash under the current cost, present ONLY when the
+     *  password was valid AND the stored hash was below current cost. The
+     *  caller persists it via `UserStore.updatePassword`. */
+    readonly rehash?: string;
+}
+
+export declare const VOLTRO_DEV_SESSION_SECRET: "voltro-dev-session-secret-32b-DO-NOT-USE-IN-PROD";
+
+export declare const voltroPasswordStrategy: (options?: VoltroPasswordStrategyOptions) => AuthStrategy;
+
+export declare interface VoltroPasswordStrategyOptions {
+    /** Secret(s) used to verify the cookie: a bare string OR a keyed
+     *  `SessionSecrets` set. Defaults to `resolveSessionSecret()` which
+     *  reads `VOLTRO_SESSION_SECRET` env with a dev fallback — same
+     *  resolver used by the mint side, so there's no drift between
+     *  issuing and verifying. A bare string is widened with the
+     *  `VOLTRO_SESSION_SECRET_PREVIOUS` env var (`sessionSecretsOf`),
+     *  so env-var rotation applies either way. */
+    readonly secret?: SessionSecretInput;
+    /** Cookie name. Defaults to `voltro:session`. Override when running
+     *  the strategy alongside another tenant on the same domain. */
+    readonly cookieName?: string;
+    /** The user store whose `sessions` rows back the request-time
+     *  revocation check. When absent, verification stays purely
+     *  stateless — a revoked session's cookie keeps working until it
+     *  expires. */
+    readonly store?: UserStore;
+    /** Tuning for the revocation check: options for the built-in TTL
+     *  cache (default window 30s), or a pre-built checker — pass the
+     *  auth plugin's own checker to share one cache between the HTTP
+     *  routes and the rpc auth chain. Ignored without a `store`
+     *  (unless a checker is passed directly). */
+    readonly revocation?: SessionRevocationOptions | SessionRevocationChecker;
+}
+
+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';
+
+export { }