@fabrika/platform-node 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform-node",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -25,6 +25,11 @@
 			"bun": "./src/postgres-migrations.ts",
 			"types": "./src/postgres-migrations.ts",
 			"default": "./src/postgres-migrations.ts"
+		},
+		"./sql": {
+			"bun": "./src/sql.ts",
+			"types": "./src/sql.ts",
+			"default": "./src/sql.ts"
 		}
 	},
 	"scripts": {
@@ -32,6 +37,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/platform": "^0.3.2"
+		"@fabrika/platform": "^0.4.0"
 	}
 }

package/src/application-postgres-grants.ts

@@ -0,0 +1,117 @@
+import type { SqlDatabase } from '@fabrika/platform'
+import { PostgresMigrationError } from './postgres-migration-error'
+
+/** Postgres' `lock_not_available`, which `lock_timeout` raises. */
+const LOCK_NOT_AVAILABLE = '55P03'
+
+const sqlState = (error: unknown): unknown => typeof error === 'object' && error !== null ? Reflect.get(error, 'errno') : undefined
+
+/**
+ * Takes the migration's session-level advisory lock. Any role may take any advisory lock, the application's own
+ * runtime included, so an application's wait is bounded by `timeoutMs`; a service plan waits as long as it takes.
+ */
+export async function acquireMigrationLock(db: SqlDatabase, lockKey: number, timeoutMs: number | undefined, label: string): Promise<void> {
+	const lock = db.prepare(`SELECT pg_catalog.pg_advisory_lock(${lockKey})`)
+	if (timeoutMs === undefined) {
+		await lock.run()
+		return
+	}
+	await db.prepare(`SET lock_timeout = ${timeoutMs}`).run()
+	try {
+		await lock.run()
+	} catch (error) {
+		if (sqlState(error) === LOCK_NOT_AVAILABLE) {
+			throw new PostgresMigrationError(
+				`the migration lock of ${label} was not free within ${timeoutMs} ms: another migration of the application, or a session that holds its advisory lock, still runs`,
+			)
+		}
+		throw error
+	} finally {
+		await db.prepare('RESET lock_timeout').run()
+	}
+}
+
+/**
+ * Clears PUBLIC from the default privileges of the session's role (the migration role), globally and in its schema,
+ * before the plan creates anything. A default the provisioning credential or a superuser set would otherwise hand
+ * every table a later migration creates to the runtime role through PUBLIC.
+ */
+export async function normalizeDefaultPrivileges(db: SqlDatabase, schema: string): Promise<void> {
+	const kinds = ['TABLES', 'SEQUENCES', 'FUNCTIONS', 'TYPES']
+	await db.batch([
+		...kinds.map((kind) => db.prepare(`ALTER DEFAULT PRIVILEGES REVOKE ALL ON ${kind} FROM PUBLIC`)),
+		...kinds.map((kind) => db.prepare(`ALTER DEFAULT PRIVILEGES IN SCHEMA ${schema} REVOKE ALL ON ${kind} FROM PUBLIC`)),
+	])
+}
+
+/**
+ * Resets the schema's privileges to what the runtime role needs: PUBLIC and the runtime role lose everything on the
+ * schema and its objects, then the runtime role gets USAGE, DML on every table but the ledger, EXECUTE on the schema's
+ * routines and USAGE on its types. One transaction, so a live runtime never sees a gap. Then the effective privileges
+ * are verified, PUBLIC included, and anything beyond that stops the deploy.
+ */
+export async function grantRuntimeRole(db: SqlDatabase, schema: string, ledgerTable: string, role: string): Promise<void> {
+	try {
+		await db.batch([
+			db.prepare('SET LOCAL search_path TO pg_catalog, pg_temp'),
+			db.prepare(`REVOKE ALL ON SCHEMA ${schema} FROM PUBLIC, ${role}`),
+			db.prepare(`REVOKE ALL ON ALL TABLES IN SCHEMA ${schema} FROM PUBLIC, ${role}`),
+			db.prepare(`REVOKE ALL ON ALL SEQUENCES IN SCHEMA ${schema} FROM PUBLIC, ${role}`),
+			db.prepare(`REVOKE ALL ON ALL ROUTINES IN SCHEMA ${schema} FROM PUBLIC, ${role}`),
+			db.prepare(`DO $types$
+				DECLARE t pg_catalog.regtype;
+				BEGIN
+					FOR t IN SELECT y.oid::pg_catalog.regtype FROM pg_catalog.pg_type y LEFT JOIN pg_catalog.pg_class c ON c.oid = y.typrelid
+						WHERE y.typnamespace = '${schema}'::pg_catalog.regnamespace AND (y.typtype IN ('e', 'd', 'r') OR c.relkind = 'c')
+					LOOP
+						EXECUTE pg_catalog.format('REVOKE ALL ON TYPE %s FROM PUBLIC, ${role}', t);
+						EXECUTE pg_catalog.format('GRANT USAGE ON TYPE %s TO ${role}', t);
+					END LOOP;
+				END $types$`),
+			db.prepare(`GRANT USAGE ON SCHEMA ${schema} TO ${role}`),
+			db.prepare(`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ${schema} TO ${role}`),
+			db.prepare(`REVOKE ALL ON TABLE ${ledgerTable} FROM ${role}`),
+			db.prepare(`GRANT EXECUTE ON ALL ROUTINES IN SCHEMA ${schema} TO ${role}`),
+		])
+	} catch (error) {
+		throw new PostgresMigrationError(`granting the runtime role ${role} its privileges in ${schema} failed`, { cause: error })
+	}
+	await verifyRuntimeRole(db, schema, ledgerTable, role)
+}
+
+interface Problem {
+	readonly problem: string
+}
+
+/** The runtime role's effective privileges in its schema, PUBLIC's included, and the migration role's default privileges. */
+async function verifyRuntimeRole(db: SqlDatabase, schema: string, ledgerTable: string, role: string): Promise<void> {
+	const { results } = await db.prepare(`
+		WITH runtime AS (SELECT oid, rolname FROM pg_catalog.pg_roles WHERE rolname OPERATOR(pg_catalog.=) ?::pg_catalog.name),
+			ledger AS (SELECT pg_catalog.to_regclass(?::pg_catalog.text) AS oid),
+			table_privileges AS (
+				SELECT pg_catalog.unnest(CASE WHEN pg_catalog.current_setting('server_version_num')::pg_catalog.int4 OPERATOR(pg_catalog.>=) 170000
+					THEN ARRAY['TRUNCATE', 'REFERENCES', 'TRIGGER', 'MAINTAIN'] ELSE ARRAY['TRUNCATE', 'REFERENCES', 'TRIGGER'] END) AS privilege)
+		SELECT pg_catalog.format('%s may create objects in schema %s', runtime.rolname, ?::pg_catalog.text) AS problem FROM runtime
+			WHERE pg_catalog.has_schema_privilege(runtime.oid, ?::pg_catalog.text, 'CREATE')
+		UNION ALL
+		SELECT pg_catalog.format('%s holds %s on %s', runtime.rolname, p.privilege, c.oid::pg_catalog.regclass) FROM runtime, table_privileges p, pg_catalog.pg_class c
+			WHERE c.relnamespace OPERATOR(pg_catalog.=) ?::pg_catalog.regnamespace AND c.relkind OPERATOR(pg_catalog.=) ANY (ARRAY['r', 'p', 'v', 'm', 'f']::"char"[])
+				AND pg_catalog.has_table_privilege(runtime.oid, c.oid, p.privilege)
+		UNION ALL
+		SELECT pg_catalog.format('%s may %s the migration ledger', runtime.rolname, p.privilege) FROM runtime, ledger, pg_catalog.unnest(ARRAY['SELECT', 'INSERT', 'UPDATE', 'DELETE']) AS p(privilege)
+			WHERE pg_catalog.has_table_privilege(runtime.oid, ledger.oid, p.privilege)
+				OR (p.privilege OPERATOR(pg_catalog.<>) 'DELETE' AND pg_catalog.has_any_column_privilege(runtime.oid, ledger.oid, p.privilege))
+		UNION ALL
+		SELECT pg_catalog.format('a default privilege of %s grants %s on every new object of kind %s to %s', pg_catalog.pg_get_userbyid(d.defaclrole),
+				a.privilege_type, d.defaclobjtype, CASE WHEN a.grantee OPERATOR(pg_catalog.=) 0 THEN 'PUBLIC' ELSE pg_catalog.pg_get_userbyid(a.grantee) END)
+			FROM pg_catalog.pg_default_acl d, pg_catalog.aclexplode(d.defaclacl) a
+			WHERE d.defaclrole OPERATOR(pg_catalog.=) (SELECT oid FROM pg_catalog.pg_roles WHERE rolname OPERATOR(pg_catalog.=) current_user)
+				AND a.grantee OPERATOR(pg_catalog.<>) d.defaclrole`).bind(role, ledgerTable, schema, schema, schema).all<Problem>()
+	if (results.length > 0) {
+		throw new PostgresMigrationError(
+			`${
+				results.map((row) => row.problem).join('; ')
+			}; the deploy stops, because the runtime role ${role} has DML on its tables and nothing else (ADR-0017)`,
+		)
+	}
+}

