@proteinjs/user-server 1.11.1 → 1.13.0

package/src/migrations/SweepMalformedAccessGrants.ts

@@ -0,0 +1,229 @@
+import {
+  getDbAsSystem,
+  getTables,
+  Migration,
+  QueryBuilder,
+  QueryBuilderFactory,
+  Record,
+  RecordIterator,
+  SourceRecordLoader,
+  Table,
+  tables as dbTables,
+} from '@proteinjs/db';
+import { AccessGrant, tables as userTables } from '@proteinjs/user';
+import { Logger } from '@proteinjs/logger';
+
+/** One access_grant row as the sweep logs and reports it. */
+export interface AccessGrantSweepRow {
+  id: string;
+  resourceTable?: string;
+  accessLevel: AccessGrant['accessLevel'];
+  created?: string;
+}
+
+/** A well-formed grant whose principal or resource id no longer resolves to a row (report only). */
+export interface DanglingAccessGrantRow extends AccessGrantSweepRow {
+  principal?: string;
+  resource?: string;
+  reason: 'principal missing' | 'resource missing' | 'resource table not registered';
+}
+
+export interface SweepMalformedAccessGrantsResult {
+  /** Rows on the invariant's exact complement (NULL principal or NULL resource) — deleted unless `dryRun`. */
+  malformed: number;
+  rows: AccessGrantSweepRow[];
+  dryRun: boolean;
+}
+
+export interface DanglingAccessGrantsReport {
+  danglingPrincipal: number;
+  danglingResource: number;
+  rows: DanglingAccessGrantRow[];
+}
+
+/**
+ * ONE-TIME SWEEP of malformed access_grant residue — rows whose `principal` or `resource`
+ * reference is NULL. The AccessGrant well-formedness invariant (`AccessGrantTable.assertWellFormed`)
+ * now refuses that shape at insert, and the session-less scope-root bootstrap no longer mints it;
+ * this migration clears what the two producers left behind before the fix (the test environment
+ * held one; app Deploy to Test 32614670162 crashed on it).
+ *
+ * The sweep's predicate is the invariant's exact complement (`principal IS NULL OR resource IS
+ * NULL`), and it rides BOTH the find and the delete — a well-formed row cannot be selected by the
+ * statement that deletes, whatever the id list. Deletes go through the system Db by id, so the
+ * registered after-delete watchers fire (a grantee's content_reference cleanup rides
+ * `ContentReferenceAccessGrantTableWatcher`). Idempotent: a re-run finds nothing.
+ *
+ * DANGLING references are a separate class and are NOT deleted here: a well-formed grant whose
+ * principal user or resource row was purged out from under it. Those are REPORTED (log +
+ * migration output) so the purge paths that strand them can be named; a delete would be a
+ * symptom patch on a producer this migration does not own.
+ *
+ * App-service/system-db path only — never raw Spanner.
+ */
+export class SweepMalformedAccessGrants implements SourceRecordLoader<Migration> {
+  table = dbTables.Migration;
+  record = {
+    id: '2b7e4d0c-5f1a-4c3e-9b8d-6a2f1e0c7d45',
+    description:
+      'Sweep malformed access_grant rows (NULL principal or NULL resource — the well-formedness invariant’s complement); report dangling references, no delete.',
+    run: async () => {
+      const logger = new Logger({ name: SweepMalformedAccessGrants.name });
+      // Dry-run pass first: every row the delete pass will touch is in the log before it goes.
+      const dry = await this.sweep({ dryRun: true });
+      const real = await this.sweep({ dryRun: false });
+      const dangling = await this.reportDangling();
+      const output = {
+        malformed: real.malformed,
+        malformedDryRun: dry.malformed,
+        danglingPrincipal: dangling.danglingPrincipal,
+        danglingResource: dangling.danglingResource,
+        malformedRows: real.rows,
+        danglingRows: dangling.rows,
+      };
+      logger.info({ message: 'SweepMalformedAccessGrants completed', obj: output });
+      return output;
+    },
+  };
+
+  /** Find (and unless `dryRun`, delete) every malformed grant. Each row is logged either way. */
+  async sweep(options: { dryRun: boolean }): Promise<SweepMalformedAccessGrantsResult> {
+    const { dryRun } = options;
+    const logger = new Logger({ name: SweepMalformedAccessGrants.name });
+    const db = getDbAsSystem<AccessGrant>();
+
+    const findQb = this.malformedPredicate(new QueryBuilderFactory().getQueryBuilder(userTables.AccessGrant)).sort([
+      { field: 'created' },
+    ]);
+    const malformed = await db.query(userTables.AccessGrant, findQb);
+    const rows = malformed.map((grant) => this.toRow(grant));
+    for (const row of rows) {
+      logger.info({
+        message: dryRun ? 'Malformed access_grant (dry run)' : 'Deleting malformed access_grant',
+        obj: row,
+      });
+    }
+
+    if (!dryRun) {
+      for (const grant of malformed) {
+        // By id, with the predicate bound: the statement that deletes cannot select a well-formed row.
+        const deleteQb = this.malformedPredicate(
+          new QueryBuilderFactory().getQueryBuilder(userTables.AccessGrant, { id: grant.id })
+        );
+        await db.delete(userTables.AccessGrant, deleteQb);
+      }
+    }
+
+    const result = { malformed: rows.length, rows, dryRun };
+    logger.info({ message: dryRun ? 'Sweep dry run' : 'Sweep pass', obj: { malformed: rows.length, dryRun } });
+    return result;
+  }
+
+  /**
+   * Report-only scan for well-formed grants whose principal or resource row no longer exists —
+   * the purged-user / purged-resource class. Nothing is deleted.
+   */
+  async reportDangling(): Promise<DanglingAccessGrantsReport> {
+    const logger = new Logger({ name: SweepMalformedAccessGrants.name });
+    const db = getDbAsSystem<AccessGrant>();
+
+    // One pass over the table, collecting the ids to resolve per referenced table.
+    const grants: AccessGrant[] = [];
+    const principalIds = new Set<string>();
+    const resourceIdsByTable = new Map<string, Set<string>>();
+    for await (const grant of new RecordIterator<AccessGrant>(userTables.AccessGrant, {}, 200, db)) {
+      const principalId = grant.principal?._id;
+      const resourceId = grant.resource?._id;
+      if (!principalId || !resourceId) {
+        continue; // the malformed class — `sweep` owns it
+      }
+      grants.push(grant);
+      principalIds.add(principalId);
+      const resourceTable = grant.resourceTable ?? grant.resource._table;
+      if (!resourceIdsByTable.has(resourceTable)) {
+        resourceIdsByTable.set(resourceTable, new Set());
+      }
+      resourceIdsByTable.get(resourceTable)!.add(resourceId);
+    }
+
+    const existingPrincipals = await this.existingIds(userTables.User, principalIds);
+    const existingResourcesByTable = new Map<string, Set<string> | null>();
+    for (const tableName of Array.from(resourceIdsByTable.keys())) {
+      const table = getTables().find((candidate) => candidate.name === tableName);
+      existingResourcesByTable.set(
+        tableName,
+        table ? await this.existingIds(table, resourceIdsByTable.get(tableName)!) : null
+      );
+    }
+
+    const report: DanglingAccessGrantsReport = { danglingPrincipal: 0, danglingResource: 0, rows: [] };
+    for (const grant of grants) {
+      const resourceTable = grant.resourceTable ?? grant.resource._table;
+      const existingResources = existingResourcesByTable.get(resourceTable);
+      let reason: DanglingAccessGrantRow['reason'] | undefined;
+      if (!existingPrincipals.has(grant.principal._id!)) {
+        reason = 'principal missing';
+        report.danglingPrincipal++;
+      } else if (existingResources === null) {
+        reason = 'resource table not registered';
+        report.danglingResource++;
+      } else if (!existingResources!.has(grant.resource._id!)) {
+        reason = 'resource missing';
+        report.danglingResource++;
+      }
+      if (!reason) {
+        continue;
+      }
+      const row: DanglingAccessGrantRow = {
+        ...this.toRow(grant),
+        principal: grant.principal._id,
+        resource: grant.resource._id,
+        reason,
+      };
+      report.rows.push(row);
+      logger.warn({ message: 'Dangling access_grant (report only, not deleted)', obj: row });
+    }
+
+    logger.info({
+      message: 'Dangling access_grant report',
+      obj: { danglingPrincipal: report.danglingPrincipal, danglingResource: report.danglingResource },
+    });
+    return report;
+  }
+
+  /** The well-formedness invariant's exact complement: a NULL principal or a NULL resource. */
+  private malformedPredicate(qb: QueryBuilder<AccessGrant>): QueryBuilder<AccessGrant> {
+    return qb.or([
+      { field: 'principal', operator: 'IS NULL' },
+      { field: 'resource', operator: 'IS NULL' },
+    ]);
+  }
+
+  /** Which of `ids` exist in `table`, resolved as system in bounded IN chunks. */
+  private async existingIds(table: Table<any>, ids: Set<string>): Promise<Set<string>> {
+    const existing = new Set<string>();
+    const all = Array.from(ids);
+    const chunkSize = 200;
+    for (let start = 0; start < all.length; start += chunkSize) {
+      const chunk = all.slice(start, start + chunkSize);
+      const qb = new QueryBuilderFactory()
+        .getQueryBuilder(table)
+        .select({ fields: ['id'] })
+        .condition({ field: 'id', operator: 'IN', value: chunk });
+      const found = (await getDbAsSystem().query(table, qb)) as Record[];
+      for (const record of found) {
+        existing.add(record.id);
+      }
+    }
+    return existing;
+  }
+
+  private toRow(grant: AccessGrant): AccessGrantSweepRow {
+    return {
+      id: grant.id,
+      resourceTable: grant.resourceTable,
+      accessLevel: grant.accessLevel,
+      created: grant.created?.toISOString(),
+    };
+  }
+}

