pipework 0.251.0 → 0.252.1

package/src/data/migrate/diff.ts

@@ -0,0 +1,357 @@
+import type {
+  PwSnapshot,
+  PwTableSnapshot,
+  PwColumnSnapshot,
+  PwIndexSnapshot,
+  PwForeignKeySnapshot,
+  PwCheckSnapshot,
+  PwUniqueSnapshot,
+  PwCompositePKSnapshot,
+} from './snapshot.js'
+
+export type DiffOp =
+  | { type: 'create_table'; table: PwTableSnapshot }
+  | { type: 'drop_table'; table: PwTableSnapshot }
+  | { type: 'add_column'; tableName: string; tableSchema: string; column: PwColumnSnapshot }
+  | { type: 'drop_column'; tableName: string; tableSchema: string; column: PwColumnSnapshot }
+  | { type: 'alter_column_type'; tableName: string; tableSchema: string; column: string; from: string; to: string; collation?: string | undefined }
+  | { type: 'alter_column_set_not_null'; tableName: string; tableSchema: string; column: string }
+  | { type: 'alter_column_drop_not_null'; tableName: string; tableSchema: string; column: string }
+  | { type: 'alter_column_set_default'; tableName: string; tableSchema: string; column: string; value: string }
+  | { type: 'alter_column_drop_default'; tableName: string; tableSchema: string; column: string }
+  | { type: 'alter_column_set_generated'; tableName: string; tableSchema: string; column: PwColumnSnapshot }
+  | { type: 'alter_column_drop_generated'; tableName: string; tableSchema: string; column: string }
+  | { type: 'alter_column_set_identity'; tableName: string; tableSchema: string; column: PwColumnSnapshot }
+  | { type: 'alter_column_drop_identity'; tableName: string; tableSchema: string; column: string }
+  | { type: 'create_index'; tableName: string; tableSchema: string; index: PwIndexSnapshot }
+  | { type: 'drop_index'; tableName: string; tableSchema: string; index: PwIndexSnapshot }
+  | { type: 'replace_index'; tableName: string; tableSchema: string; from: PwIndexSnapshot; to: PwIndexSnapshot }
+  | { type: 'add_foreign_key'; tableName: string; tableSchema: string; fk: PwForeignKeySnapshot; tablePartitioned: boolean }
+  | { type: 'drop_foreign_key'; tableName: string; tableSchema: string; fk: PwForeignKeySnapshot }
+  | { type: 'add_check'; tableName: string; tableSchema: string; check: PwCheckSnapshot }
+  | { type: 'drop_check'; tableName: string; tableSchema: string; check: PwCheckSnapshot }
+  | { type: 'add_unique'; tableName: string; tableSchema: string; unique: PwUniqueSnapshot; tablePartitioned: boolean }
+  | { type: 'replace_unique'; tableName: string; tableSchema: string; from: PwUniqueSnapshot; to: PwUniqueSnapshot; tablePartitioned: boolean }
+  | { type: 'drop_unique'; tableName: string; tableSchema: string; unique: PwUniqueSnapshot }
+  | { type: 'add_composite_pk'; tableName: string; tableSchema: string; pk: PwCompositePKSnapshot; tablePartitioned: boolean }
+  | { type: 'replace_composite_pk'; tableName: string; tableSchema: string; from: PwCompositePKSnapshot; to: PwCompositePKSnapshot; tablePartitioned: boolean }
+  | { type: 'drop_composite_pk'; tableName: string; tableSchema: string; pk: PwCompositePKSnapshot }
+
+/** The wire name of the table an op acts on, across all `DiffOp` shapes. */
+export function diffOpTableName(op: DiffOp): string {
+  return op.type === 'create_table' || op.type === 'drop_table' ? op.table.name : op.tableName
+}
+
+export function diffSnapshots(prev: PwSnapshot, cur: PwSnapshot): DiffOp[] {
+  const ops: DiffOp[] = []
+
+  const prevKeys = new Set(Object.keys(prev.tables))
+  const curKeys = new Set(Object.keys(cur.tables))
+
+  // Phase 0: A table's partitioning is fixed at creation — Postgres has no
+  // ALTER TABLE ... PARTITION BY. A changed strategy is a manual migration.
+  for (const key of prevKeys) {
+    if (!curKeys.has(key)) continue
+    assertPartitioningUnchanged(prev.tables[key]!, cur.tables[key]!)
+  }
+
+  // Phase 1: Drop constraints and indexes from tables that will be modified or dropped
+  for (const key of prevKeys) {
+    if (!curKeys.has(key)) continue
+    const prevTable = prev.tables[key]!
+    const curTable = cur.tables[key]!
+    diffDropConstraints(prevTable, curTable, ops)
+  }
+
+  // Phase 2: Drop tables
+  for (const key of prevKeys) {
+    if (!curKeys.has(key)) {
+      ops.push({ type: 'drop_table', table: prev.tables[key]! })
+    }
+  }
+
+  // Phase 3: Create tables
+  for (const key of curKeys) {
+    if (!prevKeys.has(key)) {
+      ops.push({ type: 'create_table', table: cur.tables[key]! })
+    }
+  }
+
+  // Phase 4: Alter columns on shared tables
+  for (const key of prevKeys) {
+    if (!curKeys.has(key)) continue
+    const prevTable = prev.tables[key]!
+    const curTable = cur.tables[key]!
+    diffColumns(prevTable, curTable, ops)
+  }
+
+  // Phase 5: Add constraints and indexes to modified or new tables
+  for (const key of prevKeys) {
+    if (!curKeys.has(key)) continue
+    const prevTable = prev.tables[key]!
+    const curTable = cur.tables[key]!
+    diffAddConstraints(prevTable, curTable, ops)
+  }
+
+  return ops
+}
+
+function diffDropConstraints(prev: PwTableSnapshot, cur: PwTableSnapshot, ops: DiffOp[]): void {
+  const tn = prev.name
+  const ts = prev.schema
+
+  for (const name of Object.keys(prev.foreignKeys)) {
+    const prevFk = prev.foreignKeys[name]!
+    const curFk = cur.foreignKeys[name]
+    if (curFk === undefined || !fkEqual(prevFk, curFk)) {
+      ops.push({ type: 'drop_foreign_key', tableName: tn, tableSchema: ts, fk: prevFk })
+    }
+  }
+
+  for (const name of Object.keys(prev.indexes)) {
+    const prevIdx = prev.indexes[name]!
+    const curIdx = cur.indexes[name]
+    if (curIdx === undefined) {
+      ops.push({ type: 'drop_index', tableName: tn, tableSchema: ts, index: prevIdx })
+    }
+  }
+
+  for (const name of Object.keys(prev.checks)) {
+    const prevChk = prev.checks[name]!
+    const curChk = cur.checks[name]
+    if (curChk === undefined || prevChk.value !== curChk.value) {
+      ops.push({ type: 'drop_check', tableName: tn, tableSchema: ts, check: prevChk })
+    }
+  }
+
+  for (const name of Object.keys(prev.uniqueConstraints)) {
+    const prevUc = prev.uniqueConstraints[name]!
+    const curUc = cur.uniqueConstraints[name]
+    if (curUc === undefined || (!uniqueEqual(prevUc, curUc) && !canSwapOnline(prev, cur, prevUc.columns))) {
+      ops.push({ type: 'drop_unique', tableName: tn, tableSchema: ts, unique: prevUc })
+    }
+  }
+
+  for (const name of Object.keys(prev.compositePrimaryKeys)) {
+    const prevPk = prev.compositePrimaryKeys[name]!
+    const curPk = cur.compositePrimaryKeys[name]
+    if (curPk === undefined || (!arraysEqual(prevPk.columns, curPk.columns) && !canSwapOnline(prev, cur, prevPk.columns))) {
+      ops.push({ type: 'drop_composite_pk', tableName: tn, tableSchema: ts, pk: prevPk })
+    }
+  }
+}
+
+function diffColumns(prev: PwTableSnapshot, cur: PwTableSnapshot, ops: DiffOp[]): void {
+  const tn = prev.name
+  const ts = prev.schema
+
+  const prevCols = new Set(Object.keys(prev.columns))
+  const curCols = new Set(Object.keys(cur.columns))
+
+  for (const name of prevCols) {
+    if (!curCols.has(name)) {
+      ops.push({ type: 'drop_column', tableName: tn, tableSchema: ts, column: prev.columns[name]! })
+    }
+  }
+
+  for (const name of curCols) {
+    if (!prevCols.has(name)) {
+      ops.push({ type: 'add_column', tableName: tn, tableSchema: ts, column: cur.columns[name]! })
+    }
+  }
+
+  for (const name of prevCols) {
+    if (!curCols.has(name)) continue
+    const prevCol = prev.columns[name]!
+    const curCol = cur.columns[name]!
+
+    if (prevCol.type !== curCol.type || prevCol.collation !== curCol.collation) {
+      ops.push({ type: 'alter_column_type', tableName: tn, tableSchema: ts, column: name, from: prevCol.type, to: curCol.type, collation: curCol.collation ?? (prevCol.collation !== undefined ? '"default"' : undefined) })
+    }
+
+    if (!prevCol.notNull && curCol.notNull) {
+      ops.push({ type: 'alter_column_set_not_null', tableName: tn, tableSchema: ts, column: name })
+    }
+    if (prevCol.notNull && !curCol.notNull) {
+      ops.push({ type: 'alter_column_drop_not_null', tableName: tn, tableSchema: ts, column: name })
+    }
+
+    if (prevCol.default !== curCol.default) {
+      if (curCol.default !== undefined) {
+        ops.push({ type: 'alter_column_set_default', tableName: tn, tableSchema: ts, column: name, value: curCol.default })
+      } else {
+        ops.push({ type: 'alter_column_drop_default', tableName: tn, tableSchema: ts, column: name })
+      }
+    }
+
+    if (prevCol.generated === undefined && curCol.generated !== undefined) {
+      ops.push({ type: 'alter_column_set_generated', tableName: tn, tableSchema: ts, column: curCol })
+    }
+    if (prevCol.generated !== undefined && curCol.generated === undefined) {
+      ops.push({ type: 'alter_column_drop_generated', tableName: tn, tableSchema: ts, column: name })
+    }
+    if (prevCol.generated !== undefined && curCol.generated !== undefined && prevCol.generated.as !== curCol.generated.as) {
+      ops.push({ type: 'alter_column_drop_generated', tableName: tn, tableSchema: ts, column: name })
+      ops.push({ type: 'alter_column_set_generated', tableName: tn, tableSchema: ts, column: curCol })
+    }
+
+    if (prevCol.identity === undefined && curCol.identity !== undefined) {
+      ops.push({ type: 'alter_column_set_identity', tableName: tn, tableSchema: ts, column: curCol })
+    }
+    if (prevCol.identity !== undefined && curCol.identity === undefined) {
+      ops.push({ type: 'alter_column_drop_identity', tableName: tn, tableSchema: ts, column: name })
+    }
+    if (prevCol.identity !== undefined && curCol.identity !== undefined && prevCol.identity.type !== curCol.identity.type) {
+      ops.push({ type: 'alter_column_drop_identity', tableName: tn, tableSchema: ts, column: name })
+      ops.push({ type: 'alter_column_set_identity', tableName: tn, tableSchema: ts, column: curCol })
+    }
+  }
+}
+
+function diffAddConstraints(prev: PwTableSnapshot, cur: PwTableSnapshot, ops: DiffOp[]): void {
+  const tn = cur.name
+  const ts = cur.schema
+  const partitioned = cur.partitionBy !== undefined
+
+  for (const name of Object.keys(cur.compositePrimaryKeys)) {
+    const prevPk = prev.compositePrimaryKeys[name]
+    const curPk = cur.compositePrimaryKeys[name]!
+    if (prevPk === undefined || !arraysEqual(prevPk.columns, curPk.columns)) {
+      if (prevPk !== undefined && canSwapOnline(prev, cur, prevPk.columns)) {
+        ops.push({ type: 'replace_composite_pk', tableName: tn, tableSchema: ts, from: prevPk, to: curPk, tablePartitioned: partitioned })
+      } else {
+        assertNoIndexNamed(cur, name, 'primary key')
+        ops.push({ type: 'add_composite_pk', tableName: tn, tableSchema: ts, pk: curPk, tablePartitioned: partitioned })
+      }
+    }
+  }
+
+  for (const name of Object.keys(cur.uniqueConstraints)) {
+    const prevUc = prev.uniqueConstraints[name]
+    const curUc = cur.uniqueConstraints[name]!
+    if (prevUc === undefined || !uniqueEqual(prevUc, curUc)) {
+      if (prevUc !== undefined && canSwapOnline(prev, cur, prevUc.columns)) {
+        ops.push({ type: 'replace_unique', tableName: tn, tableSchema: ts, from: prevUc, to: curUc, tablePartitioned: partitioned })
+      } else {
+        assertNoIndexNamed(cur, name, 'unique constraint')
+        ops.push({ type: 'add_unique', tableName: tn, tableSchema: ts, unique: curUc, tablePartitioned: partitioned })
+      }
+    }
+  }
+
+  for (const name of Object.keys(cur.checks)) {
+    const prevChk = prev.checks[name]
+    const curChk = cur.checks[name]!
+    if (prevChk === undefined || prevChk.value !== curChk.value) {
+      ops.push({ type: 'add_check', tableName: tn, tableSchema: ts, check: curChk })
+    }
+  }
+
+  for (const name of Object.keys(cur.indexes)) {
+    const prevIdx = prev.indexes[name]
+    const curIdx = cur.indexes[name]!
+    if (prevIdx === undefined) {
+      ops.push({ type: 'create_index', tableName: tn, tableSchema: ts, index: curIdx })
+    } else if (!indexEqual(prevIdx, curIdx)) {
+      ops.push({ type: 'replace_index', tableName: tn, tableSchema: ts, from: prevIdx, to: curIdx })
+    }
+  }
+
+  for (const name of Object.keys(cur.foreignKeys)) {
+    const prevFk = prev.foreignKeys[name]
+    const curFk = cur.foreignKeys[name]!
+    if (prevFk === undefined || !fkEqual(prevFk, curFk)) {
+      ops.push({ type: 'add_foreign_key', tableName: tn, tableSchema: ts, fk: curFk, tablePartitioned: cur.partitionBy !== undefined })
+    }
+  }
+}
+
+/**
+ * A changed key constraint is swapped in one statement (new index built
+ * beside it first) only while the old key's columns survive the migration
+ * unchanged; otherwise the old constraint is dropped up front, as before.
+ */
+function canSwapOnline(prev: PwTableSnapshot, cur: PwTableSnapshot, oldColumns: string[]): boolean {
+  return oldColumns.every(c => {
+    const p = prev.columns[c]
+    const n = cur.columns[c]
+    return p !== undefined && n !== undefined && p.type === n.type && p.collation === n.collation
+  })
+}
+
+/**
+ * An added key constraint builds its index under the constraint's name after
+ * clearing any leftover of that name, so a declared index may not share it.
+ */
+function assertNoIndexNamed(cur: PwTableSnapshot, name: string, what: string): void {
+  if (cur.indexes[name] === undefined) return
+  throw new Error(
+    `[pipework] The ${what} "${name}" on "${cur.name}" has the same name as an index on that table. ` +
+    'Give one of them another name.',
+  )
+}
+
+function fkEqual(a: PwForeignKeySnapshot, b: PwForeignKeySnapshot): boolean {
+  return a.foreignTable === b.foreignTable
+    && a.foreignSchema === b.foreignSchema
+    && a.onUpdate === b.onUpdate
+    && a.onDelete === b.onDelete
+    && (a.onDeleteColumns === undefined || b.onDeleteColumns === undefined
+      ? a.onDeleteColumns === b.onDeleteColumns
+      : arraysEqual(a.onDeleteColumns, b.onDeleteColumns))
+    && arraysEqual(a.columns, b.columns)
+    && arraysEqual(a.foreignColumns, b.foreignColumns)
+}
+
+function withEqual(a: Record<string, unknown> | undefined, b: Record<string, unknown> | undefined): boolean {
+  const ae = Object.entries(a ?? {}).sort(([x], [y]) => x.localeCompare(y))
+  const be = Object.entries(b ?? {}).sort(([x], [y]) => x.localeCompare(y))
+  return ae.length === be.length && ae.every(([k, v], i) => be[i]![0] === k && be[i]![1] === v)
+}
+
+function indexEqual(a: PwIndexSnapshot, b: PwIndexSnapshot): boolean {
+  if (a.unique !== b.unique || a.method !== b.method || a.where !== b.where) return false
+  if ((a.nullsNotDistinct ?? false) !== (b.nullsNotDistinct ?? false)) return false
+  if (!withEqual(a.with, b.with)) return false
+  const ai = a.include ?? []
+  const bi = b.include ?? []
+  if (ai.length !== bi.length || ai.some((c, i) => c !== bi[i])) return false
+  if (a.columns.length !== b.columns.length) return false
+  for (let i = 0; i < a.columns.length; i++) {
+    const ac = a.columns[i]!
+    const bc = b.columns[i]!
+    if (ac.expression !== bc.expression || ac.isExpression !== bc.isExpression
+      || ac.order !== bc.order || ac.nulls !== bc.nulls || ac.opClass !== bc.opClass || ac.collation !== bc.collation) {
+      return false
+    }
+  }
+  return true
+}
+
+function uniqueEqual(a: PwUniqueSnapshot, b: PwUniqueSnapshot): boolean {
+  return a.nullsNotDistinct === b.nullsNotDistinct && arraysEqual(a.columns, b.columns)
+}
+
+function assertPartitioningUnchanged(prev: PwTableSnapshot, cur: PwTableSnapshot): void {
+  const p = prev.partitionBy
+  const c = cur.partitionBy
+  if (p === undefined && c === undefined) return
+  if (p !== undefined && c !== undefined && p.column === c.column) return
+
+  const describe = (s: typeof p): string =>
+    s === undefined ? 'not partitioned' : `${s.strategy} (${s.column})`
+
+  throw new Error(
+    `[pipework] Cannot change the partitioning of "${cur.name}" — ${describe(p)} → ${describe(c)}.\n\n` +
+    '  Postgres has no ALTER TABLE ... PARTITION BY; partitioning is fixed at table creation.\n' +
+    '  Changing it requires a manual migration that recreates the table and moves its rows.\n',
+  )
+}
+
+function arraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}

