@proteinjs/db 1.27.0 → 1.28.1

package/index.ts

@@ -11,6 +11,8 @@ export * from './src/UpdatePreserving';
 export * from './src/reference/ReferenceCache';
 export * from './src/RecordIterator';
 export * from './src/source/SourceRecord';
+export * from './src/source/SourceRecordRepo';
+export * from './src/MigrationRunner';
 export * from './src/QueryBuilderFactory';
 export * from './src/TableWatcher';
 export * from './src/transaction/Transaction';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.27.0",
+  "version": "1.28.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,13 +41,13 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.5.0",
+    "@proteinjs/db-query": "^1.6.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.1.12",
     "@proteinjs/serializer": "^1.1.10",
-    "@proteinjs/server-api": "^3.0.10",
-    "@proteinjs/service": "^1.4.1",
-    "@proteinjs/user-auth": "^1.2.0",
+    "@proteinjs/server-api": "^3.0.11",
+    "@proteinjs/service": "^1.5.1",
+    "@proteinjs/user-auth": "^1.3.0",
     "@proteinjs/util": "^1.6.1",
     "moment": "2.29.4",
     "uuid": "8.3.0"
@@ -65,6 +65,5 @@
     "jest": "29.7.0",
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
-  },
-  "gitHead": "020e0d6b909cdd60925952aa05c23cfdecd8353d"
+  }
 }

package/src/MigrationRunner.ts

