@proteinjs/db 1.50.1 → 1.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.50.1",
+  "version": "1.51.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -46,7 +46,7 @@
     "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
     "@proteinjs/server-api": "^3.0.11",
-    "@proteinjs/service": "^1.6.0",
+    "@proteinjs/service": "^1.8.0",
     "@proteinjs/user-auth": "^1.3.0",
     "@proteinjs/util": "^1.6.1",
     "moment": "2.29.4",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "a324a92e60161ddf69fec4e17b646882fe830f85"
+  "gitHead": "1128b1e6374c7f52cd5de172620b619b8f92e119"
 }

package/src/auth/TableAuth.ts

@@ -138,26 +138,41 @@ export class TableAuth {
     }
 
     // ...except that a db door the block leaves UNDECLARED mirrors the door the table's SERVICE
-    // block declares for the same operation. The RPC runs both doors — the service gate
-    // (TableServiceAuth), then the inner Db's db-api re-check as the calling user — so a service
-    // door with no db mirror admitted the caller at the gate and refused them behind it, in the
-    // gate's own words ("db doors mirror service doors" was a rule tables hand-copied; the owner
-    // derives it). One-way: a service block that omits the door keeps the lock (the session /
-    // audit-trail pattern — no write door on either api, break-glass included), and a table with
-    // no service block keeps its db block as written.
+    // block declares for the same operation — and only where that door admits the admin role
+    // ALONE. The RPC runs both doors — the service gate (TableServiceAuth), then the inner Db's
+    // db-api re-check as the calling user — so an ['admin'] service write door with no db mirror
+    // admitted the admin at the gate and refused them behind it, in the gate's own words ("db
+    // doors mirror service doors" was a rule tables hand-copied; the owner derives it). Any wider
+    // service door — a permission, a non-admin role, 'authenticated', 'public' — leaves the
+    // undeclared db door shut: role privilege and the reach of a permission are different things,
+    // so a table that means a wider identity to write through the db api declares that door at
+    // the db block itself. One-way: a service block that omits the door keeps the lock (the
+    // session / audit-trail pattern — no write door on either api, break-glass included), and a
+    // table with no service block keeps its db block as written.
     return api === 'db' && tableAuth.all === undefined && tableAuth[operation] === undefined
-      ? this.allowsServiceDoor(table, operation)
+      ? this.mirrorsAdminOnlyServiceDoor(table, operation)
       : false;
   }
 
