@voltro/plugin-auth 0.32.0 → 0.34.0

package/dist/plugin.d.ts

@@ -1,4 +1,5 @@
 import { AuthStrategy } from '@voltro/protocol';
+import { ConnectionCredential } from '@voltro/protocol';
 import { Effect } from 'effect';
 import { SessionSecrets } from '@voltro/protocol/session';
 import { Subject } from '@voltro/protocol';
@@ -63,6 +64,17 @@ 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;
 }
 
 /**
@@ -97,13 +109,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;
 }
@@ -115,6 +150,45 @@ declare interface ChallengeStore {
     readonly take: (key: string) => Effect.Effect<string | null>;
 }
 
+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;
+}
+
+/** What an account with an unproven address may do. See the header. */
+declare type EmailVerificationPolicy = 'off' | 'soft' | 'strict';
+
 /**
  * Pull the pre-wired session strategy off a plugin list (the framework's
  * serve pipeline calls this when composing the auth chain). Returns the
@@ -122,6 +196,165 @@ declare interface ChallengeStore {
  */
 export declare const getAuthSessionStrategy: (plugins: ReadonlyArray<VoltroPlugin>) => AuthStrategy | null;
 
+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;
+}
+
+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. */
+declare type ImpersonationAuditKind = 'started' | 'stopped' | 'refused';
+
+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;
+}
+
+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;
+}
+
+/** One impersonation grant — "actor is acting as target, on this session,
+ *  until this instant". See `impersonationGrantsTable`. */
+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;
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+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;
+}
+
 /**
  * Brute-force lockout policy, resolved from `AuthConfig.lockout` and passed
  * INTO the store on each failure so the store itself stays policy-free.
@@ -179,9 +412,18 @@ declare interface PasskeyRecord {
     readonly lastUsedAt: Date | null;
 }
 
-/** Injected rebinder — the app passes `bindConnectionSubject` from
- *  `@voltro/runtime` so the plugin stays runtime-agnostic. */
-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.
+ */
+declare type RebindConnection = (clientId: number, credential: ConnectionCredential) => void;
 
 declare type SendEmail = (input: SendEmailInput) => Promise<void>;
 
@@ -194,7 +436,7 @@ 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;
 }
@@ -227,44 +469,6 @@ declare interface SessionRevocationOptions {
     readonly now?: () => number;
 }
 