package/src/data/migrate/door-generate.ts

@@ -0,0 +1,130 @@
+import type { DefinedTable } from '../domain/types.js'
+import type { ResolvedDoor } from '../../core/config/load.js'
+import { ConfigError } from '../../core/config/errors.js'
+import { quoteIdentifier } from '../db/identifiers.js'
+
+/** The setting a door's policy reads; `pipe.door()` sets it for one transaction. */
+export const DOOR_SETTING = 'pipework.door'
+
+/** What a snapshot remembers of a door, so the next generate can tell an added, removed or moved one. */
+export interface DoorSnapshot {
+  readonly table: string
+  readonly role: string
+  /** Present only for a door that also writes (pipework's own); an app door is SELECT-only. */
+  readonly ops?: readonly DoorOp[]
+}
+
+export type DoorOp = 'select' | 'update' | 'delete'
+
+/** The operations a door opens beyond SELECT, which every door has. */
+const writes = (snapshot: DoorSnapshot): DoorOp[] =>
+  (['update', 'delete'] as const).filter(op => snapshot.ops?.includes(op) === true)
+const sameDoor = (a: DoorSnapshot, b: DoorSnapshot): boolean =>
+  a.table === b.table && a.role === b.role && writes(a).join() === writes(b).join()
+
+export function doorOpPolicyName(door: string, op: 'update' | 'delete'): string {
+  return `${doorPolicyName(door)}__${op}`
+}
+
+export function doorDeletePolicyName(door: string): string {
+  return doorOpPolicyName(door, 'delete')
+}
+
+export function doorPolicyName(door: string): string {
+  return `pipework_door_${door.replace(/\./g, '__')}`
+}
+
+function sqlString(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`
+}
+
+export function createDoorPolicy(door: string, snapshot: DoorSnapshot): string {
+  return `CREATE POLICY ${quoteIdentifier(doorPolicyName(door), 'policy')} ON ${quoteIdentifier(snapshot.table, 'table')} ` +
+    `AS PERMISSIVE FOR SELECT TO ${quoteIdentifier(snapshot.role, 'role')} ` +
+    `USING (current_setting('${DOOR_SETTING}', true) = ${sqlString(door)})`
+}
+
+export function createDoorOpPolicy(door: string, snapshot: DoorSnapshot, op: 'update' | 'delete'): string {
+  return `CREATE POLICY ${quoteIdentifier(doorOpPolicyName(door, op), 'policy')} ON ${quoteIdentifier(snapshot.table, 'table')} ` +
+    `AS PERMISSIVE FOR ${op.toUpperCase()} TO ${quoteIdentifier(snapshot.role, 'role')} ` +
+    `USING (current_setting('${DOOR_SETTING}', true) = ${sqlString(door)})`
+}
+
+export function createDoorDeletePolicy(door: string, snapshot: DoorSnapshot): string {
+  return createDoorOpPolicy(door, snapshot, 'delete')
+}
+
+export function dropDoorOpPolicy(door: string, snapshot: DoorSnapshot, op: 'update' | 'delete'): string {
+  return `DROP POLICY IF EXISTS ${quoteIdentifier(doorOpPolicyName(door, op), 'policy')} ON ${quoteIdentifier(snapshot.table, 'table')}`
+}
+
+export function dropDoorDeletePolicy(door: string, snapshot: DoorSnapshot): string {
+  return dropDoorOpPolicy(door, snapshot, 'delete')
+}
+
+export function dropDoorPolicy(door: string, snapshot: DoorSnapshot): string {
+  return `DROP POLICY IF EXISTS ${quoteIdentifier(doorPolicyName(door), 'policy')} ON ${quoteIdentifier(snapshot.table, 'table')}`
+}
+
+/**
+ * The doors a database's migrations must carry: its declared doors when it is
+ * in platform mode, none otherwise. Each door's table must be tenant-scoped in
+ * a definition — any other table needs no door, and the platform role reads it
+ * on its ordinary grants.
+ */
+export function doorSnapshots(
+  doors: readonly ResolvedDoor[],
+  platformRole: string | undefined,
+  definitions: ReadonlyMap<string, DefinedTable>,
+): Record<string, DoorSnapshot> {
+  if (platformRole === undefined) return {}
+  const out: Record<string, DoorSnapshot> = {}
+  for (const door of doors) {
+    if (door.framework === true) {
+      const ops = door.ops?.filter(op => op !== 'select') ?? []
+      out[door.name] = { table: door.table, role: platformRole, ...(ops.length > 0 ? { ops: ['select', ...ops] as const } : {}) }
+      continue
+    }
+    const definition = definitions.get(door.table)
+    const tenanted = definition !== undefined
+      && Object.values(definition.$fields).some(field => field._meta.tenant === true)
+    if (!tenanted) {
+      throw new ConfigError(
+        `Door "${door.name}" names table "${door.table}", which is not tenant-scoped in any definition.`,
+        definition === undefined
+          ? `No definition produces a table named "${door.table}". Door tables are SQL names of tables defined with a .tenant() field.`
+          : `"${door.table}" has no .tenant() field, so row-level security does not hide it from the platform role and it needs no door. Remove the door.`,
+      )
+    }
+    out[door.name] = { table: door.table, role: platformRole }
+  }
+  return out
+}
+
+/** Statements that move a database from the doors `prev` recorded to the doors `cur` declares. A door whose table, role or operations changed is dropped from the old table and created on the new. */
+export function diffDoors(
+  prev: Readonly<Record<string, DoorSnapshot>> | undefined,
+  cur: Readonly<Record<string, DoorSnapshot>>,
+): string[] {
+  const before = prev ?? {}
+  const statements: string[] = []
+  for (const [name, old] of Object.entries(before)) {
+    const now = cur[name]
+    if (now !== undefined && sameDoor(old, now)) continue
+    statements.push(dropDoorPolicy(name, old))
+    for (const op of writes(old) as Array<'update' | 'delete'>) statements.push(dropDoorOpPolicy(name, old, op))
+  }
+  for (const [name, now] of Object.entries(cur)) {
+    const old = before[name]
+    if (old !== undefined && sameDoor(old, now)) continue
+    statements.push(createDoorPolicy(name, now))
+    for (const op of writes(now) as Array<'update' | 'delete'>) statements.push(createDoorOpPolicy(name, now, op))
+  }
+  return statements
+}
+
+/** The name prefix reserved for doors pipework declares itself. */
+export const FRAMEWORK_DOOR_PREFIX = 'pipework.'
+
+/** The storage sweep's door: it reads and deletes `storage_file` across tenants. */
+export const STORAGE_SWEEP_DOOR = 'pipework.storage_sweep'

package/src/data/migrate/framework-rls.ts

@@ -0,0 +1,58 @@
+// Row-level security for the built-in tenant tables. They are provisioned by
+// `provisionFrameworkTables`, not through generated migrations, so
+// `rls-generate` never sees them. When the default database configures `rls`,
+// each gets the same tenant rule as an application table, split by command:
+//
+//   pipework_tenant_read    SELECT  tenant matches the session setting, or a maintenance transaction
+//   pipework_tenant_update  UPDATE  same
+//   pipework_tenant_insert  INSERT  anything: the framework writes traces and audit rows
+//                                   for any tenant, and for none, from connections that
+//                                   carry no tenant setting
+//
+// No DELETE policy except on audit_record: retention drops partitions, and audit_record is
+// append-only. Its one DELETE policy admits a maintenance pass that has named the tenant being
+// erased (`audit.removeTenant`), and only that tenant's rows.
+
+import { sql } from '../db/sql.js'
+import type { DB } from '../db/index.js'
+import { quoteIdentifier } from '../db/identifiers.js'
+import { tenantUsingClause } from '../../auth/tenant/rls.js'
+import { validateSessionVarName } from '../../auth/tenant/validate.js'
+import { MAINTENANCE_CLAUSE } from '../db/maintenance.js'
+import { AUDIT_ERASE_SETTING } from '../../audit/chain/install.js'
+
+export const AUDIT_ERASE_POLICY = 'pipework_audit_erase'
+
+export const FRAMEWORK_POLICY_NAMES = ['pipework_tenant_read', 'pipework_tenant_update', 'pipework_tenant_insert'] as const
+
+export interface FrameworkRls {
+  readonly sessionVar: string
+  readonly force: boolean
+}
+
+/** Statements that (re)install the policies on `table`. Safe to run again. */
+export function frameworkTablePolicies(table: string, rls: FrameworkRls): string[] {
+  validateSessionVarName(rls.sessionVar)
+  const t = quoteIdentifier(table, 'table')
+  const visible = `(${tenantUsingClause('tenant_id', 'uuid', rls.sessionVar)} OR ${MAINTENANCE_CLAUSE})`
+  const policy = (name: string) => quoteIdentifier(name, 'policy')
+  return [
+    `ALTER TABLE ${t} ENABLE ROW LEVEL SECURITY`,
+    `ALTER TABLE ${t} ${rls.force ? 'FORCE' : 'NO FORCE'} ROW LEVEL SECURITY`,
+    ...FRAMEWORK_POLICY_NAMES.map(name => `DROP POLICY IF EXISTS ${policy(name)} ON ${t}`),
+    `CREATE POLICY ${policy('pipework_tenant_read')} ON ${t} FOR SELECT USING ${visible}`,
+    `CREATE POLICY ${policy('pipework_tenant_update')} ON ${t} FOR UPDATE USING ${visible}`,
+    `CREATE POLICY ${policy('pipework_tenant_insert')} ON ${t} FOR INSERT WITH CHECK (true)`,
+    `DROP POLICY IF EXISTS ${policy(AUDIT_ERASE_POLICY)} ON ${t}`,
+    ...(table === 'audit_record'
+      ? [`CREATE POLICY ${policy(AUDIT_ERASE_POLICY)} ON ${t} FOR DELETE USING ` +
+         `(${MAINTENANCE_CLAUSE} AND tenant_id::text = current_setting('${AUDIT_ERASE_SETTING}', true))`]
+      : []),
+  ]
+}
+
+export async function installFrameworkPolicies(db: DB, tables: readonly string[], rls: FrameworkRls): Promise<void> {
+  for (const table of tables) {
+    for (const statement of frameworkTablePolicies(table, rls)) await db.execute(sql.raw(statement))
+  }
+}