@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-plan-diff.test.ts

@@ -0,0 +1,204 @@
+/**
+ * The read-back projection (`attributesOf`), the plan-time comparison (`grantsDiffer`) and
+ * the cleared twin `delete` replays (`clearedDeclaration`). The declaration refusals and the
+ * repair planners live in `grants-plan.test.ts` and `grants-repair-plan.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+import { clearedDeclaration, resolveProps } from './grants-declare.ts';
+import { attributesOf, grantsDiffer } from './grants-diff.ts';
+import { planRepair } from './grants-plan.ts';
+import type { LiveGrants } from './grants-read.ts';
+
+const props: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+};
+
+const live = (over: Partial<LiveGrants> = {}): LiveGrants => ({
+  schemaExists: true,
+  schema: { role: [], public: [] },
+  tables: [],
+  columns: [],
+  defaults: [],
+  schemaOwnedByRole: false,
+  ownedTables: [],
+  ...over,
+});
+
+const names = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  tables: ['widgets'],
+  columns: [],
+  defaults: [],
+};
+
+describe('attributesOf', () => {
+  const fresh = live({
+    schema: { role: ['usage'], public: [] },
+    tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+  });
+
+  test('attributes record the role words on the named objects and the PUBLIC facts', () => {
+    const attrs = attributesOf(fresh, names);
+    expect(attrs.tables).toEqual([{ table: 'widgets', privileges: ['select'] }]);
+    expect(attrs.publicSchemaRevoked).toBe(true);
+    expect(attrs.publicTablesRevoked).toBe(true);
+  });
+
+  test('attributes record the ownership facts; an owned object records an empty word list', () => {
+    const attrs = attributesOf(
+      live({
+        schemaOwnedByRole: true,
+        ownedTables: ['widgets'],
+        tables: [{ table: 'widgets', relkind: 'r', role: [], public: [] }],
+      }),
+      names,
+    );
+    expect(attrs.schemaOwnedByRole).toBe(true);
+    expect(attrs.ownedTables).toEqual(['widgets']);
+    expect(attrs.tables).toEqual([{ table: 'widgets', privileges: [] }]);
+    // The PUBLIC fact is scoped to the relkinds the bulk revoke reaches: a sequence
+    // outside that reach cannot hold the fact back.
+    const sequence = attributesOf(
+      live({ tables: [{ table: 'app_seq', relkind: 'S', role: [], public: ['usage'] }] }),
+      { ...names, tables: ['app_seq'] },
+    );
+    expect(sequence.publicTablesRevoked).toBe(true);
+  });
+
+  test('a PUBLIC hold with the flag off is recorded as not revoked', () => {
+    const attrs = attributesOf(live({ schema: { role: ['usage'], public: ['usage'] } }), {
+      ...names,
+      tables: [],
+    });
+    expect(attrs.publicSchemaRevoked).toBe(false);
+  });
+});
+
+describe('grantsDiffer', () => {
+  const declared = resolveProps({
+    ...props,
+    tables: [{ table: 'widgets', privileges: ['select'] }],
+  });
+  const fresh = live({
+    schema: { role: ['usage'], public: [] },
+    tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+  });
+
+  test('equal declarations answer noop; a word, a name-set change and identity answer update', () => {
+    const attrs = attributesOf(fresh, names);
+    expect(grantsDiffer(declared, attrs)).toBe(false);
+    expect(grantsDiffer({ ...declared, schemaPrivileges: [] }, attrs)).toBe(true);
+    expect(grantsDiffer({ ...declared, role: 'other' }, attrs)).toBe(true);
+    const growing = resolveProps({
+      ...props,
+      tables: [
+        { table: 'widgets', privileges: ['select'] },
+        { table: 'gadgets', privileges: ['select'] },
+      ],
+    });
+    expect(grantsDiffer(growing, attrs)).toBe(true);
+  });
+
+  test('a flipped COLUMN word and a flipped DEFAULT word answer update, marks included', () => {
+    // The baseline (schema words + table words) is what the plain declaration already
+    // holds, so ONLY the flipped column or default word can answer update.
+    const baseline = {
+      schema: { role: ['usage'], public: [] },
+      tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+    };
+    const withColumn = attributesOf(
+      live({
+        ...baseline,
+        columns: [
+          { table: 'widgets', column: 'id', role: ['select'], public: [], restorable: ['select'] },
+        ],
+      }),
+      { ...names, columns: [{ table: 'widgets', column: 'id' }] },
+    );
+    expect(
+      grantsDiffer(
+        { ...declared, columns: [{ table: 'widgets', column: 'id', privileges: ['select'] }] },
+        withColumn,
+      ),
+    ).toBe(false);
+    expect(
+      grantsDiffer(
+        { ...declared, columns: [{ table: 'widgets', column: 'id', privileges: ['select*'] }] },
+        withColumn,
+      ),
+    ).toBe(true);
+
+    const withDefault = attributesOf(
+      live({ ...baseline, defaults: [{ forRole: 'owner_role', role: ['select'] }] }),
+      { ...names, defaults: ['owner_role'] },
+    );
+    expect(
+      grantsDiffer(
+        { ...declared, defaults: [{ forRole: 'owner_role', privileges: ['select'] }] },
+        withDefault,
+      ),
+    ).toBe(false);
+    expect(
+      grantsDiffer(
+        { ...declared, defaults: [{ forRole: 'owner_role', privileges: ['insert'] }] },
+        withDefault,
+      ),
+    ).toBe(true);
+  });
+
+  test('an owned object\u2019s word change is never drift; only its name set can answer update', () => {
+    const attrs = attributesOf(
+      live({
+        schemaOwnedByRole: true,
+        ownedTables: ['widgets'],
+        tables: [{ table: 'widgets', relkind: 'r', role: [], public: [] }],
+      }),
+      names,
+    );
+    expect(grantsDiffer(declared, attrs)).toBe(false);
+    expect(
+      grantsDiffer({ ...declared, tables: [{ table: 'widgets', privileges: ['insert'] }] }, attrs),
+    ).toBe(false);
+    expect(
+      grantsDiffer({ ...declared, tables: [{ table: 'other', privileges: ['select'] }] }, attrs),
+    ).toBe(true);
+  });
+
+  test('live PUBLIC holds are one-directional: not revoking is never drift', () => {
+    const attrs = attributesOf(live({ schema: { role: ['usage'], public: ['usage'] } }), {
+      ...names,
+      tables: [],
+    });
+    expect(grantsDiffer(resolveProps(props), attrs)).toBe(false);
+  });
+});
+
+describe('clearedDeclaration (the delete twin)', () => {
+  const declared = resolveProps({
+    ...props,
+    tables: [{ table: 'widgets', privileges: ['select'] }],
+  });
+  test('keeps every name, empties every word list, and turns both PUBLIC flags off', () => {
+    const cleared = clearedDeclaration(declared);
+    expect(cleared.tables.map((t) => [t.table, t.privileges])).toEqual([['widgets', []]]);
+    expect(cleared.schemaPrivileges).toEqual([]);
+    expect(cleared.publicSchemaRevoked).toBe(false);
+    expect(cleared.role).toBe('seat_writer');
+  });
+
+  test('against live grants it plans revoke-only statements, none for PUBLIC', () => {
+    const withLive = live({
+      schema: { role: ['usage'], public: ['usage'] },
+      tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: ['select'] }],
+    });
+    expect(planRepair(clearedDeclaration(declared), withLive)).toEqual([
+      'REVOKE ALL ON SCHEMA "app" FROM "seat_writer"',
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+    ]);
+  });
+});

package/src/postgres/grants-plan-restore.ts

@@ -0,0 +1,43 @@
+/**
+ * Which removed entries a reconcile's `REVOKE ALL` will actually emit.
+ *
+ * Pure — the statement text stays in `grants-plan.ts`. `planRepair` counts the tables
+ * returned here as already revoked, so it re-grants the column entries that revoke
+ * clears and plans any still-declared columns of those tables against an empty set,
+ * all from the pre-revoke read (the writes then share one transaction).
+ */
+import type { DeclaredGrants } from './grants-declare.ts';
+import type { LiveGrants } from './grants-read.ts';
+
+export interface RemovalRevokes {
+  readonly tables: ReadonlyArray<string>;
+  readonly columns: ReadonlyArray<{ readonly table: string; readonly column: string }>;
+}
+
+const tableWords = (live: LiveGrants, table: string): ReadonlyArray<string> =>
+  live.tables.find((entry) => entry.table === table)?.role ?? [];
+
+const columnWords = (live: LiveGrants, table: string, column: string): ReadonlyArray<string> =>
+  live.columns.find((entry) => entry.table === table && entry.column === column)?.role ?? [];
+
+/** Tables and columns an update removed that still show the role's words and that the
+ * role does not own. An empty catalog entry emits no revoke — and must not be counted
+ * as revoked, or the repair would re-grant columns the revoke never cleared. */
+export const removalRevokes = (
+  removed: Pick<DeclaredGrants, 'tables' | 'columns'>,
+  live: LiveGrants,
+): RemovalRevokes => {
+  const ownedTables = new Set(live.ownedTables);
+  return {
+    tables: removed.tables
+      .filter((table) => !ownedTables.has(table.table) && tableWords(live, table.table).length > 0)
+      .map((table) => table.table),
+    columns: removed.columns
+      .filter(
+        (column) =>
+          !ownedTables.has(column.table) &&
+          columnWords(live, column.table, column.column).length > 0,
+      )
+      .map(({ table, column }) => ({ table, column })),
+  };
+};