-  /** The service block's door for `operation`, as the RPC gate reads it; a table with no service block declares none. */
-  private allowsServiceDoor(table: Table<any>, operation: 'query' | 'insert' | 'update' | 'delete'): boolean {
+  /**
+   * The mirror: the service block's door for `operation` (its `all` and its own entry, as the RPC
+   * gate reads them) where every identity it declares is exactly `['admin']` admits the admin
+   * here too; a door declared any wider, or not at all, mirrors nothing. A table with no service
+   * block declares no door to mirror.
+   */
+  private mirrorsAdminOnlyServiceDoor(table: Table<any>, operation: 'query' | 'insert' | 'update' | 'delete'): boolean {
     const serviceAuth = table.auth?.service;
     if (!serviceAuth || Object.keys(serviceAuth).length == 0) {
       return false;
     }
 
-    return this.allows(serviceAuth.all) || this.allows(serviceAuth[operation]);
+    const door = [serviceAuth.all, serviceAuth[operation]].filter((identity) => identity !== undefined);
+    return door.length > 0 && door.every((identity) => this.isAdminOnly(identity)) && UserAuth.hasRole('admin');
+  }
+
+  /** A roles list naming the admin role and nothing else. */
+  private isAdminOnly(identity: Identity | undefined): boolean {
+    return Array.isArray(identity) && identity.length === 1 && identity[0] === 'admin';
   }
 
   /** One identity against the current user; undefined (nothing declared) is not a grant. */

package/src/services/DbService.ts

@@ -5,7 +5,19 @@ import { QueryBuilder } from '@proteinjs/db-query';
 import { ArrayMembershipUpdate } from '../reference/ArrayMembershipOps';
 import { PreservedPath } from '../UpdatePreserving';
 
-export const getDbService = serviceFactory<DbService>('@proteinjs/db/DbService');
+/**
+ * The db service rides the service client's retry policy by declaration alone, no logic of its
+ * own: the reads (`query`, `get`, `getRowCount`, `tableExists`) are declared `'read'` — bounded at
+ * the first contact and redelivered under the client's series when a delivery produced no
+ * response — and every write stays undeclared: one delivery, never redelivered (a redelivered
+ * `insert` would insert twice). The policy's numbers and exceptions are @proteinjs/service's.
+ */
+export const getDbService = serviceFactory<DbService>('@proteinjs/db/DbService', undefined, {
+  query: 'read',
+  get: 'read',
+  getRowCount: 'read',
+  tableExists: 'read',
+});
 
 export type Query<T> = ObjectQuery<T> | QueryBuilder<T>;
 export type ObjectQuery<T> = Partial<{ [P in keyof T]: any }>;

package/test/DbServiceRetryDeclaration.test.ts

@@ -0,0 +1,105 @@
+import { Interface, Method, SourceRepository, TypeAliasDeclaration } from '@proteinjs/reflection';
+import { READ_CONTACT_TIMEOUT_MS, REDELIVERY_BASE_MS } from '@proteinjs/service';
+import { getDbService } from '../src/services/DbService';
+
+/**
+ * The db service rides the service client's retry policy by declaration alone: its reads (`query`,
+ * `get`, `getRowCount`, `tableExists`) are declared `'read'` on the factory — bounded at the first
+ * contact and redelivered as fresh requests under the client's series when a delivery produced no
+ * response — and its writes (`insert`, `update`, `updateArrayMembership`, `updatePreserving`,
+ * `delete`) stay undeclared: one delivery, no bound, never redelivered. Nothing here is the db
+ * package's own logic — the policy, its numbers and its exceptions are @proteinjs/service's; this
+ * suite pins the declaration. Read as OUTCOMES off the transport: the requests that left and their
+ * watchdog signals, under fake timers.
+ *
+ * The service interface is seeded into the source repository directly (this package's own test pattern —
+ * DbDefaultDriverDuplicateModuleState seeds the object cache the same way), so the real factory
+ * builds the real clients without the generated source graph.
+ */
+
+type RepositoryInternals = { flattenedSourceGraph: { interfaces: { [qualifiedName: string]: Interface } } };
+
+const READS = ['query', 'get', 'getRowCount', 'tableExists'];
+const WRITES = ['insert', 'update', 'updateArrayMembership', 'updatePreserving', 'delete'];
+
+beforeAll(() => {
+  // Node's Request rejects the relative service paths a browser resolves against the page origin.
+  global.Request = class {
+    constructor(
+      public url: string,
+      public init: any
+    ) {}
+  } as any;
+  const returnType = { name: 'Promise<any>' } as unknown as TypeAliasDeclaration;
+  const methods = [...READS, ...WRITES].map(
+    (name) => new Method(name, returnType, true, false, false, false, 'public', [])
+  );
+  (SourceRepository.get() as unknown as RepositoryInternals).flattenedSourceGraph.interfaces[
+    '@proteinjs/db/DbService'
+  ] = new Interface('@proteinjs/db', 'DbService', [], methods);
+});
+
+/** A transport that never answers: its promise settles only when the request is abandoned (its signal aborts). */
+const neverAnswers = () =>
+  jest.fn(
+    (request: any) =>
+      new Promise((unused, reject) => {
+        request.init.signal?.addEventListener('abort', () =>
+          reject(Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' }))
+        );
+      })
+  );
+
+const sentRequests = (): any[] => (global.fetch as jest.Mock).mock.calls.map(([request]) => request);
+
+/** The call's outcome, readable without awaiting it — a pending call must read as pending. */
+const track = (promise: Promise<any>) => {
+  const outcome: { state: 'pending' | 'resolved' | 'rejected' } = { state: 'pending' };
+  promise.then(
+    () => {
+      outcome.state = 'resolved';
+    },
+    () => {
+      outcome.state = 'rejected';
+    }
+  );
+  return outcome;
+};
+
+const aTable = { name: 'a_table' } as any;
+
+describe('the db service under the client retry policy', () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.useRealTimers());
+
+  it.each(READS)(
+    '%s is a declared read: bounded at the first contact, redelivered as a fresh request',
+    async (name) => {
+      global.fetch = neverAnswers() as any;
+      const service = getDbService() as any;
+      const outcome = track(service[name](aTable, {}));
+
+      await jest.advanceTimersByTimeAsync(READ_CONTACT_TIMEOUT_MS);
+      expect(sentRequests()).toHaveLength(1);
+      expect(sentRequests()[0].url).toBe(`/service/@proteinjs/db/DbService/${name}`);
+      expect(sentRequests()[0].init.signal.aborted).toBe(true);
+
+      await jest.advanceTimersByTimeAsync(REDELIVERY_BASE_MS);
+      expect(sentRequests()).toHaveLength(2);
+      expect(sentRequests()[1].init.signal.aborted).toBe(false);
+      expect(outcome.state).toBe('pending');
+    }
+  );
+
+  it.each(WRITES)('%s is undeclared: one delivery, no bound, never redelivered', async (name) => {
+    global.fetch = neverAnswers() as any;
+    const service = getDbService() as any;
+    const outcome = track(service[name](aTable, {}));
+
+    await jest.advanceTimersByTimeAsync(READ_CONTACT_TIMEOUT_MS * 4);
+    expect(sentRequests()).toHaveLength(1);
+    expect(sentRequests()[0].url).toBe(`/service/@proteinjs/db/DbService/${name}`);
+    expect(sentRequests()[0].init.signal).toBeUndefined();
+    expect(outcome.state).toBe('pending');
+  });
+});

