pipework 0.252.0 → 0.253.0

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

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto'
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { pipeSystem } from '../../data/db/db.js'
+import { auditUnauthenticated } from './audit.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import type { Passwords } from './passwords.js'
+
+export interface SignInConfig {
+  readonly passwords: Passwords
+  /** Failures per account within the window before it is locked. Default 5. */
+  readonly accountThreshold?: number
+  /** Failures per client address within the window before it is locked. Default 20. */
+  readonly clientThreshold?: number
+  /** Window since the first failure after which the count restarts. Default 900 seconds. */
+  readonly windowSeconds?: number
+  /** Longest single lock. Default 900 seconds. */
+  readonly maxLockSeconds?: number
+}
+
+export interface SignInAttempt {
+  readonly account: string
+  /** The client address; without it only the account is guarded. */
+  readonly client?: string
+  readonly password: string
+  /** Finds the account's user id and stored password hash, or null if there is no such account. */
+  readonly lookup: (db: DB, account: string) => Promise<{ userId: string; passwordHash: string } | null>
+}
+
+export type SignInResult =
+  | { readonly ok: true; readonly userId: string; readonly needsRehash: boolean }
+  | { readonly ok: false; readonly reason: 'invalid' | 'locked'; readonly retryAfterSeconds?: number }
+
+export interface SignIn {
+  attempt(input: SignInAttempt): Promise<SignInResult>
+}
+
+interface Key { readonly key: string; readonly threshold: number }
+
+/**
+ * Creates a guarded password sign-in. `attempt` needs an active Flow (a request,
+ * job or test context) and runs every statement, `lookup` included, on
+ * `pipe.system()`: outside the request transaction, committed on its own, so a
+ * route that answers a bad password by throwing `UnauthorizedError` (rolling the
+ * request back) still keeps the count. Failed attempts are counted per account and
+ * per client address in `pipework_signin_attempts` (blueprint `passwords: {}`), so
+ * counts survive restarts and are shared across processes. At the threshold each
+ * further failure locks the key for 2^(failures - threshold) seconds, capped at
+ * `maxLockSeconds`. Every attempt is counted, atomically per key, before the
+ * password is checked, so a burst of parallel guesses is locked out instead of
+ * all being verified. While any key is locked an attempt is refused with
+ * `reason: 'locked'` and `retryAfterSeconds`, without checking the password (a
+ * locked key is not counted further). A success deletes the account's key and
+ * gives the client key its count back. An unknown account runs a dummy verify
+ * and counts as a failure, reported as `'invalid'` like a wrong password.
+ *
+ * Tradeoff: locking is per account, so anyone who knows an account name can lock
+ * it out by failing on purpose. Each lock is capped (default 15 minutes) and the
+ * client key bounds how fast one address can do it.
+ *
+ * Every success, failure and refusal is logged, and audited (entity `SignIn`,
+ * verbs `success`, `fail`, `locked`; never the account string or password) when
+ * the Flow has an open trace step. Route a locked result to a 429 with
+ * `throw new TooManyRequestsError(result.retryAfterSeconds)`.
+ */
+export function createSignIn(config: SignInConfig): SignIn {
+  const accountThreshold = config.accountThreshold ?? 5
+  const clientThreshold = config.clientThreshold ?? 20
+  const windowSeconds = config.windowSeconds ?? 900
+  const maxLockSeconds = config.maxLockSeconds ?? 900
+  const { passwords } = config
+
+  function keysFor(account: string, client: string | undefined): { accountKey: Key; all: Key[] } {
+    const normalized = account.normalize('NFC').trim().toLowerCase()
+    const accountKey = { key: 'account:' + createHash('sha256').update(normalized).digest('hex'), threshold: accountThreshold }
+    const all = [accountKey]
+    if (client !== undefined && client !== '') all.push({ key: 'client:' + client, threshold: clientThreshold })
+    return { accountKey, all }
+  }
+
+  // Counts the attempt before any password is checked, one statement per key, so
+  // a burst of parallel guesses is counted (and locked) before it is verified.
+  // The update applies only to a key that is not currently locked; a locked key
+  // returns no row and is read separately.
+  async function countAttempt(db: DB, { key, threshold }: Key): Promise<{ locked: boolean; failures: number; retryAfterSeconds: number }> {
+    const rows = await db.execute(sql`
+      INSERT INTO pipework_signin_attempts AS a (key, failures, first_failure_at, last_failure_at, locked_until)
+      VALUES (${key}, 1, now(), now(),
+        CASE WHEN 1 >= ${threshold}::int
+          THEN now() + least(power(2, 0), ${maxLockSeconds}::int) * interval '1 second' END)
+      ON CONFLICT (key) DO UPDATE SET
+        failures = CASE WHEN a.first_failure_at < now() - ${windowSeconds}::int * interval '1 second' THEN 1 ELSE a.failures + 1 END,
+        first_failure_at = CASE WHEN a.first_failure_at < now() - ${windowSeconds}::int * interval '1 second' THEN now() ELSE a.first_failure_at END,
+        last_failure_at = now(),
+        locked_until = CASE
+          WHEN (CASE WHEN a.first_failure_at < now() - ${windowSeconds}::int * interval '1 second' THEN 1 ELSE a.failures + 1 END) >= ${threshold}::int
+          THEN now() + least(
+            power(2, least((CASE WHEN a.first_failure_at < now() - ${windowSeconds}::int * interval '1 second' THEN 1 ELSE a.failures + 1 END) - ${threshold}::int, 30)),
+            ${maxLockSeconds}::int) * interval '1 second'
+          END
+      WHERE a.locked_until IS NULL OR a.locked_until <= now()
+      RETURNING failures, coalesce(ceil(extract(epoch FROM (locked_until - now()))), 0)::int AS remaining`)
+    if (rows.length > 0) {
+      return { locked: false, failures: Number(rows[0]!['failures']), retryAfterSeconds: Math.max(0, Number(rows[0]!['remaining'])) }
+    }
+    const held = await db.execute(sql`
+      SELECT failures, greatest(ceil(extract(epoch FROM (locked_until - now())))::int, 1) AS remaining
+      FROM pipework_signin_attempts WHERE key = ${key}`)
+    return { locked: true, failures: Number(held[0]?.['failures'] ?? 0), retryAfterSeconds: Number(held[0]?.['remaining'] ?? 1) }
+  }
+
+  const audit = (db: DB, verb: string, userId: string | null, details: Record<string, unknown>): Promise<void> =>
+    auditUnauthenticated(db, 'SignIn', verb, userId, details)
+
+  async function attempt(input: SignInAttempt): Promise<SignInResult> {
+    const db = pipeSystem()
+    const { accountKey, all } = keysFor(input.account, input.client)
+    const client = input.client ?? null
+    const base = { accountKey: accountKey.key, client }
+
+    const counted: Array<{ k: Key; r: { locked: boolean; failures: number; retryAfterSeconds: number } }> = []
+    for (const k of all) counted.push({ k, r: await countAttempt(db, k) })
+    const heldFor = Math.max(0, ...counted.filter(c => c.r.locked).map(c => c.r.retryAfterSeconds))
+    if (counted.some(c => c.r.locked)) {
+      getBaseLogger().warn({ event: 'sign-in refused', ...base, retryAfterSeconds: heldFor }, 'sign-in refused: locked')
+      await audit(db, 'locked', null, { ...base, failures: counted[0]!.r.failures, retryAfterSeconds: heldFor })
+      return { ok: false, reason: 'locked', retryAfterSeconds: heldFor }
+    }
+
+    const found = await input.lookup(db, input.account)
+    if (found === null) await passwords.verifyNone(input.password)
+    const verified = found === null ? null : await passwords.verify(found.passwordHash, input.password)
+
+    if (found !== null && verified !== null && verified.ok) {
+      await db.execute(sql`DELETE FROM pipework_signin_attempts WHERE key = ${accountKey.key}`)
+      for (const { k } of counted) {
+        if (k !== accountKey) {
+          await db.execute(sql`UPDATE pipework_signin_attempts SET failures = greatest(failures - 1, 0) WHERE key = ${k.key}`)
+        }
+      }
+      getBaseLogger().info({ event: 'sign-in success', ...base }, 'sign-in succeeded')
+      await audit(db, 'success', found.userId, { ...base, failures: 0, retryAfterSeconds: null })
+      return { ok: true, userId: found.userId, needsRehash: verified.needsRehash }
+    }
+
+    const retryAfterSeconds = Math.max(0, ...counted.map(c => c.r.retryAfterSeconds))
+    const details = { ...base, failures: counted[0]!.r.failures, retryAfterSeconds: retryAfterSeconds > 0 ? retryAfterSeconds : null }
+    getBaseLogger().warn({ event: 'sign-in failed', ...details }, 'sign-in failed')
+    await audit(db, 'fail', found?.userId ?? null, details)
+    return retryAfterSeconds > 0
+      ? { ok: false, reason: 'invalid', retryAfterSeconds }
+      : { ok: false, reason: 'invalid' }
+  }
+
+  return { attempt }
+}

