@antasphere/chassis-server 1.0.0

package/src/accounts/index.ts

@@ -0,0 +1,5 @@
+export { AccountDeletionService, LastOwnerError, isLastOwnerDbError } from './deletion.js';
+export { ErasureLog, emailHash } from './erasure-log.js';
+export { mintRefusal } from './mint-refusal.js';
+export { isDuplicateAccountError } from './signup-duplicate.js';
+export { parseSuperadminEmails } from './superadmin.js';

package/src/accounts/mint-refusal.ts

@@ -0,0 +1,67 @@
+import { and, eq, ne } from 'drizzle-orm';
+import { workspaceMembers, type Db } from '@antasphere/chassis-db';
+
+/**
+ * Shared refusal for the SIGN-IN-EQUIVALENT mint routes (PRDCT-1354,
+ * findings AUTH-1/AUTH-2/AUTH-8). `/members/{id}/reset-link`,
+ * `/members/{id}/change-email-link` and the demo pass mint
+ * (`POST /demo/passes`) all hand the caller a bearer credential
+ * for ANOTHER user's GLOBAL account: consuming any one of them signs the
+ * target in (LESSONS.md M6: "Consuming a change-email JWT while logged
+ * out CREATES a session for the target user"). A `user` row is
+ * instance-global, so the blast radius of a mint is every workspace that
+ * user belongs to — not just the minter's.
+ *
+ * Two target classes therefore make a mint a CROSS-TENANT takeover and
+ * are refused outright:
+ *
+ *  1. `origin='guest'` — the guest row exists for principal resolution
+ *     only (D2). It was created by the per-resource claim path for an
+ *     EXTERNAL party whose account is not this tenant's to administer;
+ *     the host tenant never owned that credential. Admins have no
+ *     recovery duty toward a guest, so there is nothing to trade away.
+ *  2. a target holding a membership in ANY OTHER workspace — the minted
+ *     credential would carry into that workspace too. "Admin of the
+ *     workspace" is not "owner of the person"; a user who works with two
+ *     tenants must never be recoverable by either one unilaterally.
+ *     Recovery for such a user is self-serve (`/request-password-reset`)
+ *     or the operator's break-glass surface.
+ *
+ * The role gate is OWNER, not admin (AUTH-8): the old guards only fired
+ * when `target.role === 'owner'`, so any admin could mint against any
+ * other admin and escalate laterally. Minting someone else's credential
+ * is an owner-level act on every route that calls this.
+ *
+ * Fail-CLOSED shape: a new route that mints a credential for another user
+ * must call this helper. Returning `null` means "no refusal found".
+ * `guestTargetMessage` is the tool's `guest_target` sentence
+ * (`copy.guestTarget`).
+ */
+export async function mintRefusal(
+  db: Db,
+  guestTargetMessage: string,
+  principal: { workspaceId: string },
+  target: { userId: string; origin: string }
+): Promise<{ code: string; message: string } | null> {
+  if (target.origin === 'guest') {
+    return {
+      code: 'guest_target',
+      message: guestTargetMessage
+    };
+  }
+  const [foreign] = await db
+    .select({ id: workspaceMembers.id })
+    .from(workspaceMembers)
+    .where(
+      and(eq(workspaceMembers.userId, target.userId), ne(workspaceMembers.workspaceId, principal.workspaceId))
+    )
+    .limit(1);
+  if (foreign) {
+    return {
+      code: 'cross_workspace_target',
+      message:
+        'This member also belongs to another workspace — an admin-minted link would carry into it, so it is refused'
+    };
+  }
+  return null;
+}

package/src/accounts/signup-duplicate.ts