@@ -13,22 +13,34 @@ export const getMigrationRunner = () =>
 export class MigrationRunner implements MigrationRunnerService {
   private logger = new Logger({ name: this.constructor.name });
   public serviceMetadata: Service['serviceMetadata'] = {
-    // Explicit, not implicit: running migrations is admin-only. Omitting the auth block would
-    // fall back to the same default-deny (admin role), but every service is required to declare
-    // its auth intent explicitly.
+    // Running migrations rides the abstract 'dev' PERMISSION (the developer-surface slug the
+    // db-ui dev pages also declare), resolved through the consumer app's PermissionRolesMapping.
+    // Admin still passes as break-glass. Matches the migration table's doors below the service.
     auth: {
-      roles: ['admin'],
+      permission: 'dev',
     },
     doNotAwait: true,
   };
 
-  async runMigration(id: string): Promise<void> {
+  /**
+   * The service dispatches this fire-and-forget (`doNotAwait`). The method is split along that
+   * seam: everything knowable before the run starts (a bogus id) throws synchronously — the only
+   * path on which an error can still reach the client (the executor wraps it into a
+   * ServiceError -> 400). The returned promise MAY REJECT (infrastructure failure while recording
+   * run state); the caller owns that rejection — on the service path the executor terminally
+   * observes every doNotAwait rejection (logs with method identity, never process death).
+   */
+  runMigration(id: string): Promise<void> {
     const migrationTable: Table<Migration> = new MigrationTable();
     const migration = new SourceRecordRepo().getSourceRecord<Migration>(migrationTable.name, id);
     if (!migration) {
       throw new Error(`Unable to find migration source record for id: ${id}`);
     }
 
+    return this.runAndRecord(migrationTable, migration);
+  }
+
+  private async runAndRecord(migrationTable: Table<Migration>, migration: Migration): Promise<void> {
     const db = getDb();
     migration.status = 'running';
     migration.startTime = moment();
@@ -38,6 +50,9 @@ export class MigrationRunner implements MigrationRunnerService {
       migration.output = await migration.run();
       migration.status = 'success';
     } catch (error: any) {
+      // Domain bookkeeping, not containment: a migration that throws is a run OUTCOME, recorded
+      // as failure status on the record. Only infrastructure failures (the db.update calls
+      // themselves) reject the returned promise.
       migration.failureMessage = error.message;
       migration.failureStack = error.stack;
       migration.status = 'failure';

package/src/auth/TableAuth.ts

@@ -5,8 +5,16 @@ import { Table } from '../Table';
  * @public all users, including guests (do not need to be logged in), do not need any roles
  * @authenticated - users need to be logged in, do not need any roles
  * @roles string[] - authenticated users, having at least one of these roles
+ * @permission - authenticated users holding an abstract permission slug, resolved to roles at
+ * runtime through the consumer app's `PermissionRolesMapping` (see `UserAuth.hasPermission`).
+ * Generic tables declare permissions; only the consumer names roles.
  */
-export type Identity = 'public' | 'authenticated' | string[];
+export type PermissionIdentity = { permission: string };
+
+export type Identity = 'public' | 'authenticated' | string[] | PermissionIdentity;
+
+const isPermissionIdentity = (identity: Identity | undefined): identity is PermissionIdentity =>
+  !!identity && typeof identity === 'object' && !Array.isArray(identity) && typeof identity.permission === 'string';
 
 /**
  * These Identities can perform these operations on this table.
@@ -53,7 +61,10 @@ export class TableAuth {
       (tableAuth.all === 'authenticated' && UserAuth.isLoggedIn()) ||
       (tableAuth[operation] === 'authenticated' && UserAuth.isLoggedIn()) ||
       (Array.isArray(tableAuth.all) && UserAuth.hasRoles(tableAuth.all, 'at least one')) ||
-      (Array.isArray(tableAuth[operation]) && UserAuth.hasRoles(tableAuth[operation] as string[], 'at least one'))
+      (Array.isArray(tableAuth[operation]) && UserAuth.hasRoles(tableAuth[operation] as string[], 'at least one')) ||
+      (isPermissionIdentity(tableAuth.all) && UserAuth.hasPermission(tableAuth.all.permission)) ||
+      (isPermissionIdentity(tableAuth[operation]) &&
+        UserAuth.hasPermission((tableAuth[operation] as PermissionIdentity).permission))
     );
   }
 

package/src/tables/MigrationTable.ts

@@ -17,6 +17,16 @@ export interface Migration extends SourceRecord {
 
 export class MigrationTable extends Table<Migration> {
   public name = 'migration';
+  /**
+   * Both doors ride the 'dev' permission (consumer-mapped; admin passes as break-glass),
+   * matching MigrationRunner's serviceMetadata: the Migrations record table reads/edits via
+   * the service api, and the runner writes run state via the db api as the calling user.
+   * Boot-time source-record loading is a system path (getDbAsSystem) and bypasses doors.
+   */
+  public auth: Table<Migration>['auth'] = {
+    db: { all: { permission: 'dev' } },
+    service: { all: { permission: 'dev' } },
+  };
   public columns = withSourceRecordColumns<Migration>({
     description: new StringColumn('description', {}, 4000),
     status: new StringColumn('status', { defaultValue: async () => 'proposed' }),

package/test/MigrationAuth.test.ts

@@ -0,0 +1,87 @@
+import { UserAuth } from '@proteinjs/user-auth';
+// Deep dist path on purpose: the package index doesn't export the auth gate (it is framework
+// plumbing), but the test must exercise the REAL gate, not a re-implementation of its rules.
+import { ServiceAuth } from '@proteinjs/service/dist/src/ServiceAuth';
+import { Method } from '@proteinjs/reflection';
+import { MigrationRunner } from '../src/MigrationRunner';
+import { MigrationTable } from '../src/tables/MigrationTable';
+import { TableAuth } from '../src/auth/TableAuth';
+
+/**
+ * Migrations ride the 'dev' PERMISSION (plans/ROLES_AND_PERMISSIONS.md decision 4), not the
+ * admin role: the MigrationRunner service and the migration table doors resolve 'dev' through
+ * the consumer's PermissionRolesMapping, so a consumer-mapped dev-role holder can run
+ * migrations while admin still passes everything as break-glass. The mapping deliberately names
+ * a role that is NOT the slug ('dev-crew') to prove the indirection, mirroring the
+ * TableServiceAuth suite's stubbing idiom.
+ */
+
+type UserAuthInternals = {
+  userRepo?: { getUser: () => { email: string; roles: string[] } };
+  permissionRolesMapping?: { getRoles: (permission: string) => string[] | undefined };
+};
+
+const setUser = (roles: string[]) => {
+  (UserAuth as unknown as UserAuthInternals).userRepo = {
+    getUser: () => ({ email: 'user@test.local', roles }),
+  };
+};
+
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = {
+    getRoles: (permission: string) => mapping[permission],
+  };
+};
+
+const canRunMigrations = () => {
+  const method = new Method('runMigration', undefined, true, false, false, false, 'public', []);
+  return ServiceAuth.canRunService(new MigrationRunner(), method, ['some-migration-id']);
+};
+
+describe('migrations ride the dev permission', () => {
+  beforeEach(() => {
+    setMapping({ dev: ['dev-crew'] });
+  });
+
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
+  });
+
+  it(`a consumer-mapped dev-role holder can run migrations and use the migration table's doors`, () => {
+    setUser(['dev-crew']);
+    expect(canRunMigrations()).toBe(true);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    // The record-table page reads via the service api; the runner updates via the db api.
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).not.toThrow();
+      expect(() => auth.canUpdate(table, api)).not.toThrow();
+    }
+  });
+
+  it('a permissionless user is denied the service and both table doors', () => {
+    setUser(['ops-team']);
+    expect(canRunMigrations()).toBe(false);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).toThrow('User is not authorized to query table: migration');
+      expect(() => auth.canUpdate(table, api)).toThrow('User is not authorized to update records in table: migration');
+    }
+  });
+
+  it('admin passes everything as break-glass', () => {
+    setUser(['admin']);
+    expect(canRunMigrations()).toBe(true);
+
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canQuery(table, api)).not.toThrow();
+      expect(() => auth.canUpdate(table, api)).not.toThrow();
+    }
+  });
+});