package/src/application-postgres-migrations.ts

@@ -0,0 +1,152 @@
+import type { SqlDatabase } from '@fabrika/platform'
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { type ApplicationDatabaseRoles, dropPostgresRoles, postgresRoleUrl, provisionPostgresRoles } from './application-postgres-roles'
+import { applicationDatabaseSchema, validateApplicationId } from './application-schema'
+import { classifyMigrations, type DatabaseObject } from './migration-classify'
+import {
+	applyPostgresMigrations,
+	definePostgresMigrationPlan,
+	type PostgresMigration,
+	PostgresMigrationError,
+	type PostgresMigrationPlan,
+	readPostgresMigrationBundle,
+} from './postgres-migrations'
+import { PostgresDatabase } from './sql-postgres'
+
+/** The file-name contract the checker enforces (`db/migrations/`, `@fabrika/check`); timestamps keep worktrees apart. */
+const APPLICATION_MIGRATION_NAME = /^\d{14}_[a-z0-9]+(?:_[a-z0-9]+)*\.sql$/
+
+/** Migration identity of every application (ADR-0017): bundle `app`, ledger `app_<id>.fabrika_migrations`. */
+export const APPLICATION_MIGRATION_BUNDLE = 'app'
+export const APPLICATION_MIGRATION_LEDGER = 'fabrika_migrations'
+/** Fails a migration that waits this long for a lock, so a blocked `ALTER` does not queue the live version's queries. */
+export const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 5_000
+/** Bounds a statement such as a backfill or a non-concurrent index build, which holds its lock while it runs. */
+export const DEFAULT_MIGRATION_STATEMENT_TIMEOUT_MS = 60_000
+/** How long `migrate` waits for the application's migration lock: another container's migrations, or a stray holder. */
+export const DEFAULT_MIGRATION_ADVISORY_LOCK_TIMEOUT_MS = 300_000
+
+export interface PostgresApplicationMigrationsConfig {
+	readonly appId: string
+	/** The application's `db/migrations/` directory. */
+	readonly directory: string
+	readonly lockTimeoutMs?: number
+	readonly statementTimeoutMs?: number
+	readonly advisoryLockTimeoutMs?: number
+	/**
+	 * The framework's own tables (`fabrika_*`, `@fabrika/db/migrations`), applied as their own bundle before the
+	 * application's, in the same ledger and under the same checksum rule.
+	 */
+	readonly framework?: { readonly bundle: string; readonly migrations: readonly PostgresMigration[] }
+}
+
+export interface PostgresApplicationMigrations {
+	/** `app_<id>`: the application's schema, which the data layer sets as its `search_path`. */
+	readonly schema: string
+	readonly roles: ApplicationDatabaseRoles
+	read(): PostgresMigration[]
+	plan(migrations?: readonly PostgresMigration[]): PostgresMigrationPlan
+	/**
+	 * The manifest of the framework's and the application's migrations: the database objects they declare, which the
+	 * catalog check admits at every start (`fabrika db codegen`) as the runner does before each commit.
+	 */
+	objects(migrations?: readonly PostgresMigration[]): DatabaseObject[]
+	/** Applies the plan over `db` as whatever role it connects as, and grants no runtime role: the runner's own tests. */
+	apply(db: SqlDatabase, migrations?: readonly PostgresMigration[]): Promise<string[]>
+	/**
+	 * What `fabrika db migrate` runs. With the provisioning credential it creates or checks the role family and the
+	 * schema; then it applies the plan as the migration role and grants the runtime role. No migration runs as the
+	 * provisioning credential, and a credential that cannot create roles is refused.
+	 */
+	migrate(provisioningUrl: string, migrations?: readonly PostgresMigration[]): Promise<string[]>
+}
+
+/** The first 48 bits of SHA-256(`fabrika-db:<appId>`), plus one: applications sharing a database do not serialize each other. */
+export function applicationMigrationLockKey(appId: string): number {
+	validateApplicationId(appId)
+	return createHash('sha256').update(`fabrika-db:${appId}`, 'utf8').digest().readUIntBE(0, 6) + 1
+}
+
+/** The application's schema, its migration role (named like the schema) and its runtime role `run_<id>`. */
+export function applicationDatabaseRoles(appId: string): ApplicationDatabaseRoles {
+	const schema = applicationDatabaseSchema(appId)
+	return { schema, migration: schema, runtime: `run_${schema.slice('app_'.length)}` }
+}
+
+/** The runtime role's connection URL, derived from the provisioning credential the platform hands the application. */
+export function applicationRuntimeUrl(provisioningUrl: string, appId: string): string {
+	return postgresRoleUrl(provisioningUrl, applicationDatabaseRoles(appId).runtime)
+}
+
+/** Drops an application's schema and both of its roles, as the provisioning credential: for throwaway test databases. */
+export async function dropApplicationDatabase(provisioningUrl: string, appId: string): Promise<void> {
+	const admin = PostgresDatabase.connect(provisioningUrl, { max: 1 })
+	try {
+		await dropPostgresRoles(admin, applicationDatabaseRoles(appId))
+	} finally {
+		await admin.close()
+	}
+}
+
+/** An application's migration wrapper: its schema, ledger, lock and timeouts are derived, never configured. */
+export function definePostgresApplicationMigrations(config: PostgresApplicationMigrationsConfig): PostgresApplicationMigrations {
+	const roles = applicationDatabaseRoles(config.appId)
+	const { schema } = roles
+	const lockKey = applicationMigrationLockKey(config.appId)
+	const advisoryLockTimeoutMs = config.advisoryLockTimeoutMs ?? DEFAULT_MIGRATION_ADVISORY_LOCK_TIMEOUT_MS
+	const read = (): PostgresMigration[] => {
+		if (!existsSync(config.directory)) {
+			throw new PostgresMigrationError(`No migrations directory at ${config.directory}; create the first migration with fabrika db new <slug>`)
+		}
+		const { migrations } = readPostgresMigrationBundle({ name: APPLICATION_MIGRATION_BUNDLE, directory: config.directory })
+		return [...migrations]
+	}
+	const planWith = (migrations: readonly PostgresMigration[], runtimeRole: string | undefined): PostgresMigrationPlan => {
+		for (const migration of migrations) {
+			if (!APPLICATION_MIGRATION_NAME.test(migration.name)) {
+				throw new PostgresMigrationError(`Application migration ${migration.name} is not named YYYYMMDDHHMMSS_slug.sql`)
+			}
+		}
+		return definePostgresMigrationPlan({
+			ledgerTable: `${schema}.${APPLICATION_MIGRATION_LEDGER}`,
+			lockKey,
+			bundles: [
+				...(config.framework === undefined ? [] : [{ name: config.framework.bundle, migrations: config.framework.migrations }]),
+				{ name: APPLICATION_MIGRATION_BUNDLE, migrations },
+			],
+			application: {
+				schema,
+				lockTimeoutMs: config.lockTimeoutMs ?? DEFAULT_MIGRATION_LOCK_TIMEOUT_MS,
+				statementTimeoutMs: config.statementTimeoutMs ?? DEFAULT_MIGRATION_STATEMENT_TIMEOUT_MS,
+				...(config.framework === undefined ? {} : { frameworkBundle: config.framework.bundle }),
+				...(runtimeRole === undefined ? {} : { runtimeRole, advisoryLockTimeoutMs }),
+			},
+		})
+	}
+	const plan = (migrations: readonly PostgresMigration[] = read()): PostgresMigrationPlan => planWith(migrations, undefined)
+	const objects = (migrations: readonly PostgresMigration[] = read()): DatabaseObject[] => {
+		const framework = (config.framework?.migrations ?? []).map((migration) => ({ ...migration, framework: true }))
+		return [...classifyMigrations([...framework, ...migrations], schema).objects]
+	}
+	const apply = async (db: SqlDatabase, migrations: readonly PostgresMigration[] = read()): Promise<string[]> =>
+		applyPostgresMigrations(db, plan(migrations))
+	const migrate = async (provisioningUrl: string, migrations: readonly PostgresMigration[] = read()): Promise<string[]> => {
+		const planned = planWith(migrations, roles.runtime)
+		const migrationUrl = postgresRoleUrl(provisioningUrl, roles.migration)
+		// One connection each: the advisory lock is session state.
+		const admin = PostgresDatabase.connect(provisioningUrl, { max: 1 })
+		try {
+			await provisionPostgresRoles(admin, provisioningUrl, roles, { key: lockKey, timeoutMs: advisoryLockTimeoutMs })
+		} finally {
+			await admin.close()
+		}
+		const owner = PostgresDatabase.connect(migrationUrl, { max: 1 })
+		try {
+			return await applyPostgresMigrations(owner, planned)
+		} finally {
+			await owner.close()
+		}
+	}
+	return { schema, roles, read, plan, objects, apply, migrate }
+}