-/**
- * Convert a UserRecord into the protocol Subject the framework
- * carries around per-request. Tenant id flows through; user type
- * is locked to 'user'.
- *
- * The user's tenant memberships, when supplied, are carried in
- * `metadata.memberships` (the protocol Subject's metadata slot — the
- * framework never reads it, but app code + the switch-tenant menu do).
- * Pass an explicit `tenantId` to make the ACTIVE tenant differ from the
- * user's home tenant (post switch-tenant rebind).
- *
- * `metadata` carries anything else the app needs on the Subject — most
- * often a provider credential captured at login and read back by a
- * plugin's `credentialsResolver` (`subject.metadata.jiraToken` for
- * `@voltro/plugin-atlassian`, say). Without it an app that needs such a
- * credential could not adopt this helper at all: building the Subject by
- * hand was the only way to keep the value.
- *
- * **Precedence, when a `memberships` key appears in BOTH:** the dedicated
- * `memberships` option wins. It is the specific, typed input and it is
- * projected to the `{ tenantId, role }` shape `subjectMemberships` reads,
- * so letting a free-form bag silently shadow it would break the
- * switch-tenant menu in a way nothing type-checks. A `memberships` key
- * inside `metadata` is passed through UNCHANGED when the option is absent
- * — no reshaping, no validation.
- *
- * Note this only stamps the metadata slot at CONSTRUCTION. The sign-in /
- * sign-up / magic-link / passkey handlers later merge `sessionId` (and
- * the password strategy merges `provider`) onto whatever is here, so keys
- * set through this option survive those paths — unless you name a key
- * `sessionId` or `provider`, which those merges overwrite by design.
- */
-declare const subjectFromUser: (user: UserRecord, options?: {
-    readonly tenantId?: string;
-    readonly memberships?: ReadonlyArray<MembershipRecord>;
-    readonly metadata?: Record<string, unknown>;
-}) => Subject;
-
 /**
  * A post-authentication subject guard: given the authenticated user,
  * decide whether the login may proceed. Runs after the credential check,
@@ -283,7 +487,7 @@ declare type SubjectGuardVerdict = {
     readonly message: string;
 };
 
-declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending';
+declare type TokenPurpose = 'magic-link' | 'password-reset' | 'mfa-pending' | 'email-verify';
 
 /** A single-use, hashed, expiring token (magic-link / password-reset). */
 declare interface TokenRecord {
@@ -343,6 +547,18 @@ 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.
@@ -371,6 +587,15 @@ 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
@@ -408,6 +633,52 @@ 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. */

package/dist/plugin.js

@@ -1,4 +1,5 @@
+import "./password.js";
 import "./session.js";
-import { n as e, t } from "./plugin-ZXs8LFn0.js";
+import { n as e, t } from "./plugin-BZm5Semm.js";
 import "./csrf.js";
 export { t as authRoutesPlugin, e as getAuthSessionStrategy };

package/dist/schema.d.ts

@@ -1,7 +1,7 @@
 import { TableLike } from '@voltro/database';
 
 /** Tables the plugin contributes, as an array. */
-export declare const authTables: readonly [TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike];
+export declare const authTables: readonly [TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike, TableLike];
 
 /**
  * Auth-token table. Single-use, hashed, expiring tokens for the
@@ -12,6 +12,51 @@ export declare const authTables: readonly [TableLike, TableLike, TableLike, Tabl
  */
 export declare const authTokensTable: TableLike;
 
+/**
+ * Impersonation grants — one row per "support agent A is acting as user B",
+ * written when the impersonated session is minted and closed when it ends.
+ *
+ * This table is the reason impersonation is auditable AT ALL without the app
+ * wiring anything: the session it describes is, by design, indistinguishable
+ * from B's own session everywhere downstream (same subject id, same tenant,
+ * same authority), so the fact that A is behind it exists in exactly two
+ * places — the session's `metadata.impersonation` mark, and this row. The mark
+ * can be dropped by an audit redaction policy; the row cannot.
+ *
+ * `sessionId` is UNIQUE and points at the `sessions` row for the impersonated
+ * session, which is what makes ending a grant a real revocation rather than a
+ * bookkeeping update: the stop path deletes that session row, and the
+ * request-time revocation check kills the cookie with it.
+ *
+ * `actorSessionId` is the IMPERSONATOR's own session, kept alive throughout so
+ * stopping restores them to their own identity instead of signing them out.
+ */
+export declare const impersonationGrantsTable: TableLike;
+
+/**
+ * Tenant invitations — one row per "you have been invited to <tenant> as
+ * <role>". The row IS the grant: accepting it writes the membership.
+ *
+ * Shaped like `authTokens` on purpose (hashed single-use token, `expiresAt`,
+ * a consumed stamp) because it has the same threat model — the plaintext only
+ * ever travels in the email, so a database leak yields no usable invitation.
+ * What it adds over a token row is the thing an invitation IS and a token is
+ * not: WHO it was addressed to, WHICH tenant it opens, and — the security
+ * property that decides the whole feature — WHAT ROLE it grants.
+ *
+ * `role` is written by the INVITER at creation and read at acceptance. The
+ * accept endpoint takes a token and nothing else, so an invitee cannot name
+ * their own role; the only way to change a pending invitation's role is to
+ * revoke it and issue another.
+ *
+ * Terminal states are all stamps rather than a `status` string, so a row can
+ * never claim two of them: `acceptedAt` (redeemed), `revokedAt` (withdrawn),
+ * and past `expiresAt` (lapsed). `acceptInvitation` matches on all three
+ * being clear in ONE conditional UPDATE, which is what makes acceptance
+ * single-use under concurrency rather than by convention.
+ */
+export declare const invitationsTable: TableLike;
+
 /**
  * Login-attempt counters for brute-force lockout, keyed by normalized
  * email — NOT by user id. Tracking the EMAIL (whether or not a user row

package/dist/schema.js

@@ -7,6 +7,7 @@ var a = n("users", {
 	tenantId: r(),
 	mfaSecret: r().nullable(),
 	mfaEnrolledAt: i().nullable(),
+	emailVerifiedAt: i().nullable(),
 	createdAt: i().default("now"),
 	updatedAt: i().default("now").onUpdate("now")
 }).index(["tenantId"]), o = n("sessions", {
@@ -61,7 +62,34 @@ var a = n("users", {
 	lockedUntil: i().nullable(),
 	createdAt: i().default("now"),
 	updatedAt: i().default("now").onUpdate("now")
-}), p = [
+}), p = n("invitations", {
+	id: e({ prefix: "inv" }),
+	tokenHash: r().unique(),
+	email: r(),
+	tenantId: r(),
+	role: r(),
+	invitedByUserId: r(),
+	expiresAt: i(),
+	acceptedAt: i().nullable(),
+	acceptedByUserId: r().nullable(),
+	revokedAt: i().nullable(),
+	revokedByUserId: r().nullable(),
+	createdAt: i().default("now")
+}).index(["tenantId"]).index(["email"]), m = n("impersonationGrants", {
+	id: e({ prefix: "imp" }),
+	sessionId: r().unique(),
+	actorUserId: r(),
+	actorSessionId: r(),
+	targetUserId: r(),
+	tenantId: r(),
+	reason: r().nullable(),
+	startedAt: i().default("now"),
+	expiresAt: i(),
+	endedAt: i().nullable(),
+	endedReason: r().nullable(),
+	ipAddress: r().nullable(),
+	userAgent: r().nullable()
+}).index(["actorUserId"]).index(["targetUserId"]), h = [
 	a,
 	o,
 	s,
@@ -69,7 +97,9 @@ var a = n("users", {
 	l,
 	u,
 	d,
-	f
+	f,
+	p,
+	m
 ];
 //#endregion
-export { p as authTables, c as authTokensTable, f as loginAttemptsTable, s as membershipsTable, d as passkeyChallengesTable, l as passkeysTable, u as recoveryCodesTable, o as sessionsTable, a as usersTable };
+export { h as authTables, c as authTokensTable, m as impersonationGrantsTable, p as invitationsTable, f as loginAttemptsTable, s as membershipsTable, d as passkeyChallengesTable, l as passkeysTable, u as recoveryCodesTable, o as sessionsTable, a as usersTable };

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import { KeyedSecret } from '@voltro/protocol/session';
 import { SessionSecrets } from '@voltro/protocol/session';
 import { Subject } from '@voltro/protocol';
+import { SubjectIdentity } from '@voltro/protocol';
 import { VerifyOptions } from '@voltro/protocol/session';
 import { VerifyResult } from '@voltro/protocol/session';
 
@@ -22,8 +23,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;
@@ -35,15 +42,16 @@ export { KeyedSecret }
 
 /**
  * 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