/** * Phase 06 #22 — Plugin-DB migration applier. * * Plugins that need their own tables declare them in the manifest * (foundation: single `migration.up` SQL string). The operator-side * lifecycle service calls {@link applyPluginMigration} on install, * which: * * 1. Validates the SQL text only references tables prefixed with * `plugin__` (no DROP DATABASE, no GRANT, * no cross-schema writes — the manifest cannot trick the host * into running arbitrary DDL). * 2. Executes the (possibly multi-statement) SQL via the injected * `executeRawUnsafe` seam — supplied at call-site as Prisma * `$executeRawUnsafe`. * 3. Records the applied version so re-installs are idempotent. * * Down-migrations + per-version sequencing are intentionally deferred: * the foundation accepts one up-migration per install. Subsequent * versions can re-run with their own up-SQL. */ /** * Sanitize a reverse-DNS plugin id (`com.acme.slack`) into a SQL * identifier (`com_acme_slack`). Lowercases, replaces `.` and `-` * with `_`, then rejects anything outside `[a-z0-9_]`. */ export function sanitizePluginIdForSql(pluginId: string): string { const lower = pluginId.toLowerCase(); const replaced = lower.replace(/[.\-]/g, "_"); if (!/^[a-z][a-z0-9_]*$/u.test(replaced)) { throw new PluginMigrationError( "invalid_plugin_id", `Plugin id '${pluginId}' cannot be sanitized to a SQL identifier.` ); } return replaced; } export class PluginMigrationError extends Error { public override readonly name = "PluginMigrationError"; public readonly code: | "invalid_plugin_id" | "forbidden_statement" | "prefix_violation" | "missing_tenant_id_column" | "too_many_statements" | "execute_failed"; constructor(code: PluginMigrationError["code"], message: string) { super(message); this.code = code; } } /** * Hard cap on the number of statements a single plugin migration may * declare. Defends against the "thousand-tables" DoS where a manifest * spans the entire DB with garbage. Closes F-008 from the internal * findings. Operators can override via the migration runner caller; the * default is conservative because legitimate plugin migrations rarely * exceed a handful of tables. */ export const DEFAULT_MAX_STATEMENTS_PER_MIGRATION = 32; /** * Comment / whitespace stripper used by both the statement splitter * and the keyword scanner. Removes: * - `-- line comments` * - `/* block comments *​/` * and collapses runs of whitespace. */ export function stripSqlNoise(sql: string): string { return sql .replace(/\/\*[\s\S]*?\*\//gu, " ") .replace(/--[^\n]*/gu, " ") .replace(/\s+/gu, " ") .trim(); } const FORBIDDEN_TOKENS = [ "DROP DATABASE", "DROP SCHEMA", "GRANT", "REVOKE", "CREATE USER", "ALTER USER", "DROP USER", "COPY ", "TRUNCATE", "SET ROLE", "PG_", ]; /** * F-006 — defence-in-depth AST-lite token scan. * * Stage-1 forbidden-tokens check is a substring match on the stripped * SQL — robust against simple split-comment-grant obfuscation (the comment is * removed first) but vulnerable to two failure modes: * - false positives when a string literal contains a forbidden word * (a column DEFAULT with the substring "grant" trips the rule); * * Stage-2 (this function) walks the SQL token-by-token respecting: * - single-quoted strings with two single quotes escape * - double-quoted identifiers with two double quotes escape * - dollar-quoted strings ($$ ... $$ and $tag$ ... $tag$) * - the actual unicode whitespace class * It returns the sequence of identifier-shaped tokens (uppercased). The * caller scans this sequence for forbidden keyword pairs without * worrying about content inside literals. * * Intentionally tiny — we only need enough of a tokenizer to make * obfuscation harder, not to parse arbitrary Postgres. */ export type SqlIdentifierToken = { readonly text: string; // uppercased readonly start: number; }; export function tokenizeSqlIdentifiers(sql: string): ReadonlyArray { const tokens: SqlIdentifierToken[] = []; const len = sql.length; let i = 0; while (i < len) { const ch = sql[i]!; // line comment if (ch === "-" && sql[i + 1] === "-") { while (i < len && sql[i] !== "\n") i += 1; continue; } // block comment if (ch === "/" && sql[i + 1] === "*") { i += 2; while (i < len && !(sql[i] === "*" && sql[i + 1] === "/")) i += 1; i += 2; continue; } // single-quoted string if (ch === "'") { i += 1; while (i < len) { if (sql[i] === "'" && sql[i + 1] === "'") { i += 2; continue; } if (sql[i] === "'") { i += 1; break; } i += 1; } continue; } // double-quoted identifier if (ch === '"') { const start = i; i += 1; let inner = ""; while (i < len) { if (sql[i] === '"' && sql[i + 1] === '"') { inner += '"'; i += 2; continue; } if (sql[i] === '"') { i += 1; break; } inner += sql[i]!; i += 1; } tokens.push({ text: inner.toUpperCase(), start }); continue; } // dollar-quoted string ($tag$ ... $tag$) if (ch === "$") { const tagMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i)); if (tagMatch) { const closeTag = tagMatch[0]; i += closeTag.length; const close = sql.indexOf(closeTag, i); i = close === -1 ? len : close + closeTag.length; continue; } } // identifier if (/[A-Za-z_]/.test(ch)) { const start = i; let end = i + 1; while (end < len && /[A-Za-z0-9_]/.test(sql[end]!)) end += 1; tokens.push({ text: sql.slice(start, end).toUpperCase(), start }); i = end; continue; } i += 1; } return tokens; } /** * Scan the tokenized identifier stream for any forbidden 1- or 2-word * keyword sequence. Returns the first match or null. Unlike the stage-1 * substring scan, this respects string-literal content (so a legitimate * `DEFAULT 'no grant'` no longer false-positives) AND tightens the * obfuscation surface (string-internal forbidden words cannot smuggle * a real GRANT past the splitter). */ export function findForbiddenKeyword( tokens: ReadonlyArray, ): { keyword: string; position: number } | null { for (let i = 0; i < tokens.length; i++) { const t = tokens[i]!.text; const next = tokens[i + 1]?.text ?? ""; // 2-word keywords const pair = `${t} ${next}`; if ( pair === "DROP DATABASE" || pair === "DROP SCHEMA" || pair === "CREATE USER" || pair === "ALTER USER" || pair === "DROP USER" || pair === "SET ROLE" ) { return { keyword: pair, position: tokens[i]!.start }; } // single-word keywords if ( t === "GRANT" || t === "REVOKE" || t === "TRUNCATE" || t === "COPY" ) { return { keyword: t, position: tokens[i]!.start }; } // pg_* function family if (t.startsWith("PG_")) { return { keyword: "PG_*", position: tokens[i]!.start }; } } return null; } /** * Validate that a CREATE TABLE statement targets the allowed prefix * and includes a `tenantId` column. We deliberately keep the parser * dumb — anything that does not match the simple "CREATE TABLE * ( ... )" shape is rejected. Plugin authors who want fancy * migrations should split them into multiple CREATE TABLEs. */ function validateCreateTable(statement: string, allowedPrefix: string): void { const m = /^CREATE\s+TABLE(\s+IF\s+NOT\s+EXISTS)?\s+("?)([a-z_][a-z0-9_]*)\2\s*\(([\s\S]+)\)\s*$/iu.exec(statement); if (!m) { throw new PluginMigrationError( "forbidden_statement", `CREATE TABLE statement does not match the supported shape: ${statement.slice(0, 80)}…` ); } const tableName = m[3]!; if (!tableName.startsWith(allowedPrefix)) { throw new PluginMigrationError( "prefix_violation", `Table '${tableName}' must start with '${allowedPrefix}'.` ); } const body = m[4]!; // F-021 — strict column-name check. The previous `\btenantId\b` regex // matched the substring anywhere in the body, including inside DEFAULT // literals like `comment TEXT DEFAULT 'tenantId here'`. We now require // `tenantId` to appear as a column-definition header: preceded by // either the start of the body or a comma (the column-def separator), // optionally double-quoted, followed by whitespace before the type. // Comments are already removed by stripSqlNoise before we get here. if (!/(?:^|,)\s*"?tenantId"?\s+/iu.test(body)) { throw new PluginMigrationError( "missing_tenant_id_column", `Table '${tableName}' must declare a tenantId column for tenant scoping.` ); } } function validateCreateIndex(statement: string, allowedPrefix: string): void { const m = /^CREATE\s+(UNIQUE\s+)?INDEX(\s+IF\s+NOT\s+EXISTS)?\s+("?)([a-z_][a-z0-9_]*)\3\s+ON\s+("?)([a-z_][a-z0-9_]*)\5/iu.exec(statement); if (!m) { throw new PluginMigrationError( "forbidden_statement", `CREATE INDEX statement does not match the supported shape: ${statement.slice(0, 80)}…` ); } const tableName = m[6]!; if (!tableName.startsWith(allowedPrefix)) { throw new PluginMigrationError( "prefix_violation", `Index target '${tableName}' must start with '${allowedPrefix}'.` ); } } /** * Split on top-level semicolons. Keeps it intentionally naive — the * supported migration grammar (CREATE TABLE / CREATE INDEX) does not * embed semicolons inside string literals. */ export function splitStatements(sql: string): ReadonlyArray { return stripSqlNoise(sql) .split(";") .map((s) => s.trim()) .filter((s) => s.length > 0); } export type ValidatedPluginMigration = { pluginId: string; sanitizedPluginId: string; allowedPrefix: string; statements: ReadonlyArray; }; /** * Parse + validate a plugin migration SQL blob without executing it. * Throws {@link PluginMigrationError} on any rule violation. */ export function validatePluginMigration(args: { pluginId: string; sql: string; /** Override the default DEFAULT_MAX_STATEMENTS_PER_MIGRATION cap. */ maxStatements?: number; }): ValidatedPluginMigration { const sanitized = sanitizePluginIdForSql(args.pluginId); const allowedPrefix = `plugin_${sanitized}_`; const statements = splitStatements(args.sql); const maxStatements = args.maxStatements ?? DEFAULT_MAX_STATEMENTS_PER_MIGRATION; if (statements.length > maxStatements) { throw new PluginMigrationError( "too_many_statements", `Migration declares ${statements.length} statements; cap is ${maxStatements}. ` + "Split into multiple plugin versions or raise PLUGIN_MAX_STATEMENTS_PER_MIGRATION.", ); } for (const stmt of statements) { const upper = stmt.toUpperCase(); // Stage 1 (legacy substring scan) — kept as belt-and-braces. Stage 2 // (token-aware scan, F-006) catches obfuscation + ignores string // literal content. We run both: if stage 1 rejects a string-literal // false-positive (e.g. `DEFAULT 'no grant'`) we let stage 2 override // by checking it first. If stage 2 finds nothing AND stage 1 finds // something, that something is by definition inside a string literal // or a comment — both are benign in our limited grammar. const tokens = tokenizeSqlIdentifiers(stmt); const stage2 = findForbiddenKeyword(tokens); if (stage2) { throw new PluginMigrationError( "forbidden_statement", `Statement contains forbidden token '${stage2.keyword}' at position ${stage2.position}: ${stmt.slice(0, 80)}…`, ); } // Stage 1 fallback only when stage 2 found nothing — guards against // a tokenizer edge-case missing something the substring scan would // catch. Skip the check when the only stage-1 hit is inside a // string literal (already cleared by stage 2's literal-aware walk). for (const forbidden of FORBIDDEN_TOKENS) { if (upper.includes(forbidden)) { // Only treat as a real reject if NO identifier token containing // the forbidden text exists OUTSIDE a string literal. The // tokenizer already skipped string content; if a substring match // wasn't covered by stage 2, it lives inside a literal/comment. const live = tokens.some((tk) => tk.text.includes(forbidden.trim())); if (live) { throw new PluginMigrationError( "forbidden_statement", `Statement contains forbidden token '${forbidden}': ${stmt.slice(0, 80)}…`, ); } } } if (upper.startsWith("CREATE TABLE")) { validateCreateTable(stmt, allowedPrefix); } else if (upper.startsWith("CREATE INDEX") || upper.startsWith("CREATE UNIQUE INDEX")) { validateCreateIndex(stmt, allowedPrefix); } else { throw new PluginMigrationError( "forbidden_statement", `Only CREATE TABLE / CREATE INDEX are allowed for plugin migrations. Got: ${stmt.slice(0, 40)}…` ); } } return { pluginId: args.pluginId, sanitizedPluginId: sanitized, allowedPrefix, statements }; } export type ApplyPluginMigrationDeps = { /** Prisma `$executeRawUnsafe`-shaped seam. Returns rows affected. */ executeRawUnsafe: (sql: string) => Promise; logger?: { info: (fields: Record, msg: string) => void; warn?: (fields: Record, msg: string) => void; error?: (fields: Record, msg: string) => void; }; }; /** * Validate the SQL, then execute each statement sequentially through * the injected seam. Returns the validated migration record for the * caller to persist (e.g. `plugin_migrations_applied`). */ export async function applyPluginMigration( args: { pluginId: string; sql: string }, deps: ApplyPluginMigrationDeps ): Promise { const validated = validatePluginMigration(args); // F-007 — emit a per-statement audit line BEFORE running, so even a // crash mid-execution leaves a trail of what the host attempted. // The line is structured so log aggregation can join it back to the // pluginId. We deliberately do NOT log the full statement — only the // first 200 chars (enough for forensic correlation, short enough to // bound log volume for big migrations). for (let i = 0; i < validated.statements.length; i++) { const stmt = validated.statements[i]!; deps.logger?.info?.( { pluginId: args.pluginId, statementIndex: i, statementCount: validated.statements.length, statementPreview: stmt.slice(0, 200), }, "plugin.migration.execute_statement" ); try { await deps.executeRawUnsafe(stmt); } catch (err) { deps.logger?.error?.( { pluginId: args.pluginId, statementIndex: i, statementPreview: stmt.slice(0, 200), error: err instanceof Error ? err.message : String(err), }, "plugin.migration.execute_failed" ); throw new PluginMigrationError( "execute_failed", `Plugin migration for ${args.pluginId} failed to execute: ${err instanceof Error ? err.message : String(err)}` ); } } deps.logger?.info?.( { pluginId: args.pluginId, statements: validated.statements.length }, "plugin.migration.applied" ); return validated; }