package/src/application-postgres-roles.ts

@@ -0,0 +1,239 @@
+import type { SqlDatabase } from '@fabrika/platform'
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from 'node:crypto'
+import { acquireMigrationLock } from './application-postgres-grants'
+import { PostgresMigrationError } from './postgres-migration-error'
+
+/** An application's schema and the two roles that reach it (ADR-0017). */
+export interface ApplicationDatabaseRoles {
+	/** `app_<id>`. */
+	readonly schema: string
+	/** Owns the schema and every object in it, so it is the only role that runs DDL there. Named like the schema. */
+	readonly migration: string
+	/** `run_<id>`: DML on the schema's tables except the migration ledger, and nothing else. */
+	readonly runtime: string
+}
+
+const ROLE_NAME = /^(?:app|run)_[a-z0-9_]{1,59}$/
+const SCRAM_ITERATIONS = 4096
+
+function validateRoles(roles: ApplicationDatabaseRoles): void {
+	for (const name of [roles.schema, roles.migration, roles.runtime]) {
+		if (!ROLE_NAME.test(name)) throw new PostgresMigrationError(`Invalid application database role or schema: ${name}`)
+	}
+}
+
+export function provisioningCredential(provisioningUrl: string): { readonly url: URL; readonly password: string } {
+	let url: URL
+	try {
+		url = new URL(provisioningUrl)
+	} catch {
+		throw new PostgresMigrationError('the provisioning credential is not a connection URL')
+	}
+	const password = decodeURIComponent(url.password)
+	if (password === '') {
+		throw new PostgresMigrationError("the provisioning credential has no password; the application's database roles derive theirs from it")
+	}
+	return { url, password }
+}
+
+/** HMAC-SHA-256 of the role's name under the provisioning password: whoever holds that credential derives it, so nothing stores it. */
+function derivedPassword(provisioningPassword: string, role: string): string {
+	return createHmac('sha256', provisioningPassword).update(`fabrika-db-role:${role}`, 'utf8').digest('base64url')
+}
+
+/** Postgres' SCRAM-SHA-256 verifier (RFC 7677): the password itself never reaches the server, so no statement log holds it. */
+export function scramVerifier(password: string): string {
+	const salt = randomBytes(16)
+	const salted = pbkdf2Sync(password, salt, SCRAM_ITERATIONS, 32, 'sha256')
+	const storedKey = createHash('sha256').update(createHmac('sha256', salted).update('Client Key').digest()).digest()
+	const serverKey = createHmac('sha256', salted).update('Server Key').digest()
+	return `SCRAM-SHA-256$${SCRAM_ITERATIONS}:${salt.toString('base64')}$${storedKey.toString('base64')}:${serverKey.toString('base64')}`
+}
+
+/** The URL `role` connects with: the provisioning URL's host, database and options, the role's name and derived password. */
+export function postgresRoleUrl(provisioningUrl: string, role: string): string {
+	const { url, password } = provisioningCredential(provisioningUrl)
+	url.username = role
+	url.password = derivedPassword(password, role)
+	return url.toString()
+}
+
+interface ProvisioningRole {
+	readonly rolname: string
+	readonly rolsuper: boolean
+	readonly rolcreaterole: boolean
+}
+
+interface RoleReach {
+	readonly rolname: string
+	readonly attributes: string | null
+	readonly memberships: string | null
+	readonly creates_schemas: boolean
+	readonly creates_in: string | null
+}
+
+/**
+ * Creates the role family and the schema when absent, resets both roles' passwords to their derived values, and refuses
+ * a family that holds more than it should. Runs over one connection of the provisioning credential, under the
+ * application's migration lock, so two containers starting together do not race on the same catalog rows.
+ */
+export async function provisionPostgresRoles(
+	admin: SqlDatabase,
+	provisioningUrl: string,
+	roles: ApplicationDatabaseRoles,
+	lock: { readonly key: number; readonly timeoutMs: number },
+): Promise<void> {
+	validateRoles(roles)
+	const { password } = provisioningCredential(provisioningUrl)
+	// A dedicated session: nothing an application created can shadow a catalog function here.
+	await admin.prepare('SET search_path TO pg_catalog, pg_temp').run()
+	await acquireMigrationLock(admin, lock.key, lock.timeoutMs, roles.schema)
+	try {
+		const self = await admin.prepare('SELECT rolname, rolsuper, rolcreaterole FROM pg_roles WHERE rolname = current_user').first<ProvisioningRole>()
+		if (self === null || (!self.rolsuper && !self.rolcreaterole)) {
+			throw new PostgresMigrationError(
+				`the provisioning credential connects as ${
+					self?.rolname ?? 'an unknown role'
+				}, which is neither a superuser nor holds CREATEROLE, so it cannot create the application's database roles ${roles.migration} and ${roles.runtime}; nothing runs as the provisioning credential instead`,
+			)
+		}
+		for (const role of [roles.migration, roles.runtime]) {
+			const verifier = scramVerifier(derivedPassword(password, role))
+			const exists = await admin.prepare('SELECT true AS present FROM pg_roles WHERE rolname = ?').bind(role).first()
+			// Defaults are NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS; `verifyRoles` holds an existing role to them.
+			if (exists === null) {
+				await admin.prepare(`CREATE ROLE ${role} LOGIN NOINHERIT PASSWORD '${verifier}'`).run()
+				continue
+			}
+			await admin.prepare(`ALTER ROLE ${role} WITH LOGIN PASSWORD '${verifier}'`).run()
+			// A role may set its own session defaults (`ALTER ROLE CURRENT_USER SET …`); each deploy starts it clean.
+			await admin.prepare(`ALTER ROLE ${role} RESET ALL`).run()
+		}
+		// A CREATEROLE role holds only ADMIN on a role it created; creating a schema for it needs SET (Postgres 16).
+		if (!self.rolsuper) await admin.prepare(`GRANT ${roles.migration} TO CURRENT_USER`).run()
+		const schema = await admin.prepare('SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = ?').bind(roles.schema).first<{
+			owner: string
+		}>()
+		if (schema === null) {
+			await admin.prepare(`CREATE SCHEMA ${roles.schema} AUTHORIZATION ${roles.migration}`).run()
+		} else if (schema.owner !== roles.migration) {
+			throw new PostgresMigrationError(
+				`schema ${roles.schema} is owned by ${schema.owner}, not by its migration role ${roles.migration}: it predates the application's database roles and is not adopted; drop it to start over, or make ${roles.migration} the owner of the schema and of every object in it`,
+			)
+		}
+		await verifyRoles(admin, roles)
+		await verifyForeignReach(admin, roles)
+	} finally {
+		await admin.prepare(`SELECT pg_advisory_unlock(${lock.key})`).run()
+	}
+}
+
+/** Fails closed on any reach beyond the family's: a widened attribute, a membership, or CREATE outside the migration role's schema. */
+async function verifyRoles(admin: SqlDatabase, roles: ApplicationDatabaseRoles): Promise<void> {
+	const { results } = await admin.prepare(`SELECT r.rolname,
+			concat_ws(', ',
+				CASE WHEN r.rolsuper THEN 'SUPERUSER' END, CASE WHEN r.rolcreaterole THEN 'CREATEROLE' END,
+				CASE WHEN r.rolcreatedb THEN 'CREATEDB' END, CASE WHEN r.rolreplication THEN 'REPLICATION' END,
+				CASE WHEN r.rolbypassrls THEN 'BYPASSRLS' END) AS attributes,
+			(SELECT string_agg(pg_get_userbyid(m.roleid), ', ' ORDER BY pg_get_userbyid(m.roleid)) FROM pg_auth_members m WHERE m.member = r.oid) AS memberships,
+			has_database_privilege(r.oid, current_database(), 'CREATE') AS creates_schemas,
+			(SELECT string_agg(n.nspname, ', ' ORDER BY n.nspname) FROM pg_namespace n WHERE has_schema_privilege(r.oid, n.oid, 'CREATE')) AS creates_in
+		FROM pg_roles r WHERE r.rolname IN (?, ?)`).bind(roles.migration, roles.runtime).all<RoleReach>()
+	const problems: string[] = []
+	for (const role of results) {
+		const subject = `the database role ${role.rolname}`
+		if (role.attributes !== null && role.attributes !== '') problems.push(`${subject} holds ${role.attributes}`)
+		if (role.memberships !== null) problems.push(`${subject} is a member of ${role.memberships}`)
+		if (role.creates_schemas) problems.push(`${subject} may create schemas in the database`)
+		const allowed = role.rolname === roles.migration ? roles.schema : null
+		if (role.creates_in !== allowed) {
+			problems.push(`${subject} may create objects in ${role.creates_in ?? 'no schema'} (allowed: ${allowed ?? 'none'})`)
+		}
+	}
+	if (results.length !== 2) problems.push(`the database roles ${roles.migration} and ${roles.runtime} do not both exist`)
+	if (problems.length > 0) {
+		throw new PostgresMigrationError(
+			`${problems.join('; ')}; the deploy stops until it is undone, because these roles bound what the application's SQL may do (ADR-0017)`,
+		)
+	}
+}
+
+interface ForeignGrant {
+	readonly role: string
+	readonly object: string
+	readonly privileges: string
+}
+
+/**
+ * Fails closed on any reach of the family into the rest of the database: a privilege either role was granted, or
+ * ownership it holds, on a schema, relation, column, routine, type, the database, a large object or a parameter outside
+ * its schema; and a SECURITY DEFINER routine either may call, which would run as its owner. PUBLIC's own defaults
+ * (CONNECT, TEMP, EXECUTE on built-ins) are not grants to the roles; a large object a role created itself is its own.
+ */
+async function verifyForeignReach(admin: SqlDatabase, roles: ApplicationDatabaseRoles): Promise<void> {
+	const { results } = await admin.prepare(`
+		WITH family AS (SELECT oid, rolname FROM pg_roles WHERE rolname IN (?, ?)),
+			own AS (SELECT oid FROM pg_namespace WHERE nspname = ?),
+			objects (rank, object, owner, acl) AS (
+				SELECT 1, 'schema ' || quote_ident(nspname), nspowner, nspacl FROM pg_namespace WHERE oid NOT IN (SELECT oid FROM own)
+				UNION ALL SELECT 2, CASE relkind WHEN 'S' THEN 'sequence ' WHEN 'v' THEN 'view ' WHEN 'm' THEN 'materialized view ' ELSE 'table ' END
+					|| relnamespace::regnamespace || '.' || quote_ident(relname), relowner, relacl
+					FROM pg_class WHERE relnamespace NOT IN (SELECT oid FROM own) AND relkind IN ('r', 'p', 'v', 'm', 'f', 'S')
+				UNION ALL SELECT 3, 'column ' || c.relnamespace::regnamespace || '.' || quote_ident(c.relname) || '.' || quote_ident(a.attname), c.relowner, a.attacl
+					FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid WHERE a.attacl IS NOT NULL AND c.relnamespace NOT IN (SELECT oid FROM own)
+				UNION ALL SELECT 4, 'function ' || oid::regprocedure, proowner, proacl FROM pg_proc WHERE pronamespace NOT IN (SELECT oid FROM own)
+				UNION ALL SELECT 5, 'type ' || oid::regtype, typowner, typacl FROM pg_type WHERE typnamespace NOT IN (SELECT oid FROM own)
+				UNION ALL SELECT 6, 'database ' || quote_ident(datname), datdba, datacl FROM pg_database WHERE datname = current_database()
+				UNION ALL SELECT 7, 'large object ' || oid, lomowner, lomacl FROM pg_largeobject_metadata
+				UNION ALL SELECT 8, 'parameter ' || parname, NULL, paracl FROM pg_parameter_acl
+			)
+		SELECT f.rolname AS role, o.object, string_agg(DISTINCT a.privilege_type, ', ') AS privileges
+			FROM objects o CROSS JOIN LATERAL aclexplode(o.acl) a JOIN family f ON f.oid = a.grantee
+			WHERE o.owner IS DISTINCT FROM a.grantee
+			GROUP BY f.rolname, o.rank, o.object
+		UNION ALL
+		SELECT f.rolname, o.object, 'OWNER' FROM objects o JOIN family f ON f.oid = o.owner WHERE o.rank NOT IN (6, 7)
+		ORDER BY 1, 2`).bind(roles.migration, roles.runtime, roles.schema).all<ForeignGrant>()
+	const problems: string[] = []
+	for (const role of [roles.migration, roles.runtime]) {
+		const held = results.filter((grant) => grant.role === role).map((grant) => `${grant.object} (${grant.privileges})`)
+		if (held.length > 0) problems.push(`the database role ${role} holds privileges outside its schema: ${held.join(', ')}`)
+	}
+	const { results: definers } = await admin.prepare(`
+		SELECT p.oid::regprocedure::text AS routine, pg_get_userbyid(p.proowner) AS owner FROM pg_proc p
+			WHERE p.prosecdef AND p.pronamespace NOT IN ('pg_catalog'::regnamespace, 'information_schema'::regnamespace)
+				AND p.proowner NOT IN (SELECT oid FROM pg_roles WHERE rolname IN (?, ?))
+				AND EXISTS (SELECT 1 FROM pg_roles r WHERE r.rolname IN (?, ?)
+					AND has_schema_privilege(r.oid, p.pronamespace, 'USAGE') AND has_function_privilege(r.oid, p.oid, 'EXECUTE'))
+			ORDER BY 1`).bind(roles.migration, roles.runtime, roles.migration, roles.runtime).all<{ routine: string; owner: string }>()
+	for (const definer of definers) {
+		problems.push(
+			`the SECURITY DEFINER function ${definer.routine} runs as ${definer.owner} and the application's roles may call it; revoke EXECUTE on it from PUBLIC or drop it`,
+		)
+	}
+	if (problems.length > 0) {
+		throw new PostgresMigrationError(`${problems.join('; ')}; the deploy stops, because these roles bound what the application's SQL may do (ADR-0017)`)
+	}
+}
+
+export const quotedIdentifier = (name: string): string => `"${name.replaceAll('"', '""')}"`
+
+/**
+ * Drops the schema and both roles: for throwaway test databases only. The schema is dropped as its owner, which a
+ * CREATEROLE provisioning credential may become (`provisionPostgresRoles` granted it the migration role).
+ */
+export async function dropPostgresRoles(admin: SqlDatabase, roles: ApplicationDatabaseRoles): Promise<void> {
+	validateRoles(roles)
+	const schema = await admin.prepare('SELECT pg_catalog.pg_get_userbyid(nspowner) AS owner FROM pg_catalog.pg_namespace WHERE nspname = ?').bind(
+		roles.schema,
+	).first<{ owner: string }>()
+	if (schema !== null) {
+		await admin.batch([admin.prepare(`SET LOCAL ROLE ${quotedIdentifier(schema.owner)}`), admin.prepare(`DROP SCHEMA ${roles.schema} CASCADE`)])
+	}
+	// The migration role's default privileges (`normalizeDefaultPrivileges`) are objects of its own that block DROP ROLE.
+	const migration = await admin.prepare('SELECT true AS present FROM pg_catalog.pg_roles WHERE rolname = ?').bind(roles.migration).first()
+	if (migration !== null) {
+		await admin.batch([admin.prepare(`SET LOCAL ROLE ${roles.migration}`), admin.prepare(`DROP OWNED BY ${roles.migration}`)])
+	}
+	await admin.prepare(`DROP ROLE IF EXISTS ${roles.runtime}, ${roles.migration}`).run()
+}