package/src/postgres/grants-plan-revocations.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `planRevocations`: the entries an update removed from the declaration. Extracted from
+ * `grants-repair-plan.test.ts` so both files stay under the code-size cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import { planRevocations } from './grants-plan.ts';
+import type { LiveGrants } from './grants-read.ts';
+
+const live = (over: Partial<LiveGrants> = {}): LiveGrants => ({
+  schemaExists: true,
+  schema: { role: [], public: [] },
+  tables: [],
+  columns: [],
+  defaults: [],
+  schemaOwnedByRole: false,
+  ownedTables: [],
+  ...over,
+});
+
+const removed = {
+  schema: 'app',
+  role: 'seat_writer',
+  tables: [{ table: 'widgets', privileges: [] as ReadonlyArray<string> }],
+  columns: [{ table: 'widgets', column: 'id', privileges: [] as ReadonlyArray<string> }],
+  defaults: [{ forRole: 'owner_role', privileges: [] as ReadonlyArray<string> }],
+};
+
+describe('planRevocations (the entries an update removed)', () => {
+  test('a removed object still showing the role\u2019s words earns exactly one revoke', () => {
+    expect(
+      planRevocations(
+        removed,
+        live({
+          tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+          columns: [
+            {
+              table: 'widgets',
+              column: 'id',
+              role: ['select'],
+              public: [],
+              restorable: ['select'],
+            },
+          ],
+          defaults: [{ forRole: 'owner_role', role: ['select'] }],
+        }),
+      ),
+    ).toEqual([
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+      'REVOKE ALL ("id") ON "app"."widgets" FROM "seat_writer"',
+      'ALTER DEFAULT PRIVILEGES FOR ROLE "owner_role" IN SCHEMA "app" REVOKE ALL ON TABLES FROM "seat_writer"',
+    ]);
+  });
+
+  test('a removed object the catalogs show empty for (revoked, or dropped) emits nothing', () => {
+    expect(planRevocations(removed, live())).toEqual([]);
+  });
+
+  test('a removed table the role OWNS emits nothing — the owner\u2019s implicit rights are not this resource\u2019s to revoke', () => {
+    expect(
+      planRevocations(
+        removed,
+        live({
+          ownedTables: ['widgets'],
+          tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+        }),
+      ),
+    ).toEqual([]);
+  });
+});