package/src/routes/devLogin.ts

@@ -1,5 +1,6 @@
 import { Route } from '@proteinjs/server-api';
 import { Logger } from '@proteinjs/logger';
+import { emailRegex } from '@proteinjs/util';
 import { establishSession } from '../authentication/establishSession';
 import { Signup } from '../services/Signup';
 
@@ -23,6 +24,11 @@ const emailDomain = (address: string) => address.slice(address.lastIndexOf('@')
  * Domain rail: `?email` must share `DEV_AUTO_LOGIN_EMAIL`'s domain — even a dev server must not
  * mint sessions (much less accounts) for arbitrary domains; anything else answers 400.
  *
+ * Shape rail: `?email` must be a well-formed address (the house `emailRegex`). The domain rail
+ * alone let `?email=brent+lane-a@…` through when the `+` was left unencoded — a query-string `+`
+ * decodes to a SPACE, so the route minted a stray `brent lane-a@…` account. The 400 names the
+ * remedy (`%2B`) because plus-addressing is the fan-out convention this door exists for.
+ *
  * A missing account is created through the normal signup creation path (`Signup.createAccount`)
  * as a normal test user — password `test`, matching the seeded test-account convention, so
  * interactive login works for the same identity. Composes with userCache's missing-account→guest
@@ -47,6 +53,15 @@ export const devLogin: Route = {
         response.status(400).send(`/dev/login only accepts accounts on the @${emailDomain(envEmail)} domain`);
         return;
       }
+      if (!emailRegex.test(requested)) {
+        response
+          .status(400)
+          .send(
+            `/dev/login: "${requested}" is not a valid email address — an unencoded "+" in the query ` +
+              `decodes to a space; write it as %2B (e.g. ?email=name%2Blane@${emailDomain(envEmail)})`
+          );
+        return;
+      }
       email = requested;
     }
     email = email.toLowerCase();

