@voltro/plugin-auth 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,15 +1,28 @@
 import { AuthStrategy } from '@voltro/protocol';
+import { ConnectionCredential } 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 { SubjectIdentity } 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 interface AcceptInvitationInput {
+    readonly token: string;
+    /** The authenticated caller's id. Absent means nobody is signed in. */
+    readonly userId?: string;
+}
+
+export declare interface AcceptInvitationWithSignUpInput {
+    readonly token: string;
+    readonly password: string;
+}
+
 export declare type AssertionOutcome = {
     readonly ok: true;
     readonly result: AssertionResult;
@@ -94,6 +107,17 @@ export declare interface AuthConfig {
     /** Injectable clock (epoch-ms) for the lockout counter. Default `Date.now`;
      *  tests pass a controllable one to exercise window/lock expiry. */
     readonly now?: () => number;
+    /**
+     * Email verification. OFF by default (`policy: 'off'`) — the endpoints and
+     * the `emailVerifiedAt` column exist, nothing is gated.
+     *
+     * `'strict'` is enforced through `subjectGuards`, so it covers every path
+     * that issues a session; `authRoutesPlugin` installs that guard for you.
+     * Hand-wiring the handlers? Add `emailVerificationGuard(config)` to
+     * `subjectGuards` yourself — setting the policy alone changes only what the
+     * session is MARKED with, not who may log in.
+     */
+    readonly emailVerification?: EmailVerificationConfig;
 }
 
 /**
@@ -128,13 +152,36 @@ export declare interface AuthRoutesPluginOptions extends AuthConfig {
      *  enrolment routes. */
     readonly mfa?: MfaConfig;
     /** Rebind hook for switch-tenant on the live WS path — pass
-     *  `bindConnectionSubject` from `@voltro/runtime`. */
+     *  `bindConnectionCredential` from `@voltro/runtime`. It receives the cookie
+     *  this plugin just minted, not a Subject: the connection then presents the
+     *  same credential a reconnecting browser would, and the auth chain judges it
+     *  the same way (revocation included). */
     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;
+    /**
+     * Tenant invitations. PRESENT (even as `{}`) mounts the five
+     * `/auth/invitations/*` routes and arms the retention bound on the
+     * `invitations` table; ABSENT mounts nothing.
+     *
+     * Opt-in by presence, like `mfa` and `passkey`, and for the same reason:
+     * the table ships in `authTables` but an app that has not spread it would
+     * otherwise get 500s from a route it never asked for.
+     */
+    readonly invitations?: InvitationsConfig;
+    /**
+     * User impersonation ("log in as"). PRESENT mounts `/auth/impersonate/start`
+     * + `/stop`, arms the retention bound on `impersonationGrants`, and closes
+     * the account-security routes to impersonated sessions; ABSENT mounts
+     * nothing and the block below cannot fire.
+     *
+     * Both `authority` and `audit` are REQUIRED — there is no way to switch this
+     * on while leaving either unanswered. See `ImpersonationConfig`.
+     */
+    readonly impersonation?: ImpersonationConfig;
     /** Disambiguates multiple instances of this plugin in one app. */
     readonly name?: string;
 }
@@ -157,6 +204,15 @@ export declare const clearSessionCookie: (options?: IssueSessionOptions) => stri
  *  rotation env vars. */
 export declare const configSessionSecrets: (config: AuthConfig) => SessionSecrets;
 
+export declare interface CreateInvitationInput {
+    /** The authenticated caller — resolved from their session, never from the
+     *  request body. */
+    readonly inviterUserId: string;
+    readonly tenantId: string;
+    readonly email: string;
+    readonly role: string;
+}
+
 export declare const CSRF_COOKIE_NAME: "voltro:csrf";
 
 export declare const CSRF_HEADER_NAME: "x-csrf-token";
@@ -180,6 +236,122 @@ export declare const CSRF_HEADER_NAME: "x-csrf-token";
  */
 export declare const dataStoreChallengeStore: (sql: SqlClient) => ChallengeStore;
 