package/src/auth/auth/signing-keys.ts

@@ -0,0 +1,69 @@
+import { createPublicKey, createPrivateKey, type KeyObject } from 'node:crypto'
+import { importPKCS8, importSPKI } from 'jose'
+import { AuthConfigurationError } from '../../core/errors/index.js'
+
+interface Signing { readonly algorithm: 'ES256'; readonly privateKey: string; readonly publicKey: string }
+
+/**
+ * Parses both configured signing keys now, so a key that is not valid PEM stops the server at start.
+ * Returns the public key for synchronous verification. `owner` names the factory in the message.
+ */
+export function checkSigningKeys(signing: Signing, owner: string): KeyObject {
+  let publicKey: KeyObject
+  try {
+    publicKey = createPublicKey(signing.publicKey)
+  } catch (error) {
+    throw keyFault('signing.publicKey', 'a valid SPKI PEM public key', owner, error)
+  }
+  let privateKey: KeyObject
+  try {
+    privateKey = createPrivateKey(signing.privateKey)
+  } catch (error) {
+    throw keyFault('signing.privateKey', 'a valid PKCS#8 PEM private key', owner, error)
+  }
+  assertFitsAlgorithm(publicKey, 'signing.publicKey', signing.algorithm, owner)
+  assertFitsAlgorithm(privateKey, 'signing.privateKey', signing.algorithm, owner)
+  return publicKey
+}
+
+/** Imports a configured key for jose; a failure is a configuration fault (500), never a refusal of a token. */
+export async function importSigningKey(kind: 'public' | 'private', signing: Signing, owner: string): Promise<CryptoKey> {
+  try {
+    return kind === 'public'
+      ? await importSPKI(signing.publicKey, signing.algorithm)
+      : await importPKCS8(signing.privateKey, signing.algorithm)
+  } catch (error) {
+    throw keyFault(
+      kind === 'public' ? 'signing.publicKey' : 'signing.privateKey',
+      `a key usable with ${signing.algorithm}`, owner, error,
+    )
+  }
+}
+
+function keyFault(field: string, expected: string, owner: string, error: unknown): AuthConfigurationError {
+  const reason = error instanceof Error ? error.message : String(error)
+  return new AuthConfigurationError(
+    `[pipework] ${owner}: ${field} is not ${expected}: ${reason}`,
+    { field },
+  )
+}
+
+const CURVES: Record<string, string> = { ES256: 'prime256v1', ES384: 'secp384r1', ES512: 'secp521r1' }
+
+function assertFitsAlgorithm(key: KeyObject, field: string, algorithm: string, owner: string): void {
+  const type = key.asymmetricKeyType
+  let fits: boolean | null = null
+  if (/^(RS|PS)\d+$/.test(algorithm)) {
+    fits = type === 'rsa' || (algorithm.startsWith('PS') && type === 'rsa-pss')
+  } else if (algorithm in CURVES) {
+    fits = type === 'ec' && key.asymmetricKeyDetails?.namedCurve === CURVES[algorithm]
+  } else if (algorithm === 'EdDSA') {
+    fits = type === 'ed25519' || type === 'ed448'
+  }
+  if (fits === null || fits) return
+  const curve = type === 'ec' ? ` (${key.asymmetricKeyDetails?.namedCurve ?? 'unknown curve'})` : ''
+  throw new AuthConfigurationError(
+    `[pipework] ${owner}: ${field} is a ${type ?? 'unknown'}${curve} key, which does not fit algorithm ${algorithm}`,
+    { field },
+  )
+}

