pipework 0.251.0 → 0.252.1

package/src/auth/tenant/scoped-db.ts

@@ -0,0 +1,581 @@
+import type { PgTable } from '../../data/query/pg-core/index.js'
+import type { DB } from '../../data/db/types.js'
+import type { SQL } from '../../data/query/index.js'
+import { eq, and, or, isNull, is, SQL as SQLClass, getTableColumns, getTableName } from '../../data/query/index.js'
+import { getScopeConfig } from './scope.js'
+
+type AnyFn = (...args: unknown[]) => unknown
+type Obj = Record<string, AnyFn>
+type Column = ReturnType<typeof getTableColumns>[string]
+
+/** What a connection does with a table: filter it to the tenant, or refuse it. */
+interface Policy {
+  /** Marks the builders this connection made; a CTE body or set operand must carry it. */
+  readonly owner: string | symbol
+  /** The tenant to inject into inserts; null on the guard, which refuses tenant tables. */
+  readonly tenantId: string | null
+  /** The tenant filter for a tenant table, null for any other source. The guard throws. */
+  scope(table: unknown, operation: string): { cond: SQL; column: Column; columnKey: string } | null
+  readonly refuseExecute: boolean
+}
+
+const GUARD = Symbol('tenant-guard')
+const made = new WeakMap<object, Policy['owner']>()
+/** Every tenant-scoped handle (and each nested transaction's) → the raw handle under it and its tenant. */
+const scopedHandles = new WeakMap<object, { readonly raw: DB; readonly tenantId: string }>()
+
+/**
+ * The handle a framework API runs its raw SQL on. A tenant-scoped handle yields the raw handle under it (same
+ * connection or transaction, so it commits and rolls back with the caller and keeps its session tenant) and its
+ * tenant; any other handle comes back unchanged with a null tenant. Internal: not part of the package surface.
+ */
+export function unscopedExecutor(db: DB): { readonly db: DB; readonly tenant: string | null } {
+  const scoped = scopedHandles.get(db as object)
+  return scoped === undefined ? { db, tenant: null } : { db: scoped.raw, tenant: scoped.tenantId }
+}
+
+/** The API's name and why it cannot be confined to one tenant, for the error a scoped handle gets. */
+function refuseScopedMessage(api: string, tenant: string, reason: string): string {
+  return (
+    `[pipework] ${api} was given a tenant-scoped database connection (tenant "${tenant}"), but ${reason}.\n\n` +
+    '  Pass an unscoped handle instead: the worker\'s own, pipe.system(), or\n' +
+    '  pool.getOrCreate(...).drizzle.\n'
+  )
+}
+
+/** Throws unless `db` is an unscoped handle; for APIs that act across tenants and cannot be confined to one. */
+export function requireUnscopedExecutor(db: DB, api: string, reason: string): DB {
+  const { db: raw, tenant } = unscopedExecutor(db)
+  if (tenant !== null) throw new Error(refuseScopedMessage(api, tenant, reason))
+  return raw
+}
+
+/**
+ * For an API that acts on one tenant's rows and knows which: the raw handle and the tenant to act for. A scoped
+ * handle whose tenant differs from `tenant` throws; with no `tenant` given the call is confined to the handle's.
+ */
+export function scopedExecutor(db: DB, tenant: string | null, api: string): { readonly db: DB; readonly tenant: string | null } {
+  const { db: raw, tenant: own } = unscopedExecutor(db)
+  if (own === null) return { db: raw, tenant }
+  if (tenant !== null && tenant !== own) {
+    throw new Error(
+      `[pipework] ${api} was given a handle scoped to tenant "${own}" but acts on tenant "${tenant}".\n\n` +
+      '  A tenant-scoped connection reaches only its own tenant. For another tenant use an unscoped handle:\n' +
+      '  the worker\'s own, pipe.system(), or pool.getOrCreate(...).drizzle.\n',
+    )
+  }
+  return { db: raw, tenant: own }
+}
+
+/**
+ * Wraps an API object whose methods act across tenants: a call with a tenant-scoped handle among its arguments
+ * throws the actionable error before running, any other call goes through unchanged.
+ */
+export function refuseScopedHandle<T extends object>(api: T, name: string, reason: string, except: readonly string[] = []): T {
+  return new Proxy(api, {
+    get(target, prop, receiver) {
+      const value: unknown = Reflect.get(target, prop, receiver)
+      if (typeof value !== 'function' || typeof prop !== 'string' || except.includes(prop)) return value
+      return (...args: unknown[]): unknown => {
+        for (const arg of args) {
+          const scoped = typeof arg === 'object' && arg !== null ? scopedHandles.get(arg) : undefined
+          if (scoped !== undefined) throw new Error(refuseScopedMessage(`${name}.${prop}()`, scoped.tenantId, reason))
+        }
+        return (value as AnyFn).apply(target, args)
+      }
+    },
+  })
+}
+
+const JOINS: Record<string, string> = {
+  leftJoin: 'left', leftJoinLateral: 'left', rightJoin: 'right', innerJoin: 'inner',
+  innerJoinLateral: 'inner', fullJoin: 'full', crossJoin: 'cross', crossJoinLateral: 'cross',
+}
+const SET_OPERATORS = ['union', 'unionAll', 'intersect', 'intersectAll', 'except', 'exceptAll']
+const SELECTS = ['select', 'selectDistinct', 'selectDistinctOn']
+
+function throwTenantRequired(tableName: string, operation: string): never {
+  throw new Error(
+    `[pipework] Cannot ${operation} tenant-scoped table "${tableName}" without a tenant in context.\n\n` +
+    '  This table has a .tenant() field, which means all operations require\n' +
+    '  an active tenant in the request/job context.\n\n' +
+    '  If this is a system-level operation that legitimately needs cross-tenant\n' +
+    '  access — pre-tenant auth (e.g. resolving org membership during login),\n' +
+    '  public webhook ingress, admin tooling — use pipe.system() instead. It is\n' +
+    '  the explicit unscoped channel: owner-role connection, outside the request\n' +
+    '  transaction, never tenant-filtered. Every query through it must be\n' +
+    '  deliberately cross-tenant-safe.\n',
+  )
+}
+
+function scopedPolicy(tenantId: string): Policy {
+  return {
+    owner: tenantId,
+    tenantId,
+    refuseExecute: true,
+    scope(table) {
+      const config = getScopeConfig(table as PgTable)
+      if (!config) return null
+      const column = getTableColumns(table as PgTable)[config.columnKey]!
+      return { cond: eq(column, tenantId), column, columnKey: config.columnKey }
+    },
+  }
+}
+
+const guardPolicy: Policy = {
+  owner: GUARD,
+  tenantId: null,
+  refuseExecute: false,
+  scope(table, operation) {
+    if (getScopeConfig(table as PgTable)) throwTenantRequired(getTableName(table as PgTable), operation)
+    return null
+  },
+}
+
+const SYSTEM = Symbol('platform-system')
+
+/** The platform-role system channel: it reads no tenant table, whatever the statement. */
+const systemPolicy: Policy = {
+  owner: SYSTEM,
+  tenantId: null,
+  refuseExecute: false,
+  scope(table, operation) {
+    if (!getScopeConfig(table as PgTable)) return null
+    throw new Error(
+      `[pipework] Cannot ${operation} tenant-scoped table "${getTableName(table as PgTable)}" through pipe.system().\n\n` +
+      '  This database runs its system channel on a platform role (rls.platformRole) that has no\n' +
+      '  blanket access to tenant rows. Declare a door for the table under `doors` in\n' +
+      '  pipework.config.ts, and read it with pipe.door(name, fn).\n',
+    )
+  },
+}
+
+const DOOR_READS: ReadonlySet<string> = new Set(['select from', 'join', 'count', 'update from'])
+
+function doorPolicy(door: { readonly name: string; readonly table: string; readonly ops?: readonly string[] }): Policy {
+  const reads = door.ops?.includes('delete') === true ? new Set([...DOOR_READS, 'delete']) : DOOR_READS
+  return {
+    owner: Symbol(`door:${door.name}`),
+    tenantId: null,
+    refuseExecute: false,
+    scope(table, operation) {
+      if (!getScopeConfig(table as PgTable)) return null
+      const name = getTableName(table as PgTable)
+      if (name !== door.table) {
+        throw new Error(
+          `[pipework] Cannot ${operation} tenant-scoped table "${name}" inside door "${door.name}".\n\n` +
+          `  The door opens "${door.table}" only. Declare a door for "${name}" under \`doors\` in\n` +
+          '  pipework.config.ts and read it with its own pipe.door(name, fn).\n',
+        )
+      }
+      if (!reads.has(operation)) {
+        throw new Error(
+          `[pipework] Cannot ${operation} "${name}" inside door "${door.name}": a door is read-only.\n\n` +
+          '  Write tenant rows from a request or job with a tenant in context.\n',
+        )
+      }
+      return null
+    },
+  }
+}
+
+function refuse(what: string, why: string): never {
+  throw new Error(
+    `[pipework] ${what} is not allowed on this database connection: ${why}\n\n` +
+    '  A tenant-scoped connection filters every tenant table its own builders read.\n' +
+    '  Build the statement with this connection (select, insert, update or delete, or\n' +
+    '  the callback form of $with) so the filter is part of its SQL. A raw sql fragment\n' +
+    '  or a builder from another connection (pipe.system(), an unscoped db) cannot be\n' +
+    '  filtered, so it is refused.\n',
+  )
+}
+
+function checkBuilder(policy: Policy, what: string, builder: unknown): void {
+  if (builder != null && typeof builder === 'object' && made.get(builder) === policy.owner) return
+  if (is(builder, SQLClass)) refuse(what, 'a raw sql fragment cannot be scoped to the tenant.')
+  refuse(what, 'it was not built by this connection.')
+}
+
+function withCond(on: unknown, cond: SQL): unknown {
+  if (typeof on === 'function') return (...args: unknown[]) => and((on as AnyFn)(...args) as SQL | undefined, cond)
+  return on === undefined ? cond : and(on as SQL, cond)
+}
+
+interface Entry {
+  cond: SQL
+  column: Column
+  position: number
+  /** Kept as written even when a later right/full join null-extends the table. */
+  strict: boolean
+  /** Null-extended by its own right/full join: its null rows are not another tenant's. */
+  tolerant: boolean
+}
+
+/**
+ * The where clause of one statement: the user's condition plus the tenant
+ * condition of every tenant table the statement reads. It is rewritten onto the
+ * builder after every call that changes it, so the filter is in the SQL as soon
+ * as the table is named. A table a right or full join can null-extend accepts
+ * its null rows (the tenant column is NOT NULL, so null means no row there).
+ */
+class WhereScope {
+  private user: SQL | undefined
+  private readonly entries: Entry[] = []
+  private position = 0
+  private widest = -1
+
+  constructor(private readonly target: Obj, private readonly policy: Policy) {}
+
+  table(table: unknown, operation: string, strict: boolean): void {
+    this.position++
+    const scope = this.policy.scope(table, operation)
+    if (scope) this.entries.push({ cond: scope.cond, column: scope.column, position: this.position, strict, tolerant: false })
+    this.refresh()
+  }
+
+  join(table: unknown, type: string, on: unknown): unknown {
+    this.position++
+    const wide = type === 'right' || type === 'full'
+    const scope = this.policy.scope(table, 'join')
+    const conds: SQL[] = []
+    if (scope && type !== 'cross') conds.push(scope.cond)
+    // A right or full join keeps unmatched rows of the tables before it: a row of
+    // another tenant must not match, so those tables' conditions go in its ON too.
+    if (wide) conds.push(...this.entries.map(e => or(e.cond, isNull(e.column))!))
+    if (scope && (wide || type === 'cross')) {
+      this.entries.push({ cond: scope.cond, column: scope.column, position: this.position, strict: false, tolerant: wide })
+    }
+    if (wide) this.widest = this.position
+    return conds.length > 0 ? withCond(on, and(...conds)!) : on
+  }
+
+  where(user: SQL | undefined): void {
+    this.user = user
+    this.refresh()
+  }
+
+  refresh(): void {
+    if (this.user === undefined && this.entries.length === 0) return
+    const conds = this.entries.map(e =>
+      e.tolerant || (!e.strict && this.widest > e.position) ? or(e.cond, isNull(e.column)) : e.cond)
+    this.target['where']!(and(this.user, ...conds))
+  }
+}
+
+/** Wraps a builder so the calls that return it return the wrapper, and `hooks` replace named methods. */
+function wrap(
+  target: object,
+  policy: Policy,
+  hooksFor: (self: object, t: Obj) => Record<string, AnyFn>,
+): object {
+  let hooks: Record<string, AnyFn> | undefined
+  const self: object = new Proxy(target, {
+    get(t, prop) {
+      if (typeof prop === 'string') {
+        hooks ??= hooksFor(self, t as Obj)
+        if (Object.hasOwn(hooks, prop)) return hooks[prop]
+      }
+      const value: unknown = Reflect.get(t, prop, t)
+      if (typeof value !== 'function') return value
+      return (...args: unknown[]) => {
+        const result = (value as AnyFn).apply(t, args)
+        return result === t ? self : result
+      }
+    },
+  })
+  made.set(self, policy.owner)
+  return self
+}
+
+function whereHook(scope: WhereScope, self: object): AnyFn {
+  return (user) => {
+    scope.where(user as SQL | undefined)
+    return self
+  }
+}
+
+function joinHooks(scope: WhereScope, self: object, t: Obj): Record<string, AnyFn> {
+  const hooks: Record<string, AnyFn> = {}
+  for (const [name, type] of Object.entries(JOINS)) {
+    hooks[name] = (table, on) => {
+      const scopedOn = scope.join(table, type, on)
+      t[name]!(...(scopedOn === undefined ? [table] : [table, scopedOn]))
+      scope.refresh()
+      return self
+    }
+  }
+  return hooks
+}
+
+function selectBuilder(builder: object, table: unknown, policy: Policy): object {
+  const t = builder as Obj
+  const scope = new WhereScope(t, policy)
+  scope.table(table, 'select from', false)
+  return wrap(builder, policy, (self) => ({
+    where: whereHook(scope, self),
+    ...joinHooks(scope, self, t),
+    ...Object.fromEntries(SET_OPERATORS.map(name => [name, (right: unknown) => {
+      const checked = typeof right === 'function'
+        ? (...ops: unknown[]) => {
+            const resolved = (right as AnyFn)(...ops)
+            checkBuilder(policy, `${name}()`, resolved)
+            return resolved
+          }
+        : right
+      if (typeof right !== 'function') checkBuilder(policy, `${name}()`, right)
+      t[name]!(checked)
+      return self
+    }])),
+  }))
+}
+
+function selectStart(builder: object, policy: Policy): object {
+  return new Proxy(builder, {
+    get(t, prop) {
+      if (prop === 'from') {
+        return (table: unknown, ...rest: unknown[]) =>
+          selectBuilder((t as Obj)['from']!(table, ...rest) as object, table, policy)
+      }
+      const value: unknown = Reflect.get(t, prop, t)
+      return typeof value === 'function' ? (value as AnyFn).bind(t) : value
+    },
+  })
+}
+
+function updateBuilder(builder: object, table: unknown, policy: Policy): object {
+  const t = builder as Obj
+  const scope = new WhereScope(t, policy)
+  scope.table(table, 'update', true)
+  return wrap(builder, policy, (self) => ({
+    where: whereHook(scope, self),
+    ...joinHooks(scope, self, t),
+    from: (source) => {
+      t['from']!(source)
+      scope.table(source, 'update from', false)
+      return self
+    },
+  }))
+}
+
+function updateStart(builder: object, table: unknown, policy: Policy): object {
+  return new Proxy(builder, {
+    get(t, prop) {
+      if (prop === 'set') {
+        return (...args: unknown[]) => updateBuilder((t as Obj)['set']!(...args) as object, table, policy)
+      }
+      const value: unknown = Reflect.get(t, prop, t)
+      return typeof value === 'function' ? (value as AnyFn).bind(t) : value
+    },
+  })
+}
+
+function deleteBuilder(builder: object, table: unknown, policy: Policy): object {
+  const scope = new WhereScope(builder as Obj, policy)
+  scope.table(table, 'delete', true)
+  return wrap(builder, policy, (self) => ({ where: whereHook(scope, self) }))
+}
+
+function insertBuilder(builder: object, table: unknown, policy: Policy): object {
+  const t = builder as Obj
+  const scope = policy.scope(table, 'insert')
+  // A conflict with another tenant's row must update nothing: the existing row has to be ours.
+  const finish = (result: unknown): object =>
+    wrap(result as object, policy, (self, base) => ({
+      ...(scope && {
+        onConflictDoUpdate: (config: unknown) => {
+          const { where, setWhere, ...rest } = config as { where?: SQL; setWhere?: SQL }
+          base['onConflictDoUpdate']!({ ...rest, setWhere: and(where, setWhere, scope.cond) })
+          return self
+        },
+      }),
+    }))
+  return wrap(builder, policy, (self) => ({
+    values: (values) => {
+      if (!scope) return finish(t['values']!(values))
+      const { columnKey } = scope
+      const tenantId = policy.tenantId!
+      const inject = (row: Record<string, unknown>): Record<string, unknown> => {
+        const existing = row[columnKey]
+        if (existing !== undefined && existing !== tenantId) {
+          throw new Error(
+            `[pipework] Tenant-scoped insert: value has ${columnKey} "${String(existing)}" ` +
+            `but the current context tenant is "${tenantId}".\n\n` +
+            `  Remove the explicit ${columnKey} from your insert values — it's set automatically.\n` +
+            '  If you need cross-tenant writes, file an issue on the pipework repo.\n',
+          )
+        }
+        return { ...row, [columnKey]: tenantId }
+      }
+      const scoped = Array.isArray(values)
+        ? (values as Record<string, unknown>[]).map(inject)
+        : inject(values as Record<string, unknown>)
+      return finish(t['values']!(scoped))
+    },
+    select: (source) => {
+      if (scope) {
+        refuse(
+          `insert().select() into tenant-scoped table "${getTableName(table as PgTable)}"`,
+          `the tenant column ${scope.columnKey} cannot be set from a select.`,
+        )
+      }
+      if (typeof source === 'function') {
+        return finish(t['select']!((qb: unknown) => {
+          const body = (source as AnyFn)(scopedQueryBuilder(qb as object, policy))
+          checkBuilder(policy, 'insert().select()', body)
+          return body
+        }))
+      }
+      checkBuilder(policy, 'insert().select()', source)
+      return finish(t['select']!(source))
+    },
+    overridingSystemValue: () => {
+      t['overridingSystemValue']!()
+      return self
+    },
+  }))
+}
+
+function scopedWith(source: Obj, policy: Policy): AnyFn {
+  return (alias, selection) => {
+    const raw = source['$with']!(alias, selection) as {
+      as: AnyFn
+      materialized: () => { as: AnyFn }
+      notMaterialized: () => { as: AnyFn }
+    }
+    const build = (as: AnyFn) => (body: unknown) => {
+      const cte = typeof body === 'function'
+        ? as((qb: unknown) => {
+            const result = (body as AnyFn)(scopedQueryBuilder(qb as object, policy))
+            checkBuilder(policy, '$with() body', result)
+            return result
+          })
+        : (checkBuilder(policy, '$with() body', body), as(body))
+      made.set(cte as object, policy.owner)
+      return cte
+    }
+    return {
+      as: build(raw.as),
+      materialized: () => ({ as: build(raw.materialized().as) }),
+      notMaterialized: () => ({ as: build(raw.notMaterialized().as) }),
+    }
+  }
+}
+
+/** The statement starters of a connection, a `with(...)` result or a query builder. */
+function starters(source: Obj, policy: Policy): Record<string, AnyFn> {
+  const hooks: Record<string, AnyFn> = {}
+  for (const name of SELECTS) {
+    if (typeof source[name] !== 'function') continue
+    hooks[name] = (...args) => selectStart(source[name]!(...args) as object, policy)
+  }
+  if (typeof source['insert'] === 'function') {
+    hooks['insert'] = (table) => {
+      policy.scope(table, 'insert')
+      return insertBuilder(source['insert']!(table) as object, table, policy)
+    }
+  }
+  if (typeof source['update'] === 'function') {
+    hooks['update'] = (table) => {
+      policy.scope(table, 'update')
+      return updateStart(source['update']!(table) as object, table, policy)
+    }
+  }
+  if (typeof source['delete'] === 'function') {
+    hooks['delete'] = (table) => {
+      policy.scope(table, 'delete')
+      return deleteBuilder(source['delete']!(table) as object, table, policy)
+    }
+  }
+  return hooks
+}
+
+function withHooks(source: Obj, policy: Policy): Record<string, AnyFn> {
+  return {
+    $with: scopedWith(source, policy),
+    with: (...ctes) => {
+      for (const cte of ctes) {
+        if (cte == null || typeof cte !== 'object' || made.get(cte) !== policy.owner) {
+          refuse('with()', 'every CTE must come from $with() on this connection.')
+        }
+      }
+      return starters(source['with']!(...ctes) as Obj, policy)
+    },
+  }
+}
+
+function scopedQueryBuilder(qb: object, policy: Policy): object {
+  const source = qb as Obj
+  const hooks = { ...starters(source, policy), ...withHooks(source, policy) }
+  return new Proxy(qb, {
+    get(t, prop) {
+      if (typeof prop === 'string' && Object.hasOwn(hooks, prop)) return hooks[prop]
+      const value: unknown = Reflect.get(t, prop, t)
+      return typeof value === 'function' ? (value as AnyFn).bind(t) : value
+    },
+  })
+}
+
+function createDb(db: DB, policy: Policy): DB {
+  const source = db as unknown as Obj
+  const hooks: Record<string, AnyFn> = {
+    ...starters(source, policy),
+    ...withHooks(source, policy),
+    $count: (table, filters) => {
+      const scope = policy.scope(table, 'count')
+      const combined = scope ? (filters !== undefined ? and(filters as SQL, scope.cond) : scope.cond) : filters
+      return source['$count']!(table, combined)
+    },
+    transaction: (callback, config) =>
+      source['transaction']!((tx: unknown) => (callback as AnyFn)(createDb(tx as DB, policy)), config),
+  }
+  if (policy.refuseExecute) {
+    hooks['execute'] = () => {
+      throw new Error(
+        '[pipework] execute() is not available on a tenant-scoped database connection.\n\n' +
+        '  Tenant-scoped connections only support select, insert, update, and delete\n' +
+        '  operations, which are automatically filtered by tenant.\n\n' +
+        '  If you need to run a query that the builder cannot express, file an issue\n' +
+        '  on the pipework repo describing your use case.\n',
+      )
+    }
+  }
+  const proxy = new Proxy(db, {
+    get(target, prop, receiver) {
+      if (typeof prop === 'string') {
+        if (Object.hasOwn(hooks, prop)) return hooks[prop]
+        if (prop === 'query') {
+          const query = Reflect.get(target, prop, receiver) as object | undefined
+          if (query && Object.keys(query).length > 0) {
+            return new Proxy({}, {
+              get() {
+                refuse('A relational query (db.query)', 'it reads tables without the tenant filter.')
+              },
+            })
+          }
+          return query
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+  if (policy.refuseExecute && policy.tenantId !== null) scopedHandles.set(proxy, { raw: db, tenantId: policy.tenantId })
+  return proxy
+}
+
+export function createTenantGuardDb(db: DB): DB {
+  return createDb(db, guardPolicy)
+}
+
+export function createScopedDb(db: DB, tenantId: string): DB {
+  return createDb(db, scopedPolicy(tenantId))
+}
+
+/** The system channel's handle on a platform role: every tenant table is refused at build time. */
+export function createSystemGuardDb(db: DB): DB {
+  return createDb(db, systemPolicy)
+}
+
+/** A door's handle: SELECT from the door's table and from non-tenant tables; any other tenant table, and any write to the door's table, is refused at build time. */
+export function createDoorDb(db: DB, door: { readonly name: string; readonly table: string; readonly ops?: readonly string[] }): DB {
+  return createDb(db, doorPolicy(door))
+}

package/src/auth/tenant/types.ts

@@ -0,0 +1,14 @@
+/** Configuration for tenant extraction and isolation strategy. */
+export interface TenantConfig {
+  readonly extract: (auth: unknown) => string | null
+  readonly sessionVars?: Record<string, (ctx: TenantContext) => string>
+  readonly validate?: (tenantId: string) => boolean
+  readonly required?: boolean
+}
+
+/** Resolved tenant context — tenant ID, request ID, and user ID. */
+export interface TenantContext {
+  readonly tenant: string
+  readonly requestId: string
+  readonly userId: string | null
+}

package/src/auth/tenant/validate.ts

@@ -0,0 +1,27 @@
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+const SAFE_VAR_NAME = /^[a-z][a-z0-9_.]*$/
+
+export function validateTenantId(value: string): boolean {
+  return UUID_PATTERN.test(value)
+}
+
+export function validateSessionVarName(name: string): void {
+  if (!SAFE_VAR_NAME.test(name)) {
+    throw new Error(
+      `[pipework] Invalid session variable name: "${name}". ` +
+      `Variable names must match /^[a-z][a-z0-9_.]*$/. ` +
+      `This prevents SQL injection in SET LOCAL statements.`,
+    )
+  }
+}
+
+export function validateSessionVarValue(value: string): void {
+  if (/[;'"\n\r]/.test(value)) {
+    throw new Error(
+      `[pipework] Unsafe session variable value rejected. ` +
+      `Values must not contain semicolons, quotes, or newlines. ` +
+      `Received: "${value.slice(0, 40)}${value.length > 40 ? '...' : ''}"`,
+    )
+  }
+}