@proteinjs/user-server 1.11.0 → 1.12.0

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);
 });

package/test/SweepMalformedAccessGrants.integration.test.ts

@@ -0,0 +1,255 @@
+import { getDbAsSystem, QueryBuilder, Reference, Table, TableWatcher } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+import { AccessGrant, tables, User } from '@proteinjs/user';
+import { SweepMalformedAccessGrants } from '../src/migrations/SweepMalformedAccessGrants';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+
+/** Same harness cast as MachineAccounts.integration.test.ts: recompute the static watcher map on the next Db. */
+const resetTableWatcherMap = () => {
+  const runner = (getDbAsSystem() as unknown as { tableWatcherRunner: object }).tableWatcherRunner;
+  (runner.constructor as { tableWatcherMap?: unknown }).tableWatcherMap = undefined;
+};
+
+/**
+ * Observes access_grant deletes the way the app's watchers do (ContentReferenceAccessGrantTableWatcher
+ * lives in space-common, above this package): a delete that rides the Db layer lands here with the
+ * deleted rows; a raw-SQL delete never would.
+ */
+class RecordingAccessGrantWatcher implements TableWatcher<AccessGrant> {
+  static deletedIds: string[] = [];
+
+  name(): string {
+    return 'RecordingAccessGrantWatcher';
+  }
+
+  table(): Table<AccessGrant> {
+    return tables.AccessGrant;
+  }
+
+  async afterDelete<T extends AccessGrant>(_count: number, deletedRecords: T[]): Promise<void> {
+    for (const record of deletedRecords) {
+      RecordingAccessGrantWatcher.deletedIds.push(record.id);
+    }
+  }
+}
+
+/**
+ * SweepMalformedAccessGrants (one-time migration): the AccessGrant well-formedness invariant now
+ * refuses a grant with no principal or resource id, but the rows its two pre-fix producers left
+ * behind (the test environment's NULL-principal `thought` grant that crashed Deploy to Test
+ * 32614670162) are still there. The sweep deletes EXACTLY the invariant's complement
+ * (`principal IS NULL OR resource IS NULL`) by id through the Db layer — watchers fire — and
+ * nothing else: well-formed grants survive, and DANGLING grants (non-null ids pointing at purged
+ * rows) are reported, never deleted. Idempotent.
+ *
+ * Red-first: written against the contract; a no-op sweep fails the delete legs, and a sweep on
+ * the wrong predicate fails the well-formed-survives legs.
+ */
+describe('SweepMalformedAccessGrants — deletes exactly the malformed rows through the Db layer; reports dangling; idempotent', () => {
+  let owner: User;
+  let grantee: User;
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    // The dangling report resolves resource tables by name off the source graph (none is loaded
+    // in tests) — register exactly this package's tables, as the app's composition would.
+    objectCache()['@proteinjs/db/Table'] = Object.values(tables);
+    objectCache()['@proteinjs/db/TableWatcher'] = [new RecordingAccessGrantWatcher()];
+    resetTableWatcherMap();
+  }, 120_000);
+
+  afterAll(async () => {
+    delete objectCache()['@proteinjs/db/Table'];
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+    resetTableWatcherMap();
+    await testEnv.afterAll();
+  }, 60_000);
+
+  beforeEach(async () => {
+    const db = getDbAsSystem();
+    await db.delete(tables.AccessGrant, {});
+    await db.delete(tables.User, {});
+    RecordingAccessGrantWatcher.deletedIds = [];
+    owner = await testEnv.createUser({ name: 'Owner', email: 'owner@test.local' });
+    grantee = await testEnv.createUser({ name: 'Grantee', email: 'grantee@test.local' });
+  });
+
+  /** A well-formed grant, inserted as system (the invariant admits it). Resource rides the user table here. */
+  async function insertGrant(args: {
+    principalId: string;
+    resourceId: string;
+    resourceTable?: string;
+    accessLevel: AccessGrant['accessLevel'];
+  }): Promise<AccessGrant> {
+    const resourceTable = args.resourceTable ?? tables.User.name;
+    return await getDbAsSystem().insert(tables.AccessGrant, {
+      principal: new Reference(tables.User.name, args.principalId),
+      resource: new Reference(resourceTable, args.resourceId),
+      resourceTable,
+      accessLevel: args.accessLevel,
+    });
+  }
+
+  /**
+   * Seed the malformed shape BENEATH the insert invariant (which rightly refuses it now): insert
+   * well-formed, then null the reference in place — the row the environment actually holds.
+   */
+  async function nullOut(grantId: string, field: 'principal' | 'resource'): Promise<void> {
+    await getDbAsSystem().update(tables.AccessGrant, { [field]: null } as Partial<AccessGrant>, { id: grantId });
+  }
+
+  async function grantById(id: string): Promise<AccessGrant | undefined> {
+    return await getDbAsSystem().get(tables.AccessGrant, { id });
+  }
+
+  async function allGrantIds(): Promise<string[]> {
+    const grants = await getDbAsSystem().query(
+      tables.AccessGrant,
+      new QueryBuilder<AccessGrant>(tables.AccessGrant.name)
+    );
+    return grants.map((grant) => grant.id).sort();
+  }
+
+  it('dry run reports without deleting; real run deletes exactly the malformed rows (watchers fire); well-formed and dangling survive; re-run is a no-op', async () => {
+    // Well-formed — must survive untouched.
+    const ownerGrant = await insertGrant({ principalId: owner.id, resourceId: owner.id, accessLevel: 'owner' });
+    const readGrant = await insertGrant({ principalId: grantee.id, resourceId: owner.id, accessLevel: 'read' });
+    // Malformed — the invariant's complement, one of each shape.
+    const nullPrincipal = await insertGrant({ principalId: grantee.id, resourceId: owner.id, accessLevel: 'write' });
+    await nullOut(nullPrincipal.id, 'principal');
+    const nullResource = await insertGrant({ principalId: grantee.id, resourceId: owner.id, accessLevel: 'admin' });
+    await nullOut(nullResource.id, 'resource');
+    // Dangling — well-formed ids that resolve to nothing. A separate class: reported, never deleted.
+    const purgedPrincipal = await insertGrant({
+      principalId: 'purged-user',
+      resourceId: owner.id,
+      accessLevel: 'read',
+    });
+    const purgedResource = await insertGrant({
+      principalId: grantee.id,
+      resourceId: 'purged-row',
+      accessLevel: 'read',
+    });
+    const unregisteredTable = await insertGrant({
+      principalId: grantee.id,
+      resourceId: 'some-thought',
+      resourceTable: 'thought',
+      accessLevel: 'write',
+    });
+
+    expect((await grantById(nullPrincipal.id))?.principal ?? null).toBeNull();
+    expect((await grantById(nullResource.id))?.resource ?? null).toBeNull();
+    const seededIds = [
+      ownerGrant.id,
+      readGrant.id,
+      nullPrincipal.id,
+      nullResource.id,
+      purgedPrincipal.id,
+      purgedResource.id,
+      unregisteredTable.id,
+    ].sort();
+    expect(await allGrantIds()).toEqual(seededIds);
+
+    const sweep = new SweepMalformedAccessGrants();
+
+    // ---------- DRY RUN: the two malformed rows are listed; nothing is deleted ----------
+    const dry = await sweep.sweep({ dryRun: true });
+    expect(dry.dryRun).toBe(true);
+    expect(dry.malformed).toBe(2);
+    expect(dry.rows.map((row) => row.id).sort()).toEqual([nullPrincipal.id, nullResource.id].sort());
+    expect(dry.rows.find((row) => row.id === nullPrincipal.id)).toMatchObject({
+      resourceTable: tables.User.name,
+      accessLevel: 'write',
+    });
+    expect(dry.rows.every((row) => typeof row.created === 'string' && row.created.length > 0)).toBe(true);
+    expect(await allGrantIds()).toEqual(seededIds);
+    expect(RecordingAccessGrantWatcher.deletedIds).toEqual([]);
+
+    // ---------- REAL RUN: exactly the malformed rows go, through the Db layer ----------
+    const real = await sweep.sweep({ dryRun: false });
+    expect(real.dryRun).toBe(false);
+    expect(real.malformed).toBe(2);
+    expect(await grantById(nullPrincipal.id)).toBeUndefined();
+    expect(await grantById(nullResource.id)).toBeUndefined();
+    // The after-delete watchers saw precisely the deleted rows — the delete rode the Db layer.
+    expect(RecordingAccessGrantWatcher.deletedIds.sort()).toEqual([nullPrincipal.id, nullResource.id].sort());
+    // Well-formed rows intact, levels unchanged.
+    expect((await grantById(ownerGrant.id))?.accessLevel).toBe('owner');
+    expect((await grantById(readGrant.id))?.accessLevel).toBe('read');
+    // Dangling rows intact — reported below, not deleted.
+    expect(await grantById(purgedPrincipal.id)).toBeDefined();
+    expect(await grantById(purgedResource.id)).toBeDefined();
+    expect(await grantById(unregisteredTable.id)).toBeDefined();
+    expect(await allGrantIds()).toEqual(
+      [ownerGrant.id, readGrant.id, purgedPrincipal.id, purgedResource.id, unregisteredTable.id].sort()
+    );
+
+    // ---------- DANGLING REPORT: each purged reference named with its reason; still nothing deleted ----------
+    const dangling = await sweep.reportDangling();
+    expect(dangling.danglingPrincipal).toBe(1);
+    expect(dangling.danglingResource).toBe(2);
+    expect(dangling.rows.find((row) => row.id === purgedPrincipal.id)).toMatchObject({
+      principal: 'purged-user',
+      reason: 'principal missing',
+    });
+    expect(dangling.rows.find((row) => row.id === purgedResource.id)).toMatchObject({
+      resource: 'purged-row',
+      reason: 'resource missing',
+    });
+    expect(dangling.rows.find((row) => row.id === unregisteredTable.id)).toMatchObject({
+      resourceTable: 'thought',
+      reason: 'resource table not registered',
+    });
+    expect(dangling.rows.map((row) => row.id)).not.toContain(ownerGrant.id);
+    expect(dangling.rows.map((row) => row.id)).not.toContain(readGrant.id);
+    expect(await allGrantIds()).toEqual(
+      [ownerGrant.id, readGrant.id, purgedPrincipal.id, purgedResource.id, unregisteredTable.id].sort()
+    );
+
+    // ---------- IDEMPOTENCY: a second real run finds nothing, deletes nothing ----------
+    RecordingAccessGrantWatcher.deletedIds = [];
+    const again = await sweep.sweep({ dryRun: false });
+    expect(again.malformed).toBe(0);
+    expect(again.rows).toEqual([]);
+    expect(RecordingAccessGrantWatcher.deletedIds).toEqual([]);
+    expect(await allGrantIds()).toEqual(
+      [ownerGrant.id, readGrant.id, purgedPrincipal.id, purgedResource.id, unregisteredTable.id].sort()
+    );
+  }, 120_000);
+
+  it('the migration record runs dry-run pass, delete pass, and dangling report; its output carries the rows; a second run is zero', async () => {
+    const ownerGrant = await insertGrant({ principalId: owner.id, resourceId: owner.id, accessLevel: 'owner' });
+    const nullPrincipal = await insertGrant({ principalId: grantee.id, resourceId: owner.id, accessLevel: 'read' });
+    await nullOut(nullPrincipal.id, 'principal');
+    const purgedPrincipal = await insertGrant({
+      principalId: 'purged-user',
+      resourceId: owner.id,
+      accessLevel: 'read',
+    });
+
+    const migration = new SweepMalformedAccessGrants();
+    expect(migration.table.name).toBe('migration');
+
+    const output = await migration.record.run();
+    expect(output).toMatchObject({
+      malformedDryRun: 1,
+      malformed: 1,
+      danglingPrincipal: 1,
+      danglingResource: 0,
+    });
+    expect(output.malformedRows.map((row) => row.id)).toEqual([nullPrincipal.id]);
+    expect(output.danglingRows.map((row) => row.id)).toEqual([purgedPrincipal.id]);
+    expect(await allGrantIds()).toEqual([ownerGrant.id, purgedPrincipal.id].sort());
+    expect(RecordingAccessGrantWatcher.deletedIds).toEqual([nullPrincipal.id]);
+
+    const second = await migration.record.run();
+    expect(second).toMatchObject({ malformedDryRun: 0, malformed: 0, danglingPrincipal: 1, danglingResource: 0 });
+    expect(second.malformedRows).toEqual([]);
+    expect(await allGrantIds()).toEqual([ownerGrant.id, purgedPrincipal.id].sort());
+  }, 120_000);
+});