@@ -0,0 +1,21 @@
+/**
+ * True when a failed `signUpEmail` means "this email already has an account":
+ * either Better Auth's own pre-check (APIError USER_ALREADY_EXISTS / 422) or,
+ * in the tight concurrent-signup race where two callers pass an account lookup
+ * together, the losing INSERT's Postgres unique_violation (23505) on the user
+ * email — found anywhere down the wrapped error's `cause` chain.
+ *
+ * Shared by every public account-minting endpoint (invitation accept,
+ * collaborator claim): the existence-revealing 409 is answered ONLY here, after
+ * the caller has committed real credentials, so a credential-less probe can
+ * never read it (PRDCT-1437).
+ */
+export function isDuplicateAccountError(e: unknown): boolean {
+  for (let cur: unknown = e, depth = 0; cur instanceof Error && depth < 10; cur = cur.cause, depth++) {
+    const anyErr = cur as { code?: unknown; status?: unknown; body?: { code?: unknown } };
+    if (anyErr.code === '23505') return true;
+    if (anyErr.body?.code === 'USER_ALREADY_EXISTS') return true;
+    if (anyErr.status === 'UNPROCESSABLE_ENTITY' || anyErr.status === 422) return true;
+  }
+  return false;
+}

package/src/accounts/superadmin.ts

@@ -0,0 +1,46 @@
+/**
+ * Break-glass superadmin recognition (ADR 010).
+ *
+ * The capability is env-derived and off by default: `SUPERADMIN_EMAILS` is a
+ * comma-separated allowlist, and a caller is superadmin ONLY when all three
+ * hold at once:
+ *
+ *   1. the request carries a Better Auth SESSION (never a machine credential —
+ *      the break-glass routes are unlisted in the fail-closed scope allowlist,
+ *      and the handlers resolve the session directly);
+ *   2. the session user's email is on the allowlist;
+ *   3. that email is VERIFIED (`user.email_verified`) — an unverified match
+ *      must never qualify, or squatting an allowlisted address would be enough.
+ *
+ * There is deliberately NO persistent DB super-role: unset/empty env means no
+ * superadmin exists and the capability is fully dormant.
+ */
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Parse `SUPERADMIN_EMAILS` into a lowercased set (Better Auth stores emails
+ * lowercased, so membership checks compare in that form).
+ *
+ * Throws on malformed entries so the env schema fails LOUDLY at boot — a typo
+ * must never silently disarm break-glass. `undefined` (unset/blank through
+ * `blankToUndefined`) yields the empty set: dormant.
+ */
+export function parseSuperadminEmails(raw: string | undefined): Set<string> {
+  const allowlist = new Set<string>();
+  if (raw === undefined || raw.trim() === '') return allowlist;
+  const entries = raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (entries.length === 0) {
+    throw new Error('SUPERADMIN_EMAILS must list at least one email address');
+  }
+  for (const entry of entries) {
+    if (!EMAIL_RE.test(entry)) {
+      throw new Error(`SUPERADMIN_EMAILS entry "${entry}" is not a valid email address`);
+    }
+    allowlist.add(entry.toLowerCase());
+  }
+  return allowlist;
+}

package/src/api/apikeys.ts