package/src/application-schema.ts

@@ -0,0 +1,21 @@
+// The application's schema name (ADR-0017), runtime-neutral: the runner derives it, and Control classifies a commit's
+// migrations against the same name in a Worker.
+
+import { PostgresMigrationError } from './postgres-migration-error'
+
+/** IAM's application id alphabet; `-` maps to `_`, which the alphabet lacks, so two ids never share a schema. */
+const APP_ID = /^[a-z0-9][a-z0-9-]*$/
+/** Postgres truncates identifiers to 63 bytes; `app_` takes four of them. */
+const MAX_APP_ID_LENGTH = 59
+
+export function validateApplicationId(appId: string): void {
+	if (!APP_ID.test(appId) || appId.length > MAX_APP_ID_LENGTH) {
+		throw new PostgresMigrationError(`Invalid application id for a database schema: ${appId} (lowercase letters, digits and -, at most 59)`)
+	}
+}
+
+/** `app_<id>`: the schema an application's migrations create and its data layer sets as its `search_path`. */
+export function applicationDatabaseSchema(appId: string): string {
+	validateApplicationId(appId)
+	return `app_${appId.replaceAll('-', '_')}`
+}

package/src/blob-s3.ts

@@ -9,7 +9,15 @@
 // same round trip, whereas S3 needs a HEAD first. `get()` therefore costs one extra request on a hit.
 // Nothing here logs the credentials, the endpoint, or an error object that might quote a signed URL.
 
