Files
MikrotikManager/backend/src/db/controlled-migrations.ts
T

146 lines
11 KiB
TypeScript

import { createHash, randomUUID } from "node:crypto"
import { readdir, readFile } from "node:fs/promises"
import type { PoolClient } from "pg"
import { acquireDatabaseSchemaControl } from "./database-schema-control.js"
import { checkDatabaseSchemaControlState, type DatabaseSchemaIntent, type DatabaseSchemaTerminal } from "./database-schema-control-model.js"
import { analyzeMigration, MIGRATION_MANIFEST, migrationManifestDigest, validateMigrationFileSet, type MigrationReview } from "./migration-manifest.js"
import { PARTITION_WRITER_ADVISORY_KEY } from "../services/partition-write-transaction.js"
import { fingerprint, privateSecretFingerprint } from "../modules/mcp/security.js"
/** Opt-in internal dispatcher only. Default startup remains on the old path.
* Control DDL/enrollment, imports, data verification and READY are absent. */
export const CONTROLLED_MIGRATIONS_SQL = Object.freeze({
history: `SELECT id::text AS id, intent, terminal FROM mmapp_control.database_schema_intents ORDER BY id LIMIT ${MIGRATION_MANIFEST.length + 1}`,
namespaces: "SELECT nspname AS name FROM pg_catalog.pg_namespace WHERE nspname !~ '^pg_' AND nspname <> 'information_schema' ORDER BY nspname",
publicObjects: "SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_depend WHERE refclassid = 'pg_catalog.pg_namespace'::pg_catalog.regclass AND refobjid = 'public'::pg_catalog.regnamespace) OR EXISTS (SELECT 1 FROM pg_catalog.pg_extension WHERE extnamespace = 'public'::pg_catalog.regnamespace) AS present",
markerTable: "SELECT c.relkind::text AS kind, c.relpersistence::text AS persistence, c.relrowsecurity AS rls, c.relforcerowsecurity AS force_rls, EXISTS (SELECT 1 FROM pg_catalog.pg_trigger t WHERE t.tgrelid = c.oid AND NOT t.tgisinternal) AS user_triggers FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'public' AND c.relname = 'schema_migrations'",
markers: `SELECT id FROM public.schema_migrations ORDER BY id LIMIT ${MIGRATION_MANIFEST.length + 1}`,
marker: "INSERT INTO public.schema_migrations (id) VALUES ($1)",
})
export class ControlledMigrationsError extends Error {
readonly code = "CONTROLLED_MIGRATIONS_REFUSED"
constructor(message: string, readonly outcomeUnknown = false, options?: ErrorOptions) { super(message, options) }
}
const refuse = (message: string): never => { throw new ControlledMigrationsError(message) }
const digest = (value: string) => createHash("sha256").update(value).digest("hex")
const canonical = (value: unknown): string => JSON.stringify(value, (_key, item: unknown) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item)
function requireCommitAck(result: unknown): void {
const terminal = Array.isArray(result) ? result.at(-1) : result
if (!terminal || typeof terminal !== "object" || Reflect.get(terminal, "command") !== "COMMIT") refuse("Application COMMIT command acknowledgement unavailable")
}
async function observation(intent: DatabaseSchemaIntent, pin: MigrationReview) {
// Fixed, purpose-separated server-keyed ACK issuer. Caller-supplied hashes
// cannot mint a prefix receipt. This still does not attest that current
// schema/data is unchanged, and never issues a READY capability.
return privateSecretFingerprint(fingerprint({ format: "controlled-migration-file-ack-v1", intent, file: pin.file, transaction: pin.transaction, selfMarker: pin.selfMarker, fileCommitAck: true, markerAck: true }), "database-controlled-migration-file-ack-v1")
}
interface ExactFile { pin: MigrationReview; sql: string }
async function exactFiles(): Promise<ExactFile[]> {
const directory = new URL("../../drizzle/", import.meta.url)
const entries = (await readdir(directory, { withFileTypes: true })).filter(entry => entry.name.toLowerCase().endsWith(".sql"))
if (entries.some(entry => !entry.isFile())) refuse("Migration SQL must be ordinary pinned files")
validateMigrationFileSet(entries.map(entry => entry.name))
// Read ONCE and validate those SAME bytes. Never execute a second unchecked
// read after inventory validation, and never expose the source to a caller.
return Promise.all(MIGRATION_MANIFEST.map(async pin => {
const bytes = await readFile(new URL(pin.file, directory))
analyzeMigration(pin.file, bytes, pin)
return { pin, sql: new TextDecoder("utf-8", { fatal: true }).decode(bytes) }
}))
}
async function exactHistory(rows: Record<string, unknown>[], current: ReturnType<typeof checkDatabaseSchemaControlState>, manifest: string) {
if (rows.length > MIGRATION_MANIFEST.length || current.intent !== null) refuse("Unresolved or unexpected migration history")
const completed = new Map<string, DatabaseSchemaTerminal>(), ids = new Set<string>()
for (const row of rows) {
if (Object.keys(row).sort().join(" ") !== "id intent terminal" || typeof row.id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(row.id) || ids.has(row.id)) refuse("Invalid migration history envelope")
ids.add(row.id as string)
// Reuse the strict persisted terminal parser; no boolean/hash alone is a
// readiness grant. A fabricated newer epoch is rejected here as well.
const parsed = checkDatabaseSchemaControlState({ format: current.format, epoch: current.epoch, owner: current.owner, phase: "TERMINAL", intent: null, terminal: row.terminal })
const terminal = parsed.terminal!
if (canonical(row.intent) !== canonical(terminal.intent) || terminal.intent.id !== row.id || terminal.intent.kind !== "migration" || terminal.intent.manifestSha256 !== manifest || terminal.outcome !== "observed-success") refuse("Unknown, failed, foreign or mismatched migration receipt")
const pin = MIGRATION_MANIFEST.find(entry => entry.sha256 === terminal.intent.artifactSha256)
if (!pin || completed.has(pin.file) || terminal.observationSha256 !== await observation(terminal.intent, pin)) return refuse("Migration receipt is not the exact internally recorded file ACK")
completed.set(pin.file, terminal)
}
const prefix = MIGRATION_MANIFEST.slice(0, completed.size)
if (prefix.some(pin => !completed.has(pin.file))) refuse("Migration history is not an exact completed prefix")
const last = prefix.length ? completed.get(prefix[prefix.length - 1].file) : null
if (canonical(last) !== canonical(current.terminal)) refuse("Current control terminal disagrees with completed prefix")
return prefix.length
}
async function baseline(client: PoolClient, prefix: number) {
const namespaces = (await client.query(CONTROLLED_MIGRATIONS_SQL.namespaces)).rows
if (canonical(namespaces) !== canonical([{ name: "mmapp_control" }, { name: "public" }])) refuse("Unexpected database namespace scope")
if (prefix === 0) {
const rows = (await client.query(CONTROLLED_MIGRATIONS_SQL.publicObjects)).rows
if (rows.length !== 1 || rows[0].present !== false) refuse("Legacy or unmarked application state cannot be enrolled")
return
}
const table = (await client.query(CONTROLLED_MIGRATIONS_SQL.markerTable)).rows
if (canonical(table) !== canonical([{ kind: "r", persistence: "p", rls: false, force_rls: false, user_triggers: false }])) refuse("Ordinary unguarded migration marker table required")
const markers = (await client.query(CONTROLLED_MIGRATIONS_SQL.markers)).rows
const expected = MIGRATION_MANIFEST.slice(0, prefix).map(pin => ({ id: pin.file.slice(0, -4) }))
if (canonical(markers) !== canonical(expected)) refuse("Migration markers disagree with exact controlled prefix")
}
/** Fixed production pool + fixed pinned source path; no caller-supplied SQL,
* pool, execution callback, receipt, or verifier. Tests may replace module I/O
* in their isolated loader; that is not a production admission interface. */
export async function executeControlledSqlMigrations() {
const files = await exactFiles(), manifest = migrationManifestDigest()
const { pool } = await import("./index.js")
const control = await acquireDatabaseSchemaControl(pool)
let app: PoolClient | undefined, released = false, activeIntent: DatabaseSchemaIntent | undefined
let applicationSqlSent = false, completedFiles = 0
try {
app = await pool.connect()
await app.query("SET lock_timeout = '10s'")
await app.query("SET statement_timeout = '120s'")
await app.query("SET synchronous_commit = on")
// Exclusive SESSION lock fences every adopted partition writer for the
// whole DDL sequence, including self-managed files and marker gaps.
await app.query("SELECT pg_catalog.pg_advisory_lock($1::bigint)", [PARTITION_WRITER_ADVISORY_KEY])
await app.query("SET search_path = public, pg_catalog")
const current = (await control.read()).state
completedFiles = await exactHistory((await app.query(CONTROLLED_MIGRATIONS_SQL.history)).rows, current, manifest)
await baseline(app, completedFiles)
for (const { pin, sql } of files.slice(completedFiles)) {
const id = randomUUID()
const started = await control.transition({ type: "begin", id, kind: "migration", manifestSha256: manifest, artifactSha256: pin.sha256 })
activeIntent = started.state.intent!
// These writes are reached only after the durable intent COMMIT ACK.
applicationSqlSent = true
if (pin.transaction === "owner-transaction") {
await app.query("BEGIN")
await app.query(sql)
await app.query(CONTROLLED_MIGRATIONS_SQL.marker, [pin.file.slice(0, -4)])
requireCommitAck(await app.query("COMMIT"))
} else {
// Do not wrap, split, strip or rewrite the audited BEGIN...COMMIT.
requireCommitAck(await app.query(sql))
if (!pin.selfMarker) await app.query(CONTROLLED_MIGRATIONS_SQL.marker, [pin.file.slice(0, -4)])
}
await baseline(app, completedFiles + 1)
await control.transition({ type: "terminal", id, outcome: "observed-success", observationSha256: await observation(activeIntent, pin) })
activeIntent = undefined; completedFiles++
}
await baseline(app, completedFiles)
const unlocked = await app.query("SELECT pg_catalog.pg_advisory_unlock($1::bigint) AS unlocked", [PARTITION_WRITER_ADVISORY_KEY])
if (unlocked.rows.length !== 1 || unlocked.rows[0].unlocked !== true) refuse("Application schema lease release unconfirmed")
for (const setting of ["search_path", "synchronous_commit", "lock_timeout", "statement_timeout"]) await app.query("RESET " + setting)
app.release(false); released = true
await control.close()
return Object.freeze({ completedFiles, manifestSha256: manifest, ready: false as const, schemaAndDataVerified: false as const })
} catch (cause) {
if (activeIntent) {
// If intent/terminal COMMIT itself lost ACK the store is poisoned; this
// best-effort record fails closed and the unresolved intent survives.
try { await control.transition({ type: "terminal", id: activeIntent.id, outcome: "interrupted-unknown", observationSha256: digest(JSON.stringify({ format: "controlled-migration-unknown-v1", intent: activeIntent })) }) } catch { /* never retry application SQL */ }
}
if (app && !released) { released = true; app.release(true) }
try { await control.close() } catch { /* preserve unknown outcome */ }
throw new ControlledMigrationsError("Controlled migration stopped; automatic replay forbidden", applicationSqlSent, { cause })
}
}