package/src/auth/auth/types.ts

@@ -0,0 +1,26 @@
+import type { DB } from '../../data/db/types.js'
+
+/** Runtime auth context passed to strategies — carries the resolved DB and request metadata. */
+export interface AuthContext {
+  readonly db: (name?: string) => DB
+}
+
+/** Pluggable auth strategy — implement authenticate() to extract auth from a request. */
+export interface AuthStrategy<TAuth> {
+  readonly name: string
+  extract(request: AuthRequest, context: AuthContext): Promise<TAuth | null>
+  verify(extracted: TAuth, context: AuthContext): Promise<TAuth>
+}
+
+/** Normalized request shape passed to auth strategies — headers, the parsed `Cookie` header, and the upper-case HTTP method. */
+export interface AuthRequest {
+  readonly headers: Readonly<Record<string, string | undefined>>
+  readonly cookies: Readonly<Record<string, string | undefined>>
+  readonly method?: string
+}
+
+/** Minimum auth shape — userId and tenantId. Extend for app-specific auth fields. */
+export interface BaseAuth {
+  readonly userId: string
+  readonly tenantId: string
+}

package/src/auth/auth/uuid.ts

@@ -0,0 +1,10 @@
+import { ValidationError } from '../../core/errors/index.js'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** Throws a ValidationError unless `value` is a uuid; the session and org tables type tenant and org ids uuid. */
+export function assertUuid(value: string, what: string): void {
+  if (!UUID_RE.test(value)) {
+    throw new ValidationError(`${what} must be a uuid, got "${value}". The pipework_refresh_tokens and pipework_user_orgs tables type it uuid.`)
+  }
+}