@@ -0,0 +1,147 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import { and, desc, eq } from 'drizzle-orm';
+import type { ScopeRoutes } from './scope-routes.js';
+import { apiKeys, workspaceMembers, type ApiKey, type Db } from '@antasphere/chassis-db';
+import { sql } from 'drizzle-orm';
+import type { ApiKeyService } from '../apikeys/service.js';
+import { cursorRowId, keysetBefore, pageOf } from '../pagination.js';
+import { requireAuth } from '../middleware/auth-context.js';
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+
+const toWire = (k: ApiKey) => ({
+  id: k.id,
+  name: k.name,
+  keyId: k.keyId,
+  scopes: k.scopes as string[],
+  workspaceId: k.workspaceId,
+  createdBy: k.createdBy,
+  createdAt: k.createdAt.toISOString(),
+  lastUsedAt: k.lastUsedAt?.toISOString() ?? null,
+  revokedAt: k.revokedAt?.toISOString() ?? null,
+  expiresAt: k.expiresAt?.toISOString() ?? null
+});
+
+/**
+ * API keys are USER credentials (user-scoped credential model): the listing
+ * and the revoke are keyed on the CREATOR, not on any workspace — a key acts
+ * as its holder wherever their memberships reach, so "my keys" is the only
+ * honest scope. Mint stays sessions-only and accepts an optional workspace
+ * PIN (least privilege); revocation is creator-only (a workspace admin has
+ * no standing over another user's credential).
+ */
+export function registerApiKeyRoutes(
+  api: OpenAPIHono,
+  db: Db,
+  service: ApiKeyService,
+  routes: Pick<ScopeRoutes, 'apiKeysListRoute' | 'apiKeyCreateRoute' | 'apiKeyRevokeRoute'>
+): void {
+  const { apiKeysListRoute, apiKeyCreateRoute, apiKeyRevokeRoute } = routes;
+  api.use('/api-keys', requireAuth());
+  api.use('/api-keys/*', requireAuth());
+
+  api.openapi(apiKeysListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { cursor, limit } = c.req.valid('query');
+    const cursorId = cursorRowId(cursor);
+    const rows = await db
+      .select()
+      .from(apiKeys)
+      .where(
+        and(
+          eq(apiKeys.createdBy, principal.userId),
+          ...(cursorId
+            ? [
+                keysetBefore({
+                  table: apiKeys,
+                  id: apiKeys.id,
+                  createdAt: apiKeys.createdAt,
+                  // The keyset scope column (see pagination.ts): the listing
+                  // is creator-scoped, so a foreign user's cursor can never
+                  // position inside this user's ordering.
+                  workspaceId: apiKeys.createdBy,
+                  cursorId,
+                  workspace: principal.userId
+                })
+              ]
+            : [])
+        )
+      )
+      .orderBy(desc(apiKeys.createdAt), desc(apiKeys.id))
+      .limit(limit + 1);
+    const { page, nextCursor } = pageOf(rows, limit);
+    return c.json({ apiKeys: page.map(toWire), nextCursor }, 200);
+  });
+
+  api.openapi(apiKeyCreateRoute, async (c) => {
+    const principal = c.get('principal')!;
+    // Locked rule: a key never mints a key. Sessions only.
+    if (principal.via !== 'session') {
+      return c.json(err('sessions_only', 'API keys can only be created from a browser session'), 403);
+    }
+    const body = c.req.valid('json');
+    // Optional PIN: an ACTIVE membership of the pinned workspace is required
+    // — one uniform 403 whether the workspace does not exist or the caller
+    // is not a member (no oracle about other workspaces).
+    if (body.workspaceId) {
+      const [member] = await db
+        .select({ id: workspaceMembers.id })
+        .from(workspaceMembers)
+        .where(
+          and(
+            eq(workspaceMembers.userId, principal.userId),
+            eq(workspaceMembers.workspaceId, body.workspaceId),
+            eq(workspaceMembers.isActive, true)
+          )
+        )
+        .limit(1);
+      if (!member) {
+        return c.json(err('no_membership', 'This workspace is not available to this account'), 403);
+      }
+    }
+    // The client sends a TTL in days; the server owns the absolute expiry.
+    const expiresAt = body.expiresInDays ? new Date(Date.now() + body.expiresInDays * 86_400_000) : null;
+    const minted = await service.mint({
+      workspaceId: body.workspaceId ?? null,
+      createdBy: principal.userId,
+      name: body.name,
+      scopes: body.scopes,
+      expiresAt
+    });
+    const [row] = await db.select().from(apiKeys).where(eq(apiKeys.id, minted.id)).limit(1);
+    c.set('audit', {
+      action: 'apikey.create',
+      resourceType: 'api_key',
+      resourceId: minted.id,
+      metadata: {
+        name: body.name,
+        scopes: body.scopes,
+        workspaceId: body.workspaceId ?? null,
+        expiresAt: expiresAt?.toISOString() ?? null
+      }
+    });
+    return c.json({ apiKey: toWire(row!), key: minted.key }, 201);
+  });
+
+  api.openapi(apiKeyRevokeRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { id } = c.req.valid('param');
+    // Creator-only: a key is its creator's credential. A foreign key answers
+    // the same 404 as a nonexistent one (existence is not probeable).
+    const [key] = await db
+      .select()
+      .from(apiKeys)
+      .where(and(eq(apiKeys.id, id), eq(apiKeys.createdBy, principal.userId)))
+      .limit(1);
+    if (!key) return c.json(err('not_found', 'API key not found'), 404);
+    if (!key.revokedAt) {
+      await db
+        .update(apiKeys)
+        .set({ revokedAt: sql`now()` })
+        .where(eq(apiKeys.id, key.id));
+    }
+    const [updated] = await db.select().from(apiKeys).where(eq(apiKeys.id, key.id)).limit(1);
+    c.set('audit', { action: 'apikey.revoke', resourceType: 'api_key', resourceId: key.id });
+    return c.json(toWire(updated!), 200);
+  });
+}

