@proteinjs/db 1.40.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "6717117d3893b6c915fe59c86ce8f65c29c49e14"
+  "gitHead": "149e538c8a05858b6eb7d3a2dc362e5ff196caf9"
 }

package/src/Table.ts

@@ -115,6 +115,25 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
   public cascadeDeleteReferences: () => { table: string; referenceColumn: string }[] = () => [];
   /** Options for configuring SourceRecords (see {@link SourceRecordOptions}) */
   public sourceRecordOptions: SourceRecordOptions<T> = {};
+  /**
+   * Presentation the table declares for the GENERIC record surfaces (@proteinjs/db-ui) — the
+   * framework renders what tables declare; per-table display choices never hard-code into the
+   * generic components. Distinct from `auth.ui`, which gates WHO may see those surfaces.
+   */
+  public ui?: {
+    recordTable?: {
+      /**
+       * The columns rendered as the record table's row columns, in this order. `created` and
+       * `updated` are appended automatically (the record family's shared face) unless already
+       * listed. Undeclared tables get the meaningful-data default pick
+       * (db-ui `defaultRecordTableColumns`). Declare when the default pick misses a column a
+       * human scans for (e.g. the migration ledger's `duration`) or surfaces one that has no
+       * business in a row scan (e.g. an invite's redeemable `token` — row hygiene; the record
+       * form still carries the full record).
+       */
+      columns?: (keyof T & string)[];
+    };
+  };
   public auth?: {
     db?: TableOperationsAuth;
     service?: TableOperationsAuth;

package/src/auth/TableAuth.ts

@@ -45,6 +45,28 @@ export class TableAuthError extends Error {
  * Util to check which table operations a user can perform
  */
 export class TableAuth {
+  /**
+   * Non-throwing capability read: whether the CURRENT user clears this operation's declared
+   * door on this api. The seam UI derivation rides (db-ui's record-table affordances render
+   * only the operations the declaration actually opens — a table with no insert door draws no
+   * create button); the throwing guards below stay the enforcement path.
+   *
+   * Answers false — never throws — when the auth machinery itself cannot resolve a user (e.g.
+   * a context whose source graph never loaded `AuthenticatedUserRepo`): the same fail-closed
+   * reading UserAuth documents for a missing repo, applied to a capability READ.
+   */
+  canPerform(
+    table: Table<any>,
+    operation: 'query' | 'insert' | 'update' | 'delete',
+    api: 'db' | 'service' = 'db'
+  ): boolean {
+    try {
+      return this.canAccess(table, api, operation);
+    } catch {
+      return false;
+    }
+  }
+
   private canAccess(
     table: Table<any>,
     api: 'db' | 'service',

package/src/tables/MigrationTable.ts

@@ -58,14 +58,28 @@ 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),
+   * The 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.
+   * INSERT deliberately has no door — for anyone, break-glass included: ledger rows are born
+   * from source declarations only (boot-time loading rides getDbAsSystem, which bypasses
+   * doors), so a caller-path insert could only mint a row no source owns. The generic record
+   * surfaces derive their affordances from these doors (db-ui renders no create button here).
    */
   public auth: Table<Migration>['auth'] = {
-    db: { all: { permission: 'dev' } },
-    service: { all: { permission: 'dev' } },
+    db: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
+    service: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
+  };
+  /**
+   * The row scan the founder actually reads: what ran, how it went, HOW LONG it took
+   * (duration — stamped by the runner at completion; the default pick's five-column cap
+   * dropped it), then the declaration flags. Failure detail and timestamps stay on the
+   * record form.
+   */
+  public ui: Table<Migration>['ui'] = {
+    recordTable: {
+      columns: ['description', 'status', 'duration', 'manual', 'preSchemaSync', 'retired'],
+    },
   };
   public columns = withSourceRecordColumns<Migration>({
     description: new StringColumn('description', {}, 4000),

package/test/MigrationAuth.test.ts

@@ -84,4 +84,29 @@ describe('migrations ride the dev permission', () => {
       expect(() => auth.canUpdate(table, api)).not.toThrow();
     }
   });
+
+  it('insert has no door — for anyone, break-glass included: ledger rows are born from source declarations only', () => {
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const roles of [['dev-crew'], ['admin']]) {
+      setUser(roles);
+      for (const api of ['db', 'service'] as const) {
+        expect(() => auth.canInsert(table, api)).toThrow(
+          'User is not authorized to insert records into table: migration'
+        );
+        // The capability read the record surfaces derive affordances from agrees with the gate.
+        expect(auth.canPerform(table, 'insert', api)).toBe(false);
+      }
+    }
+  });
+
+  it('delete keeps its dev door (ledger hygiene stays possible)', () => {
+    setUser(['dev-crew']);
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canDelete(table, api)).not.toThrow();
+      expect(auth.canPerform(table, 'delete', api)).toBe(true);
+    }
+  });
 });