-import type { BlobStore } from '@fabrika/platform'
+import {
+	type BlobStore,
+	type FileObjectStore,
+	ObjectExistsError,
+	type ObjectMetadata,
+	ObjectTooLargeError,
+	type ObjectWriteOptions,
+	type StoredObject,
+} from '@fabrika/platform'
 
 /** Connection details for an S3-compatible bucket. `endpoint` is what makes it R2, MinIO, or AWS. */
 export interface S3BlobStoreOptions {
@@ -32,7 +40,7 @@ interface BlobBody {
 	text(): Promise<string>
 }
 
-export class S3BlobStore implements BlobStore {
+export class S3BlobStore implements BlobStore, FileObjectStore {
 	constructor(private readonly client: Bun.S3Client) {}
 
 	/** Build a store from plain connection options. Never logs them. */
@@ -76,4 +84,82 @@ export class S3BlobStore implements BlobStore {
 	async delete(key: string): Promise<void> {
 		await this.client.delete(key)
 	}
+
+	async write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata> {
+		// Bun's client sends no `If-None-Match`; a file's key is a fresh UUID behind a unique row, and a download checks
+		// the version the scan recorded, so this check refuses a reused key rather than racing a concurrent writer.
+		if ((await statOrNull(this.client.file(key))) !== null) {
+			await body.cancel()
+			throw new ObjectExistsError()
+		}
+		let size = 0
+		// Erroring the transform cancels `body` and fails the upload, so no more than one chunk past the limit is read.
+		const bounded = body.pipeThrough(
+			new TransformStream<Uint8Array, Uint8Array>({
+				transform(chunk, controller) {
+					size += chunk.byteLength
+					if (size > options.maxBytes) {
+						controller.error(new ObjectTooLargeError(options.maxBytes))
+						return
+					}
+					controller.enqueue(chunk)
+				},
+			}),
+		)
+		try {
+			await this.client.write(key, new Response(bounded), { type: options.contentType })
+		} catch (error) {
+			await this.client.delete(key).catch(() => undefined)
+			throw size > options.maxBytes ? new ObjectTooLargeError(options.maxBytes) : error
+		}
+		return { size, contentType: options.contentType }
+	}
+
+	read(key: string, signal?: AbortSignal): Promise<StoredObject | null> {
+		return this.#get(key, {}, signal)
+	}
+
+	readVersion(key: string, version: string, signal?: AbortSignal): Promise<StoredObject | null> {
+		return this.#get(key, { 'If-Match': version }, signal)
+	}
+
+	/**
+	 * One GET through a short-lived presigned URL, so the ETag, the size and the body come from the same answer and a
+	 * conditional header can be sent, which `Bun.S3File` does not offer. Errors never carry the URL: it is signed.
+	 */
+	async #get(key: string, headers: Readonly<Record<string, string>>, signal: AbortSignal | undefined): Promise<StoredObject | null> {
+		const url = this.client.file(key).presign({ method: 'GET', expiresIn: PRESIGNED_READ_SECONDS })
+		let response: Response
+		try {
+			response = await fetch(url, { headers, ...(signal === undefined ? {} : { signal }) })
+		} catch {
+			throw new Error(signal?.aborted === true ? 'the object read was stopped' : 'the object store did not answer a read')
+		}
+		if (response.status === 404 || response.status === 412) {
+			await response.body?.cancel()
+			return null
+		}
+		const version = response.headers.get('ETag')
+		const size = Number(response.headers.get('Content-Length'))
+		if (!response.ok || response.body === null || version === null || !Number.isSafeInteger(size)) {
+			await response.body?.cancel()
+			throw new Error(`the object store answered a read with ${response.status}`)
+		}
+		const type = response.headers.get('Content-Type')
+		return { size, contentType: type === null || type === '' ? null : type, version, body: response.body }
+	}
+}
+
+const PRESIGNED_READ_SECONDS = 60
+
+/** One HEAD; a missing key is `null`, any other failure propagates. */
+async function statOrNull(file: Bun.S3File): Promise<Bun.S3Stats | null> {
+	try {
+		return await file.stat()
+	} catch (error) {
+		if (error instanceof Error && 'code' in error && error.code === 'NoSuchKey') {
+			return null
+		}
+		throw error
+	}
 }