pipework 0.252.0 → 0.253.0

package/src/auth/tenant/extract.ts

@@ -0,0 +1,33 @@
+import type { TenantConfig } from './types.js'
+import { validateTenantId } from './validate.js'
+import { UnauthorizedError } from '../../core/errors/index.js'
+
+export interface TenantExtractionResult {
+  readonly tenant: string | null
+}
+
+export function extractTenant(
+  auth: unknown,
+  config: TenantConfig,
+): TenantExtractionResult {
+  const raw = config.extract(auth)
+
+  if (raw === null || raw === '') {
+    if (config.required !== false) {
+      throw new UnauthorizedError(
+        'Tenant context required but not present. Ensure auth strategy returns a tenantId.',
+      )
+    }
+    return { tenant: null }
+  }
+
+  const validator = config.validate ?? validateTenantId
+  if (!validator(raw)) {
+    throw new UnauthorizedError(
+      `Invalid tenant identifier: "${raw.slice(0, 40)}${raw.length > 40 ? '...' : ''}". ` +
+      `Tenant IDs must be valid UUIDs (or pass your custom validate function).`,
+    )
+  }
+
+  return { tenant: raw }
+}

package/src/auth/tenant/in-tenant.ts

@@ -0,0 +1,49 @@
+import { sql } from '../../data/db/sql.js'
+import { pipeSystemRaw } from '../../data/db/db.js'
+import type { DB } from '../../data/db/index.js'
+import type { Flow } from '../../request/context/types.js'
+import type { Manifold } from '../../core/pipework.js'
+
+/** Inside `tx`, sets the tenant session variable for the transaction, runs `fn`, and puts the previous value back (under a collapsed test transaction this is a savepoint, so the setting would otherwise outlive it). */
+async function withSessionVar<T>(tx: DB, sessionVar: string, tenantId: string, fn: (tx: DB) => Promise<T>): Promise<T> {
+  const before = await tx.execute(sql`SELECT current_setting(${sessionVar}, true) AS v`)
+  await tx.execute(sql`SELECT set_config(${sessionVar}, ${tenantId}, true)`)
+  const result = await fn(tx)
+  await tx.execute(sql`SELECT set_config(${sessionVar}, ${(before[0]?.['v'] as string | null) ?? ''}, true)`)
+  return result
+}
+
+/**
+ * Runs `fn` in a transaction on the system connection with the tenant session
+ * variable set for that transaction only — the same `set_config(..., true)` the
+ * request path uses, so the tenant policies apply as they do for any tenant
+ * write. For callers with no tenant in the Flow (public routes, webhooks) that
+ * have been told which tenant to act for.
+ */
+export async function inTenant<T>(flow: Flow, tenantId: string, fn: (tx: DB) => Promise<T>): Promise<T> {
+  const dbName = flow.instance.config.defaultDatabaseName()
+  const sessionVar = flow.instance.config.database(dbName).rls?.sessionVar ?? 'pipework.tenant_id'
+  return pipeSystemRaw(dbName).transaction((tx: DB) => withSessionVar(tx, sessionVar, tenantId, fn))
+}
+
+/**
+ * For framework code that reads tenant tables from outside a bound transaction
+ * (cache loaders, RBAC resolution). Where the database is not in platform mode
+ * it hands `fn` the pooled connection, as before. In platform mode the pooled
+ * connection is the platform role, which sees no tenant row until the session
+ * variable is set, so `fn` runs in a short transaction with it set to `tenant`.
+ * With no tenant (`null`) `fn` runs on the platform connection as is, and
+ * tenant tables return nothing: fail closed.
+ */
+export async function withTenantSetting<T>(
+  instance: Manifold,
+  dbName: string,
+  tenant: string | null,
+  fn: (db: DB) => Promise<T>,
+): Promise<T> {
+  const dbConfig = instance.config.database(dbName)
+  const db = instance.pool.getOrCreate(dbConfig).drizzle
+  if (dbConfig.rls?.platformRole === undefined || tenant === null) return fn(db)
+  const sessionVar = dbConfig.rls.sessionVar
+  return db.transaction((tx: DB) => withSessionVar(tx, sessionVar, tenant, fn))
+}

package/src/auth/tenant/index.ts

@@ -0,0 +1,7 @@
+export type { TenantConfig, TenantContext } from './types.js'
+export { validateTenantId, validateSessionVarName, validateSessionVarValue } from './validate.js'
+export { propagateTenantLocals } from './propagate.js'
+export { extractTenant, type TenantExtractionResult } from './extract.js'
+export { tenantIsolationPolicy, enableTenantRls, verifyPrincipalContext } from './rls.js'
+export { scopeTable, getScopeConfig, isTenantScoped, type ScopeConfig } from './scope.js'
+export { createScopedDb, createTenantGuardDb } from './scoped-db.js'