package/src/auth/rbac/cache.ts

@@ -0,0 +1,55 @@
+import type { PermissionSet } from './types.js'
+
+interface CacheEntry {
+  readonly set: PermissionSet
+  readonly expiresAt: number
+}
+
+export class PermissionCache {
+  private readonly store = new Map<string, CacheEntry>()
+  private readonly ttlMs: number
+
+  constructor(ttlMs: number) {
+    this.ttlMs = ttlMs
+  }
+
+  get(userId: string, tenantId: string, authVersion: number): PermissionSet | null {
+    const key = this.key(userId, tenantId, authVersion)
+    const entry = this.store.get(key)
+    if (!entry) return null
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return null
+    }
+    return entry.set
+  }
+
+  set(permissionSet: PermissionSet): void {
+    const key = this.key(permissionSet.userId, permissionSet.tenantId, permissionSet.authVersion)
+    this.store.set(key, {
+      set: permissionSet,
+      expiresAt: Date.now() + this.ttlMs,
+    })
+  }
+
+  invalidate(userId: string, tenantId: string): void {
+    const prefix = `${userId}:${tenantId}:`
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key)
+      }
+    }
+  }
+
+  clear(): void {
+    this.store.clear()
+  }
+
+  get size(): number {
+    return this.store.size
+  }
+
+  private key(userId: string, tenantId: string, authVersion: number): string {
+    return `${userId}:${tenantId}:${authVersion}`
+  }
+}

package/src/auth/rbac/check.ts

@@ -0,0 +1,30 @@
+import type { ResolvedPermission } from './types.js'
+
+const DEFAULT_HIERARCHY: readonly string[] = ['own', 'team', 'territory', 'tenant']
+
+export function scopeSatisfies(
+  granted: string,
+  required: string,
+  hierarchy: readonly string[] = DEFAULT_HIERARCHY,
+): boolean {
+  const grantedIdx = hierarchy.indexOf(granted)
+  const requiredIdx = hierarchy.indexOf(required)
+  if (grantedIdx === -1 || requiredIdx === -1) return false
+  return grantedIdx >= requiredIdx
+}
+
+export function hasPermission(
+  permissions: readonly ResolvedPermission[],
+  resource: string,
+  action: string,
+  requiredScope?: string,
+  hierarchy: readonly string[] = DEFAULT_HIERARCHY,
+): boolean {
+  for (const perm of permissions) {
+    if (perm.resource === resource && perm.action === action) {
+      if (requiredScope === undefined) return true
+      if (scopeSatisfies(perm.scope, requiredScope, hierarchy)) return true
+    }
+  }
+  return false
+}

package/src/auth/rbac/create.ts