package/test/MigrationRunnerContainment.test.ts

@@ -0,0 +1,104 @@
+// EnvInfo.isDev() requires a GlobalDataStorage implementation that only exists in a running app
+// (same mock the @proteinjs/service executor suite uses).
+jest.mock('@proteinjs/server-api', () => ({
+  EnvInfo: { isDev: () => true },
+}));
+
+import { Logger, Log, DefaultLogWriter } from '@proteinjs/logger';
+import { Interface, Method } from '@proteinjs/reflection';
+import { Serializer } from '@proteinjs/serializer';
+// Deep dist path on purpose: the package index doesn't export the executor (framework plumbing),
+// but the executor check below must run the REAL BUILT owner of the doNotAwait seam.
+import { ServiceExecutor } from '@proteinjs/service/dist/src/ServiceExecutor';
+import { MigrationRunner } from '../src/MigrationRunner';
+import { Migration, MigrationTable } from '../src/tables/MigrationTable';
+import { SourceRecordRepo } from '../src/source/SourceRecordRepo';
+import { registerTestUser, clearTestUser } from './util/testUser';
+
+/**
+ * MigrationRunnerService is dispatched fire-and-forget (`doNotAwait`): ServiceExecutor calls
+ * runMigration WITHOUT awaiting, so its try/catch sees only SYNCHRONOUS throws and the detached
+ * promise's rejections are terminally observed by the executor itself (service c16645d — logged
+ * with method identity, never an unhandled rejection).
+ *
+ * MigrationRunner's own contract along that seam:
+ * - everything knowable BEFORE the run starts (a bogus id) throws synchronously, the only
+ *   path on which an error can still reach the client (executor wraps it -> 400);
+ * - migration.run() failures are run OUTCOMES, recorded as failure status on the migration
+ *   record (pinned on the emulator in @proteinjs/db-driver-spanner's MigrationRunner.test.ts);
+ * - infrastructure failures (recording run state itself) REJECT the returned promise — the
+ *   caller owns them. On the service path that caller is the executor.
+ */
+
+type ExecutorInternals = { logger: Logger };
+
+/**
+ * This harness loads no reflection graph and registers no DefaultDbDriverFactory, so the body's
+ * FIRST db access (`new Db()` constructing its table-watcher runner) throws this. The specific
+ * message is a harness accident standing in for any mid-run infrastructure failure (db.update
+ * rejecting); the contract under test is that the failure escapes as a rejection at all.
+ */
+const infrastructureFailure = 'Unable to find type: @proteinjs/db/TableWatcher';
+
+const plantMigration = (id: string): Migration => {
+  const migration = {
+    id,
+    description: 'containment test migration',
+    run: async () => undefined,
+  } as Migration;
+  new SourceRecordRepo().loadSourceRecord(new MigrationTable().name, migration);
+  return migration;
+};
+
+describe('MigrationRunner containment (doNotAwait dispatch)', () => {
+  it('throws synchronously on a bogus migration id, not through the detached promise', () => {
+    const runner = new MigrationRunner();
+    expect(() => runner.runMigration('bogus-migration-id')).toThrow(
+      'Unable to find migration source record for id: bogus-migration-id'
+    );
+  });
+
+  it('rejects the detached promise on a mid-run infrastructure failure — the caller owns it', async () => {
+    // The runner no longer swallows infrastructure failures: the rejection escapes to whoever
+    // holds the promise.
+    plantMigration('containment-test-migration');
+
+    const runner = new MigrationRunner();
+    await expect(runner.runMigration('containment-test-migration')).rejects.toThrow(infrastructureFailure);
+  });
+
+  it('through the real built executor, an infrastructure-failure rejection is terminally logged — not process death', async () => {
+    // Admin identity passes the service's 'dev' permission as break-glass (MigrationAuth.test.ts
+    // pins the mapping itself).
+    registerTestUser();
+    try {
+      plantMigration('containment-test-migration-executor');
+
+      const runner = new MigrationRunner();
+      const method = new Method('runMigration', undefined, true, false, false, false, 'public', []);
+      const _interface = new Interface('@proteinjs/db', 'MigrationRunnerService', [], [method]);
+      const executor = new ServiceExecutor(runner, _interface, method);
+      const entries: Log[] = [];
+      (executor as unknown as ExecutorInternals).logger = new Logger({
+        name: 'MigrationRunnerService.runMigration',
+        logWriter: { write: (log: Log) => entries.push(log) } as unknown as DefaultLogWriter,
+      });
+
+      // The client response does not carry the failure — execute resolves immediately.
+      await expect(
+        executor.execute(Serializer.serialize(['containment-test-migration-executor']))
+      ).resolves.toBeUndefined();
+      // The detached rejection settles after the microtask queue drains; flush macrotasks so the
+      // executor's terminal catch has written its log entry. Were the rejection unobserved, jest
+      // would surface it as a failure here — and a bare node process would die.
+      await new Promise((resolve) => setImmediate(resolve));
+      await new Promise((resolve) => setImmediate(resolve));
+
+      const errorEntry = entries.find((entry) => entry.logLevel === 'error');
+      expect(errorEntry?.error?.message).toContain(infrastructureFailure);
+      expect(errorEntry?.obj?.functionName).toBe('MigrationRunnerService.runMigration');
+    } finally {
+      clearTestUser();
+    }
+  });
+});