package/src/auth/tenant/namespace.ts

@@ -0,0 +1,23 @@
+import { validateTenantId } from './validate.js'
+import { enableTenantRls, tenantIsolationPolicy, verifyPrincipalContext } from './rls.js'
+import { propagateTenantLocals } from './propagate.js'
+import { extractTenant } from './extract.js'
+import { isTenantScoped } from './scope.js'
+
+/** Multi-tenant isolation namespace — RLS policies, tenant extraction, Postgres-side verification. */
+export const tenant = {
+  /** Validates a tenant ID format (non-empty string, safe characters). */
+  validate: validateTenantId,
+  /** Enables RLS on a table and creates the tenant isolation policy in Postgres. */
+  rls: enableTenantRls,
+  /** Returns the SQL string for a tenant isolation RLS policy — use in migrations. */
+  policy: tenantIsolationPolicy,
+  /** Cross-checks the ALS principal (tenant, user, asOf) against the Postgres session GUCs — defense-in-depth. */
+  verify: verifyPrincipalContext,
+  /** Sets pipework.tenant_id on the Postgres connection via set_config(). */
+  propagate: propagateTenantLocals,
+  /** Extracts tenant ID from auth context using the configured extraction strategy. */
+  extract: extractTenant,
+  /** Returns true if a table has been marked as tenant-scoped (via .tenant() field metadata). */
+  isTenantScoped,
+}

package/src/auth/tenant/propagate.ts

@@ -0,0 +1,20 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import type { TenantConfig, TenantContext } from './types.js'
+import { validateSessionVarValue } from './validate.js'
+
+export async function propagateTenantLocals(
+  tx: DB,
+  config: TenantConfig,
+  ctx: TenantContext,
+): Promise<void> {
+  const vars = config.sessionVars
+  if (!vars) return
+
+  for (const [name, resolver] of Object.entries(vars)) {
+    const value = resolver(ctx)
+    if (value === '') continue
+    validateSessionVarValue(value)
+    await tx.execute(sql`SELECT set_config(${name}, ${value}, true)`)
+  }
+}

package/src/auth/tenant/rls.ts