@@ -0,0 +1,35 @@
+import type { DB } from '../../data/db/index.js'
+import type { RbacConfig, Rbac, PermissionSet, SeedData } from './types.js'
+import { PermissionCache } from './cache.js'
+import { resolveUserPermissions } from './resolve.js'
+import { hasPermission } from './check.js'
+import { seedRbac } from './seed.js'
+
+/** Creates an Rbac instance from role/permission config — provides check, enforce, and seed operations. */
+export function createRbac(config: RbacConfig): Rbac {
+  const cache = new PermissionCache(config.cacheTtlMs ?? 60_000)
+  const scopes = config.scopes ?? ['own', 'team', 'territory', 'tenant']
+
+  return {
+    async resolve(db: DB, userId: string, tenantId: string, authVersion: number): Promise<PermissionSet> {
+      const cached = cache.get(userId, tenantId, authVersion)
+      if (cached) return cached
+
+      const resolved = await resolveUserPermissions(db, userId, tenantId, authVersion, config)
+      cache.set(resolved)
+      return resolved
+    },
+
+    check(permissions: PermissionSet, resource: string, action: string, requiredScope?: string): boolean {
+      return hasPermission(permissions.permissions, resource, action, requiredScope, scopes)
+    },
+
+    invalidate(userId: string, tenantId: string): void {
+      cache.invalidate(userId, tenantId)
+    },
+
+    async seed(db: DB, data: SeedData): Promise<void> {
+      await seedRbac(db, data, config)
+    },
+  }
+}

package/src/auth/rbac/index.ts

@@ -0,0 +1,5 @@
+export type { RbacConfig, Rbac, PermissionSet, ResolvedPermission, Scope, SeedData, SeedPermission, SeedRole, SeedRolePermission, SeedUserRole } from './types.js'
+export { hasPermission, scopeSatisfies } from './check.js'
+export { PermissionCache } from './cache.js'
+export { enforcePermission } from './middleware.js'
+export { createRbac } from './create.js'

package/src/auth/rbac/middleware.ts

@@ -0,0 +1,20 @@
+import type { DB } from '../../data/db/index.js'
+import type { Rbac } from './types.js'
+import { ForbiddenError } from '../../core/errors/index.js'
+
+export async function enforcePermission(
+  rbac: Rbac,
+  db: DB,
+  userId: string,
+  tenantId: string,
+  authVersion: number,
+  resource: string,
+  action: string,
+  requiredScope?: string,
+): Promise<void> {
+  const permissions = await rbac.resolve(db, userId, tenantId, authVersion)
+  const granted = rbac.check(permissions, resource, action, requiredScope)
+  if (!granted) {
+    throw new ForbiddenError(`Missing permission: ${resource}:${action}`)
+  }
+}

package/src/auth/rbac/namespace.ts

@@ -0,0 +1,15 @@
+import { createRbac, hasPermission, enforcePermission, scopeSatisfies, PermissionCache } from './index.js'
+
+/** Role-based access control namespace — permission checking, enforcement, scope hierarchy. */
+export const rbac = {
+  /** Creates an Rbac instance from config (roles, permissions, hierarchy). */
+  create: createRbac,
+  /** Checks if a permission set includes the required resource/action/scope. Pure function, no DB. */
+  check: hasPermission,
+  /** Checks permission and throws ForbiddenError if denied. Loads permissions from DB with caching. */
+  enforce: enforcePermission,
+  /** Checks if a granted scope satisfies a required scope given a hierarchy (e.g. org > team > self). */
+  satisfies: scopeSatisfies,
+  /** LRU cache for resolved permissions — avoids repeated DB lookups within a request. */
+  PermissionCache,
+}

package/src/auth/rbac/resolve.ts