package/test/TableServiceAuth.test.ts

@@ -63,6 +63,25 @@ class NoAuthTable extends Table<Doc> {
   });
 }
 
+/**
+ * Mirrors the user table's shape: doors keyed to an abstract PERMISSION resolved through the
+ * consumer mapping, with a service-protected column reserved to a dedicated service.
+ */
+class PermissionGatedTable extends Table<Doc> {
+  public name = 'permission_gated_test';
+  public auth: Table<Doc>['auth'] = {
+    service: {
+      query: { permission: 'users' },
+      update: { permission: 'users' },
+    },
+    serviceProtectedColumns: ['owner'],
+  };
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    owner: new StringColumn('owner'),
+  });
+}
+
 /** Read-only intent: only `query` granted (the canDelete-regression shape). */
 class ReadOnlyTable extends Table<Doc> {
   public name = 'read_only_test';
@@ -76,7 +95,10 @@ class ReadOnlyTable extends Table<Doc> {
   });
 }
 
-type UserAuthInternals = { userRepo?: { getUser: () => { email: string; roles: string[] } } };
+type UserAuthInternals = {
+  userRepo?: { getUser: () => { email: string; roles: string[] } };
+  permissionRolesMapping?: { getRoles: (permission: string) => string[] | undefined };
+};
 
 const setUser = (roles: string[]) => {
   (UserAuth as unknown as UserAuthInternals).userRepo = {
@@ -84,6 +106,12 @@ const setUser = (roles: string[]) => {
   };
 };
 
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = {
+    getRoles: (permission: string) => mapping[permission],
+  };
+};
+
 const auth = () => new TableServiceAuth();
 
 /** A denial must be a client-safe ServiceError naming the table and operation. */
@@ -142,6 +170,67 @@ describe('TableServiceAuth — per-operation service grants', () => {
   });
 });
 