@@ -0,0 +1,120 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { quoteIdentifier } from '../../data/db/identifiers.js'
+import { validateSessionVarName } from './validate.js'
+
+/**
+ * SQL types a tenant discriminator column may be. The union members are
+ * literal Postgres type names, so they double as the cast target — a tenant
+ * policy compares the column against the session GUC cast to this type. A
+ * field whose kind is not one of these cannot be a tenant key; the generate
+ * layer rejects it before reaching here (see rls-generate.ts).
+ */
+export type TenantKeyType = 'uuid' | 'text' | 'integer' | 'bigint'
+
+function tenantPolicyName(table: string): string {
+  return `pipework_tenant_isolation_${table.replace(/[^a-zA-Z0-9_]/g, '_')}`
+}
+
+/**
+ * The USING predicate of a tenant isolation policy.
+ *
+ * The cast (`::uuid` etc.) is required: current_setting returns text, and
+ * Postgres will not implicitly compare `uuid = text`. NULLIF(...,'') means an
+ * unset or explicitly-empty session GUC yields NULL — a deny-by-default match —
+ * instead of throwing on `''::uuid`. (current_setting(var, true) is itself NULL
+ * when the GUC was never set; the NULLIF only guards the empty-string case that
+ * set_config can produce.)
+ */
+export function tenantUsingClause(column: string, keyType: TenantKeyType, sessionVar: string): string {
+  const c = quoteIdentifier(column, 'column')
+  return `${c} = NULLIF(current_setting('${sessionVar}', true), '')::${keyType}`
+}
+
+export function tenantIsolationPolicy(
+  table: string,
+  column: string = 'tenant_id',
+  keyType: TenantKeyType = 'uuid',
+  sessionVar: string = 'pipework.tenant_id',
+  force: boolean = true,
+): string {
+  validateSessionVarName(sessionVar)
+
+  const t = quoteIdentifier(table, 'table')
+
+  return [
+    `ALTER TABLE ${t} ENABLE ROW LEVEL SECURITY`,
+    ...(force ? [`ALTER TABLE ${t} FORCE ROW LEVEL SECURITY`] : []),
+    `CREATE POLICY ${quoteIdentifier(tenantPolicyName(table), 'policy')} ON ${t} USING (${tenantUsingClause(column, keyType, sessionVar)})`,
+  ].join(';\n')
+}
+
+export async function enableTenantRls(
+  db: DB,
+  table: string,
+  column: string = 'tenant_id',
+  keyType: TenantKeyType = 'uuid',
+  force: boolean = true,
+): Promise<void> {
+  const t = quoteIdentifier(table, 'table')
+  const policyName = quoteIdentifier(tenantPolicyName(table), 'policy')
+
+  await db.execute(sql.raw(`ALTER TABLE ${t} ENABLE ROW LEVEL SECURITY`))
+  if (force) await db.execute(sql.raw(`ALTER TABLE ${t} FORCE ROW LEVEL SECURITY`))
+  await db.execute(sql.raw(
+    `CREATE POLICY ${policyName} ON ${t} USING (${tenantUsingClause(column, keyType, 'pipework.tenant_id')})`,
+  ))
+}
+
+/** The principal axes carried on the request/job context and propagated as GUCs. */
+export interface ExpectedPrincipal {
+  readonly tenant: string | null
+  readonly user: string | null
+  readonly asOf: string | null
+}
+
+/**
+ * Cross-checks the application's principal (tenant, user, asOf) against the GUCs
+ * actually set on the Postgres session — defense-in-depth against an
+ * AsyncLocalStorage context swap propagating one principal's identity onto
+ * another's transaction. All three axes are checked together so a mismatch on
+ * any one aborts before a query can read the wrong rows.
+ */
+export async function verifyPrincipalContext(
+  db: DB,
+  expected: ExpectedPrincipal,
+): Promise<void> {
+  const result = await db.execute(sql`SELECT
+    current_setting('pipework.tenant_id', true) AS tenant_id,
+    current_setting('pipework.user_id', true) AS user_id,
+    current_setting('pipework.asof', true) AS asof`)
+  const row = (result as unknown as Array<{ tenant_id: string | null; user_id: string | null; asof: string | null }>)[0]
+
+  const mismatches: string[] = []
+  if (normalizeGuc(row?.tenant_id) !== expected.tenant) mismatches.push(formatAxis('tenant', expected.tenant, normalizeGuc(row?.tenant_id)))
+  if (normalizeGuc(row?.user_id) !== expected.user) mismatches.push(formatAxis('user', expected.user, normalizeGuc(row?.user_id)))
+  if (normalizeGuc(row?.asof) !== expected.asOf) mismatches.push(formatAxis('asOf', expected.asOf, normalizeGuc(row?.asof)))
+
+  if (mismatches.length > 0) {
+    throw new Error(
+      `[pipework] Principal context mismatch between application and database.\n\n` +
+      mismatches.join('\n') + `\n\n` +
+      `  This indicates an AsyncLocalStorage context integrity failure.\n` +
+      `  The request has been aborted to prevent cross-tenant or cross-user data access.\n`,
+    )
+  }
+}
+
+// current_setting(var, true) is NULL when the GUC was never set; set_config can
+// also leave an empty string. Both collapse to null so they compare equal to an
+// absent application-side axis.
+function normalizeGuc(raw: string | null | undefined): string | null {
+  const v = raw ?? null
+  return v === '' ? null : v
+}
+
+function formatAxis(axis: string, app: string | null, pg: string | null): string {
+  return `  ${axis}: application context = ${app ?? '(null)'}, PostgreSQL session = ${pg ?? '(null)'}`
+}
+
+

package/src/auth/tenant/scope.ts

@@ -0,0 +1,33 @@
+import type { PgTable } from '../../data/query/pg-core/index.js'
+import { getTableColumns } from '../../data/query/index.js'
+
+export interface ScopeConfig {
+  readonly columnKey: string
+}
+
+const SCOPED_TABLES = new WeakMap<PgTable, ScopeConfig>()
+
+export function scopeTable<T extends PgTable>(table: T, column?: string): T {
+  const key = column ?? 'tenantId'
+  const columns = getTableColumns(table)
+
+  if (!(key in columns)) {
+    const available = Object.keys(columns).join(', ')
+    throw new Error(
+      `[pipework] tenant.scoped(): Table does not have column "${key}".\n\n` +
+      `  Available columns: ${available}\n` +
+      `  Hint: Pass the column name as the second argument: tenant.scoped(table, 'myColumn')\n`,
+    )
+  }
+
+  SCOPED_TABLES.set(table, { columnKey: key })
+  return table
+}
+
+export function getScopeConfig(table: PgTable): ScopeConfig | null {
+  return SCOPED_TABLES.get(table) ?? null
+}
+
+export function isTenantScoped(table: PgTable): boolean {
+  return SCOPED_TABLES.has(table)
+}