@voltro/plugin-auth 0.71.1 → 0.72.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { AuthStrategy } from '@voltro/protocol';
 import { ConnectionCredential } from '@voltro/protocol';
+import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
 import { KeyedSecret } from '@voltro/protocol/session';
+import { MembershipsSource } from '@voltro/protocol';
 import { SessionSecrets } from '@voltro/protocol/session';
 import { SqlClient } from '@effect/sql/SqlClient';
 import { Subject } from '@voltro/protocol';
@@ -120,6 +122,8 @@ export declare interface AuthConfig {
     readonly emailVerification?: EmailVerificationConfig;
 }
 
+export declare const authMemberships: (store: UserStore) => MembershipsSource;
+
 /**
  * The auth plugin instance also carries a pre-wired session
  * `AuthStrategy` (keyed verify + the SAME revocation cache the HTTP
@@ -423,7 +427,7 @@ export declare const guardSubject: (user: UserRecord, config: AuthConfig) => Eff
  * a winning redemption goes on to write the membership. Reversed, two
  * concurrent accepts would both write.
  */
-export declare const handleAcceptInvitation: (input: AcceptInvitationInput, store: UserStore, deps?: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+export declare const handleAcceptInvitation: (input: AcceptInvitationInput, store: IdentityStore & MembershipStore & InvitationStore, deps?: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
 
 /**
  * Accept an invitation by CREATING the account it was addressed to — the
@@ -441,7 +445,7 @@ export declare const handleAcceptInvitation: (input: AcceptInvitationInput, stor
  * caller to sign in and use {@link handleAcceptInvitation} — creating a second
  * account for one address is not a fallback, it is a duplicate identity.
  */
-export declare const handleAcceptInvitationWithSignUp: (input: AcceptInvitationWithSignUpInput, store: UserStore, deps: InvitationDeps & {
+export declare const handleAcceptInvitationWithSignUp: (input: AcceptInvitationWithSignUpInput, store: IdentityStore & MembershipStore & InvitationStore, deps: InvitationDeps & {
     /** Hash a plaintext password. Injected so this module does not import the
      *  password module's Effect error channel into the invitation surface. */
     readonly hashPassword: (plaintext: string) => Effect.Effect<string, unknown>;
@@ -458,7 +462,7 @@ export declare const handleAcceptInvitationWithSignUp: (input: AcceptInvitationW
  * email) is revoked first, so the address never holds two live tokens and
  * "resend" cannot be used to accumulate them.
  */
-export declare const handleCreateInvitation: (input: CreateInvitationInput, store: UserStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+export declare const handleCreateInvitation: (input: CreateInvitationInput, store: MembershipStore & InvitationStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
 
 /**
  * Issue a CSRF token. Returns the token in the JSON body AND sets a
@@ -474,7 +478,7 @@ export declare const handleCsrf: (config: AuthConfig) => HandlerResult;
  * Issues NO session — see the header. The response says whether the address is
  * now verified, and the client sends the user to sign in.
  */
-export declare const handleEmailVerifyConfirm: (input: EmailVerifyConfirmInput, store: UserStore) => Effect.Effect<HandlerResultShape>;
+export declare const handleEmailVerifyConfirm: (input: EmailVerifyConfirmInput, store: IdentityStore & TokenStore) => Effect.Effect<HandlerResultShape>;
 
 /**
  * Request (or re-request) a verification link.
@@ -485,9 +489,9 @@ export declare const handleEmailVerifyConfirm: (input: EmailVerifyConfirmInput,
  * are registered, and (through the cooldown) whether one was recently active.
  * An already-verified user is also answered 202 and sent nothing.
  */
-export declare const handleEmailVerifyRequest: (input: EmailVerifyRequestInput, store: UserStore, deps: EmailVerificationDeps) => Effect.Effect<HandlerResultShape>;
+export declare const handleEmailVerifyRequest: (input: EmailVerifyRequestInput, store: IdentityStore & TokenStore, deps: EmailVerificationDeps) => Effect.Effect<HandlerResultShape>;
 
-export declare const handleImpersonationStart: (input: ImpersonationStartInput, store: UserStore, deps: ImpersonationDeps) => Effect.Effect<HandlerResultShape_3>;
+export declare const handleImpersonationStart: (input: ImpersonationStartInput, store: IdentityStore & ImpersonationStore, deps: ImpersonationDeps) => Effect.Effect<HandlerResultShape_3>;
 
 /**
  * End an impersonation and put the impersonator back in their own identity.
@@ -507,42 +511,42 @@ export declare const handleImpersonationStart: (input: ImpersonationStartInput,
  * meanwhile, the response clears the cookie — being signed out is the correct
  * outcome, and it is strictly better than staying signed in as somebody else.
  */
-export declare const handleImpersonationStop: (input: ImpersonationStopInput, store: UserStore, deps: ImpersonationDeps) => Effect.Effect<HandlerResultShape_3>;
+export declare const handleImpersonationStop: (input: ImpersonationStopInput, store: IdentityStore & SessionStore & ImpersonationStore, deps: ImpersonationDeps) => Effect.Effect<HandlerResultShape_3>;
 
 export declare const handleListInvitations: (input: {
     readonly callerUserId: string;
     readonly tenantId: string;
-}, store: UserStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+}, store: MembershipStore & InvitationStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
 
 export declare const handleListMemberships: (input: {
     readonly userId: string;
-}, store: UserStore) => Effect.Effect<HandlerResult>;
+}, store: MembershipStore) => Effect.Effect<HandlerResult>;
 
-export declare const handleListSessions: (input: ListSessionsInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleListSessions: (input: ListSessionsInput, store: SessionStore) => 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>;
+export declare const handleMagicLinkConsume: (input: MagicLinkConsumeInput, store: IdentityStore & MembershipStore & SessionStore & TokenStore & LockoutStore, 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 handleMagicLinkRequest: (input: MagicLinkRequestInput, store: IdentityStore & TokenStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
-export declare const handleMfaEnrollStart: (input: MfaEnrollStartInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleMfaEnrollStart: (input: MfaEnrollStartInput, store: IdentityStore & MfaStore) => Effect.Effect<HandlerResult>;
 
-export declare const handleMfaEnrollVerify: (input: MfaEnrollVerifyInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleMfaEnrollVerify: (input: MfaEnrollVerifyInput, store: IdentityStore & MfaStore) => 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 handleMfaRegenerateRecoveryCodes: (input: MfaRegenerateRecoveryCodesInput, store: IdentityStore & MfaStore) => Effect.Effect<HandlerResult>;
 
-export declare const handleMfaUnenroll: (input: MfaUnenrollInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleMfaUnenroll: (input: MfaUnenrollInput, store: IdentityStore & MfaStore) => Effect.Effect<HandlerResult>;
 
 /**
  * Complete an MFA sign-in: redeem the single-use pending token, verify the
@@ -553,29 +557,29 @@ export declare const handleMfaUnenroll: (input: MfaUnenrollInput, store: UserSto
  * 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>;
+export declare const handleMfaVerify: (input: MfaVerifyInput, store: IdentityStore & MfaStore & MembershipStore & SessionStore & TokenStore & LockoutStore, 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>;
+export declare const handlePasskeyAssertOptions: (input: PasskeyAssertOptionsInput, store: PasskeyStore, 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>;
+export declare const handlePasskeyAssertVerify: (input: PasskeyAssertVerifyInput, store: IdentityStore & MembershipStore & SessionStore & PasskeyStore & LockoutStore, 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>;
+export declare const handlePasskeyRegisterOptions: (input: PasskeyRegisterOptionsInput, store: IdentityStore & PasskeyStore, 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>;
+export declare const handlePasskeyRegisterVerify: (input: PasskeyRegisterVerifyInput, store: IdentityStore & PasskeyStore, 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>;
+export declare const handlePasswordResetConfirm: (input: PasswordResetConfirmInput, store: IdentityStore & SessionStore & TokenStore) => 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 handlePasswordResetRequest: (input: PasswordResetRequestInput, store: IdentityStore & TokenStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
 /**
  * What is behind this link, without redeeming it — the accept page's read.
@@ -587,17 +591,17 @@ export declare const handlePasswordResetRequest: (input: PasswordResetRequestInp
  */
 export declare const handlePreviewInvitation: (input: {
     readonly token: string;
-}, store: UserStore, deps?: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+}, store: InvitationStore, deps?: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
 
-export declare const handleRevokeAllOtherSessions: (input: RevokeOtherSessionsInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleRevokeAllOtherSessions: (input: RevokeOtherSessionsInput, store: SessionStore) => Effect.Effect<HandlerResult>;
 
 export declare const handleRevokeInvitation: (input: {
     readonly callerUserId: string;
     readonly tenantId: string;
     readonly invitationId: string;
-}, store: UserStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+}, store: MembershipStore & InvitationStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
 
-export declare const handleRevokeSession: (input: RevokeSessionInput, store: UserStore) => Effect.Effect<HandlerResult>;
+export declare const handleRevokeSession: (input: RevokeSessionInput, store: SessionStore) => Effect.Effect<HandlerResult>;
 
 export declare interface HandlerResult {
     readonly status: number;
@@ -648,7 +652,7 @@ declare interface HandlerResultShape_3 {
  * 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>;
+export declare const handleSignIn: (input: SignInInput, store: IdentityStore & MembershipStore & SessionStore & TokenStore & LockoutStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
 /**
  * Sign-out handler. Clears the session cookie. Synchronous so it
@@ -666,7 +670,7 @@ export declare const handleSignOut: (config: AuthConfig) => HandlerResult;
  * 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>;
+export declare const handleSignUp: (input: SignUpInput, store: IdentityStore & MembershipStore & SessionStore & TokenStore & LockoutStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
 /**
  * Switch the active tenant. Validates the user is actually a member of
@@ -680,7 +684,13 @@ export declare const handleSignUp: (input: SignUpInput, store: UserStore, config
  * nothing re-scopes them, and nothing ever did — the `onBindConnectionSubject`
  * listener that claimed to had no subscribers in the entire framework.
  */
-export declare const handleSwitchTenant: (input: SwitchTenantInput, store: UserStore, config: AuthConfig, rebind?: RebindConnection) => Effect.Effect<HandlerResult>;
+export declare const handleSwitchTenant: (input: SwitchTenantInput, store: IdentityStore & MembershipStore, config: AuthConfig, rebind?: RebindConnection, 
+/** The app's DataStore, when the plugin has been bound to one: the switch
+ *  is then ALSO recorded as the framework's tenant selection
+ *  (`_voltro_tenant_selections`), so the cookie and the selection never
+ *  disagree — a request this user makes with any OTHER credential (an IdP
+ *  JWT, an API key) resolves in the tenant they switched to as well. */
+dataStore?: DataStore) => Effect.Effect<HandlerResult>;
 
 /**
  * Hash a password. Returns a self-describing string that
@@ -694,6 +704,56 @@ export declare const hashPassword: (plaintext: string) => Effect.Effect<string,
  *  brute-force surface that would need a slow KDF. */
 export declare const hashToken: (plaintext: string) => string;
 
+/** The identity columns the store reads and writes, by their record name. */
+export declare type IdentityColumn = 'id' | 'email' | 'passwordHash' | 'tenantId' | 'createdAt' | 'updatedAt' | 'mfaSecret' | 'mfaEnrolledAt' | 'emailVerifiedAt' | 'deactivatedAt';
+
+/** Identity — who a user is. The only role an app with its own identity table has to write itself; everything else composes from the shipped store. */
+export declare interface IdentityStore {
+    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>;
+    /**
+     * Stamp `emailVerifiedAt` — the address has been proven.
+     *
+     * IDEMPOTENT and non-regressing: a user already verified keeps their
+     * ORIGINAL timestamp. "When was this address first proven" is the question
+     * the column answers, and re-stamping it on every later magic-link login
+     * would quietly turn it into "when did they last click something".
+     */
+    readonly markEmailVerified: (userId: string) => Effect.Effect<UserRecord, UserNotFoundError>;
+}
+
+export declare interface IdentityTableMapping {
+    /** The table (default `users`). Unqualified or `schema.table`. */
+    readonly table?: string;
+    /**
+     * Record name → column name. Unmapped columns keep their record name.
+     * `id`, `email`, `tenantId` and `createdAt` must exist. The others may be
+     * `false` — "my table has no such column": reads answer null, and a write
+     * that exists only to set that column (`updatePassword` → `passwordHash`,
+     * the MFA methods → `mfaSecret` / `mfaEnrolledAt`, `markEmailVerified` →
+     * `emailVerifiedAt`) dies naming the mapping. `updatedAt: false` merely
+     * omits the stamp; `deactivatedAt` is `false` by default because the
+     * shipped table has no such column — map it to read the app's own.
+     */
+    readonly columns?: {
+        readonly id?: string;
+        readonly email?: string;
+        readonly tenantId?: string;
+        readonly createdAt?: string;
+        readonly passwordHash?: string | false;
+        readonly updatedAt?: string | false;
+        readonly mfaSecret?: string | false;
+        readonly mfaEnrolledAt?: string | false;
+        readonly emailVerifiedAt?: string | false;
+        readonly deactivatedAt?: string | false;
+    };
+}
+
 /** Default grant lifetime — 15 minutes. A support interaction, not a shift. */
 export declare const IMPERSONATION_DEFAULT_DURATION_S: number;
 
@@ -905,6 +965,17 @@ export declare interface ImpersonationStopInput {
     readonly sessionId: string;
 }
 
+/** Impersonation grants. */
+export declare interface ImpersonationStore {
+    /** Record an impersonation grant when the impersonated session is minted. */
+    readonly insertImpersonationGrant: (grant: Omit<ImpersonationGrantRecord, 'startedAt' | 'endedAt' | 'endedReason'>) => Effect.Effect<ImpersonationGrantRecord>;
+    /** The grant for an impersonated session, or null. The stop path's lookup. */
+    readonly findImpersonationGrantBySession: (sessionId: string) => Effect.Effect<ImpersonationGrantRecord | null>;
+    /** Close a grant. Only an OPEN grant is closed (`endedAt IS NULL`), so a
+     *  double stop is a no-op rather than a rewritten end time. */
+    readonly endImpersonationGrant: (sessionId: string, endedReason: string, now: Date) => Effect.Effect<boolean>;
+}
+
 /** Default cap on live invitations per tenant. */
 export declare const INVITATION_MAX_PENDING = 500;
 
@@ -986,6 +1057,38 @@ export declare interface InvitationsConfig {
     readonly canGrantRole?: (ctx: GrantRoleContext) => boolean;
 }
 
+/** Tenant invitations. */
+export declare interface InvitationStore {
+    /** Persist an invitation (token already hashed). */
+    readonly insertInvitation: (invitation: Omit<InvitationRecord, 'acceptedAt' | 'acceptedByUserId' | 'revokedAt' | 'revokedByUserId' | 'createdAt'>) => Effect.Effect<InvitationRecord>;
+    /** Look an invitation up by token hash WITHOUT redeeming it — the read the
+     *  "what am I being invited to" preview needs. Returns the row whatever its
+     *  state; the caller decides what an expired or revoked one means. */
+    readonly findInvitationByHash: (tokenHash: string) => Effect.Effect<InvitationRecord | null>;
+    /**
+     * Atomically redeem an invitation: returns the row only when it exists, is
+     * unaccepted, unrevoked and unexpired — and stamps `acceptedAt` +
+     * `acceptedByUserId` in the same step. Null otherwise.
+     *
+     * The single-use guard, and it has to be ONE statement: two clicks on the
+     * same emailed link race, and a read-then-write would let both through and
+     * write the membership twice.
+     */
+    readonly acceptInvitation: (tokenHash: string, acceptedByUserId: string, now: Date) => Effect.Effect<InvitationRecord | null>;
+    /** Withdraw a PENDING invitation, scoped to its tenant so an admin of one
+     *  tenant cannot revoke another's by id. Returns whether a row changed. */
+    readonly revokeInvitation: (invitationId: string, tenantId: string, revokedByUserId: string, now: Date) => Effect.Effect<boolean>;
+    /** Every invitation for a tenant, newest first. The admin list. */
+    readonly listInvitations: (tenantId: string) => Effect.Effect<ReadonlyArray<InvitationRecord>>;
+    /** How many invitations for this tenant are still redeemable — the bound
+     *  `maxPending` enforces. */
+    readonly countPendingInvitations: (tenantId: string, now: Date) => Effect.Effect<number>;
+    /** Revoke every pending invitation for (tenant, email). Called before
+     *  issuing a fresh one so re-inviting supersedes rather than accumulates —
+     *  otherwise every resend leaves a live token behind. Returns the count. */
+    readonly supersedePendingInvitations: (tenantId: string, email: string, revokedByUserId: string, now: Date) => Effect.Effect<number>;
+}
+
 /** Verify a token's own HMAC (signature integrity), independent of the
  *  cookie/header match. */
 export declare const isCsrfTokenWellFormed: (token: string, secret: string) => boolean;
@@ -1054,7 +1157,7 @@ export declare interface IssueSessionOptions {
  * this body — which is exactly how a mark added in one place ends up missing
  * on two of five login paths, discoverable only by logging in the right way.
  */
-export declare const issueUserSession: (user: UserRecord, store: UserStore, config: AuthConfig, meta?: IssueUserSessionOptions) => Effect.Effect<{
+export declare const issueUserSession: (user: UserRecord, store: MembershipStore & SessionStore & LockoutStore, config: AuthConfig, meta?: IssueUserSessionOptions) => Effect.Effect<{
     readonly setCookie: string;
     readonly subject: ReturnType<typeof subjectFromUser>;
 }>;
@@ -1124,6 +1227,20 @@ declare interface LockoutState {
     readonly retryAfterSeconds: number;
 }
 
+/** Brute-force lockout, keyed by normalized email. */
+export declare interface LockoutStore {
+    /** Is this email currently locked out? Reads only — never mutates. Returns
+     *  the remaining cooldown so the handler can surface a retry-after. */
+    readonly isLockedOut: (email: string, now: number) => Effect.Effect<LockoutState>;
+    /** Record one failed credential attempt for `email`. Opens a fresh window
+     *  when the previous one (or a prior lock) has expired, otherwise increments;
+     *  sets the lock once `failedCount` reaches `policy.maxAttempts`. Called only
+     *  for a NOT-currently-locked email (the handler checks `isLockedOut` first). */
+    readonly recordLoginFailure: (email: string, now: number, policy: LockoutPolicy) => Effect.Effect<void>;
+    /** Clear the counter for `email` on a completed login. */
+    readonly clearLoginFailures: (email: string) => Effect.Effect<void>;
+}
+
 /** Default magic-link lifetime — short, since it's an inbox round-trip. */
 export declare const MAGIC_LINK_TTL_S: number;
 
@@ -1179,6 +1296,21 @@ export declare interface MembershipRecord {
     readonly joinedAt: Date;
 }
 
+/** Memberships + switch-tenant. */
+export declare interface MembershipStore {
+    /** 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>;
+}
+
 /** 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`. */
@@ -1227,6 +1359,31 @@ export declare interface MfaRegenerateRecoveryCodesInput {
     readonly userId: string;
 }
 
+/** TOTP enrolment + recovery codes. */
+export declare interface MfaStore {
+    /** 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>;
+    /** 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>;
+}
+
 export declare interface MfaUnenrollInput {
     readonly userId: string;
 }
@@ -1352,6 +1509,21 @@ declare interface PasskeyRegisterVerifyInput {
     readonly transports?: string;
 }
 
+/** Passkeys (WebAuthn). */
+export declare interface PasskeyStore {
+    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>;
+}
+
 /** Default password-reset lifetime — a bit longer. */
 export declare const PASSWORD_RESET_TTL_S: number;
 
@@ -1386,13 +1558,20 @@ declare interface PasswordResetRequestInput {
 
 /**
  * Build a UserStore that reads + writes the auth tables via the provided
- * `SqlClient`. The caller owns the client's lifecycle.
+ * `SqlClient`. The caller owns the client's lifecycle. `options.identity`
+ * points the identity role at an existing table (see `IdentityTableMapping`).
  *
  * 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;
+export declare const postgresUserStore: (sql: SqlClient, options?: PostgresUserStoreOptions) => UserStore;
+
+export declare interface PostgresUserStoreOptions {
+    /** Map the identity role onto an existing table. Every other role stays on
+     *  the plugin's own tables. */
+    readonly identity?: IdentityTableMapping;
+}
 
 /**
  * Read + verify the session cookie from a Cookie header string.
@@ -1517,7 +1696,7 @@ export declare interface SendEmailInput {
  * suppressed it or no transport is wired. The caller must NOT surface that
  * distinction to an unauthenticated client (see `handleEmailVerifyRequest`).
  */
-export declare const sendEmailVerification: (user: UserRecord, store: UserStore, deps: EmailVerificationDeps) => Effect.Effect<boolean>;
+export declare const sendEmailVerification: (user: UserRecord, store: TokenStore, deps: EmailVerificationDeps) => Effect.Effect<boolean>;
 
 export declare const SESSION_COOKIE_NAME: "voltro:session";
 
@@ -1589,6 +1768,29 @@ export { SessionSecrets }
  */
 export declare const sessionSecretsOf: (secret: SessionSecretInput) => SessionSecrets;
 
+/** Server-side sessions — enumeration + revocation. */
+export declare interface SessionStore {
+    /** 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>;
+}
+
 export declare interface SignInInput {
     readonly email: string;
     readonly password: string;
@@ -1707,6 +1909,28 @@ export declare interface TokenRecord {
     readonly createdAt: Date;
 }
 
+/** Single-use tokens: magic link, password reset, MFA pending, email verification. */
+export declare interface TokenStore {
+    /** 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>;
+    /**
+     * The most recently CREATED token of this purpose for the user, consumed or
+     * not — or null when there is none.
+     *
+     * Exists for the resend cooldown, which is the only bound on an endpoint
+     * that sends mail to an address supplied by an unauthenticated caller. Note
+     * it deliberately does NOT filter on `consumedAt`: the cost being rate-
+     * limited is the EMAIL, and a token that was minted and then redeemed cost
+     * exactly as much to send as one still pending.
+     */
+    readonly latestToken: (userId: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
+}
+
 export declare class TotpVerifyError extends TotpVerifyError_base<{
     readonly reason: 'invalidCode' | 'malformedSecret' | 'replay';
 }> {
@@ -1795,148 +2019,8 @@ export declare interface UserRecord {
     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>;
-    /**
-     * Stamp `emailVerifiedAt` — the address has been proven.
-     *
-     * IDEMPOTENT and non-regressing: a user already verified keeps their
-     * ORIGINAL timestamp. "When was this address first proven" is the question
-     * the column answers, and re-stamping it on every later magic-link login
-     * would quietly turn it into "when did they last click something".
-     */
-    readonly markEmailVerified: (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>;
-    /**
-     * The most recently CREATED token of this purpose for the user, consumed or
-     * not — or null when there is none.
-     *
-     * Exists for the resend cooldown, which is the only bound on an endpoint
-     * that sends mail to an address supplied by an unauthenticated caller. Note
-     * it deliberately does NOT filter on `consumedAt`: the cost being rate-
-     * limited is the EMAIL, and a token that was minted and then redeemed cost
-     * exactly as much to send as one still pending.
-     */
-    readonly latestToken: (userId: string, purpose: TokenPurpose) => Effect.Effect<TokenRecord | null>;
-    /** Persist an invitation (token already hashed). */
-    readonly insertInvitation: (invitation: Omit<InvitationRecord, 'acceptedAt' | 'acceptedByUserId' | 'revokedAt' | 'revokedByUserId' | 'createdAt'>) => Effect.Effect<InvitationRecord>;
-    /** Look an invitation up by token hash WITHOUT redeeming it — the read the
-     *  "what am I being invited to" preview needs. Returns the row whatever its
-     *  state; the caller decides what an expired or revoked one means. */
-    readonly findInvitationByHash: (tokenHash: string) => Effect.Effect<InvitationRecord | null>;
-    /**
-     * Atomically redeem an invitation: returns the row only when it exists, is
-     * unaccepted, unrevoked and unexpired — and stamps `acceptedAt` +
-     * `acceptedByUserId` in the same step. Null otherwise.
-     *
-     * The single-use guard, and it has to be ONE statement: two clicks on the
-     * same emailed link race, and a read-then-write would let both through and
-     * write the membership twice.
-     */
-    readonly acceptInvitation: (tokenHash: string, acceptedByUserId: string, now: Date) => Effect.Effect<InvitationRecord | null>;
-    /** Withdraw a PENDING invitation, scoped to its tenant so an admin of one
-     *  tenant cannot revoke another's by id. Returns whether a row changed. */
-    readonly revokeInvitation: (invitationId: string, tenantId: string, revokedByUserId: string, now: Date) => Effect.Effect<boolean>;
-    /** Every invitation for a tenant, newest first. The admin list. */
-    readonly listInvitations: (tenantId: string) => Effect.Effect<ReadonlyArray<InvitationRecord>>;
-    /** How many invitations for this tenant are still redeemable — the bound
-     *  `maxPending` enforces. */
-    readonly countPendingInvitations: (tenantId: string, now: Date) => Effect.Effect<number>;
-    /** Revoke every pending invitation for (tenant, email). Called before
-     *  issuing a fresh one so re-inviting supersedes rather than accumulates —
-     *  otherwise every resend leaves a live token behind. Returns the count. */
-    readonly supersedePendingInvitations: (tenantId: string, email: string, revokedByUserId: string, now: Date) => Effect.Effect<number>;
-    /** Record an impersonation grant when the impersonated session is minted. */
-    readonly insertImpersonationGrant: (grant: Omit<ImpersonationGrantRecord, 'startedAt' | 'endedAt' | 'endedReason'>) => Effect.Effect<ImpersonationGrantRecord>;
-    /** The grant for an impersonated session, or null. The stop path's lookup. */
-    readonly findImpersonationGrantBySession: (sessionId: string) => Effect.Effect<ImpersonationGrantRecord | null>;
-    /** Close a grant. Only an OPEN grant is closed (`endedAt IS NULL`), so a
-     *  double stop is a no-op rather than a rewritten end time. */
-    readonly endImpersonationGrant: (sessionId: string, endedReason: string, now: Date) => Effect.Effect<boolean>;
-    /** 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>;
-    /** Is this email currently locked out? Reads only — never mutates. Returns
-     *  the remaining cooldown so the handler can surface a retry-after. */
-    readonly isLockedOut: (email: string, now: number) => Effect.Effect<LockoutState>;
-    /** Record one failed credential attempt for `email`. Opens a fresh window
-     *  when the previous one (or a prior lock) has expired, otherwise increments;
-     *  sets the lock once `failedCount` reaches `policy.maxAttempts`. Called only
-     *  for a NOT-currently-locked email (the handler checks `isLockedOut` first). */
-    readonly recordLoginFailure: (email: string, now: number, policy: LockoutPolicy) => Effect.Effect<void>;
-    /** Clear the counter for `email` on a completed login. */
-    readonly clearLoginFailures: (email: string) => Effect.Effect<void>;
+/** Every role at once — what the shipped stores return and what `authRoutesPlugin` takes. */
+export declare interface UserStore extends IdentityStore, MfaStore, MembershipStore, SessionStore, TokenStore, InvitationStore, ImpersonationStore, PasskeyStore, LockoutStore {
 }
 
 /** Verify a passkey assertion (sign-in). */