+/** Default set of roles allowed to invite at all. */
+export declare const DEFAULT_INVITER_ROLES: ReadonlyArray<string>;
+
+/** Default role ordering, most privileged first. */
+export declare const DEFAULT_ROLE_RANK: ReadonlyArray<string>;
+
+/** The shipped rank-based rule. Exported so an app extending it can call it. */
+export declare const defaultCanGrantRole: (ctx: GrantRoleContext, rank?: ReadonlyArray<string>) => boolean;
+
+/** The 403 body's `error` when `'strict'` refuses a login. */
+export declare const EMAIL_NOT_VERIFIED_CODE: "email_not_verified";
+
+/** The subject-metadata key carrying the verification mark. */
+export declare const EMAIL_VERIFIED_METADATA_KEY: "emailVerified";
+
+/** Default gap between two verification emails to one user. */
+export declare const EMAIL_VERIFY_RESEND_COOLDOWN_S = 60;
+
+/**
+ * Default email-verification lifetime — 24 hours.
+ *
+ * Longer than the other two on purpose, and the asymmetry is the point. A
+ * magic link and a reset link are CREDENTIALS: whoever holds one signs in, so
+ * a short fuse is worth the friction of asking for another. A verification
+ * link grants nothing — redeeming it only asserts that the address reaches its
+ * owner — so the cost of a short lifetime is all friction and no security, paid
+ * by exactly the users who check mail once a day.
+ */
+export declare const EMAIL_VERIFY_TTL_S: number;
+
+/** Whether the verification feature does anything at all for this app. */
+export declare const emailVerificationActive: (config: EmailVerificationConfig | undefined) => boolean;
+
+export declare interface EmailVerificationConfig {
+    /** Default `'off'` — see the header for why a stricter default is an
+     *  outage rather than a safer choice. */
+    readonly policy?: EmailVerificationPolicy;
+    /** Lifetime of a verification link. Default {@link EMAIL_VERIFY_TTL_S} (24h). */
+    readonly ttlSeconds?: number;
+    /** Path the emailed link points at. Default `/auth/verify-email/callback`. */
+    readonly callbackPath?: string;
+    /**
+     * Minimum gap between two verification emails to the same user. Default 60s.
+     *
+     * The only bound on an endpoint that sends mail to an address chosen by an
+     * unauthenticated caller. Without it, "resend" is a mail-bomb primitive
+     * pointed at any address the attacker knows has an account, and the cost is
+     * carried by your sending reputation.
+     */
+    readonly resendCooldownSeconds?: number;
+    /** Send the verification email automatically on sign-up. Default: true
+     *  whenever `policy` is not `'off'`. */
+    readonly sendOnSignUp?: boolean;
+    /**
+     * Accounts created STRICTLY BEFORE this instant count as verified.
+     *
+     * The migration seam, and the reason `'strict'` is adoptable at all: an app
+     * turning the policy on has a table full of `emailVerifiedAt IS NULL` rows
+     * belonging to real users who did nothing wrong. Set this to the deploy
+     * instant and only accounts created from then on have to prove anything.
+     *
+     * It is deliberately a CONFIG value rather than a backfill we run for you:
+     * an app that genuinely wants its existing users to re-verify says so by
+     * leaving this unset, and one that does not is spared writing to every row
+     * of its users table.
+     */
+    readonly exemptAccountsCreatedBefore?: Date;
+}
+
+/** The `AuthConfig` slice these handlers read. Declared structurally so this
+ *  module does not import `handlers.ts` (which imports this one). */
+export declare interface EmailVerificationDeps {
+    readonly appBaseUrl?: string;
+    readonly sendEmail?: (input: {
+        readonly to: string;
+        readonly subject: string;
+        readonly html: string;
+        readonly text: string;
+        readonly kind: 'magic-link' | 'password-reset' | 'email-verify' | 'invitation';
+        readonly actionUrl: string;
+    }) => Promise<void>;
+    readonly emailVerification?: EmailVerificationConfig;
+    readonly now?: () => number;
+}
+
+/**
+ * The `'strict'` enforcement, as a post-authentication subject guard.
+ *
+ * A guard rather than a check inside `handleSignIn` on purpose: the seam
+ * already runs at EVERY path that grants a session to a pre-existing user
+ * (password, MFA verify, magic-link consume, passkey assertion), so wiring it
+ * here covers all four and cannot be forgotten on the fifth. `authRoutesPlugin`
+ * appends it automatically under `'strict'`; an app hand-wiring the handlers
+ * adds it to `subjectGuards` itself.
+ *
+ * Under `'off'` and `'soft'` it returns a guard that always allows, rather
+ * than the caller having to decide whether to install one — a policy read in
+ * two places is a policy that can disagree with itself.
+ */
+export declare const emailVerificationGuard: (config: EmailVerificationConfig | undefined) => SubjectGuard;
+
+/** What an account with an unproven address may do. See the header. */
+export declare type EmailVerificationPolicy = 'off' | 'soft' | 'strict';
+
+export declare interface EmailVerifyConfirmInput {
+    readonly token: string;
+}
+
+export declare interface EmailVerifyRequestInput {
+    /** The address to send to. Either this or `userId`. */
+    readonly email?: string;
+    /** The authenticated caller's id — the "resend to me" path, which needs no
+     *  address in the request and therefore cannot be pointed at someone else. */
+    readonly userId?: string;
+}
+
 /** 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. */
@@ -208,6 +380,14 @@ export declare const generateTotpSecret: () => string;
  */
 export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugin>) => AuthStrategy | null;
 
+export declare interface GrantRoleContext {
+    /** The inviter's role in THIS tenant, as read from `memberships`. */
+    readonly inviterRole: string;
+    /** The role the invitation would carry. */
+    readonly requestedRole: string;
+    readonly tenantId: string;
+}
+
 /**
  * Run the config's post-authentication subject guards against a resolved
  * user. Returns a 403 `HandlerResult` (carrying the vetoing guard's `code`
@@ -221,6 +401,65 @@ export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugi
  */
 export declare const guardSubject: (user: UserRecord, config: AuthConfig) => Effect.Effect<HandlerResult | null>;
 
