cursedbelt 2.8.0 → 3.0.0

package/src/server/services/accountService.ts

@@ -1,817 +0,0 @@
-/**
- * `AccountService` — the account surface the GuardEngine consumes (02 §1/§2). The
- * first and only production consumer of the landed `RegistryIdentityStore`
- * (`cwip/cc-registry`), and the concrete value for the `resolveIdentity` seam.
- *
- * `resolveIdentity` (§1) is the value `createGuardService` calls on the unlock
- * path:
- *
- *   * **local** — a single-user machine. There is no login; the ONE identity is
- *     the reserved `t_local`/`u_local` OWNER bootstrap (`bootstrapLocalIdentity`),
- *     carrying `infra:write`. A successful passphrase check always resolves to
- *     that owner, and local DX is unchanged (no login prompt).
- *   * **saas** — many tenants. The identity is whoever the request's verified
- *     session says it is: `login` minted the token, the signer already verified it
- *     on the request path, and `resolveIdentity` reads the claims back through the
- *     injected `currentClaims` accessor. It re-reads the membership from the store
- *     so a role change or a revoked membership is honored on the NEXT resolve
- *     (§3) rather than frozen into the token.
- *
- * `signup`/`login`/`changePassword` (§2) are the authentication surface, mounted
- * behind `guard.features.accounts` in `guard.mixin.ts` — no method here is an
- * orphan seam (Law #1). Every password rides the ONE argon2id KDF seam through
- * {@link ../guard/passwordVerifier} (Law #7): there is no second hash, no second
- * at-rest secret format, no `server/auth/password.ts`. Passwords arrive as bytes
- * the service CONSUMES (zeroized before return, on every path — 01 §3.4).
- */
-import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import {
-  type Membership,
-  type MembershipRole,
-  type RegistryIdentityStore,
-  RESERVED_TENANT_ID,
-} from 'cwip/cc-registry';
-import { type Argon2idDeriver, zeroize } from 'cwip/guard';
-import type { SignupMode } from '../../config/appConfig';
-import {
-  type CCRole,
-  type CCUserClaims,
-  CC_ROLE_RANK,
-  effectivePermissions,
-  hasPermission,
-  INFRA_WRITE,
-  roleAtLeast,
-} from '../../core/session/claims';
-import { AppError } from '../errors';
-import type {
-  AccountService,
-  CallScope,
-  MemberPatch,
-  MemberView,
-  SessionView,
-  UnlockedIdentity,
-} from '../mixins/services';
-import { createInProcessPasswordVerifier, type PasswordVerifierPort } from '../guard/passwordVerifier';
-import type { SessionSigner } from '../guard/sessionSigner';
-
-// The account interface + its request/view types live in the client-light
-// `mixins/services.ts` alongside every other engine service interface (02 §2);
-// re-exported here for the existing `../services` barrel import sites.
-export type {
-  AccountService,
-  AccountView,
-  InvitationView,
-  LoginRequest,
-  MemberPatch,
-  MemberView,
-  PasswordChangeRequest,
-  SessionView,
-  SignupRequest,
-  TenantView,
-} from '../mixins/services';
-
-/** Which resolution rule applies — mirrors `manifest.profile`. */
-export type AccountProfile = 'local' | 'saas';
-
-/**
- * The ONE rule for whether a signup attempt is admissible under a
- * {@link SignupMode} (D33). Shared by the service (authoritative, refuses
- * before the KDF or any store write) and the guard mixin (a cheap short-circuit
- * before the password bytes are even read), so the two can never disagree
- * about what a closed door is. Returns the error to throw, or null.
- */
-export const refuseGatedSignup = (mode: SignupMode, hasInviteToken: boolean): AppError | null => {
-  if (mode === 'closed')
-    return new AppError('New account sign-ups are not open yet.', {
-      code: 'SIGNUP_CLOSED',
-      status: 403,
-      category: 'security',
-    });
-  if (mode === 'invite' && !hasInviteToken)
-    return new AppError('Sign-ups are invite-only right now. Open your invitation link to create an account.', {
-      code: 'SIGNUP_INVITE_ONLY',
-      status: 403,
-      category: 'security',
-    });
-  return null;
-};
-
-export interface CreateAccountServiceOptions {
-  /** The opened identity store (handle injection — the host owns the registry db). */
-  readonly identity: RegistryIdentityStore;
-  /** `local` resolves the bootstrap owner; `saas` resolves the request session. */
-  readonly profile: AccountProfile;
-  /**
-   * saas only: the verified claims of the in-flight request. The server sets this
-   * per request (the signer has already verified the token); the resolver reads it
-   * back. Returning `null` (no session) resolves the identity to `null`. Ignored
-   * under `local`, where there is no per-request session.
-   */
-  readonly currentClaims?: () => CCUserClaims | null;
-  /**
-   * The session signer used to MINT on login (the SAME instance the runtime
-   * verifies with). Optional: a resolveIdentity-only construction (the recipe's
-   * local default) omits it; `login` then fails loudly rather than minting an
-   * unverifiable token.
-   */
-  readonly signer?: SessionSigner;
-  /**
-   * The argon2id deriver for password verifiers. Omitted ⇒ the process-wide one
-   * registered at boot (`setArgon2idDeriver`) is used — the normal path.
-   */
-  readonly deriver?: Argon2idDeriver;
-  /**
-   * WHERE password derivation runs (05 §B6). Omitted ⇒ on this thread, using
-   * `deriver` — the behavior that shipped before this option existed, and the
-   * right one for a single-user local app.
-   *
-   * A saas host expecting login concurrency passes
-   * `createKdfWorkerPasswordVerifier({ entry: kdfWorkerEntryUrl() })` instead:
-   * argon2id is ~150–250 ms of pure CPU per attempt and the seam is synchronous,
-   * so on one thread a login burst serializes AND stalls every unrelated request
-   * on the node. Supplying a port DOES NOT change the KDF, the envelope format
-   * or the verifier — the worker runs these very functions — so the two
-   * configurations are interoperable: an envelope sealed on one opens on the
-   * other. When both are given, `passwords` wins and `deriver` is unused.
-   */
-  readonly passwords?: PasswordVerifierPort;
-  /**
-   * The launch gate (D33): who may sign up. `guard.features.signupMode` feeds
-   * this (the recipe passes `effectiveSignupMode(manifest.instances)`).
-   * Default `open` — the pre-gate behavior, and the right one for local apps.
-   */
-  readonly signupMode?: SignupMode;
-  /** Id generator for new users/tenants. Default `crypto.randomUUID`. */
-  readonly mintId?: () => string;
-  /** Clock (epoch ms) for invitation expiry. Injected by tests. */
-  readonly now?: () => number;
-  /** Default invitation lifetime. 7 days. */
-  readonly invitationTtlMinutes?: number;
-}
-
-/**
- * A membership → the identity a session carries. `permissions` is the EFFECTIVE
- * grant (the role's own ∪ the explicit per-membership grants, 02 §3), not the
- * stored array: roles are the RBAC surface, and a membership row's `permissions`
- * column is the exception list on top of it. The array is freshly built per call
- * so a caller mutating it cannot corrupt the stored (or memoized) membership.
- */
-const identityFromMembership = (
-  membership: { tenantId: string; userId: string; role: UnlockedIdentity['role']; permissions: readonly string[] },
-): UnlockedIdentity => ({
-  tenantId: membership.tenantId,
-  userId: membership.userId,
-  role: membership.role,
-  permissions: effectivePermissions(membership.role, membership.permissions),
-});
-
-// ONE message for "no such user" and "wrong password" — anything finer is a
-// user-enumeration oracle. Returns the error so call sites `throw` it, which lets
-// control-flow analysis narrow the null checks that precede it.
-const loginRejected = (): AppError =>
-  new AppError('Invalid email or password.', { code: 'LOGIN_REJECTED', status: 401, category: 'security' });
-
-export function createAccountService(options: CreateAccountServiceOptions): AccountService {
-  const { identity, profile, deriver } = options;
-  // One port for every password operation in this service. The default keeps the
-  // derivation on this thread, so a host that passes neither option behaves
-  // exactly as it did before the port existed.
-  const passwords = options.passwords ?? createInProcessPasswordVerifier(deriver);
-  const mintId = options.mintId ?? (() => randomUUID());
-  const now = options.now ?? (() => Date.now());
-  const invitationTtlMinutes = options.invitationTtlMinutes ?? 7 * 24 * 60;
-
-  const requireSigner = (): SessionSigner => {
-    if (!options.signer)
-      throw new AppError('AccountService was constructed without a signer; login cannot mint a session.', {
-        code: 'ACCOUNT_SIGNER_MISSING',
-        status: 500,
-        category: 'security',
-        isOperational: false,
-      });
-    return options.signer;
-  };
-
-  // ── resolveIdentity (§1) ──────────────────────────────────────────────────
-  // The bootstrap owner is idempotent to mint, but the resolve runs on the unlock
-  // path — memoize the store read so a repeated unlock is not a repeated write +
-  // signature verify. A FRESH identity is built per resolve so a caller mutating
-  // the returned `permissions` cannot corrupt the memoized state.
-  let bootstrapMembership: Membership | null = null;
-
-  const resolveLocal = async (): Promise<UnlockedIdentity> => {
-    if (!bootstrapMembership) bootstrapMembership = (await identity.bootstrapLocalIdentity()).membership;
-    return identityFromMembership(bootstrapMembership);
-  };
-
-  const resolveSaas = async (): Promise<UnlockedIdentity | null> => {
-    const claims = options.currentClaims?.() ?? null;
-    if (!claims) return null;
-    // The token is already signature-verified; re-read the membership so the
-    // AUTHORITATIVE role/permissions win over whatever the token froze, and a
-    // membership that was revoked/suspended since the token was minted rejects
-    // the resolve (§3 — the next resolve honors the grant change).
-    const membership = await identity.getMembership(claims.tenantId, claims.userId);
-    // A suspended MEMBERSHIP or a suspended TENANT resolves to nobody (§3).
-    if (!membership || !(await usable(membership))) return null;
-    return identityFromMembership(membership);
-  };
-
-  // ── login enumeration resistance (§2) ─────────────────────────────────────
-  // A login for an unknown email must still pay one argon2id derivation, or the
-  // response-time difference reveals which emails have accounts. Lazily seal a
-  // throwaway verifier once and re-check the presented password against it.
-  let dummyEnvelope: string | null = null;
-  const burnAgainstDummy = async (password: Uint8Array): Promise<void> => {
-    if (!dummyEnvelope) dummyEnvelope = await passwords.seal('cc-dummy', new Uint8Array(randomBytes(32)));
-    // Consumes `password`; the verdict is discarded.
-    await passwords.verify('cc-dummy', dummyEnvelope, password);
-  };
-
-  /**
-   * A membership is only usable when BOTH it and its tenant are active (§3).
-   * Checking the membership alone would let a suspended tenant's members log
-   * straight back in after the suspension revoked their sessions — the
-   * suspension would revoke tokens and change nothing.
-   */
-  const usable = async (membership: Membership): Promise<boolean> =>
-    membership.status === 'active' && (await identity.getTenant(membership.tenantId))?.status === 'active';
-
-  /**
-   * The first usable membership. Sequential on purpose: `usable` hits the store,
-   * and `Array.find` cannot await — mapping every membership through it in
-   * parallel would issue a tenant read per membership when the first one almost
-   * always answers.
-   */
-  const pickMembership = async (
-    userId: string,
-  ): Promise<{ tenantId: string; userId: string; role: MembershipRole; permissions: readonly string[] } | null> => {
-    for (const membership of await identity.membershipsForUser(userId))
-      if (await usable(membership)) return membership;
-    return null;
-  };
-
-  // ── tenant / RBAC administration (§3) ─────────────────────────────────────
-  //
-  // Every rule below is decided HERE, from the store, on every call. Three
-  // properties this shape buys that a route-level check cannot:
-  //
-  //   * the acting role is re-read from `memberships`, so a demotion takes
-  //     effect on the next admin call even if the caller's token still says
-  //     ADMIN (the token is authentication; the store is authority);
-  //   * a caller may only administer the tenant their session is FOR, so a
-  //     token for tenant A is not an admin credential for tenant B;
-  //   * the escalation rules are one function, so no verb can forget them.
-
-  const denied = (message: string, code: string, status = 403, context?: Record<string, unknown>): never => {
-    throw new AppError(message, { code, status, category: 'security', ...(context ? { context } : {}) });
-  };
-
-  const toMemberView = async (membership: Membership): Promise<MemberView> => ({
-    tenantId: membership.tenantId,
-    userId: membership.userId,
-    email: (await identity.getUser(membership.userId))?.email,
-    role: membership.role,
-    grants: [...membership.permissions],
-    permissions: effectivePermissions(membership.role, membership.permissions),
-    status: membership.status,
-  });
-
-  /** The caller's CURRENT membership in `tenantId`, or a typed refusal. */
-  const actingMembership = async (scope: CallScope, tenantId: string): Promise<Membership> => {
-    const claims = scope.claims;
-    if (claims.tenantId !== tenantId)
-      denied('This session is not for that tenant.', 'CROSS_TENANT_DENIED', 403, { tenantId });
-    const membership = await identity.getMembership(tenantId, claims.userId);
-    if (!membership || membership.status !== 'active')
-      denied('This account has no active membership in that tenant.', 'MEMBERSHIP_INACTIVE', 403, { tenantId });
-    return membership as Membership;
-  };
-
-  const requireRole = async (scope: CallScope, tenantId: string, floor: CCRole): Promise<Membership> => {
-    const actor = await actingMembership(scope, tenantId);
-    if (!roleAtLeast(actor.role, floor))
-      denied(`This operation requires the ${floor} role or higher.`, 'ROLE_REQUIRED', 403, { required: floor });
-    return actor;
-  };
-
-  /**
-   * The privilege-escalation rule, in one place: you may never hand out a role
-   * above your own — which is also what makes "only an OWNER assigns OWNER"
-   * true, since OWNER is the top rank. A VIEWER cannot grant themselves up
-   * because they never clear the ADMIN floor to reach this at all.
-   */
-  const assertCanAssignRole = (actor: Membership, role: CCRole): void => {
-    // An unknown role has no rank, so `roleAtLeast` refuses it — fail-closed by
-    // construction. Naming it separately turns a confusing 403 into a 400.
-    if (CC_ROLE_RANK[role] === undefined)
-      throw new AppError(`'${role}' is not a role.`, {
-        code: 'ROLE_INVALID',
-        status: 400,
-        category: 'validation',
-        context: { role, roles: Object.keys(CC_ROLE_RANK) },
-      });
-    if (!roleAtLeast(actor.role, role))
-      denied(`A ${actor.role} cannot assign the ${role} role.`, 'ROLE_ESCALATION_DENIED', 403, {
-        actorRole: actor.role,
-        requested: role,
-      });
-  };
-
-  /** Explicit grants are capped by what the ACTOR themselves effectively holds. */
-  const assertCanAssignGrants = (actor: Membership, grants: readonly string[]): void => {
-    // The patch arrives from a JSON body: validate the SHAPE here rather than
-    // trusting the route's cast, or a `grants: "infra:write"` string reaches
-    // `.filter` as a 500 instead of a typed 400.
-    if (!Array.isArray(grants) || grants.some((grant) => typeof grant !== 'string'))
-      throw new AppError('`grants` must be an array of permission strings.', {
-        code: 'GRANTS_INVALID',
-        status: 400,
-        category: 'validation',
-      });
-    const held = new Set(effectivePermissions(actor.role, actor.permissions));
-    const beyond = grants.filter((grant) => !held.has(grant));
-    if (beyond.length > 0)
-      denied(
-        `Cannot grant permissions you do not hold: ${beyond.join(', ')}.`,
-        'PERMISSION_ESCALATION_DENIED',
-        403,
-        { beyond },
-      );
-  };
-
-  const assertCanActOn = (actor: Membership, target: Membership): void => {
-    if (actor.userId === target.userId)
-      denied(
-        'An administrator cannot change their own membership — ask another OWNER/ADMIN.',
-        'SELF_ADMIN_DENIED',
-        403,
-      );
-    if (CC_ROLE_RANK[target.role] > CC_ROLE_RANK[actor.role])
-      denied(`A ${actor.role} cannot act on a ${target.role}.`, 'ROLE_ESCALATION_DENIED', 403, {
-        actorRole: actor.role,
-        targetRole: target.role,
-      });
-  };
-
-  /**
-   * Refuse a change that would leave the tenant with no active OWNER — an
-   * ownerless tenant can never be administered again, and no amount of support
-   * tooling brings one back without a manual db edit.
-   */
-  const assertNotLastOwner = async (target: Membership): Promise<void> => {
-    if (target.role !== 'OWNER' || target.status !== 'active') return;
-    const owners = (await identity.membersOfTenant(target.tenantId)).filter(
-      (member) => member.role === 'OWNER' && member.status === 'active',
-    );
-    if (owners.length <= 1)
-      denied(
-        'This is the tenant’s last active OWNER — promote another owner first.',
-        'LAST_OWNER',
-        409,
-        { tenantId: target.tenantId },
-      );
-  };
-
-  /**
-   * A grant change must close the target's live sessions. Routes authorize from
-   * the token's claims (`guardVerify` → `hasPermission`), so a demotion that
-   * leaves the old token alive is a demotion that did not happen. Under saas the
-   * signer writes each revoked jti through to the shared `revocationStore`, so
-   * the close is fleet-wide (03 §4a).
-   */
-  const revokeSessionsOf = (userId: string): void => {
-    options.signer?.revokeUser(userId);
-  };
-
-  /** A signer record → the wire view. Epoch seconds become ISO strings once, here. */
-  const toSessionView = (
-    record: { jti: string; tenantId: string; deviceLabel?: string; issuedAt: number; exp: number },
-    currentJti: string,
-  ): SessionView => ({
-    jti: record.jti,
-    tenantId: record.tenantId,
-    ...(record.deviceLabel ? { deviceLabel: record.deviceLabel } : {}),
-    issuedAt: new Date(record.issuedAt * 1000).toISOString(),
-    expiresAt: new Date(record.exp * 1000).toISOString(),
-    current: record.jti === currentJti,
-  });
-
-  const hashInviteToken = (token: string): string => createHash('sha256').update(token, 'utf8').digest('hex');
-
-  /**
-   * Validate an invitation and hand back what it grants. Shared by
-   * `acceptInvitation` (an existing account) and invite-gated `signup` (a brand
-   * new one) so the two can never disagree about what a valid invite is.
-   */
-  const consumableInvitation = async (
-    token: string,
-    email: string,
-  ): Promise<{ tenantId: string; role: CCRole; tokenHash: string }> => {
-    const tokenHash = hashInviteToken(token);
-    const invitation = await identity.getInvitation(tokenHash);
-    // One message for "no such invitation" and "wrong token": an invite token is
-    // a bearer secret, and distinguishing the two is a probing oracle.
-    if (!invitation)
-      throw new AppError('That invitation is not valid.', { code: 'INVITATION_INVALID', status: 404, category: 'security' });
-    if (invitation.acceptedAt)
-      throw new AppError('That invitation has already been used.', {
-        code: 'INVITATION_USED',
-        status: 409,
-        category: 'security',
-      });
-    if (Date.parse(invitation.expiresAt) <= now())
-      throw new AppError('That invitation has expired.', { code: 'INVITATION_EXPIRED', status: 410, category: 'security' });
-    if (invitation.email.trim().toLowerCase() !== email.trim().toLowerCase())
-      throw new AppError('That invitation was issued to a different email address.', {
-        code: 'INVITATION_EMAIL_MISMATCH',
-        status: 403,
-        category: 'security',
-      });
-    return { tenantId: invitation.tenantId, role: invitation.role, tokenHash };
-  };
-
-  return {
-    async resolveIdentity() {
-      return profile === 'local' ? resolveLocal() : resolveSaas();
-    },
-
-    async signup(req) {
-      // The launch gate (D33) runs FIRST — before the KDF, before any store
-      // read. A closed door must not double as a user-enumeration oracle, so it
-      // refuses without ever asking whether the email exists.
-      const gateError = refuseGatedSignup(options.signupMode ?? 'open', req.inviteToken !== undefined);
-      if (gateError) {
-        zeroize(req.password);
-        throw gateError;
-      }
-      const email = req.email?.trim();
-      // Validate BEFORE the KDF consumes the password, zeroizing on an early throw.
-      if (!email) {
-        zeroize(req.password);
-        throw new AppError('An email is required to sign up.', { code: 'EMAIL_REQUIRED', status: 400, category: 'validation' });
-      }
-      if (await identity.getUserByEmail(email)) {
-        zeroize(req.password);
-        throw new AppError('An account with that email already exists.', {
-          code: 'EMAIL_IN_USE',
-          status: 409,
-          category: 'validation',
-          context: { email },
-        });
-      }
-
-      // An invite-gated signup (§3): validate BEFORE the KDF runs, so a bad
-      // token costs no derivation and the password is zeroized on the way out.
-      let invited: { tenantId: string; role: CCRole; tokenHash: string } | null = null;
-      if (req.inviteToken !== undefined) {
-        try {
-          invited = await consumableInvitation(req.inviteToken, email);
-        } catch (error) {
-          zeroize(req.password);
-          throw error;
-        }
-      }
-
-      const userId = `u_${mintId()}`;
-      // Consumes req.password.
-      const pwEnvelope = await passwords.seal(userId, req.password);
-      await identity.createUser({ userId, email, pwEnvelope });
-
-      let tenantId: string;
-      let role: MembershipRole;
-      if (invited) {
-        // The inviter decided the tenant AND the role; `req.role`/`tenantTitle`
-        // are ignored, or an invitee would name their own privileges.
-        await identity.acceptInvitation(invited.tokenHash);
-        tenantId = invited.tenantId;
-        role = invited.role;
-      } else if (profile === 'saas') {
-        tenantId = `t_${mintId()}`;
-        await identity.createTenant({ tenantId, title: req.tenantTitle?.trim() || email });
-        role = req.role ?? 'OWNER';
-      } else {
-        // Local: the single machine's tenant. Ensure it exists, then add the user.
-        await identity.bootstrapLocalIdentity();
-        tenantId = RESERVED_TENANT_ID;
-        role = req.role ?? 'MEMBER';
-      }
-      await identity.createMembership({ tenantId, userId, role });
-      return { userId, email, tenantId, role };
-    },
-
-    async login(req) {
-      const signer = requireSigner();
-      const email = req.email?.trim();
-      const user = email ? await identity.getUserByEmail(email) : null;
-      const envelope = user ? await identity.passwordEnvelope(user.userId) : null;
-
-      if (!user || !envelope) {
-        // Equalize timing against the present-user path, then reject uniformly.
-        await burnAgainstDummy(req.password);
-        throw loginRejected();
-      }
-
-      // Consumes req.password.
-      const ok = await passwords.verify(user.userId, envelope, req.password);
-      if (!ok) throw loginRejected();
-
-      const membership = await pickMembership(user.userId);
-      if (!membership)
-        throw new AppError('This account has no active membership.', {
-          code: 'NO_ACTIVE_MEMBERSHIP',
-          status: 403,
-          category: 'security',
-          context: { userId: user.userId },
-        });
-
-      const minted = signer.mint(
-        {
-          tenantId: membership.tenantId,
-          userId: user.userId,
-          role: membership.role,
-          // The EFFECTIVE grant: the role's own permissions ∪ the explicit ones
-          // (§3). Minting only the explicit list is what made `features.rbac` a
-          // switch that locked every non-bootstrap account out of every gated route.
-          permissions: effectivePermissions(membership.role, membership.permissions),
-          // Login establishes identity, not a private-mode reveal — that is `unlock`.
-          privateScope: false,
-        },
-        // Display metadata for the sessions panel (§4), recorded beside the jti.
-        req.deviceLabel ? { deviceLabel: req.deviceLabel } : undefined,
-      );
-      return { token: minted.token, claims: minted.claims };
-    },
-
-    async changePassword(scope, userId, req) {
-      const caller = scope.claims;
-      const isSelf = caller.userId === userId;
-      const isAdmin = caller.role === 'OWNER' || caller.role === 'ADMIN' || hasPermission(caller, INFRA_WRITE);
-
-      const bail = (message: string, code: string, status: number): never => {
-        if (req.current) zeroize(req.current);
-        zeroize(req.next);
-        throw new AppError(message, { code, status, category: 'security' });
-      };
-
-      if (!isSelf && !isAdmin)
-        bail('Changing another account’s password requires ADMIN or OWNER.', 'PERMISSION_DENIED', 403);
-      if (!(await identity.getUser(userId))) bail('No such account.', 'ACCOUNT_NOT_FOUND', 404);
-
-      if (isSelf) {
-        // A self-change re-authenticates with the current password so a hijacked
-        // (but not password-knowing) session cannot lock the real user out.
-        const envelope = await identity.passwordEnvelope(userId);
-        const verified =
-          req.current !== undefined && envelope !== null && (await passwords.verify(userId, envelope, req.current));
-        if (!verified) {
-          // If verify short-circuited (no current / no envelope) it never consumed
-          // `current` — zeroize it here; otherwise verify already did.
-          if (req.current !== undefined && envelope === null) zeroize(req.current);
-          zeroize(req.next);
-          throw new AppError('The current password is incorrect.', {
-            code: 'CURRENT_PASSWORD_REJECTED',
-            status: 401,
-            category: 'security',
-          });
-        }
-      } else if (req.current !== undefined) {
-        // Admin reset does not re-auth with the target's current password; if the
-        // caller sent one anyway, it is unused — zeroize it.
-        zeroize(req.current);
-      }
-
-      // Consumes req.next.
-      const pwEnvelope = await passwords.seal(userId, req.next);
-      await identity.setPassword(userId, pwEnvelope);
-    },
-
-    /* ---- session concurrency & lifecycle, multi-device (§4) ------------- */
-
-    async listSessions(scope) {
-      const signer = requireSigner();
-      return signer.sessionsOf(scope.claims.userId).map((record) => toSessionView(record, scope.claims.jti));
-    },
-
-    async refreshSession(scope) {
-      const signer = requireSigner();
-      const claims = scope.claims;
-      // The store, not the token, decides what the NEW token carries: refresh is
-      // the moment a still-valid session picks up an authoritative re-read, so a
-      // membership that was suspended (or whose tenant was) cannot refresh its
-      // way past the change.
-      const membership = await identity.getMembership(claims.tenantId, claims.userId);
-      if (!membership || !(await usable(membership)))
-        throw new AppError('This session’s membership is no longer active.', {
-          code: 'MEMBERSHIP_INACTIVE',
-          status: 403,
-          category: 'security',
-        });
-
-      // Carry the device label across so a refreshed session does not silently
-      // become "unknown device" in the panel.
-      const previous = signer.sessionsOf(claims.userId).find((record) => record.jti === claims.jti);
-      const minted = signer.mint(
-        {
-          tenantId: membership.tenantId,
-          userId: claims.userId,
-          role: membership.role,
-          permissions: effectivePermissions(membership.role, membership.permissions),
-          // A refresh is not a re-unlock: the private-mode reveal is re-earned
-          // with the passphrase, never extended by rotating the token.
-          privateScope: false,
-        },
-        previous?.deviceLabel ? { deviceLabel: previous.deviceLabel } : undefined,
-      );
-      // Mint FIRST, then close the old jti: the exchange must not leave the
-      // caller session-less if minting throws.
-      signer.revoke(claims.jti);
-      return { token: minted.token, claims: minted.claims };
-    },
-
-    async endSession(scope, jti) {
-      const signer = requireSigner();
-      // Only among the CALLER's own sessions: a jti is a bearer handle, and
-      // revoking one you merely guessed would be a logout oracle for other
-      // accounts. An unknown/foreign jti is reported as "nothing ended".
-      const owned = signer.sessionsOf(scope.claims.userId).some((record) => record.jti === jti);
-      if (!owned) return false;
-      signer.revoke(jti);
-      return true;
-    },
-
-    async logoutEverywhere(scope) {
-      const signer = requireSigner();
-      // Including the calling session — "log out everywhere" that leaves the
-      // device you clicked it on logged in is the bug the verb exists to avoid.
-      return { revoked: signer.revokeUser(scope.claims.userId).length };
-    },
-
-    /* ---- tenant lifecycle & RBAC administration (§3) -------------------- */
-
-    async getTenant(scope, tenantId) {
-      // Any active member may read their own tenant — it is the header of every
-      // account screen. Administering it is the ADMIN/OWNER surface below.
-      await actingMembership(scope, tenantId);
-      const tenant = await identity.getTenant(tenantId);
-      return tenant
-        ? { tenantId: tenant.tenantId, title: tenant.title, status: tenant.status, planId: tenant.planId }
-        : null;
-    },
-
-    async updateTenant(scope, tenantId, patch) {
-      const actor = await requireRole(scope, tenantId, 'ADMIN');
-      if (!(await identity.getTenant(tenantId)))
-        throw new AppError('No such tenant.', { code: 'TENANT_NOT_FOUND', status: 404, category: 'validation' });
-
-      if (patch.title !== undefined) {
-        const title = patch.title.trim();
-        if (!title)
-          throw new AppError('A tenant title cannot be empty.', {
-            code: 'TENANT_TITLE_REQUIRED',
-            status: 400,
-            category: 'validation',
-          });
-        await identity.renameTenant(tenantId, title);
-      }
-      if (patch.status !== undefined) {
-        // Suspending or soft-deleting a tenant takes the whole product away from
-        // every one of its members — an ADMIN runs the tenant, an OWNER decides
-        // whether it exists.
-        if (actor.role !== 'OWNER')
-          denied('Only an OWNER may change a tenant’s status.', 'ROLE_REQUIRED', 403, { required: 'OWNER' });
-        await identity.setTenantStatus(tenantId, patch.status);
-        // A suspended/deleted tenant must stop serving NOW, not at token expiry.
-        if (patch.status !== 'active')
-          for (const member of await identity.membersOfTenant(tenantId)) revokeSessionsOf(member.userId);
-      }
-      const tenant = (await identity.getTenant(tenantId)) as NonNullable<Awaited<ReturnType<RegistryIdentityStore['getTenant']>>>;
-      return { tenantId: tenant.tenantId, title: tenant.title, status: tenant.status, planId: tenant.planId };
-    },
-
-    async setTenantPlan(scope, tenantId, planId) {
-      // Platform-scoping happens at the route (the store-anchored platform
-      // tenant — see the interface doc); the service owns validation and the
-      // write. `scope` still matters: the verb requires an authenticated
-      // caller, and the id in the audit trail is the assigner's.
-      void scope;
-      if (!/^[a-z][a-z0-9-]{0,39}$/.test(planId))
-        throw new AppError('A plan id is 1-40 chars of [a-z0-9-], starting with a letter.', {
-          code: 'PLAN_ID_INVALID',
-          status: 400,
-          category: 'validation',
-        });
-      const updated = await identity.setTenantPlan(tenantId, planId);
-      if (!updated)
-        throw new AppError('No such tenant.', { code: 'TENANT_NOT_FOUND', status: 404, category: 'validation' });
-      return { tenantId: updated.tenantId, title: updated.title, status: updated.status, planId: updated.planId };
-    },
-
-    async listMembers(scope, tenantId) {
-      await requireRole(scope, tenantId, 'ADMIN');
-      return Promise.all((await identity.membersOfTenant(tenantId)).map(toMemberView));
-    },
-
-    async inviteMember(scope, tenantId, input) {
-      const actor = await requireRole(scope, tenantId, 'ADMIN');
-      const email = input.email?.trim();
-      if (!email)
-        throw new AppError('An email is required to invite someone.', {
-          code: 'EMAIL_REQUIRED',
-          status: 400,
-          category: 'validation',
-        });
-      assertCanAssignRole(actor, input.role);
-
-      const existing = await identity.getUserByEmail(email);
-      if (existing && (await identity.getMembership(tenantId, existing.userId)))
-        throw new AppError('That account is already a member of this tenant.', {
-          code: 'ALREADY_A_MEMBER',
-          status: 409,
-          category: 'validation',
-        });
-
-      // The token is a 256-bit bearer secret handed back ONCE; the store keeps
-      // only its SHA-256, so a leaked registry file yields no usable invite.
-      const token = randomBytes(32).toString('base64url');
-      const expiresAt = new Date(now() + (input.ttlMinutes ?? invitationTtlMinutes) * 60_000).toISOString();
-      await identity.createInvitation({ tokenHash: hashInviteToken(token), tenantId, email, role: input.role, expiresAt });
-      return { tenantId, email, role: input.role, expiresAt, token };
-    },
-
-    async acceptInvitation(scope, token) {
-      const claims = scope.claims;
-      const user = await identity.getUser(claims.userId);
-      if (!user?.email)
-        denied('This account has no email address, so it cannot accept an invitation.', 'ACCOUNT_EMAIL_MISSING', 400);
-      const invited = await consumableInvitation(token, (user as { email: string }).email);
-
-      if (await identity.getMembership(invited.tenantId, claims.userId))
-        throw new AppError('That account is already a member of this tenant.', {
-          code: 'ALREADY_A_MEMBER',
-          status: 409,
-          category: 'validation',
-        });
-      // Consume FIRST: the update is conditional on `accepted_at IS NULL`, so
-      // two concurrent accepts cannot both create a membership.
-      if (!(await identity.acceptInvitation(invited.tokenHash)))
-        throw new AppError('That invitation has already been used.', {
-          code: 'INVITATION_USED',
-          status: 409,
-          category: 'security',
-        });
-      return toMemberView(
-        await identity.createMembership({ tenantId: invited.tenantId, userId: claims.userId, role: invited.role }),
-      );
-    },
-
-    async updateMember(scope, tenantId, userId, patch: MemberPatch) {
-      const actor = await requireRole(scope, tenantId, 'ADMIN');
-      const target = await identity.getMembership(tenantId, userId);
-      if (!target)
-        throw new AppError('No such member.', { code: 'MEMBER_NOT_FOUND', status: 404, category: 'validation' });
-      assertCanActOn(actor, target);
-
-      if (patch.role !== undefined && patch.role !== target.role) {
-        assertCanAssignRole(actor, patch.role);
-        // Demoting the last OWNER leaves a tenant nobody can administer.
-        if (patch.role !== 'OWNER') await assertNotLastOwner(target);
-        await identity.changeRole(tenantId, userId, patch.role);
-      }
-      if (patch.grants !== undefined) {
-        assertCanAssignGrants(actor, patch.grants);
-        await identity.setMembershipPermissions(tenantId, userId, patch.grants);
-      }
-      if (patch.status !== undefined && patch.status !== target.status) {
-        // A closed vocabulary: `status` reaches a signed row, and an arbitrary
-        // string there is a value every later `status === 'active'` check would
-        // silently treat as "not active" — or worse, a typo that reads as one.
-        if (patch.status !== 'active' && patch.status !== 'suspended')
-          throw new AppError('A membership status is `active` or `suspended`.', {
-            code: 'MEMBER_STATUS_INVALID',
-            status: 400,
-            category: 'validation',
-            context: { status: patch.status },
-          });
-        if (patch.status !== 'active') await assertNotLastOwner(target);
-        await identity.setMembershipStatus(tenantId, userId, patch.status);
-      }
-
-      // The whole point of §3: the change is live NOW. The target's next request
-      // fails verification and their next login mints the new grant.
-      revokeSessionsOf(userId);
-      return toMemberView((await identity.getMembership(tenantId, userId)) as Membership);
-    },
-
-    async removeMember(scope, tenantId, userId) {
-      const actor = await requireRole(scope, tenantId, 'ADMIN');
-      const target = await identity.getMembership(tenantId, userId);
-      if (!target) return false;
-      assertCanActOn(actor, target);
-      await assertNotLastOwner(target);
-      const removed = await identity.removeMembership(tenantId, userId);
-      if (removed) revokeSessionsOf(userId);
-      return removed;
-    },
-  };
-}