+describe('TableServiceAuth — permission-keyed doors (the user table shape)', () => {
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
+  });
+
+  it(`grants a holder of the consumer's mapped role; denies without the role`, () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+
+    setUser(['support']);
+    expect(auth().canAccess('query', [table, {}])).toBe(true);
+    expect(auth().canAccess('update', [table, { id: 'x', title: 't' }])).toBe(true);
+
+    setUser(['dev']);
+    expectDenied(
+      () => auth().canAccess('query', [table, {}]),
+      'User is not authorized to query table: permission_gated_test'
+    );
+  });
+
+  it('denies everyone but admin when no mapping is registered (default deny)', () => {
+    const table = new PermissionGatedTable();
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('query', [table, {}]),
+      'User is not authorized to query table: permission_gated_test'
+    );
+
+    setUser(['admin']);
+    expect(auth().canAccess('query', [table, {}])).toBe(true);
+  });
+
+  it('operations without a grant stay closed even for permission holders (and admin)', () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('insert', [table, { title: 't' }]),
+      'User is not authorized to insert records into table: permission_gated_test'
+    );
+    // An auth block with no grant for the operation is a deliberate lock, not an admin default —
+    // the audit-table shape (role_grant_event) depends on this.
+    setUser(['admin']);
+    expectDenied(
+      () => auth().canAccess('delete', [table, { id: 'x' }]),
+      'User is not authorized to delete records from table: permission_gated_test'
+    );
+  });
+
+  it('the protected column stays unwritable even for a permission holder with the update grant', () => {
+    const table = new PermissionGatedTable();
+    setMapping({ users: ['support'] });
+    setUser(['support']);
+    expectDenied(
+      () => auth().canAccess('update', [table, { id: 'x', owner: 'someone' }]),
+      "Column 'owner' cannot be written via the db service on table: permission_gated_test"
+    );
+  });
+});
+
 describe('TableServiceAuth — default deny (no auth block)', () => {
   afterEach(() => {
     (UserAuth as unknown as UserAuthInternals).userRepo = undefined;

package/test/index.ts

@@ -5,6 +5,8 @@ export * from './reusable/DynamicReferenceColumnTests';
 export * from './reusable/TransactionTests';
 export * from './reusable/CascadeDeleteTests';
 
+export * from './util/testUser';
+
 export * from './util/tables/cascadeDeleteTestTables';
 export * from './util/tables/columnTypesTestTables';
 export * from './util/tables/crudTestTables';

package/test/util/DbTestEnvironment.ts

@@ -1,4 +1,5 @@
 import { Table, DbDriver } from '@proteinjs/db';
+import { registerTestUser, clearTestUser } from './testUser';
 import { cascadeDeleteTestTables } from './tables/cascadeDeleteTestTables';
 import { columnTypesTestTables } from './tables/columnTypesTestTables';
 import { crudTestTables } from './tables/crudTestTables';
@@ -25,6 +26,9 @@ export class DbTestEnvironment {
   ) {}
 
   async beforeAll() {
+    // UserAuth is fail-closed; the suites run non-system Db paths, so they carry an explicit
+    // identity instead of leaning on an open gate.
+    registerTestUser();
     if (this.dbDriver.start) {
       await this.dbDriver.start();
     }
@@ -35,6 +39,7 @@ export class DbTestEnvironment {
   }
 
   async afterAll() {
+    clearTestUser();
     for (const table of TABLES.reverse()) {
       await this.dropTestTable(table);
     }

package/test/util/testUser.ts

@@ -0,0 +1,27 @@
+import { UserAuth } from '@proteinjs/user-auth';
+
+/**
+ * Explicit test identity for suites that exercise non-system `Db` paths.
+ *
+ * `UserAuth` is FAIL-CLOSED: with no registered `AuthenticatedUserRepo` every table gate denies.
+ * Test harnesses that run `Db` outside a server (driver suites, the reusable CRUD suites) must
+ * therefore say who they are instead of leaning on an open gate. Register in `beforeAll`, clear
+ * in `afterAll`; `DbTestEnvironment` does both for the reusable suites.
+ *
+ * The static is reached via a runtime cast per the test-harness convention — widening `UserAuth`
+ * with a setter only tests need would be the wrong trade.
+ *
+ * @internal This module is intended to be used only in tests. Do not use it in production code.
+ */
+
+type UserAuthInternals = { userRepo?: { getUser: () => { email: string; roles: string[] } } };
+
+/** Register an explicit identity on `UserAuth` (admin by default — the reusable suites test CRUD, not table doors). */
+export const registerTestUser = (roles: string[] = ['admin'], email = 'db-test-user@test.local') => {
+  (UserAuth as unknown as UserAuthInternals).userRepo = { getUser: () => ({ email, roles }) };
+};
+
+/** Remove the registered test identity, restoring the deny-everything unregistered state. */
+export const clearTestUser = () => {
+  (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+};

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Brent Bahry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.