package/src/postgres/grants-plan.test.ts

@@ -0,0 +1,148 @@
+/**
+ * The pure declaration layer: `resolveProps`' defaults and normalization, the declaration
+ * refusals (vocabulary, plain-vs-starred conflict, duplicates, name length) and
+ * `splitGrantWords`. The repair and revocation planners live in
+ * `grants-repair-plan.test.ts`; the projection and comparison in `grants-plan-diff.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+import { declarationRefusal, grantsNamesRefusal } from './grants-refuse.ts';
+import { resolveProps, splitGrantWords } from './grants-declare.ts';
+
+const props: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+};
+
+describe('resolveProps', () => {
+  test('schemaUsage defaults true, schemaCreate and the PUBLIC revokes default false', () => {
+    const declared = resolveProps(props);
+    expect(declared.schemaPrivileges).toEqual(['usage']);
+    expect(declared.publicSchemaRevoked).toBe(false);
+    expect(declared.publicTablesRevoked).toBe(false);
+  });
+
+  test('lists are deduplicated and sorted, both for stability and for positional equality', () => {
+    const declared = resolveProps({
+      ...props,
+      tables: [
+        { table: 'zeta', privileges: ['insert', 'select', 'select'] },
+        { table: 'alpha', privileges: ['select'] },
+      ],
+      columnGrants: [{ table: 'zeta', column: 'b', privileges: ['select'] }],
+    });
+    expect(declared.tables.map((t) => [t.table, t.privileges])).toEqual([
+      ['alpha', ['select']],
+      ['zeta', ['insert', 'select']],
+    ]);
+    expect(declared.columns).toEqual([{ table: 'zeta', column: 'b', privileges: ['select'] }]);
+  });
+});
+
+describe('declarationRefusal', () => {
+  test('a table word outside the table vocabulary is refused with the prop naming the table', () => {
+    const refusal = declarationRefusal(
+      resolveProps({ ...props, tables: [{ table: 'widgets', privileges: ['execute'] }] }),
+    );
+    expect(refusal).toEqual({ kind: 'privilege', prop: 'tables.widgets', word: 'execute' });
+  });
+
+  test('a column word that is table-wide only (TRUNCATE) is refused', () => {
+    const refusal = declarationRefusal(
+      resolveProps({
+        ...props,
+        columnGrants: [{ table: 'widgets', column: 'id', privileges: ['truncate'] }],
+      }),
+    );
+    expect(refusal).toEqual({
+      kind: 'privilege',
+      prop: 'columnGrants.widgets.id',
+      word: 'truncate',
+    });
+  });
+
+  test('a default-privileges word must be a table word, not a schema word', () => {
+    const refusal = declarationRefusal(
+      resolveProps({ ...props, defaultPrivileges: [{ forRole: 'owner', privileges: ['usage'] }] }),
+    );
+    expect(refusal).toEqual({ kind: 'privilege', prop: 'defaultPrivileges.owner', word: 'usage' });
+  });
+
+  test('a bare "*" is never a privilege', () => {
+    const refusal = declarationRefusal(
+      resolveProps({ ...props, tables: [{ table: 'widgets', privileges: ['*'] }] }),
+    );
+    expect(refusal).toEqual({ kind: 'privilege', prop: 'tables.widgets', word: '*' });
+  });
+
+  test('a base word declared both plain and WITH GRANT OPTION is refused — the server keeps one aclitem per grantee per grantor, so the pair can never converge', () => {
+    expect(
+      declarationRefusal(
+        resolveProps({
+          ...props,
+          tables: [{ table: 'widgets', privileges: ['select', 'select*'] }],
+        }),
+      ),
+    ).toEqual({ kind: 'duplicate', prop: 'tables.widgets', name: 'select' });
+    expect(
+      declarationRefusal(
+        resolveProps({
+          ...props,
+          columnGrants: [{ table: 'widgets', column: 'id', privileges: ['update', 'update*'] }],
+        }),
+      ),
+    ).toEqual({ kind: 'duplicate', prop: 'columnGrants.widgets.id', name: 'update' });
+  });
+
+  test('the same table, column pair or forRole twice is a duplicate refusal', () => {
+    expect(
+      declarationRefusal(
+        resolveProps({
+          ...props,
+          tables: [
+            { table: 'widgets', privileges: ['select'] },
+            { table: 'widgets', privileges: ['insert'] },
+          ],
+        }),
+      ),
+    ).toEqual({ kind: 'duplicate', prop: 'tables', name: 'widgets' });
+    expect(
+      declarationRefusal(
+        resolveProps({
+          ...props,
+          columnGrants: [
+            { table: 'widgets', column: 'id', privileges: ['select'] },
+            { table: 'widgets', column: 'id', privileges: ['insert'] },
+          ],
+        }),
+      ),
+    ).toEqual({ kind: 'duplicate', prop: 'columnGrants', name: 'widgets.id' });
+    expect(
+      declarationRefusal(
+        resolveProps({
+          ...props,
+          defaultPrivileges: [
+            { forRole: 'owner', privileges: ['select'] },
+            { forRole: 'owner', privileges: ['insert'] },
+          ],
+        }),
+      ),
+    ).toEqual({ kind: 'duplicate', prop: 'defaultPrivileges', name: 'owner' });
+  });
+
+  test('grantsNamesRefusal flags the first over-long name, a 63-byte one passes', () => {
+    const refused = grantsNamesRefusal(resolveProps({ ...props, role: 'a'.repeat(64) }));
+    expect(refused).toEqual({ name: 'a'.repeat(64), byteLength: 64, limit: 63 });
+    expect(grantsNamesRefusal(resolveProps({ ...props, schema: 'a'.repeat(63) }))).toBeUndefined();
+  });
+});
+
+describe('splitGrantWords', () => {
+  test('splits by the trailing mark, order preserved', () => {
+    expect(splitGrantWords(['select', 'insert*', 'update'])).toEqual({
+      plain: ['select', 'update'],
+      grantable: ['insert*'],
+    });
+  });
+});