+/**
+ * Accept an invitation as an ALREADY-AUTHENTICATED user.
+ *
+ * The three refusals, in the order they matter:
+ *
+ *   - **401 `authentication_required`** when nobody is signed in. The response
+ *     carries the invited `email` so the sign-in page can pre-fill it — that
+ *     address is already in the recipient's mailbox, so echoing it to the
+ *     holder of the token reveals nothing they do not have.
+ *   - **403 `invitation_email_mismatch`** when the signed-in user's address is
+ *     not the invited one. This is the property that makes a leaked or
+ *     forwarded link useless: without it, the first person to open the link
+ *     while signed into any account joins the tenant.
+ *   - **401 `invalid_or_expired_invitation`** for a token that is unknown,
+ *     spent, revoked or lapsed — one answer for all four, because
+ *     distinguishing them tells a holder of a dead token which kind of dead.
+ *
+ * The membership is written with the role from the INVITATION ROW. Note the
+ * ordering: the invitation is redeemed FIRST (the single-use UPDATE), and only
+ * 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>;
+
+/**
+ * Accept an invitation by CREATING the account it was addressed to — the
+ * "you've been invited, choose a password" flow.
+ *
+ * The account's email is taken from the INVITATION, never from the request:
+ * an input-supplied address would let the holder of a leaked token create an
+ * account under an address of their choosing and have it join the tenant. For
+ * the same reason there is no `tenantId` input — it is the invitation's.
+ *
+ * The new account is created ALREADY VERIFIED: the invitation arrived in that
+ * mailbox and came back, which is the same proof a verification link provides.
+ *
+ * Refuses with 409 when the address already has an account, and directs the
+ * 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 & {
+    /** 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>;
+    /** Minimum password length, mirroring `handleSignUp`. Default 8. */
+    readonly minPasswordLength?: number;
+}) => Effect.Effect<HandlerResultShape_2>;
+
+/**
+ * Create + email an invitation.
+ *
+ * Refuses when the caller may not invite into this tenant, when the requested
+ * role is above what they may grant, or when the tenant is at its pending cap.
+ * A re-invite SUPERSEDES: every pending invitation for the same (tenant,
+ * 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>;
+
 /**
  * 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
@@ -229,6 +468,52 @@ export declare const guardSubject: (user: UserRecord, config: AuthConfig) => Eff
  */
 export declare const handleCsrf: (config: AuthConfig) => HandlerResult;
 
+/**
+ * Redeem a verification link.
+ *
+ * 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>;
+
+/**
+ * Request (or re-request) a verification link.
+ *
+ * Always 202, whether or not the address has an account and whether or not the
+ * cooldown suppressed the send — same reasoning as magic-link and
+ * password-reset. Two things leak from a status that varies: which addresses
+ * 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 handleImpersonationStart: (input: ImpersonationStartInput, store: UserStore, deps: ImpersonationDeps) => Effect.Effect<HandlerResultShape_3>;
+
+/**
+ * End an impersonation and put the impersonator back in their own identity.
+ *
+ * Three things happen, in this order, and all three matter:
+ *
+ *   1. the grant is CLOSED (`endedAt`), so the record says when it stopped;
+ *   2. the impersonated `sessions` row is DELETED and dropped from the
+ *      revocation cache — so a copy of that cookie taken during the grant is
+ *      dead immediately, not at its own expiry;
+ *   3. the actor's ORIGINAL session row (never revoked, still ticking) gets a
+ *      fresh cookie for its REMAINING lifetime.
+ *
+ * (3) is why the actor's session is left alive throughout. Minting them a new
+ * session instead would silently extend their login by a full TTL every time
+ * they used the support tool. If their own session has expired or been revoked
+ * 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 handleListInvitations: (input: {
+    readonly callerUserId: string;
+    readonly tenantId: string;
+}, store: UserStore, deps: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+
 export declare const handleListMemberships: (input: {
     readonly userId: string;
 }, store: UserStore) => Effect.Effect<HandlerResult>;
@@ -292,8 +577,26 @@ export declare const handlePasswordResetConfirm: (input: PasswordResetConfirmInp
  *  a single-use reset token when the user exists. */
 export declare const handlePasswordResetRequest: (input: PasswordResetRequestInput, store: UserStore, config: AuthConfig) => Effect.Effect<HandlerResult>;
 
+/**
+ * What is behind this link, without redeeming it — the accept page's read.
+ *
+ * Deliberately unauthenticated and deliberately thin: tenant, role, the
+ * invited address and whether it is still live. It does NOT reveal whether an
+ * account already exists for the address, because that would turn a leaked
+ * invitation into an account-existence oracle for a third party.
+ */
+export declare const handlePreviewInvitation: (input: {
+    readonly token: string;
+}, store: UserStore, deps?: InvitationDeps) => Effect.Effect<HandlerResultShape_2>;
+
 export declare const handleRevokeAllOtherSessions: (input: RevokeOtherSessionsInput, store: UserStore) => 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>;
