Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,448 @@
|
||||
/**
|
||||
* 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;
|
||||
}
|
||||
Reference in new issue
Block a user