@@ -0,0 +1,31 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import type { RbacConfig, PermissionSet, ResolvedPermission } from './types.js'
+import { quoteIdentifier } from '../../data/db/identifiers.js'
+import { resolveRbacTables } from './tables.js'
+
+export async function resolveUserPermissions(
+  db: DB,
+  userId: string,
+  tenantId: string,
+  authVersion: number,
+  config: RbacConfig,
+): Promise<PermissionSet> {
+  const { userRoles: userRolesTable, rolePermissions: rolePermissionsTable, permissions: permissionsTable } = resolveRbacTables(config)
+
+  const rows = await db.execute(sql`
+    SELECT p.resource, p.action, rp.scope
+    FROM ${sql.raw(quoteIdentifier(userRolesTable, 'userRoles table'))} ur
+    JOIN ${sql.raw(quoteIdentifier(rolePermissionsTable, 'rolePermissions table'))} rp ON rp.role_id = ur.role_id
+    JOIN ${sql.raw(quoteIdentifier(permissionsTable, 'permissions table'))} p ON p.id = rp.permission_id
+    WHERE ur.user_id = ${userId} AND ur.tenant_id = ${tenantId}
+  `)
+
+  const permissions: ResolvedPermission[] = rows.map((row) => ({
+    resource: row['resource'] as string,
+    action: row['action'] as string,
+    scope: row['scope'] as string,
+  }))
+
+  return { userId, tenantId, authVersion, permissions }
+}

package/src/auth/rbac/schema.sql