package/src/services/Roles.ts

@@ -1,5 +1,5 @@
 import { getDbAsSystem } from '@proteinjs/db';
-import { RolesService, RolesCatalog, UserRepo, tables, USER_PERMISSIONS } from '@proteinjs/user';
+import { RolesService, RolesCatalog, UserAuth, UserRepo, tables, USER_PERMISSIONS } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import { Service } from '@proteinjs/service';
 
@@ -8,6 +8,8 @@ import { Service } from '@proteinjs/service';
  * record writes cannot touch it). Grants and revokes are validated against the roles catalog and
  * audited: the role update and its `role_grant_event` row (actor, target, role, action; `created`
  * is the timestamp) commit in one transaction, so the trail cannot diverge from the grants.
+ *
+ * Break-glass roles are never granted here — see `changeRole`; revoking one stays allowed.
  */
 export class Roles implements RolesService {
   public serviceMetadata: Service['serviceMetadata'] = {
@@ -26,10 +28,34 @@ export class Roles implements RolesService {
 
   private async changeRole(userId: string, role: string, action: 'grant' | 'revoke'): Promise<void> {
     const logger = new Logger({ name: `Roles.${action}Role` });
-    if (!RolesCatalog.isKnownRole(role)) {
+    const entry = RolesCatalog.getEntry(role);
+    if (!entry) {
       throw new Error(`'${role}' is not a known role. Pick one from the roles catalog.`);
     }
 
+    // Break-glass passes every permission check, so no permission-mapped role — including
+    // 'roles' — may mint it: the only path to break-glass is a manual UPDATE on the user row
+    // in Spanner Studio, by a human, on purpose. Revoke stays open: de-escalation toward
+    // "held by nobody day-to-day" should ride the audited path, not require database access.
+    if (entry.breakGlass && action === 'grant') {
+      throw new Error(
+        `'${role}' is a break-glass role — this service refuses to grant it. The only path to ` +
+          `break-glass is a manual UPDATE on the user row in Spanner Studio. (Revoking it here ` +
+          `stays allowed.)`
+      );
+    }
+
+    // Admin-grant-only roles (catalog `adminGrantOnly`) exceed the people-management trust the
+    // 'roles' permission carries — only an admin may hand them out. Server-side and fail-closed:
+    // the service door admits 'roles' holders, so this check is what keeps a user-admin from
+    // granting such a role. Revoke stays open — the break-glass de-escalation precedent above.
+    if (entry.adminGrantOnly && action === 'grant' && !UserAuth.hasRole('admin')) {
+      throw new Error(
+        `'${role}' can only be granted by an admin — the 'roles' grant does not cover it. ` +
+          `(Revoking it here stays allowed.)`
+      );
+    }
+
     const db = getDbAsSystem();
     const user = await db.get(tables.User, { id: userId });
     if (!user) {

package/test/DevLogin.test.ts

@@ -135,6 +135,32 @@ describe('devLogin route', () => {
     expect(await getUserRow('intruder@evil.example')).toBeUndefined();
   });
 
+  it('rejects a malformed same-domain ?email with 400 — no session, no stray account', async () => {
+    // The observed shape: an unencoded `+` in the query decodes to a space, so
+    // `?email=brent+shareproof-a@...` arrived as `brent shareproof-a@...` and minted a stray
+    // account. The domain rail alone let it through (the domain half was fine).
+    const malformed = 'brent shareproof-a@test.local';
+
+    const outcome = await invokeDevLogin({ email: malformed });
+
+    expect(outcome.status).toBe(400);
+    expect(String(outcome.body)).toMatch(/not a valid email/i);
+    expect(String(outcome.body)).toMatch(/%2B/); // the remedy: percent-encode the `+`
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(outcome.sessionSaved).toBe(false);
+    expect(outcome.redirect).toBeUndefined();
+    expect(await getUserRow(malformed)).toBeUndefined();
+  });
+
+  it('still accepts a plus-addressed ?email once it is encoded (the fan-out convention)', async () => {
+    const outcome = await invokeDevLogin({ email: 'agent6+lane-a@test.local' });
+
+    expect(outcome.loggedInAs).toBe('agent6+lane-a@test.local');
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+    expect(await getUserRow('agent6+lane-a@test.local')).toBeDefined();
+  });
+
   it('404s when DEVELOPMENT is unset, even with a ?email', async () => {
     delete process.env.DEVELOPMENT;
 

package/test/MachineAccounts.integration.test.ts

@@ -159,44 +159,87 @@ describe('Machine accounts as source records', () => {
     expect((await getDbAsSystem().query(tables.User, { email: 'machine-ops@test.local' })).length).toBe(1);
   });
 
-  // KNOWN CROSS-TRAIN GAP (it.failing — flips RED the moment it starts passing, forcing the
-  // marker's removal): the re-declare-after-removal leg needs db's soft-removal re-adoption
-  // (integration/r5-db ba9f4ba7 — the sync currently INSERTs the existing machine-test-ops row
-  // instead of adopting it). Green everywhere else against db ^1.35.0; this leg lands with the
-  // R5 db mint. Exact repro + the semantics call recorded on this suite's landing commit.
+  it('removed from source: deactivated (never deleted), sessions killed, login refused; re-declaring reactivates', async () => {
+    const human = await testEnv.createUser({ name: 'A human', email: 'human@test.local' });
+    await boot([new TestOpsMachineAccount()]);
+    await insertSession('machine-session', 'machine-ops@test.local');
+    await insertSession('human-session', human.email);
+
+    // Removal under the db >=1.34.4 ownership law: the reconcile only touches rows whose
+    // sourcePackage the RUNNING build still declares from (shared-db safety — a build missing a
+    // package must never deactivate that package's rows). The real removal case is the package
+    // still booting with THIS declaration gone — modeled by keeping another declaration from
+    // the same package aboard. boot([]) would model "package vanished", which the law protects.
+    // The sibling is a DISTINCT account (its own declared id): re-using the stable id under a
+    // new email is the rename-adopt case, pinned by the next test.
+    class SurvivingSibling extends TestOpsMachineAccount {
+      id = 'machine-sibling';
+      email = 'machine-sibling@test.local';
+      accountName = 'Surviving sibling machine';
+      secretName = 'sibling-secret';
+    }
+    await boot([new SurvivingSibling()]);
+
+    const removed = await machineRow();
+    expect(removed).toBeDefined();
+    expect(removed.status).toBe('deactivated');
+    // The categorical watcher killed the machine sessions; the human session is untouched.
+    expect(await sessionEmails()).toEqual([human.email]);
+    // The one login door refuses a deactivated account even with matching credentials.
+    await getDbAsSystem().update(tables.User, { id: removed.id, password: sha256('bridge-pw').toString() });
+    expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe('This account has been deactivated');
+
+    // Decommission is reversible in code: re-declaring reverts status via drift reversion.
+    await boot([new TestOpsMachineAccount()]);
+    expect((await machineRow()).status).toBe('active');
+    expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe(true);
+  });
+
+  // KNOWN CROSS-TRAIN GAP, RESTORED at the v1.20 early landing (it.failing — flips RED the
+  // moment it starts passing, forcing the marker's removal): this leg needs db's soft-removal
+  // re-adoption (integration/r5-db ba9f4ba7 — the sync currently INSERTs the existing
+  // machine-test-ops row instead of adopting it), which is NOT in the published db line
+  // (verified absent from db main at 1.38.0). The r5-user composition retired main's original
+  // marker BY DESIGN for the composed R5 world (dab44a0); landing the user leg ahead of the
+  // R5 db mint re-opens the gap, so the marker returns until that mint lands and self-flips it.
   it.failing(
-    'removed from source: deactivated (never deleted), sessions killed, login refused; re-declaring reactivates',
+    're-declared under a renamed email: the soft-removed row is adopted by its stable id — reactivated, re-derived from the declaration, credential preserved',
     async () => {
-      const human = await testEnv.createUser({ name: 'A human', email: 'human@test.local' });
+      // The user table SOFT-removes (deactivate, never delete — rows carry grants/history), so a
+      // re-declaration whose email no longer matches the kept row (an account rename, or any
+      // re-declare-after-removal under a changed natural key) must adopt the row by its stable
+      // declared id instead of INSERTing into a PK collision.
       await boot([new TestOpsMachineAccount()]);
+      // Runtime-owned credential on the row, plus role drift the re-derivation must NOT resurrect.
+      await getDbAsSystem().update(tables.User, {
+        id: 'machine-test-ops',
+        password: sha256('cred').toString(),
+        roles: ['ops', 'stale-role'],
+      });
       await insertSession('machine-session', 'machine-ops@test.local');
-      await insertSession('human-session', human.email);
-
-      // Removal under the db >=1.34.4 ownership law: the reconcile only touches rows whose
-      // sourcePackage the RUNNING build still declares from (shared-db safety — a build missing a
-      // package must never deactivate that package's rows). The real removal case is the package
-      // still booting with THIS declaration gone — modeled by keeping another declaration from
-      // the same package aboard. boot([]) would model "package vanished", which the law protects.
-      class SurvivingSibling extends TestOpsMachineAccount {
-        email = 'machine-sibling@test.local';
-        name = 'Surviving sibling machine';
-        secretName = 'sibling-secret';
+
+      class RenamedOps extends TestOpsMachineAccount {
+        email = 'machine-ops-renamed@test.local';
       }
-      await boot([new SurvivingSibling()]);
-
-      const removed = await machineRow();
-      expect(removed).toBeDefined();
-      expect(removed.status).toBe('deactivated');
-      // The categorical watcher killed the machine sessions; the human session is untouched.
-      expect(await sessionEmails()).toEqual([human.email]);
-      // The one login door refuses a deactivated account even with matching credentials.
-      await getDbAsSystem().update(tables.User, { id: removed.id, password: sha256('bridge-pw').toString() });
-      expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe('This account has been deactivated');
-
-      // Decommission is reversible in code: re-declaring reverts status via drift reversion.
-      await boot([new TestOpsMachineAccount()]);
-      expect((await machineRow()).status).toBe('active');
-      expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe(true);
+      await boot([new RenamedOps()]);
+
+      // One row, adopted in place: id kept (references + credential survive), email re-derived,
+      // reactivated, grants exactly the declaration's (no resurrection of stale grants).
+      expect(await getDbAsSystem().query(tables.User, {})).toHaveLength(1);
+      expect(await getDbAsSystem().get(tables.User, { email: 'machine-ops@test.local' })).toBeUndefined();
+      const adopted = await getDbAsSystem().get(tables.User, { email: 'machine-ops-renamed@test.local' });
+      expect(adopted).toMatchObject({
+        id: 'machine-test-ops',
+        name: 'Test ops machine',
+        roles: ['ops'],
+        status: 'active',
+        isLoadedFromSource: true,
+      });
+      expect(adopted.password).toBe(sha256('cred').toString());
+      // The rename transited the removal patch: the categorical watcher killed the old sessions...
+      expect(await sessionEmails()).toEqual([]);
+      // ...and the surviving credential logs in under the new email.
+      expect(await authenticate('machine-ops-renamed@test.local', 'cred')).toBe(true);
     }
   );
 

package/test/Roles.integration.test.ts

@@ -62,7 +62,14 @@ describe('Roles service — grant/revoke outcomes and audit trail', () => {
     ];
     (SourceRepository.get() as any).objectCache['@proteinjs/user/RoleCatalogEntry'] = [
       { role: 'ops', description: 'Run the ops cockpit' } as RoleCatalogEntry,
+      { role: 'dev', description: 'Drive the dev tooling' } as RoleCatalogEntry,
+      // Admin-grant-only entry (the consumer compliance-grant shape): granting requires the
+      // caller to BE an admin; the ordinary 'roles' grant does not cover it.
+      { role: 'data-access', description: 'Compliance decrypt grant', adminGrantOnly: true } as RoleCatalogEntry,
     ];
+    // The admin-grant-only check resolves the CALLER through UserAuth — same session-backed
+    // repo the services use.
+    (SourceRepository.get() as any).objectCache['@proteinjs/user-auth/AuthenticatedUserRepo'] = [new UserRepo()];
     jest.spyOn(Db, 'getDefaultDbDriver').mockImplementation(() => spannerDriver);
 
     await SpannerEmulatorProvisioner.ensureProvisioned({
@@ -131,16 +138,40 @@ describe('Roles service — grant/revoke outcomes and audit trail', () => {
   it('revoke removes the role and audits the revoke', async () => {
     const roles = new Roles();
     await roles.grantRole(targetId, 'ops');
-    await roles.grantRole(targetId, 'admin');
+    await roles.grantRole(targetId, 'dev');
     await roles.revokeRole(targetId, 'ops');
 
-    expect(await targetRoles()).toEqual(['admin']);
+    expect(await targetRoles()).toEqual(['dev']);
     const events = await auditRows();
     expect(events).toHaveLength(3);
     const revoke = events.find((event) => event.action === 'revoke');
     expect(revoke).toMatchObject({ actor: 'actor-1', target: targetId, role: 'ops' });
   }, 60000);
 
+  it('refuses to grant the break-glass role, and writes nothing — the only path to admin is a manual UPDATE in Spanner Studio', async () => {
+    // The error teaches: names break-glass, refuses the grant, and points at the one real path.
+    await expect(new Roles().grantRole(targetId, 'admin')).rejects.toThrow(
+      /break-glass role — this service refuses to grant it.*manual UPDATE on the user row in Spanner Studio/
+    );
+
+    // A refusal is not a role change: no user write, no audit row (the trail records what
+    // happened, and nothing happened).
+    expect(await targetRoles()).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+  }, 60000);
+
+  it('revokes the break-glass role — de-escalation through the audited path stays available', async () => {
+    // Admin arrives only via the manual database path; mirror that here with a system write.
+    await getDbAsSystem().update(tables.User, { id: targetId, roles: ['admin'] });
+
+    await new Roles().revokeRole(targetId, 'admin');
+
+    expect(await targetRoles()).toEqual([]);
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ actor: 'actor-1', target: targetId, role: 'admin', action: 'revoke' });
+  }, 60000);
+
   it('revoking a role the user does not hold changes nothing and writes no audit row', async () => {
     await new Roles().revokeRole(targetId, 'ops');
 
@@ -160,4 +191,38 @@ describe('Roles service — grant/revoke outcomes and audit trail', () => {
     await expect(new Roles().grantRole('nobody-1', 'ops')).rejects.toThrow('No user found for id: nobody-1');
     expect(await auditRows()).toHaveLength(0);
   }, 60000);
+
+  it('refuses to grant an admin-grant-only role when the caller is not an admin — and writes nothing', async () => {
+    // A user-admin's full day-to-day grant set — pointedly including 'roles' (the door this
+    // service sits behind) — must NOT be able to hand out an admin-grant-only role.
+    new UserRepo().setUser({ ...actor, roles: ['users', 'roles', 'sessions'] });
+    try {
+      await expect(new Roles().grantRole(targetId, 'data-access')).rejects.toThrow(/can only be granted by an admin/);
+      expect(await targetRoles()).toEqual([]);
+      expect(await auditRows()).toHaveLength(0);
+    } finally {
+      new UserRepo().setUser(actor);
+    }
+  }, 60000);
+
+  it('grants an admin-grant-only role when the caller IS an admin, audited like any grant', async () => {
+    await new Roles().grantRole(targetId, 'data-access');
+
+    expect(await targetRoles()).toEqual(['data-access']);
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ actor: 'actor-1', target: targetId, role: 'data-access', action: 'grant' });
+  }, 60000);
+
+  it('a roles-holder can still REVOKE an admin-grant-only role — de-escalation stays open (the break-glass precedent)', async () => {
+    await new Roles().grantRole(targetId, 'data-access');
+    new UserRepo().setUser({ ...actor, roles: ['roles'] });
+    try {
+      await new Roles().revokeRole(targetId, 'data-access');
+      expect(await targetRoles()).toEqual([]);
+      expect((await auditRows()).map((event) => event.action).sort()).toEqual(['grant', 'revoke']);
+    } finally {
+      new UserRepo().setUser(actor);
+    }
+  }, 60000);
 });