package/src/api/audit.ts

@@ -0,0 +1,83 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import { count, eq, lt, desc } from 'drizzle-orm';
+import { auditListRoute } from '@antasphere/chassis-contract/routes';
+import { auditLog, user as userTable, type Db } from '@antasphere/chassis-db';
+import { requireRole } from '../middleware/auth-context.js';
+import { auditFilterConditions, auditWhere, cursorId } from '../audit/filters.js';
+
+export function registerAuditRoutes(api: OpenAPIHono, db: Db): void {
+  api.use('/audit', requireRole('admin'));
+  api.openapi(auditListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const query = c.req.valid('query');
+    const { limit } = query;
+
+    // SECURITY: the scope is the caller's workspace and nothing in the
+    // query can widen it; every filter narrows within it, as a bound
+    // parameter (audit/filters.ts). The cursor stays the last row id, so
+    // a page is "the next `limit` rows older than the cursor that match
+    // the same filters": a client that changes a filter starts over.
+    const scope = eq(auditLog.workspaceId, principal.workspaceId);
+    const filters = auditFilterConditions(query);
+    const cursor = cursorId(query.cursor);
+    const where = auditWhere(scope, filters, cursor !== null ? lt(auditLog.id, cursor) : null);
+
+    const rows = await db
+      .select({
+        id: auditLog.id,
+        actorUserId: auditLog.actorUserId,
+        actorEmail: userTable.email,
+        actorVia: auditLog.actorVia,
+        apiKeyId: auditLog.apiKeyId,
+        action: auditLog.action,
+        resourceType: auditLog.resourceType,
+        resourceId: auditLog.resourceId,
+        requestId: auditLog.requestId,
+        ip: auditLog.ip,
+        metadata: auditLog.metadata,
+        createdAt: auditLog.createdAt
+      })
+      .from(auditLog)
+      .leftJoin(userTable, eq(auditLog.actorUserId, userTable.id))
+      .where(where)
+      .orderBy(desc(auditLog.id))
+      .limit(limit + 1);
+
+    // The total is counted once per listing, on the first page: the count
+    // walks the same join and WHERE without the cursor, and a client keeps
+    // the figure while it loads the pages after.
+    let total: number | null = null;
+    if (cursor === null) {
+      const [counted] = await db
+        .select({ n: count() })
+        .from(auditLog)
+        .leftJoin(userTable, eq(auditLog.actorUserId, userTable.id))
+        .where(auditWhere(scope, filters, null));
+      total = counted?.n ?? 0;
+    }
+
+    const page = rows.slice(0, limit);
+    const nextCursor = rows.length > limit ? String(page[page.length - 1]?.id ?? '') : null;
+    return c.json(
+      {
+        entries: page.map((r) => ({
+          id: r.id,
+          actorUserId: r.actorUserId,
+          actorEmail: r.actorEmail,
+          actorVia: r.actorVia,
+          apiKeyId: r.apiKeyId,
+          action: r.action,
+          resourceType: r.resourceType,
+          resourceId: r.resourceId,
+          requestId: r.requestId,
+          ip: r.ip,
+          metadata: r.metadata,
+          createdAt: r.createdAt.toISOString()
+        })),
+        nextCursor,
+        total
+      },
+      200
+    );
+  });
+}

package/src/api/break-glass.ts