@@ -0,0 +1,31 @@
+CREATE TABLE IF NOT EXISTS pipework_permissions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  resource text NOT NULL,
+  action text NOT NULL,
+  UNIQUE (resource, action)
+);
+
+CREATE TABLE IF NOT EXISTS pipework_roles (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  name text NOT NULL,
+  tenant_id text NOT NULL,
+  description text,
+  UNIQUE (tenant_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS pipework_role_permissions (
+  role_id uuid NOT NULL REFERENCES pipework_roles(id) ON DELETE CASCADE,
+  permission_id uuid NOT NULL REFERENCES pipework_permissions(id) ON DELETE CASCADE,
+  scope text NOT NULL DEFAULT 'own',
+  PRIMARY KEY (role_id, permission_id),
+  CONSTRAINT valid_scope CHECK (scope = ANY(ARRAY['own', 'team', 'territory', 'tenant']))
+);
+
+CREATE TABLE IF NOT EXISTS pipework_user_roles (
+  user_id text NOT NULL,
+  role_id uuid NOT NULL REFERENCES pipework_roles(id) ON DELETE CASCADE,
+  tenant_id text NOT NULL,
+  PRIMARY KEY (user_id, role_id, tenant_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_user_roles_lookup ON pipework_user_roles (user_id, tenant_id);

package/src/auth/rbac/seed.ts

@@ -0,0 +1,67 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import type { RbacConfig, SeedData } from './types.js'
+import { quoteIdentifier } from '../../data/db/identifiers.js'
+import { resolveRbacTables } from './tables.js'
+
+export async function seedRbac(
+  db: DB,
+  data: SeedData,
+  config: RbacConfig,
+): Promise<void> {
+  const tables = resolveRbacTables(config)
+
+  const permQ = quoteIdentifier(tables.permissions, 'permissions table')
+  const rolesQ = quoteIdentifier(tables.roles, 'roles table')
+  const rolePermQ = quoteIdentifier(tables.rolePermissions, 'rolePermissions table')
+  const userRolesQ = quoteIdentifier(tables.userRoles, 'userRoles table')
+
+  for (const perm of data.permissions) {
+    await db.execute(sql`
+      INSERT INTO ${sql.raw(permQ)} (resource, action)
+      VALUES (${perm.resource}, ${perm.action})
+      ON CONFLICT (resource, action) DO NOTHING
+    `)
+  }
+
+  for (const role of data.roles) {
+    if (role.description !== undefined) {
+      await db.execute(sql`
+        INSERT INTO ${sql.raw(rolesQ)} (name, tenant_id, description)
+        VALUES (${role.name}, ${role.tenantId}, ${role.description})
+        ON CONFLICT (tenant_id, name) DO UPDATE SET
+          description = EXCLUDED.description
+      `)
+    } else {
+      await db.execute(sql`
+        INSERT INTO ${sql.raw(rolesQ)} (name, tenant_id)
+        VALUES (${role.name}, ${role.tenantId})
+        ON CONFLICT (tenant_id, name) DO UPDATE SET
+          description = EXCLUDED.description
+      `)
+    }
+
+    for (const rp of role.permissions) {
+      await db.execute(sql`
+        INSERT INTO ${sql.raw(rolePermQ)} (role_id, permission_id, scope)
+        SELECT r.id, p.id, ${rp.scope}
+        FROM ${sql.raw(rolesQ)} r, ${sql.raw(permQ)} p
+        WHERE r.name = ${role.name} AND r.tenant_id = ${role.tenantId}
+          AND p.resource = ${rp.resource} AND p.action = ${rp.action}
+        ON CONFLICT (role_id, permission_id) DO UPDATE SET scope = EXCLUDED.scope
+      `)
+    }
+  }
+
+  if (data.userRoles) {
+    for (const ur of data.userRoles) {
+      await db.execute(sql`
+        INSERT INTO ${sql.raw(userRolesQ)} (user_id, role_id, tenant_id)
+        SELECT ${ur.userId}, r.id, ${ur.tenantId}
+        FROM ${sql.raw(rolesQ)} r
+        WHERE r.name = ${ur.roleName} AND r.tenant_id = ${ur.tenantId}
+        ON CONFLICT (user_id, role_id, tenant_id) DO NOTHING
+      `)
+    }
+  }
+}

package/src/auth/rbac/tables.ts

@@ -0,0 +1,32 @@
+import type { RbacConfig } from './types.js'
+import { assertValidIdentifier } from '../../data/db/identifiers.js'
+
+export interface RbacTableNames {
+  readonly permissions: string
+  readonly roles: string
+  readonly rolePermissions: string
+  readonly userRoles: string
+}
+
+export const RBAC_TABLE_DEFAULTS: RbacTableNames = {
+  permissions: 'pipework_permissions',
+  roles: 'pipework_roles',
+  rolePermissions: 'pipework_role_permissions',
+  userRoles: 'pipework_user_roles',
+}
+
+export function resolveRbacTables(config: RbacConfig): RbacTableNames {
+  const tables: RbacTableNames = {
+    permissions: config.table?.permissions ?? RBAC_TABLE_DEFAULTS.permissions,
+    roles: config.table?.roles ?? RBAC_TABLE_DEFAULTS.roles,
+    rolePermissions: config.table?.rolePermissions ?? RBAC_TABLE_DEFAULTS.rolePermissions,
+    userRoles: config.table?.userRoles ?? RBAC_TABLE_DEFAULTS.userRoles,
+  }
+
+  assertValidIdentifier(tables.permissions, 'permissions table')
+  assertValidIdentifier(tables.roles, 'roles table')
+  assertValidIdentifier(tables.rolePermissions, 'rolePermissions table')
+  assertValidIdentifier(tables.userRoles, 'userRoles table')
+
+  return tables
+}

package/src/auth/rbac/types.ts

@@ -0,0 +1,65 @@
+import type { DB } from '../../data/db/index.js'
+
+export type Scope = 'own' | 'team' | 'territory' | 'tenant'
+
+export interface RbacConfig {
+  readonly database: string
+  readonly scopes?: readonly string[]
+  readonly cacheTtlMs?: number
+  readonly table?: {
+    readonly permissions?: string
+    readonly roles?: string
+    readonly rolePermissions?: string
+    readonly userRoles?: string
+  }
+}
+
+export interface ResolvedPermission {
+  readonly resource: string
+  readonly action: string
+  readonly scope: string
+}
+
+export interface PermissionSet {
+  readonly userId: string
+  readonly tenantId: string
+  readonly authVersion: number
+  readonly permissions: readonly ResolvedPermission[]
+}
+
+export interface SeedPermission {
+  readonly resource: string
+  readonly action: string
+}
+
+export interface SeedRolePermission {
+  readonly resource: string
+  readonly action: string
+  readonly scope: string
+}
+
+export interface SeedRole {
+  readonly name: string
+  readonly tenantId: string
+  readonly description?: string
+  readonly permissions: readonly SeedRolePermission[]
+}
+
+export interface SeedUserRole {
+  readonly userId: string
+  readonly roleName: string
+  readonly tenantId: string
+}
+
+export interface SeedData {
+  readonly permissions: readonly SeedPermission[]
+  readonly roles: readonly SeedRole[]
+  readonly userRoles?: readonly SeedUserRole[]
+}
+
+export interface Rbac {
+  resolve(db: DB, userId: string, tenantId: string, authVersion: number): Promise<PermissionSet>
+  check(permissions: PermissionSet, resource: string, action: string, requiredScope?: string): boolean
+  invalidate(userId: string, tenantId: string): void
+  seed(db: DB, data: SeedData): Promise<void>
+}