package/test/TableAuthIdentity.test.ts

@@ -13,7 +13,8 @@ import { TableAuth } from '../src/auth/TableAuth';
  * - it fails CLOSED when no user can be resolved;
  * - the operation doors (`canPerform`) keep the declared-block semantics: within a declared block
  *   an undeclared operation stays closed to everyone, admin included — unless the table's SERVICE
- *   block names that door, which the db door then mirrors (the last describe).
+ *   block names that door for the admin role alone, which the db door then mirrors (the last two
+ *   describes).
  *
  * `UserAuth` reads from a static repo; tests stub it directly per identity — no server needed.
  */
@@ -118,13 +119,15 @@ describe('TableAuth operation doors keep their declared-block semantics', () =>
 /**
  * The RPC runs BOTH doors — the service gate (`TableServiceAuth`) and then the inner `Db`'s
  * db-api re-check as the calling user — so a db door a table leaves UNDECLARED mirrors the door
- * its service block declares for the same operation. "db doors mirror service doors" was a rule
- * tables hand-copied; the owner derives it now: fifteen consumer tables opened `['admin']` writes
- * on the service api over a query-only db block, and every one refused the admin at the inner
- * check in the gate's own words — the gate admitted them, the re-check behind it did not, two
- * verdicts for one caller. One-way: a service block that omits the door keeps the lock (the
- * session / audit-trail pattern — no write door on either api, break-glass included), and a table
- * with no service block keeps its db block as written (the pin above).
+ * its service block declares for the same operation, where that door admits the admin role ALONE
+ * (declared exactly `['admin']`). "db doors mirror service doors" was a rule tables hand-copied;
+ * the owner derives it now: consumer tables opened `['admin']` writes on the service api over a
+ * query-only db block, and every one refused the admin at the inner check in the gate's own words
+ * — the gate admitted them, the re-check behind it did not, two verdicts for one caller. One-way:
+ * a service block that omits the door keeps the lock (the session / audit-trail pattern — no
+ * write door on either api, break-glass included), and a table with no service block keeps its
+ * db block as written (the pin above). A service door declared any wider than the admin role is
+ * the next describe's: it mirrors nothing.
  */
 class ReadOpenWriteAdminTable extends Table<Doc> {
   public name = 'identity_read_open_write_admin_test';
@@ -144,7 +147,7 @@ class LockedLedgerTable extends Table<Doc> {
   public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
 }
 
-describe('TableAuth — an undeclared db door mirrors the declared service door', () => {
+describe("TableAuth — an undeclared db door mirrors the declared ['admin'] service door", () => {
   beforeEach(() => {
     setMapping({ ledger: ['ledger'] });
   });
@@ -206,3 +209,120 @@ describe('TableAuth — an undeclared db door mirrors the declared service door'
     );
   });
 });
+
+/**
+ * Role privilege and the reach of a permission are different things: the mirror carries the
+ * admin's break-glass across the two apis, never a wider identity. The service block here opens
+ * three writes to identities wider than the admin role — a permission, a non-admin role, every
+ * signed-in user — over a query-only db block, and none of them is mirrored: the gate admits the
+ * holder and the db door behind it stays shut, exactly as before the mirror existed. A table that
+ * means a wider identity to write through the db api declares that door at the db block itself.
+ */
+class WiderServiceDoorsTable extends Table<Doc> {
+  public name = 'identity_wider_service_doors_test';
+  public auth: Table<Doc>['auth'] = {
+    db: { query: { permission: 'ledger' } },
+    service: {
+      query: { permission: 'ledger' },
+      update: { permission: 'ledger' },
+      insert: ['ledger'],
+      delete: 'authenticated',
+    },
+  };
+  public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
+}
+
+/** A service write door the admin role shares with another role: not the admin role alone. */
+class SharedRoleDoorTable extends Table<Doc> {
+  public name = 'identity_shared_role_door_test';
+  public auth: Table<Doc>['auth'] = {
+    db: { query: 'authenticated' },
+    service: { query: 'authenticated', update: ['admin', 'ledger'] },
+  };
+  public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
+}
+
+/** The admin-only door named by `all`: the same door, read the way the gate reads it. */
+class AllAdminServiceTable extends Table<Doc> {
+  public name = 'identity_all_admin_service_test';
+  public auth: Table<Doc>['auth'] = {
+    db: { query: 'authenticated' },
+    service: { all: ['admin'] },
+  };
+  public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
+}
+
+/** An `['admin']` entry beside an `all` that widens the door to every signed-in user: not admin alone. */
+class WidenedByAllTable extends Table<Doc> {
+  public name = 'identity_widened_by_all_test';
+  public auth: Table<Doc>['auth'] = {
+    db: { query: 'authenticated' },
+    service: { all: 'authenticated', update: ['admin'] },
+  };
+  public columns = withRecordColumns<Doc>({ title: new StringColumn('title') });
+}
+
+describe('TableAuth — the mirror reaches only a service door that admits the admin role alone', () => {
+  beforeEach(() => {
+    setMapping({ ledger: ['ledger'] });
+  });
+
+  afterEach(() => {
+    (UserAuth as any).userRepo = undefined;
+    (UserAuth as any).permissionRolesMapping = undefined;
+  });
+
+  test('a permission-declared service write with no db door stays shut for the permission holder — the gate admits, the db door does not', () => {
+    setUser(['ledger']);
+    const table = new WiderServiceDoorsTable();
+    expect(new TableAuth().canPerform(table, 'update', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(table, 'update', 'db')).toBe(false);
+    expect(() => new TableAuth().canUpdate(table)).toThrow(
+      'User is not authorized to update records in table: identity_wider_service_doors_test'
+    );
+    expect(() => new TableAuth().canQuery(table)).not.toThrow();
+  });
+
+  test("a non-admin role door and an 'authenticated' door are as shut on the db api as the permission door", () => {
+    setUser(['ledger']);
+    const table = new WiderServiceDoorsTable();
+    expect(new TableAuth().canPerform(table, 'insert', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(table, 'insert', 'db')).toBe(false);
+    expect(new TableAuth().canPerform(table, 'delete', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(table, 'delete', 'db')).toBe(false);
+    expect(() => new TableAuth().canInsert(table)).toThrow(
+      'User is not authorized to insert records into table: identity_wider_service_doors_test'
+    );
+  });
+
+  test('a wider service door opens nothing on the db api for the admin either — shut as it was before the mirror', () => {
+    setUser(['admin']);
+    const table = new WiderServiceDoorsTable();
+    expect(new TableAuth().canPerform(table, 'update', 'db')).toBe(false);
+    expect(new TableAuth().canPerform(table, 'insert', 'db')).toBe(false);
+    expect(new TableAuth().canPerform(table, 'delete', 'db')).toBe(false);
+    expect(() => new TableAuth().canUpdate(table)).toThrow(
+      'User is not authorized to update records in table: identity_wider_service_doors_test'
+    );
+  });
+
+  test('a door the admin role shares with another role is not the admin role alone: shut on the db api for both', () => {
+    const table = new SharedRoleDoorTable();
+    setUser(['admin']);
+    expect(new TableAuth().canPerform(table, 'update', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(table, 'update', 'db')).toBe(false);
+    setUser(['ledger']);
+    expect(new TableAuth().canPerform(table, 'update', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(table, 'update', 'db')).toBe(false);
+  });
+
+  test("the admin-only door may be named by `all`; an `all` that widens the door beside an ['admin'] entry mirrors nothing", () => {
+    setUser(['admin']);
+    expect(new TableAuth().canPerform(new AllAdminServiceTable(), 'update', 'db')).toBe(true);
+    expect(() => new TableAuth().canUpdate(new AllAdminServiceTable())).not.toThrow();
+    expect(new TableAuth().canPerform(new WidenedByAllTable(), 'update', 'service')).toBe(true);
+    expect(new TableAuth().canPerform(new WidenedByAllTable(), 'update', 'db')).toBe(false);
+    setUser(['ledger']);
+    expect(new TableAuth().canPerform(new AllAdminServiceTable(), 'update', 'db')).toBe(false);
+  });
+});