@@ -0,0 +1,294 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { Context } from 'hono';
+import { and, eq } from 'drizzle-orm';
+import {
+  breakGlassClaimOwnershipRoute,
+  breakGlassResetTwoFactorRoute
+} from '@antasphere/chassis-contract/routes';
+import { twoFactor, user as userTable, workspaceMembers, workspaces, type Db } from '@antasphere/chassis-db';
+import type { Auth } from '../identity/better-auth.js';
+import type { AuditService } from '../audit/service.js';
+import type { Logger } from '../logger.js';
+import { parseSuperadminEmails } from '../accounts/superadmin.js';
+
+/**
+ * Break-glass superadmin recovery (ADR 010) — the instance-level recovery
+ * surface for the per-tenant hosting model. Two capabilities only:
+ *
+ *  - claim-ownership: make the calling superadmin (or a named existing user)
+ *    an ACTIVE OWNER of a workspace — creating the membership when absent,
+ *    reactivating and promoting when present. It ADDS an owner and never
+ *    removes one, so the migration-0009 last-owner trigger is satisfied by
+ *    construction. The target workspace is explicit (`workspaceId`) once the
+ *    instance runs several (ADR 014); a single-workspace instance keeps the
+ *    old no-argument call.
+ *  - reset-2fa: clear a locked-out user's second factor (the recovery ADR 009
+ *    deferred to manual DB surgery). User-level — needs no workspace; its
+ *    audit row is instance-attributed.
+ *
+ * SAFETY MODEL (a bug here = full instance compromise — keep all of it):
+ *
+ *  - Off by default: superadmin exists ONLY while SUPERADMIN_EMAILS is set.
+ *  - Session-only, twice over: these paths are deliberately UNLISTED in the
+ *    fail-closed scope allowlist (middleware/scopes.ts), so machine
+ *    principals 403 before reaching the handlers; AND the handlers resolve
+ *    the Better Auth session directly — a request without a session cookie
+ *    can never qualify, whatever headers it carries.
+ *  - Verified email required: an allowlisted address that was never proven
+ *    (invitation copyable-link accounts are unverified) does NOT match.
+ *  - Identity is re-read from the DB by session user id — never derived from
+ *    any header, body field, or client-supplied value.
+ *  - No requireAuth()/requireRole() gate: the recovering operator may hold a
+ *    session with NO membership (principal resolves to null), which is
+ *    exactly the state break-glass exists to fix. The handlers do their own
+ *    authentication and are exempted from the generic audit middleware
+ *    because they write their own richer rows (see audit/service.ts).
+ */
+
+export interface BreakGlassRouteDeps {
+  db: Db;
+  auth: Auth;
+  audit: AuditService;
+  logger: Logger;
+  /** Raw SUPERADMIN_EMAILS value (already validated by the env schema). */
+  superadminEmails: string | undefined;
+}
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+
+type SuperadminResolution =
+  | { kind: 'ok'; caller: { userId: string; email: string; name: string } }
+  | { kind: 'unauthenticated' }
+  | { kind: 'forbidden' };
+
+export function registerBreakGlassRoutes(api: OpenAPIHono, deps: BreakGlassRouteDeps): void {
+  const { db, auth, audit, logger } = deps;
+  const allowlist = parseSuperadminEmails(deps.superadminEmails);
+
+  /**
+   * Resolve the caller as a superadmin. One uniform `forbidden` for every
+   * rejection reason (dormant, not listed, unverified) so the endpoint is
+   * not an oracle for the allowlist's contents.
+   */
+  const resolveSuperadmin = async (c: Context): Promise<SuperadminResolution> => {
+    // Session-only: the verified session identity, never a header or bearer.
+    // Machine credentials died at the fail-closed scope gate already; a
+    // cookieless request has no session and stops here.
+    const session = await auth.api.getSession({ headers: c.req.raw.headers });
+    if (!session?.user) return { kind: 'unauthenticated' };
+    if (allowlist.size === 0) return { kind: 'forbidden' };
+    // Fresh row by session user id — email + verification state are read
+    // from the database, not trusted from session claims.
+    const [u] = await db
+      .select({
+        id: userTable.id,
+        email: userTable.email,
+        emailVerified: userTable.emailVerified,
+        name: userTable.name
+      })
+      .from(userTable)
+      .where(eq(userTable.id, session.user.id))
+      .limit(1);
+    if (!u) return { kind: 'forbidden' };
+    if (!allowlist.has(u.email.toLowerCase())) return { kind: 'forbidden' };
+    if (!u.emailVerified) return { kind: 'forbidden' };
+    return { kind: 'ok', caller: { userId: u.id, email: u.email, name: u.name } };
+  };
+
+  /**
+   * The workspace an owner-claim targets (ADR 014). Explicit `workspaceId`
+   * wins; omitted, it resolves ONLY while the instance runs a single
+   * workspace — with several, recovery must name its target (400
+   * workspace_required), never guess one.
+   */
+  const resolveTargetWorkspace = async (
+    explicit: string | undefined
+  ): Promise<
+    { kind: 'ok'; id: string } | { kind: 'not_found' } | { kind: 'not_setup' } | { kind: 'ambiguous' }
+  > => {
+    if (explicit) {
+      const [ws] = await db
+        .select({ id: workspaces.id })
+        .from(workspaces)
+        .where(eq(workspaces.id, explicit))
+        .limit(1);
+      return ws ? { kind: 'ok', id: ws.id } : { kind: 'not_found' };
+    }
+    const rows = await db.select({ id: workspaces.id }).from(workspaces).limit(2);
+    const [only] = rows;
+    if (!only) return { kind: 'not_setup' };
+    if (rows.length > 1) return { kind: 'ambiguous' };
+    return { kind: 'ok', id: only.id };
+  };
+
+  api.openapi(breakGlassClaimOwnershipRoute, async (c) => {
+    const resolved = await resolveSuperadmin(c);
+    if (resolved.kind === 'unauthenticated') {
+      return c.json(err('unauthenticated', 'Authentication required'), 401);
+    }
+    if (resolved.kind === 'forbidden') {
+      return c.json(err('forbidden', 'Break-glass is not available to this caller'), 403);
+    }
+    const caller = resolved.caller;
+    const body = c.req.valid('json');
+
+    const targetWs = await resolveTargetWorkspace(body.workspaceId);
+    if (targetWs.kind === 'not_setup') {
+      return c.json(err('not_setup', 'This instance has not completed setup'), 409);
+    }
+    if (targetWs.kind === 'not_found') {
+      return c.json(err('not_found', 'Target workspace not found'), 404);
+    }
+    if (targetWs.kind === 'ambiguous') {
+      return c.json(
+        err('workspace_required', 'This instance has several workspaces — pass workspaceId explicitly'),
+        400
+      );
+    }
+    const ws = { id: targetWs.id };
+
+    // Target: a named existing user, or the calling superadmin.
+    let target = { userId: caller.userId, email: caller.email };
+    if (body.userId) {
+      const [t] = await db
+        .select({ id: userTable.id, email: userTable.email })
+        .from(userTable)
+        .where(eq(userTable.id, body.userId))
+        .limit(1);
+      if (!t) return c.json(err('not_found', 'Target user not found'), 404);
+      target = { userId: t.id, email: t.email };
+    }
+
+    const [before] = await db
+      .select({
+        id: workspaceMembers.id,
+        role: workspaceMembers.role,
+        isActive: workspaceMembers.isActive
+      })
+      .from(workspaceMembers)
+      .where(and(eq(workspaceMembers.workspaceId, ws.id), eq(workspaceMembers.userId, target.userId)))
+      .limit(1);
+
+    // Additive by construction: create-or-promote to an ACTIVE OWNER. The
+    // 0009 last-owner trigger only rejects operations that REMOVE the last
+    // active owner — adding one is always legal, including the first owner
+    // of an ownerless workspace.
+    const [after] = await db
+      .insert(workspaceMembers)
+      // origin='local' on BOTH paths (BG-1, PRDCT-1356): a break-glass owner
+      // is the tool's own business, never hub truth. Left at 'hub' (the
+      // conflict path once kept the row's old origin), the cloud reconciler's
+      // deactivation sweep — which targets origin='hub' rows the hub no
+      // longer asserts — undid the recovery ~12 s later.
+      .values({ workspaceId: ws.id, userId: target.userId, role: 'owner', isActive: true, origin: 'local' })
+      .onConflictDoUpdate({
+        target: [workspaceMembers.workspaceId, workspaceMembers.userId],
+        set: { role: 'owner', isActive: true, origin: 'local' }
+      })
+      .returning({ id: workspaceMembers.id });
+    if (!after) throw new Error('break-glass ownership upsert returned no row');
+
+    logger.warn(
+      {
+        superadminUserId: caller.userId,
+        superadminEmail: caller.email,
+        targetUserId: target.userId,
+        targetEmail: target.email,
+        workspaceId: ws.id
+      },
+      'BREAK-GLASS: workspace ownership claimed'
+    );
+    await audit.write({
+      workspaceId: ws.id,
+      principal: { userId: caller.userId, via: 'session' },
+      action: 'break_glass.claim_ownership',
+      resourceType: 'member',
+      resourceId: after.id,
+      requestId: c.get('requestId'),
+      metadata: {
+        superadminUserId: caller.userId,
+        superadminEmail: caller.email,
+        targetUserId: target.userId,
+        targetEmail: target.email,
+        before: before ? { role: before.role, isActive: before.isActive } : null,
+        after: { role: 'owner', isActive: true },
+        created: !before
+      }
+    });
+
+    return c.json(
+      {
+        memberId: after.id,
+        userId: target.userId,
+        email: target.email,
+        workspaceId: ws.id,
+        role: 'owner' as const,
+        isActive: true,
+        created: !before
+      },
+      200
+    );
+  });
+
+  api.openapi(breakGlassResetTwoFactorRoute, async (c) => {
+    const resolved = await resolveSuperadmin(c);
+    if (resolved.kind === 'unauthenticated') {
+      return c.json(err('unauthenticated', 'Authentication required'), 401);
+    }
+    if (resolved.kind === 'forbidden') {
+      return c.json(err('forbidden', 'Break-glass is not available to this caller'), 403);
+    }
+    const caller = resolved.caller;
+    const { userId } = c.req.valid('json');
+
+    const [target] = await db
+      .select({
+        id: userTable.id,
+        email: userTable.email,
+        twoFactorEnabled: userTable.twoFactorEnabled
+      })
+      .from(userTable)
+      .where(eq(userTable.id, userId))
+      .limit(1);
+    if (!target) return c.json(err('not_found', 'Target user not found'), 404);
+
+    // Clear the factor: the two_factor row (secret + backup codes) and the
+    // user flag. Idempotent — resetting an unenrolled user is a no-op 200.
+    const removed = await db
+      .delete(twoFactor)
+      .where(eq(twoFactor.userId, target.id))
+      .returning({ id: twoFactor.id });
+    await db.update(userTable).set({ twoFactorEnabled: false }).where(eq(userTable.id, target.id));
+    const hadTwoFactor = removed.length > 0 || target.twoFactorEnabled === true;
+
+    logger.warn(
+      {
+        superadminUserId: caller.userId,
+        superadminEmail: caller.email,
+        targetUserId: target.id,
+        targetEmail: target.email,
+        hadTwoFactor
+      },
+      'BREAK-GLASS: two-factor reset'
+    );
+    // INSTANCE-attributed (workspace_id NULL, ADR 014): a second factor is a
+    // user property, not any workspace's — the row needs no workspace home.
+    await audit.write({
+      workspaceId: null,
+      principal: { userId: caller.userId, via: 'session' },
+      action: 'break_glass.reset_two_factor',
+      resourceType: 'user',
+      resourceId: target.id,
+      requestId: c.get('requestId'),
+      metadata: {
+        superadminUserId: caller.userId,
+        superadminEmail: caller.email,
+        targetUserId: target.id,
+        targetEmail: target.email,
+        hadTwoFactor
+      }
+    });
+
+    return c.json({ userId: target.id, hadTwoFactor }, 200);
+  });
+}