449 lines
15 KiB
TypeScript
449 lines
15 KiB
TypeScript
/**
|
||
* 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_<sanitized-plugin-id>_` (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<SqlIdentifierToken> {
|
||
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<SqlIdentifierToken>,
|
||
): { 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
|
||
* <name> ( ... )" 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<string> {
|
||
return stripSqlNoise(sql)
|
||
.split(";")
|
||
.map((s) => s.trim())
|
||
.filter((s) => s.length > 0);
|
||
}
|
||
|
||
export type ValidatedPluginMigration = {
|
||
pluginId: string;
|
||
sanitizedPluginId: string;
|
||
allowedPrefix: string;
|
||
statements: ReadonlyArray<string>;
|
||
};
|
||
|
||
/**
|
||
* 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<number>;
|
||
logger?: {
|
||
info: (fields: Record<string, unknown>, msg: string) => void;
|
||
warn?: (fields: Record<string, unknown>, msg: string) => void;
|
||
error?: (fields: Record<string, unknown>, 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<ValidatedPluginMigration> {
|
||
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;
|
||
}
|