pipework 0.252.0 → 0.253.0

package/src/data/db/db.ts

@@ -0,0 +1,276 @@
+import type { DB, TransactionConfig } from './index.js'
+import { sql } from './sql.js'
+import { requireContext, runInContext } from '../../request/context/store.js'
+import { verifyTransactionBinding, bindTransaction } from '../../request/context/guard.js'
+import { propagateLocals } from '../../request/context/run-in-transaction.js'
+import { unboundDb } from './unbound.js'
+import { createScopedDb, createTenantGuardDb, createSystemGuardDb, createDoorDb } from '../../auth/tenant/scoped-db.js'
+
+function resolveDb(name?: string): DB {
+  const ctx = requireContext()
+  const resolvedName = name ?? ctx.instance.config.defaultDatabaseName()
+  const dbConfig = ctx.instance.config.database(resolvedName)
+
+  const bound = ctx.transactions.get(resolvedName)
+  if (bound) {
+    verifyTransactionBinding(ctx, bound, resolvedName)
+    return bound.drizzle
+  }
+
+  return unboundDb(ctx, resolvedName, dbConfig, 'pipe()')
+}
+
+/**
+ * The database handle for the active Flow: its bound transaction, scoped to the
+ * Flow's tenant (or tenant-guarded when there is none).
+ *
+ * With no bound transaction, `pipe()` uses the pooled connection. On a
+ * platform-mode database (`rls.platformRole`) that is the platform role: with no
+ * tenant in the Flow it runs as is and tenant tables return nothing (fail
+ * closed); with a tenant in the Flow it throws, naming `pipe.transaction` and the
+ * request or job transaction, because the tenant setting can only be set per
+ * transaction and a builder runs its statement unwrapped.
+ */
+export function pipe(name?: string): DB {
+  const ctx = requireContext()
+  const db = resolveDb(name)
+
+  if (ctx.tenant !== null) {
+    return createScopedDb(db, ctx.tenant)
+  }
+  return createTenantGuardDb(db)
+}
+
+/**
+ * The unwrapped database handle: no tenant filter on anything it builds. Only a
+ * carrier for statements already compiled against the scoped `pipe()` db, such
+ * as the audit-write CTE, which the scoped connection cannot `.execute()`.
+ */
+export function pipeRaw(name?: string): DB {
+  return resolveDb(name)
+}
+
+/**
+ * The system channel — deliberate cross-tenant database access for surfaces
+ * that legitimately operate without a tenant in context: pre-tenant auth
+ * (membership resolution during login), public webhook ingress, admin tooling.
+ *
+ * Unlike `pipe()`, the handle is never tenant-scoped and never tenant-guarded.
+ * Unlike `pipeRaw()`, it does not return the request's bound transaction — it
+ * resolves the owner-role pooled connection, outside the request/job
+ * transaction. The bound transaction authenticates as the runtime app role
+ * and is RLS-bound fail-closed, so an unscoped query inside it would silently
+ * return zero rows once role separation is on; the owner connection is the
+ * only honest carrier for a cross-tenant read. Queries here see committed
+ * data only and do not participate in request atomicity.
+ *
+ * Under collapsed test isolation (a pool override is registered for the
+ * database) every role shares the single rolled-back connection, and that
+ * connection is reserved by the open transaction — so the channel runs on that
+ * same connection and transaction and sees the test's uncommitted rows. Where
+ * the database has `rls`, the test template carries a permissive policy,
+ * `pipework_test_system`, that opens only while a statement sent through this
+ * handle runs, so it reads and writes every tenant's rows as the owner does.
+ * Limit: a RESTRICTIVE policy still filters in tests; BYPASSRLS would not.
+ *
+ * Where the database sets `rls.platformRole` the channel runs on that role
+ * (`systemUrl`), which bypasses nothing. The handle refuses at build time any
+ * statement over a tenant-scoped table; a platform read of one goes through a
+ * door declared in config, with `pipe.door()`.
+ */
+export function pipeSystem(name?: string): DB {
+  const db = pipeSystemRaw(name)
+  const ctx = requireContext()
+  const resolvedName = name ?? ctx.instance.config.defaultDatabaseName()
+  return ctx.instance.config.database(resolvedName).rls?.platformRole !== undefined ? createSystemGuardDb(db) : db
+}
+
+/** The system channel's connection without the platform guard: framework code that sets the tenant itself (`inTenant`) writes tenant tables on it. */
+export function pipeSystemRaw(name?: string): DB {
+  const ctx = requireContext()
+  const resolvedName = name ?? ctx.instance.config.defaultDatabaseName()
+
+  const dbConfig = ctx.instance.config.database(resolvedName)
+  const bound = ctx.transactions.get(resolvedName)
+  if (ctx.instance.pool.isOverridden(resolvedName)) {
+    const conn = ctx.instance.pool.getOrCreate(dbConfig)
+    return conn.system ?? bound?.drizzle ?? conn.drizzle
+  }
+
+  return ctx.instance.pool.getOrCreate(dbConfig).drizzle
+}
+
+/**
+ * A named cross-tenant read. The door must be declared under `doors` in config;
+ * generated migrations give the platform role (`rls.platformRole`) a SELECT
+ * policy on the door's table that opens only while `pipework.door` names it.
+ * `fn` runs in one transaction on the system connection, and the setting is
+ * set for that transaction only. The `db` it receives reads the door's table
+ * and non-tenant tables; any other tenant table, and any write to the door's
+ * table, is refused at build time. Columns are not limited: the door opens the
+ * whole table.
+ *
+ * Under collapsed test isolation the door runs on the test connection, each
+ * statement bracketed with the door open and the test-only system policy.
+ */
+export async function pipeDoor<T>(
+  name: string,
+  fn: (db: DB) => Promise<T>,
+  options?: { database?: string },
+): Promise<T> {
+  const ctx = requireContext()
+  const config = ctx.instance.config
+  const declared = config.doors[name]
+  const resolvedName = options?.database ?? declared?.database ?? config.defaultDatabaseName()
+  const dbConfig = config.database(resolvedName)
+
+  if (dbConfig.rls?.platformRole === undefined) {
+    throw new Error(
+      `[pipework] pipe.door("${name}") needs a platform role: database "${resolvedName}" has no rls.platformRole.\n\n` +
+      '  Doors replace the system channel\'s blanket RLS bypass. Fix: set `rls.platformRole` and `systemUrl`\n' +
+      `  on "${resolvedName}" (a role that is not BYPASSRLS), then declare the door under \`doors\`.\n`,
+    )
+  }
+  if (declared === undefined) {
+    const names = Object.keys(config.doors)
+    throw new Error(
+      `[pipework] pipe.door("${name}"): no door by that name is declared.\n\n` +
+      `  Declared doors: ${names.length > 0 ? names.join(', ') : '(none)'}\n` +
+      '  Fix: declare it under `doors` in pipework.config.ts with its table and reason.\n',
+    )
+  }
+  if (declared.database !== resolvedName) {
+    throw new Error(
+      `[pipework] pipe.door("${name}", ..., { database: "${resolvedName}" }): the door is declared on database "${declared.database}".\n`,
+    )
+  }
+
+  return runDoor(ctx.instance, dbConfig, declared, fn)
+}
+
+async function runDoor<T>(
+  instance: import('../../core/pipework.js').Manifold,
+  dbConfig: import('../../core/config/load.js').ResolvedDatabase,
+  door: import('../../core/config/load.js').ResolvedDoor,
+  fn: (db: DB) => Promise<T>,
+): Promise<T> {
+  if (instance.pool.isOverridden(dbConfig.name)) {
+    const conn = instance.pool.getOrCreate(dbConfig)
+    const handle = conn.door?.(door.name) ?? conn.system ?? conn.drizzle
+    return handle.transaction((tx: DB) => fn(createDoorDb(tx, door)))
+  }
+
+  const conn = instance.pool.getOrCreate(dbConfig, 'system')
+  return conn.drizzle.transaction(async (tx: DB) => {
+    await openDoor(tx, door.name)
+    return fn(createDoorDb(tx, door))
+  })
+}
+
+async function openDoor(tx: DB, name: string): Promise<void> {
+  await tx.execute(sql`SELECT set_config('pipework.door', ${name}, true)`)
+}
+
+/**
+ * A framework door as a database handle, for pipework's own long-lived loops that have no Flow (the
+ * worker's claim and reap): every statement runs in its own transaction with the door open, and
+ * `transaction()` opens it first. `db` is the platform connection. The generated policy for the
+ * door decides what the statements may touch.
+ */
+export function frameworkDoorDb(db: DB, doorName: string): DB {
+  return new Proxy(db, {
+    get(target, prop, receiver) {
+      if (prop === 'execute') {
+        return (query: Parameters<DB['execute']>[0]) => target.transaction(async (tx: DB) => {
+          await openDoor(tx, doorName)
+          return tx.execute(query)
+        })
+      }
+      if (prop === 'transaction') {
+        return (fn: (tx: DB) => Promise<unknown>, config?: Parameters<DB['transaction']>[1]) =>
+          target.transaction(async (tx: DB) => {
+            await openDoor(tx, doorName)
+            return fn(tx)
+          }, config)
+      }
+      const value = Reflect.get(target, prop, receiver) as unknown
+      return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(target) : value
+    },
+  })
+}
+
+/**
+ * Pipework's own doors (`config.frameworkDoors`), for its internal work only —
+ * deliberately not on `pipe`. Same transaction as `pipe.door`, but the door may
+ * also delete where it was declared to. Throws by name where the database is not
+ * in platform mode or the door is not declared (its substrate is not configured).
+ */
+export async function pipeFrameworkDoor<T>(name: string, fn: (db: DB) => Promise<T>, database?: string): Promise<T> {
+  const ctx = requireContext()
+  const door = ctx.instance.config.frameworkDoors[name]
+  if (door === undefined) {
+    throw new Error(
+      `[pipework] The framework door "${name}" is not declared: it exists only where the default database sets rls.platformRole and the blueprint enables its substrate.`,
+    )
+  }
+  return runDoor(ctx.instance, ctx.instance.config.database(database ?? door.database), door, fn)
+}
+
+
+pipe.transaction = async function transaction<T>(
+  nameOrFn: string | ((tx: DB) => Promise<T>),
+  maybeFnOrConfig?: ((tx: DB) => Promise<T>) | TransactionConfig,
+  maybeConfig?: TransactionConfig,
+): Promise<T> {
+  const ctx = requireContext()
+
+  let resolvedName: string
+  let fn: (tx: DB) => Promise<T>
+  let config: TransactionConfig | undefined
+
+  if (typeof nameOrFn === 'function') {
+    resolvedName = ctx.instance.config.defaultDatabaseName()
+    fn = nameOrFn
+    config = maybeFnOrConfig as TransactionConfig | undefined
+  } else {
+    resolvedName = nameOrFn
+    fn = maybeFnOrConfig as (tx: DB) => Promise<T>
+    config = maybeConfig
+  }
+
+  const existingBound = ctx.transactions.get(resolvedName)
+  if (existingBound) {
+    verifyTransactionBinding(ctx, existingBound, resolvedName)
+    // Nested transactions use savepoints. Postgres does not support SET TRANSACTION
+    // ISOLATION LEVEL inside a savepoint — the savepoint inherits from the outer
+    // transaction. Drizzle's PgTransaction.transaction() does not accept config.
+    return existingBound.drizzle.transaction(async (nestedTx) => {
+      const childCtx = {
+        ...ctx,
+        transactions: new Map(ctx.transactions),
+      }
+      childCtx.transactions.set(resolvedName, bindTransaction(ctx, resolvedName, nestedTx))
+      return runInContext(childCtx, () => fn(nestedTx))
+    })
+  }
+
+  const dbConfig = ctx.instance.config.database(resolvedName)
+  // The app role and the context's locals, both for the same reason: this
+  // transaction is a NEW connection, so nothing the entry already set on its
+  // own connection reaches it. Without the locals `pipework.tenant_id` is
+  // unset and every policy under FORCE RLS reads zero rows; without the app
+  // role the statements run as the owner, where policies are inert. Both are
+  // what `executeInTransaction` does for the entry's own transaction — this is
+  // the same transaction, opened later.
+  const conn = ctx.instance.pool.getOrCreate(dbConfig, 'app')
+
+  return conn.drizzle.transaction(async (tx) => {
+    const childCtx = {
+      ...ctx,
+      transactions: new Map(ctx.transactions),
+    }
+    childCtx.transactions.set(resolvedName, bindTransaction(ctx, resolvedName, tx))
+    await propagateLocals(tx, ctx, ctx.tenantConfig)
+    return runInContext(childCtx, () => fn(tx))
+  }, config)
+}

package/src/data/db/excluded.ts

@@ -0,0 +1,16 @@
+import { sql } from '../query/index.js'
+import { getTableColumns } from '../query/index.js'
+import type { SQL, Table } from './types.js'
+
+type ExcludedColumns<T extends Table> = {
+  [K in keyof T['_']['columns']]: SQL
+}
+
+export function excluded<T extends Table>(table: T): ExcludedColumns<T> {
+  const columns = getTableColumns(table)
+  const result: Record<string, SQL> = {}
+  for (const [key, col] of Object.entries(columns)) {
+    result[key] = sql.raw(`excluded."${col.name}"`)
+  }
+  return result as ExcludedColumns<T>
+}