+
 export declare const handleRevokeSession: (input: RevokeSessionInput, store: UserStore) => Effect.Effect<HandlerResult>;
 
 export declare interface HandlerResult {
@@ -304,6 +607,26 @@ export declare interface HandlerResult {
     readonly location?: string;
 }
 
+declare interface HandlerResultShape {
+    readonly status: number;
+    readonly body: string;
+    readonly contentType?: string;
+}
+
+declare interface HandlerResultShape_2 {
+    readonly status: number;
+    readonly body: string;
+    readonly contentType?: string;
+    readonly setCookie?: string;
+}
+
+declare interface HandlerResultShape_3 {
+    readonly status: number;
+    readonly body: string;
+    readonly contentType?: string;
+    readonly setCookie?: string;
+}
+
 /**
  * Sign-in handler. Accepts either form-encoded OR JSON input with
  * `email` + `password`. Returns:
@@ -347,10 +670,15 @@ export declare const handleSignUp: (input: SignUpInput, store: UserStore, config
 
 /**
  * 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).
+ * `targetTenantId` (the switch-tenant guard), re-issues the session cookie
+ * with the new active tenant, and — when a `clientId` + `rebind` are supplied —
+ * presents that new cookie on the live connection so its subsequent calls
+ * resolve against the target tenant without a reconnect.
+ *
+ * Calls only. Subscriptions already open on that connection were authorized
+ * under the previous cookie and keep running until the client re-subscribes;
+ * 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>;
 
@@ -366,10 +694,324 @@ 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;
 
+/** Default grant lifetime — 15 minutes. A support interaction, not a shift. */
+export declare const IMPERSONATION_DEFAULT_DURATION_S: number;
+
+/**
+ * Sub-paths of the auth surface that an IMPERSONATED session may not reach.
+ *
+ * Every one of them either mints a durable credential on the account (MFA,
+ * passkeys), destroys the impersonator's way back (revoke-others, which would
+ * kill the actor's own restored-to session), moves the session somewhere the
+ * grant does not describe (switch-tenant), or extends the grant (a second
+ * impersonation). Suffixes, matched against the plugin's configured prefix.
+ */
+export declare const IMPERSONATION_FORBIDDEN_SUBPATHS: ReadonlyArray<string>;
+
+/** The subject-metadata key carrying the mark. */
+export declare const IMPERSONATION_METADATA_KEY: "impersonation";
+
+export declare interface ImpersonationAuditEvent {
+    readonly kind: ImpersonationAuditKind;
+    readonly at: Date;
+    /** The impersonator. Null only when the attempt had no resolvable caller. */
+    readonly actorUserId: string | null;
+    readonly actorEmail: string | null;
+    /** The impersonated user. Null on a refusal that never resolved one. */
+    readonly targetUserId: string | null;
+    readonly targetEmail: string | null;
+    readonly tenantId: string | null;
+    /** The impersonated session, once one exists. */
+    readonly sessionId?: string;
+    readonly grantId?: string;
+    readonly reason?: string | null;
+    readonly expiresAt?: Date;
+    /** The machine code on `kind: 'refused'` — `self`, `nested`, `not_permitted`,
+     *  `target_may_impersonate`, `reason_required`, `target_not_found`. */
+    readonly refusal?: string;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+/** What happened, for the audit sink. `refused` is recorded too: an attempt
+ *  that was turned away is the single most interesting row in this table. */
+export declare type ImpersonationAuditKind = 'started' | 'stopped' | 'refused';
+
+/**
+ * A `redactSubject` function for `@voltro/plugin-audit` that keeps the
+ * impersonation mark and redacts the rest of `subject.metadata`.
+ *
+ * **Wire this, or your audit rows will not say who was behind an impersonated
+ * action.** `auditPlugin`'s default is `redactSubject: 'metadata'`, which
+ * replaces the whole metadata bag — correct in general (that bag is where a
+ * per-user provider credential lands, and an audit table is the last place a
+ * live PAT should be) and it takes this mark with it. The result is a trail in
+ * which an impersonated action is indistinguishable from the user's own, which
+ * is the exact failure this module exists to prevent.
+ *
+ *     auditPlugin({
+ *       sink: 'datastore',
+ *       redactSubject: impersonationAuditRedactor(),
+ *     })
+ *
+ * It is strictly safer than `redactSubject: 'none'` (which would store the
+ * whole bag, credentials included) and strictly more informative than the
+ * default. The `impersonationGrants` row remains the record that does not
+ * depend on anyone wiring this.
+ */
+export declare const impersonationAuditRedactor: () => (subject: Subject) => unknown;
+
+export declare interface ImpersonationAuthorityInput {
+    /** The caller's resolved subject. */
+    readonly actor: Subject;
+    /** The caller's user row. */
+    readonly actorUser: UserRecord;
+    /** The user they are asking to act as. */
+    readonly target: UserRecord;
+}
+
+export declare interface ImpersonationConfig {
+    /**
+     * MAY this actor impersonate this target? REQUIRED — see the header for why
+     * there is no default and why it must not be a scope check.
+     *
+     * It is called TWICE per start: once as asked, and once with the identities
+     * SWAPPED to answer "could the target impersonate the actor?". A `true` from
+     * the second call refuses the request (the PEER rule). Write it as a pure
+     * predicate over the two records; a function whose answer depends on which
+     * request is in flight will make that probe meaningless.
+     */
+    readonly authority: (input: ImpersonationAuthorityInput) => Effect.Effect<boolean>;
+    /**
+     * Where impersonation events go. REQUIRED, and required precisely because
+     * this is the feature whose whole risk is an unrecorded action: a config
+     * that let you enable impersonation while leaving the destination unset
+     * would make the dangerous half optional and the safe half opt-in.
+     *
+     * Called for `started`, `stopped` AND `refused`. A throwing or rejecting
+     * sink is swallowed — a broken log must not leave a grant half-created —
+     * so treat this as best-effort ON TOP of the `impersonationGrants` row,
+     * which is written transactionally with the session and is not.
+     */
+    readonly audit: (event: ImpersonationAuditEvent) => Effect.Effect<void> | Promise<void> | void;
+    /**
+     * Hard ceiling on one grant, in seconds. Default 900 (15 minutes).
+     *
+     * A caller may request LESS and never more — a requested duration is
+     * clamped, not validated, because a support tool asking for eight hours
+     * should get fifteen minutes rather than an error it will retry around.
+     * The number is the impersonated cookie's TTL as well as the grant row's
+     * `expiresAt`, so the bound survives the process that issued it.
+     */
+    readonly maxDurationSeconds?: number;
+    /** Require a non-empty `reason` on every start. Default `true` — a support
+     *  action with no stated cause is the one you cannot review later. */
+    readonly requireReason?: boolean;
+}
+
+export declare interface ImpersonationDeps {
+    readonly impersonation: ImpersonationConfig;
+    readonly issuer: ImpersonationSessionIssuer;
+    readonly now?: () => number;
+    /** Drop a session id from the request-time revocation cache, so ending a
+     *  grant kills the cookie on THIS process immediately rather than within the
+     *  cache window. */
+    readonly invalidateSession?: (sessionId: string) => void;
+}
+
+/** One impersonation grant — "actor is acting as target, on this session,
+ *  until this instant". See `impersonationGrantsTable`. */
+export declare interface ImpersonationGrantRecord {
+    readonly id: string;
+    /** The IMPERSONATED session's row id. */
+    readonly sessionId: string;
+    readonly actorUserId: string;
+    /** The impersonator's own session, restored when the grant ends. */
+    readonly actorSessionId: string;
+    readonly targetUserId: string;
+    readonly tenantId: string;
+    readonly reason: string | null;
+    readonly startedAt: Date;
+    readonly expiresAt: Date;
+    readonly endedAt: Date | null;
+    readonly endedReason: string | null;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+/** The mark carried on an impersonated session's Subject. Plain JSON — it is
+ *  serialised into a cookie payload and into audit rows. */
+export declare interface ImpersonationMark {
+    /** The impersonating user. */
+    readonly actorUserId: string;
+    /** Their own session, restored when the grant ends. */
+    readonly actorSessionId: string;
+    readonly grantId: string;
+    /** ISO-8601. */
+    readonly startedAt: string;
+    /** ISO-8601. Equals the cookie's own expiry — one number, two places. */
+    readonly expiresAt: string;
+    readonly reason?: string;
+}
+
+/** The impersonation mark on a Subject, or null for an ordinary session. */
+export declare const impersonationOf: (subject: Subject) => ImpersonationMark | null;
+
+/**
+ * How a session is minted. Injected rather than imported so this module has no
+ * edge to `handlers.ts` — and, more usefully, so a test can observe exactly
+ * what TTL and what metadata the impersonated cookie was built with.
+ */
+export declare interface ImpersonationSessionIssuer {
+    readonly issue: (user: UserRecord, options: {
+        readonly sessionId: string;
+        readonly ttlSeconds: number;
+        readonly metadata: Record<string, unknown>;
+        readonly ipAddress?: string | null;
+        readonly userAgent?: string | null;
+    }) => Effect.Effect<{
+        readonly setCookie: string;
+        readonly subject: Subject;
+    }>;
+    /** Re-issue a cookie for an EXISTING session row — the restore on stop. */
+    readonly reissue: (user: UserRecord, options: {
+        readonly sessionId: string;
+        readonly ttlSeconds: number;
+    }) => Effect.Effect<{
+        readonly setCookie: string;
+        readonly subject: Subject;
+    }>;
+    /** A `Set-Cookie` that clears the session — the fallback when the actor's
+     *  own session no longer exists to restore. */
+    readonly clear: () => string;
+}
+
+export declare interface ImpersonationStartInput {
+    /** The caller's resolved subject — from the session cookie, never the body. */
+    readonly actorSubject: Subject;
+    /** The caller's own server-side session id. Restored when the grant ends. */
+    readonly actorSessionId: string;
+    /** Who to act as. One of the two; `userId` wins when both are given. */
+    readonly targetUserId?: string;
+    readonly targetEmail?: string;
+    readonly reason?: string;
+    /** Requested duration. CLAMPED to `maxDurationSeconds`, never exceeded. */
+    readonly durationSeconds?: number;
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+}
+
+export declare interface ImpersonationStopInput {
+    /** The caller's resolved subject — must be an impersonated one. */
+    readonly subject: Subject;
+    /** The caller's current (impersonated) session id. */
+    readonly sessionId: string;
+}
+
+/** Default cap on live invitations per tenant. */
+export declare const INVITATION_MAX_PENDING = 500;
+
+/** Default invitation lifetime — 7 days. Long enough to survive a weekend and
+ *  a holiday Monday, short enough that a forgotten mailbox is not a standing
+ *  key to a tenant. */
+export declare const INVITATION_TTL_S: number;
+
+/** The `AuthConfig` slice these handlers read. Structural so this module does
+ *  not import `handlers.ts`. */
+export declare interface InvitationDeps {
+    readonly appBaseUrl?: string;
+    readonly sendEmail?: (input: {
+        readonly to: string;
+        readonly subject: string;
+        readonly html: string;
+        readonly text: string;
+        readonly kind: 'magic-link' | 'password-reset' | 'email-verify' | 'invitation';
+        readonly actionUrl: string;
+    }) => Promise<void>;
+    readonly invitations?: InvitationsConfig;
+    readonly now?: () => number;
+}
+
+/**
+ * A tenant invitation — the grant that turns into a `memberships` row when
+ * redeemed. See `invitationsTable` for why `role` lives here and not in the
+ * accept request.
+ */
+export declare interface InvitationRecord {
+    readonly id: string;
+    /** SHA-256 hex of the plaintext token. The plaintext lives only in the email. */
+    readonly tokenHash: string;
+    /** The invited address, lower-cased. */
+    readonly email: string;
+    readonly tenantId: string;
+    /** The role the membership is created with. Chosen by the INVITER. */
+    readonly role: string;
+    readonly invitedByUserId: string;
+    readonly expiresAt: Date;
+    readonly acceptedAt: Date | null;
+    readonly acceptedByUserId: string | null;
+    readonly revokedAt: Date | null;
+    readonly revokedByUserId: string | null;
+    readonly createdAt: Date;
+}
+
+export declare interface InvitationsConfig {
+    /** Lifetime of an invitation. Default {@link INVITATION_TTL_S} (7 days). */
+    readonly ttlSeconds?: number;
+    /** Path the emailed link points at. Default `/auth/invitations/accept`. */
+    readonly callbackPath?: string;
+    /**
+     * Cap on simultaneously-live invitations per tenant. Default 500.
+     *
+     * A bound, not a business rule: a compromised admin account otherwise turns
+     * the invite endpoint into a mail cannon aimed at any list of addresses, one
+     * row and one message each, with your domain as the sender.
+     */
+    readonly maxPending?: number;
+    /** Roles permitted to create / list / revoke invitations. Default
+     *  `['owner', 'admin']`. */
+    readonly inviterRoles?: ReadonlyArray<string>;
+    /** Role ordering, most privileged FIRST. Feeds the default
+     *  {@link InvitationsConfig.canGrantRole}. Default
+     *  `['owner','admin','member','viewer']`. */
+    readonly roleRank?: ReadonlyArray<string>;
+    /**
+     * Replace the whole "may this inviter hand out this role" rule.
+     *
+     * The default ranks by {@link InvitationsConfig.roleRank} and permits an
+     * inviter to grant their own role or any role BELOW it; a requested role
+     * absent from the rank list may be granted only by the top-ranked role, and
+     * an inviter whose own role is absent may grant nothing. Supply your own for
+     * any model that is not a line — a matrix, a per-tenant plan, a capability
+     * set. Whatever you write, keep it a refusal by default: this function is
+     * the only thing between an admin and self-promotion by invitation.
+     */
+    readonly canGrantRole?: (ctx: GrantRoleContext) => boolean;
+}
+
 /** Verify a token's own HMAC (signature integrity), independent of the
  *  cookie/header match. */
 export declare const isCsrfTokenWellFormed: (token: string, secret: string) => boolean;
 
+/**
+ * Read the verification mark off a session's Subject.
+ *
+ *   `true`  — proven.
+ *   `false` — NOT proven, and the session says so.
+ *   `null`  — this session carries no mark at all.
+ *
+ * **`null` is not `false`, and conflating them is the failure this tri-state
+ * exists to prevent.** A session minted while the policy was `'off'` — or by
+ * an app that never enabled it — has nothing to say about verification. App
+ * code that treats "no mark" as "unverified" would refuse every one of those
+ * callers the moment the policy is switched on, which is the same outage the
+ * `'off'` default avoids, re-created one layer up. Gate on `=== false`.
+ */
+export declare const isEmailVerified: (subject: Subject) => boolean | null;
+
+/** Is this session an impersonated one? */
+export declare const isImpersonated: (subject: Subject) => 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
@@ -389,8 +1031,14 @@ export declare interface IssuedSession {
  * 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).
+ *
+ * The subject is a `Subject | SubjectIdentity` at the type level and an
+ * IDENTITY on the wire: a session cookie carries no `scopes`, and
+ * `signSession` throws rather than dropping them silently. Authority for
+ * this session is resolved per request by `auth.resolveScopes`, so a role
+ * removed after sign-in takes effect on this same session.
  */
-export declare const issueSession: (subject: Subject, secret: SessionSecretInput, options?: IssueSessionOptions) => IssuedSession;
+export declare const issueSession: (subject: Subject | SubjectIdentity, secret: SessionSecretInput, options?: IssueSessionOptions) => IssuedSession;
 
 export declare interface IssueSessionOptions {
     readonly ttlSeconds?: number;
@@ -399,20 +1047,60 @@ export declare interface IssueSessionOptions {
 }
 
 /**
- * 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.
+ * Issue a real session for a user: load memberships, write the `sessions` row
+ * (so device-list + revocation cover it), and mint the signed cookie.
+ *
+ * **The ONE path that mints a session.** Password sign-in (post-MFA), sign-up,
+ * magic-link, MFA verify, passkey assertion and impersonation all come through
+ * here, so rotation, revocation, the session row and every metadata mark apply
+ * uniformly. Sign-up and magic-link used to carry their own inline copies of
+ * 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?: {
-    readonly ipAddress?: string | null;
-    readonly userAgent?: string | null;
-}) => Effect.Effect<{
+export declare const issueUserSession: (user: UserRecord, store: UserStore, config: AuthConfig, meta?: IssueUserSessionOptions) => Effect.Effect<{
     readonly setCookie: string;
     readonly subject: ReturnType<typeof subjectFromUser>;
 }>;
 
+/** What an `issueUserSession` caller may vary. */
+export declare interface IssueUserSessionOptions {
+    readonly ipAddress?: string | null;
+    readonly userAgent?: string | null;
+    /**
+     * Pre-allocated session-row id. Impersonation supplies one so the grant row
+     * can be written BEFORE the session exists — a session with no record of who
+     * is behind it must never be reachable, not even for a moment.
+     */
+    readonly sessionId?: string;
+    /** Cookie + session-row lifetime. Defaults to the 7-day session TTL;
+     *  impersonation passes its (much shorter) grant duration. */
+    readonly ttlSeconds?: number;
+    /**
+     * `'insert'` (default) writes a fresh `sessions` row. `'existing'` mints a
+     * cookie for a row that is ALREADY there and leaves it untouched.
+     *
+     * `'existing'` is the impersonation stop path putting the actor back into
+     * their own, never-revoked session. Inserting there would duplicate the row
+     * (the memory store appends; a keyed lookup then answers with whichever came
+     * first), and touching it would silently extend the actor's own login by a
+     * full lifetime every time they used the support tool.
+     */
+    readonly sessionRow?: 'insert' | 'existing';
+    /** Extra keys merged onto the Subject's metadata slot — the impersonation
+     *  mark. `sessionId` and the verification flag are set by this function and
+     *  win over anything here. */
+    readonly metadata?: Record<string, unknown>;
+    /**
+     * Clear the brute-force counter for this email. Default TRUE, because a
+     * completed login is proof the password is known.
+     *
+     * IMPERSONATION PASSES FALSE. Nobody authenticated as the target, so
+     * clearing their lockout would let a support action undo brute-force
+     * protection on the very account someone is hammering.
+     */
+    readonly clearLoginFailures?: boolean;
+}
+
 export { KeyedSecret }
 
 declare interface ListSessionsInput {
@@ -508,7 +1196,12 @@ export declare const memoryUserStore: (seed?: ReadonlyArray<UserRecord>) => User
 
 /** 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. */
+ *  that a leaked challenge is near-useless.
+ *
+ *  Lives HERE rather than beside the MFA handler that mints it, because the
+ *  default-TTL table below has to be exhaustive over `TokenPurpose` and a
+ *  constant imported from `handlers.ts` would be a cycle. `handlers.ts`
+ *  re-exports it, so the public spelling is unchanged. */
 export declare const MFA_PENDING_TTL_S: number;
 
 /** MFA (TOTP) enrolment config. */
@@ -564,6 +1257,19 @@ export declare interface MintedToken {
     readonly purpose: TokenPurpose;
 }
 
+/**
+ * Mint a fresh single-use secret with NO purpose attached — 32 CSPRNG bytes,
+ * its SHA-256, and an expiry.
+ *
+ * Exists for the credentials that are single-use, hashed and expiring but do
+ * NOT live in `authTokens`: a tenant invitation carries its own row (with an
+ * address, a tenant and a role), so it has no `TokenPurpose` to name. Reaching
+ * for `mintToken('magic-link', …)` just to obtain the bytes would file an
+ * invitation under a purpose it does not have, in a type everything else reads
+ * as authoritative.
+ */
+export declare const mintSecret: (ttlSeconds: number) => Omit<MintedToken, "purpose">;
+
 /**
  * Mint a fresh single-use token. The caller persists `{ tokenHash,
  * userId, purpose, expiresAt }` via `UserStore.insertToken` and emails
@@ -596,7 +1302,8 @@ declare interface ParsedHash {
 }
 
 /** 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`. */
+ *  string isn't a well-formed `scrypt$N$r$p$salt$derived`, or when its
+ *  parameters exceed the derivation ceiling. */
 export declare const parseScryptParams: (stored: string) => ParsedHash | null;
 
 declare interface PasskeyAssertOptionsInput {
@@ -692,15 +1399,16 @@ 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.
+ * Returns the decoded IDENTITY (a Subject with no `scopes` — authority is
+ * resolved per request, never carried in the cookie) or null when the cookie
+ * is missing, malformed, tampered, expired, or minted under a superseded
+ * payload version. 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;
+export declare const readSession: (cookieHeader: string | undefined, secret: SessionSecretInput) => SubjectIdentity | null;
 
 /**
  * Keyed read: the full `VerifyResult` — subject + the `kid` that
@@ -710,9 +1418,18 @@ export declare const readSession: (cookieHeader: string | undefined, secret: Ses
  */
 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;
+/**
+ * Injected rebinder — the app passes `bindConnectionCredential` from
+ * `@voltro/runtime` so the plugin stays runtime-agnostic.
+ *
+ * It takes the CREDENTIAL this handler just minted, not the Subject it built.
+ * The Subject form was a fast path around the entire auth chain: the middleware
+ * returned the stored value directly, so the connection never re-ran the
+ * session-revocation check, `resolveScopes` or the scope cache again. Handing
+ * the cookie over instead means the connection presents the same credential a
+ * reconnecting browser would, and is judged the same way.
+ */
+export declare type RebindConnection = (clientId: number, credential: ConnectionCredential) => void;
 
 /** A hashed, single-use MFA recovery (backup) code. Minted alongside
  *  enrolment; accepted at sign-in as an alternative to a TOTP code when
@@ -790,11 +1507,21 @@ export declare interface SendEmailInput {
     readonly html: string;
     readonly text: string;
     /** Discriminates the flow so a custom sender can branch. */
-    readonly kind: 'magic-link' | 'password-reset';
+    readonly kind: 'magic-link' | 'password-reset' | 'email-verify' | 'invitation';
     /** The action URL embedded in the email (also present inside `html`). */
     readonly actionUrl: string;
 }
 
+/**
+ * Mint + send a verification link for `user`. Shared by the request handler
+ * and by sign-up, so the cooldown and the URL shape have ONE implementation.
+ *
+ * Returns whether an email was actually dispatched — `false` when the cooldown
+ * 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 SESSION_COOKIE_NAME: "voltro:session";
 
 /** Read the server-side session id carried on a Subject (stamped by the
@@ -970,7 +1697,7 @@ export declare interface SwitchTenantInput {
     readonly metadata?: Record<string, unknown>;
 }
 
-export declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+export declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify';
 
 /** A single-use, hashed, expiring token (magic-link / password-reset). */
 export declare interface TokenRecord {
@@ -1001,6 +1728,16 @@ declare const UserAlreadyExistsError_base: new <A extends Record<string, any> =
     readonly _tag: "UserAlreadyExistsError";
 } & Readonly<A>;
 
+/**
+ * Is this user's address proven, under `config`?
+ *
+ * `exemptAccountsCreatedBefore` is applied HERE rather than at the guard, so
+ * the exemption and the session mark cannot disagree — an exempt user must
+ * read as verified to the client too, or the app shows a "confirm your email"
+ * banner to someone the login already excused.
+ */
+export declare const userEmailVerified: (user: UserRecord, config: EmailVerificationConfig | undefined) => boolean;
+
 export declare class UserNotFoundError extends UserNotFoundError_base<{
     readonly userId: string;
 }> {
@@ -1039,6 +1776,18 @@ export declare interface UserRecord {
      *  verify). Distinct from the secret being set — a half-completed
      *  enrolment leaves `mfaSecret` populated but this null. */
     readonly mfaEnrolledAt?: Date | null;
+    /**
+     * When this address was PROVEN to reach its owner — by redeeming a
+     * verification link, a magic link, or a password-reset link. `null` /
+     * absent = unproven.
+     *
+     * A store whose backing table predates the `emailVerifiedAt` column simply
+     * leaves it undefined, which reads as unverified — and that is why
+     * `emailVerification.policy` defaults to `'off'`: under any stricter
+     * default, "the column is not there yet" and "this user never confirmed"
+     * would both refuse the login.
+     */
+    readonly emailVerifiedAt?: 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.
@@ -1067,6 +1816,15 @@ export declare interface UserStore {
     /** 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
@@ -1104,6 +1862,52 @@ export declare interface UserStore {
      *  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. */