backupdrill 1.0.0 → 2.0.0

package/dist/manifest.js

@@ -6,11 +6,155 @@
  *  - 缺失该字段的 manifest = 版本 1(1.0 之前写出的旧快照)
  *  - 读取端遇到**更高**的版本必须明确报错,而不是按旧结构硬解析出错误结果
  *    ——对备份工具来说,"旧程序静默误读新归档"是最不能接受的失败方式。
+ *
+ * 版本史:
+ *  - 1:初始格式。
+ *  - 2(恢复闭环 PRD §5.1):storage 增加 buckets 属性清单(public/大小/MIME 限制),
+ *    files 增加 contentType/cacheControl/metadata 等恢复所需元数据;tables 预留
+ *    验证升级字段(本期不生成)。全部为**可加字段**——v2 读取端兼容 v1 快照。
+ */
+export const MANIFEST_SCHEMA_VERSION = 2;
+/** 结构断言失败时的统一出错口径:说清哪个字段坏了,让"桶里的 manifest 被篡改/截断"可定位。 */
+function malformed(what) {
+    throw new Error(`manifest.json is malformed: ${what}`);
+}
+/**
+ * 演练/恢复实际依赖的字段做结构校验(手写而非 JSON Schema 依赖:CLI 保持零校验库依赖,
+ * 校验面 = 恢复代码真正会解引用的路径,新增可选字段不在此列——它们缺失是合法的 v1 形态)。
+ * 半截上传、被篡改或非本工具写的 JSON 要在这里被拦下,而不是在 pg_restore 中途炸开。
  */
-export const MANIFEST_SCHEMA_VERSION = 1;
+/** 可选字段:缺席合法(v1 形态),在场就必须是期望类型——错型值会驱动恢复端做错事。 */
+function optionalString(value, what) {
+    if (value !== undefined && typeof value !== "string")
+        malformed(what);
+}
+function assertManifestShape(m) {
+    // ref 驱动同源安全门:malformed 值会被当"身份已知"却永远匹配不上 = 保护静默失效
+    if (m.sourceProjectRef !== undefined && !/^[a-z0-9]{16,}$/.test(m.sourceProjectRef)) {
+        malformed("sourceProjectRef (not a Supabase project ref)");
+    }
+    const d = m.dump;
+    if (typeof d !== "object" || d === null)
+        malformed("dump section missing");
+    const dump = m.dump;
+    if (typeof dump.key !== "string" || !dump.key)
+        malformed("dump.key");
+    if (typeof dump.sha256 !== "string" || !dump.sha256)
+        malformed("dump.sha256");
+    if (typeof dump.bytes !== "number")
+        malformed("dump.bytes");
+    if (typeof m.database !== "object" || m.database === null)
+        malformed("database section missing");
+    // serverVersion 决定沙箱镜像 tag(parseInt)——不可解析的值会在起容器后才炸
+    if (typeof m.database.serverVersion !== "string" || !(parseInt(m.database.serverVersion, 10) > 0)) {
+        malformed("database.serverVersion");
+    }
+    // 恢复端的工具版本闸要解析它(requiredRestoreToolMajor)——错型值不能到那才炸
+    if (typeof m.database.pgDumpVersion !== "string" || !m.database.pgDumpVersion) {
+        malformed("database.pgDumpVersion");
+    }
+    if (!Array.isArray(m.database.schemas) || m.database.schemas.some((s) => typeof s !== "string" || !s)) {
+        malformed("database.schemas");
+    }
+    if (m.database.extensions !== undefined) {
+        if (!Array.isArray(m.database.extensions))
+            malformed("database.extensions");
+        for (const e of m.database.extensions) {
+            // 这些值会进 CREATE EXTENSION/SCHEMA 的标识符(quoteIdent 兜住注入,这里兜类型)
+            if (typeof e?.name !== "string" || !e.name || typeof e?.version !== "string" || typeof e?.schema !== "string" || !e.schema) {
+                malformed("database.extensions[]");
+            }
+        }
+    }
+    if (typeof m.database.tableCount !== "number")
+        malformed("database.tableCount");
+    if (!Array.isArray(m.database.tables))
+        malformed("database.tables");
+    // 写入端恒有 tableCount === tables.length;不相等 = tables 数组被截断/篡改,
+    // 逐表检查会静默缩水而表数检查还显得正常
+    if (m.database.tableCount !== m.database.tables.length) {
+        malformed("database.tableCount does not match tables.length");
+    }
+    for (const t of m.database.tables) {
+        if (typeof t?.schema !== "string" || typeof t?.name !== "string")
+            malformed("database.tables[]");
+        // estimatedRows 缺失/错型会让演练的"备份时非空的表恢复后不为空"检查静默失效
+        // (undefined > 0 恒 false)——空表假 PASS 是最不能接受的失败方式
+        if (typeof t.estimatedRows !== "number" || !Number.isFinite(t.estimatedRows) || t.estimatedRows < 0) {
+            malformed("database.tables[].estimatedRows");
+        }
+    }
+    // 写入端恒写 storage: null(DB-only)或对象——字段整体缺失只可能是截断/损坏,
+    // 静默当成 DB-only 会跳过全部 Storage 验证与恢复
+    if (m.storage === undefined)
+        malformed("storage section missing (null means DB-only)");
+    if (m.storage !== null) {
+        if (typeof m.storage !== "object")
+            malformed("storage section");
+        if (typeof m.storage.fileCount !== "number" || typeof m.storage.totalBytes !== "number") {
+            malformed("storage.fileCount/totalBytes");
+        }
+        if (!Array.isArray(m.storage.files))
+            malformed("storage.files");
+        // 聚合数与清单对账:files 被截断而 fileCount 完好时,Storage 验证会静默缩水
+        if (m.storage.fileCount !== m.storage.files.length) {
+            malformed("storage.fileCount does not match files.length");
+        }
+        const byteSum = m.storage.files.reduce((n, f) => n + (typeof f?.bytes === "number" ? f.bytes : 0), 0);
+        if (m.storage.totalBytes !== byteSum)
+            malformed("storage.totalBytes does not match files");
+        for (const f of m.storage.files) {
+            if (typeof f?.bucket !== "string" || typeof f?.key !== "string")
+                malformed("storage.files[]");
+            if (typeof f.bytes !== "number" || typeof f.sha256 !== "string")
+                malformed("storage.files[]");
+            // 路径穿越防线:bucket/key 会被拼进本地写路径(restore)与目标上传路径。
+            // manifest 是"从桶里来的数据"——被篡改时不得升级成任意文件写。
+            // 不破坏向后兼容(2026-07-24 实测):Supabase 在写入时就把 //、/./、/../ 和
+            // 前导 / 规范化掉、拒绝反斜杠 —— storage.objects.name(备份列举到的形态)
+            // 永远不含这些段,合法快照不可能被此处拒绝。
+            if (!f.bucket || f.bucket.includes("/") || f.bucket.includes("\\") || f.bucket.includes("\0") || f.bucket === "." || f.bucket === "..") {
+                malformed("storage.files[].bucket (unsafe path segment)");
+            }
+            if (!f.key ||
+                f.key.includes("\\") ||
+                f.key.includes("\0") ||
+                f.key.split("/").some((seg) => seg === "" || seg === "." || seg === "..")) {
+                malformed("storage.files[].key (unsafe path segment)");
+            }
+            optionalString(f.contentType, "storage.files[].contentType");
+            optionalString(f.cacheControl, "storage.files[].cacheControl");
+            optionalString(f.contentEncoding, "storage.files[].contentEncoding");
+            optionalString(f.lastModified, "storage.files[].lastModified");
+            if (f.metadata !== undefined && (typeof f.metadata !== "object" || f.metadata === null || Array.isArray(f.metadata))) {
+                malformed("storage.files[].metadata");
+            }
+        }
+        if (m.storage.buckets !== undefined) {
+            if (!Array.isArray(m.storage.buckets))
+                malformed("storage.buckets");
+            for (const b of m.storage.buckets) {
+                if (typeof b?.name !== "string" || !b.name)
+                    malformed("storage.buckets[]");
+                if (b.public !== null && b.public !== undefined && typeof b.public !== "boolean") {
+                    malformed("storage.buckets[].public");
+                }
+                if (b.fileSizeLimit !== null && b.fileSizeLimit !== undefined && typeof b.fileSizeLimit !== "number") {
+                    malformed("storage.buckets[].fileSizeLimit");
+                }
+                if (b.allowedMimeTypes !== null &&
+                    b.allowedMimeTypes !== undefined &&
+                    !(Array.isArray(b.allowedMimeTypes) && b.allowedMimeTypes.every((v) => typeof v === "string"))) {
+                    malformed("storage.buckets[].allowedMimeTypes");
+                }
+            }
+        }
+    }
+}
 /**
  * 解析桶里的 manifest.json,并做**向前兼容**校验:比本程序更新的格式一律拒绝,
  * 明确告诉用户升级,绝不按旧结构硬解析(那会静默产出错误的演练/恢复结果)。
+ * 版本关之后再做结构校验(assertManifestShape)——两类失败要给出不同的处置指引。
  */
 export function parseManifest(json) {
     let parsed;
@@ -20,11 +164,21 @@ export function parseManifest(json) {
     catch (error) {
         throw new Error(`manifest.json is not valid JSON: ${error.message}`);
     }
-    const version = parsed.schemaVersion ?? 1; // 缺失 = 1.0 之前的旧快照
-    if (!Number.isFinite(version) || version > MANIFEST_SCHEMA_VERSION) {
+    // 根检查必须先于一切属性访问:JSON 里合法的 null/数字/字符串会把裸 TypeError 抛给用户
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        malformed("root is not an object");
+    }
+    // 版本字段:**属性缺席**才算 1.0 之前的旧快照;显式 null/0/负数/小数/字符串
+    // 都不是本工具写过的值,按坏 manifest 拒绝,不得混过前向兼容闸门
+    const version = "schemaVersion" in parsed ? parsed.schemaVersion : 1;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        malformed(`schemaVersion ${JSON.stringify(parsed.schemaVersion)}`);
+    }
+    if (version > MANIFEST_SCHEMA_VERSION) {
         throw new Error(`This snapshot's manifest uses schema version ${String(parsed.schemaVersion)}, but this ` +
             `BackupDrill understands up to ${MANIFEST_SCHEMA_VERSION}. Upgrade the CLI ` +
             `(npm i -g backupdrill@latest) to read it.`);
     }
+    assertManifestShape(parsed);
     return parsed;
 }

package/dist/recovery-doc.d.ts

@@ -0,0 +1,11 @@
+import type { Manifest } from "./manifest.js";
+/** 生成手册所需的非秘密快照坐标。刻意不收连接串/密钥类型——签名即防线。 */
+export interface RecoveryDocContext {
+    snapshot: string;
+    bucket: string;
+    endpoint?: string;
+    region?: string;
+    prefix: string;
+    projectName: string;
+}
+export declare function renderRecoveryDoc(manifest: Manifest, ctx: RecoveryDocContext): string;

package/dist/recovery-doc.js

@@ -0,0 +1,123 @@
+function quoteSqlIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** POSIX 安全的 shell 值引用:项目名/前缀里合法的空格与元字符不得拆散或改写命令。 */
+function shellQuote(value) {
+    return /^[A-Za-z0-9._/:@=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function renderRecoveryDoc(manifest, ctx) {
+    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    const db = manifest.database;
+    const extensions = db.extensions ?? [];
+    const storage = manifest.storage;
+    const mb = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+    // 归档格式跟随 dump 工具版本(允许比服务端新):pg_restore 必须 ≥ 两者较大值,
+    // 只按服务端版本指引会让 PG17 的 pg_restore 读不了 PG18 pg_dump 写的归档。
+    // 解析口径与 backup.ts parsePgDumpMajor 一致(不 import:backup → recovery-doc 会成环)
+    const dumpToolMajor = db.pgDumpVersion.match(/\(PostgreSQL\)\s+(\d+)/)?.[1] ??
+        db.pgDumpVersion.match(/(\d+)(?:\.\d+)+/)?.[1];
+    const requiredRestoreMajor = Math.max(Number(dumpToolMajor ?? 0), parseInt(db.serverVersion, 10) || 0);
+    const extensionSql = extensions.length
+        ? extensions
+            .map((e) => `create schema if not exists ${quoteSqlIdent(e.schema)};\n` +
+            `create extension if not exists ${quoteSqlIdent(e.name)} schema ${quoteSqlIdent(e.schema)} cascade;`)
+            .join("\n")
+        : "-- (this snapshot records no extensions)";
+    // 2.0 形态:凭据只经环境变量(argv 对全机器可见);写入需要键入目标 ref 确认。
+    // DB-only 快照不出现 Storage 凭据与旗标——不为用不上的能力索要宽权限 key
+    const cliRestoreCommand = [
+        `read -rs BACKUPDRILL_TARGET_DATABASE_URL && export BACKUPDRILL_TARGET_DATABASE_URL   # hidden prompt`,
+        ...(storage
+            ? [`read -rs BACKUPDRILL_TARGET_SERVICE_ROLE_KEY && export BACKUPDRILL_TARGET_SERVICE_ROLE_KEY`]
+            : []),
+        `backupdrill restore \\`,
+        `  --snapshot ${shellQuote(ctx.snapshot)} \\`,
+        `  --bucket ${shellQuote(ctx.bucket)} \\`,
+        ...(ctx.endpoint ? [`  --endpoint ${shellQuote(ctx.endpoint)} \\`] : []),
+        ...(ctx.region ? [`  --region ${shellQuote(ctx.region)} \\`] : []),
+        `  --prefix ${shellQuote(ctx.prefix)} \\`,
+        `  --project-name ${shellQuote(ctx.projectName)} \\`,
+        `  --database \\`,
+        ...(storage ? [`  --target-supabase-url https://<target-ref>.supabase.co \\`] : []),
+        `  --confirm-target <target-ref>`,
+    ].join("\n");
+    return `# BackupDrill recovery runbook — ${ctx.projectName} @ ${ctx.snapshot}
+
+This file was written next to the snapshot it describes and is **self-contained**:
+even if BackupDrill (the service and the website) is unreachable, everything below
+works with standard PostgreSQL tools against this bucket alone.
+
+## What this snapshot contains
+
+- **Database dump**: \`${manifest.dump.key}\`
+  (pg_dump custom format, ${mb(manifest.dump.bytes)} MB, sha256 \`${manifest.dump.sha256}\`)
+  - schemas: ${db.schemas.join(", ")} — ${db.tableCount} tables, ~${db.estimatedRowTotal.toLocaleString("en-US")} rows at backup time
+  - source PostgreSQL ${db.serverVersion}, archive written by ${db.pgDumpVersion} — restore with pg_restore ${requiredRestoreMajor} or newer (the archive format follows the dump tool, not the server)
+${extensions.length
+        ? `  - extensions required: ${extensions.map((e) => `${e.name} (schema "${e.schema}")`).join(", ")}`
+        : "  - no extensions recorded"}
+- **Storage files**: ${storage
+        ? `${storage.fileCount} files, ${mb(storage.totalBytes)} MB under \`${base}/storage/<bucket>/<key>\` — per-file sha256 in manifest.json`
+        : "none (database-only snapshot)"}
+- **Machine-readable inventory**: \`${base}/manifest.json\`
+
+## Not covered — plan for these separately
+
+Supabase **Auth users/sessions, secret values, Edge Function code and most
+platform settings are NOT in this snapshot**. After restoring, reconfigure them
+by hand. This is a database + Storage snapshot, not a full project image.
+
+## Restore the database (into an EMPTY project)
+
+1. Create a **fresh** Supabase project (never restore onto the source project),
+   and use its **Session Pooler** connection string.
+2. Install the required extensions first (the dump references their types):
+
+\`\`\`sql
+${extensionSql}
+\`\`\`
+
+3. Download \`${manifest.dump.key}\` from this bucket, then verify it:
+
+\`\`\`bash
+shasum -a 256 dump.pgcustom   # must print ${manifest.dump.sha256}
+\`\`\`
+
+4. Restore — **without \`--clean\`**, into the empty target. Enter the password at
+   a hidden prompt so it never touches the URL, argv, or shell history:
+
+\`\`\`bash
+read -rs PGPASSWORD && export PGPASSWORD   # hidden prompt
+pg_restore --no-owner --no-privileges \\
+  --dbname "postgresql://postgres.<target-ref>@<target-pooler-host>:5432/postgres" dump.pgcustom
+unset PGPASSWORD
+\`\`\`
+
+One error is expected and harmless: \`schema "public" already exists\` (the
+target always has it). Do **not** use \`--clean\` against a Supabase project —
+dropping and recreating \`public\` silently wipes Supabase's default grants for
+\`anon\`/\`authenticated\`, and the restored API answers 401.
+
+## Restore Storage files
+
+Files live at \`${base}/storage/<original-bucket>/<original-key>\` in this
+bucket. Recreate each bucket in the target project, then re-upload the files
+${storage?.buckets ? "(bucket attributes — public flag, size and MIME limits — are recorded in manifest.json under `storage.buckets`)" : "(bucket attributes were not captured for this snapshot; recreate buckets with the settings you know)"}.
+
+## Easiest path — the BackupDrill CLI
+
+\`\`\`bash
+npm install -g backupdrill
+${cliRestoreCommand}
+\`\`\`
+
+Add \`--dry-run\` first to preview every check without writing anything. (Skip the
+\`read\` lines to have the CLI prompt you itself; \`unset\` both variables afterwards.)
+The CLI verifies the archive checksum, refuses non-empty targets, installs the
+extensions, restores through the same engine the weekly drills use, verifies
+table counts and row presence afterwards, then rebuilds buckets, uploads the
+Storage files back and reconciles every one against the target.
+
+More: https://backupdrill.com/docs/restore
+`;
+}

package/dist/restore-engine.d.ts

@@ -0,0 +1,80 @@
+import type { ExtensionInfo } from "./manifest.js";
+export type RestoreTargetKind = "sandbox" | "supabase";
+/** 主机名规范化:剥掉合法的 DNS 根点(db.x.supabase.co. ≡ db.x.supabase.co)。
+ * 身份比较不规范化 = 一个尾点就能绕过同源阻断(supabase-ca 对同类早有钉子)。 */
+export declare function normalizeHost(hostname: string): string;
+/**
+ * 从连接串提取 Supabase 项目 ref(纯函数):直连主机 `db.<ref>.supabase.co` 或
+ * pooler 用户名 `postgres.<ref>`。放在引擎层:备份端(写 manifest.sourceProjectRef)
+ * 与恢复端(同源阻断)共用同一个身份判定。非 Supabase 形态返回 null。
+ */
+export declare function projectRefOf(connString: string): string | null;
+/** 从 Supabase Storage S3 端点(https://<ref>.storage.supabase.co/…)提取项目 ref。 */
+export declare function refFromStorageEndpoint(endpoint: string): string | null;
+export interface ClassifiedPass {
+    /** allowlist 命中数(环境预期/托管冲突)——如实入报告,不算失败 */
+    expectedSkips: number;
+    /** 真失败(压缩到 200 字符的错误块) */
+    failures: string[];
+}
+export interface EngineResult {
+    preData: ClassifiedPass;
+    postData: ClassifiedPass;
+    ok: boolean;
+}
+export declare function spawnPgRestore(bin: string, args: string[], extraEnv?: NodeJS.ProcessEnv): Promise<{
+    code: number | null;
+    stderr: string;
+}>;
+export declare const SANDBOX_MANAGED_ERROR: RegExp;
+export declare const SCHEMA_EXISTS_ERROR: RegExp;
+/**
+ * 把 pg_restore 的 stderr 拆成单个错误块并按 allowlist 分类。
+ * 只对 ERROR 原因行分类,不看 "Command was:" 之后的语句文本——否则一个恰好
+ * 引用 auth.uid 的用户对象因"损坏/语法错误"失败时,会被误判成预期跳过。
+ */
+export declare function classifyBlocks(stderr: string, allow: RegExp): ClassifiedPass;
+/**
+ * 一遍恢复的最终裁决,两条独立规则:
+ * 1. 被信号杀死(code=null)**无条件失败**——即使 stderr 里已有被 allowlist 解释的
+ *    错误块。真实目标恒有一个预期 schema 跳过,若跳过能抵扣信号死亡,中途被 OOM/kill
+ *    的半截恢复就会被报成功(评审第 7 轮抓出的假成功路径)。
+ * 2. 非零退出且零错误块(归档器致命错、非英文 locale…)同样不能谎报成功。
+ *    非零退出但每个错误都已分类 = pg_restore 对被忽略错误的正常退出形态,通过。
+ */
+export declare function finalizePass(code: number | null, stderr: string, classified: ClassifiedPass): ClassifiedPass;
+/** 标识符转义(内嵌引号翻倍)。导出:任何把目录里读到的名字拼进 SQL 的地方都必须用它。 */
+export declare function quoteIdent(name: string): string;
+/**
+ * 恢复前把 manifest 记录的扩展装进目标(--schema 转储不含 CREATE EXTENSION)。
+ * 必须装进与源库相同的 schema:dump 里的类型是限定名(如 extensions.vector)。
+ * 装不上的扩展如实收集返回,由调用方按目标类型裁决:沙箱记录后继续(托管扩展
+ * 本就装不上,public 转储通常不引用),真实目标应当阻断(用户能在 dashboard 开启)。
+ */
+export declare function installExtensions(connString: string, extensions: ExtensionInfo[]): Promise<string[]>;
+/**
+ * 两遍恢复(真实首演炸出的设计,现为 drill 与真实恢复共用):
+ * 1. pre-data+data —— 表结构 + 数据。除 schema 冲突(预期)外任何错误都是硬失败。
+ * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;allowlist 按目标类型:
+ *    沙箱豁免 Supabase 托管对象引用,真实 Supabase 目标零豁免。
+ */
+/**
+ * 凭据不进 argv(D6 同源要求):连接串里的密码对 `ps` 全程可见——拆出来经
+ * PGPASSWORD 环境变量传给 libpq,argv 里的 URL 不再携带。解析不了的连接串
+ * 原样透传(libpq 自己适配的形态,不在这里破坏)。
+ */
+export declare function credentialSafeDbArgs(connString: string): {
+    url: string;
+    env: NodeJS.ProcessEnv;
+};
+/**
+ * 拒绝连接串里的 host/hostaddr/user 查询覆盖:驱动会让它们改写实际连接目标/租户——
+ * 身份判定(ref/主机)看的是 authority,读写却发生在别处。备份侧(源身份自记)与
+ * 恢复侧(确认门/同源阻断)共用本检查。
+ */
+export declare function assertNoHostOverride(connString: string): void;
+export declare function restoreDatabaseArtifact(opts: {
+    dumpPath: string;
+    connString: string;
+    target: RestoreTargetKind;
+}): Promise<EngineResult>;

package/dist/restore-engine.js

@@ -0,0 +1,267 @@
+// 统一数据库恢复引擎(恢复闭环 PRD §5.2):drill 沙箱与真实 Supabase 目标共用同一条
+// pg_restore 路径与错误分类,同一快照不得在演练与真实恢复中得出不同结论。
+//
+// R0 spike 的三条实证直接塑造了这里的形状:
+//  1. 裸退出码在真实目标上永远不干净 → 成功判定 = 零未分类错误(版本化 allowlist);
+//  2. 不用 --clean:与"只允许空目标"(D5)冲突、制造伪错,且在真实 Supabase 上
+//     DROP/CREATE public 会抹掉 anon/authenticated 的默认授权(--no-privileges 转储
+//     不会带回来),恢复出的 API 直接 401;
+//  3. dump 自带 CREATE SCHEMA,而目标(新容器或 Supabase)恒有同名 schema →
+//     pre-data 阶段的 schema "already exists" 是两类目标共同的预期冲突。
+import { spawn } from "node:child_process";
+import { Client } from "pg";
+import { resolvePgRestoreBin } from "./pgbin.js";
+import { pgConnectOptions } from "./supabase-ca.js";
+/** 主机名规范化:剥掉合法的 DNS 根点(db.x.supabase.co. ≡ db.x.supabase.co)。
+ * 身份比较不规范化 = 一个尾点就能绕过同源阻断(supabase-ca 对同类早有钉子)。 */
+export function normalizeHost(hostname) {
+    return hostname.replace(/\.$/, "").toLowerCase();
+}
+/**
+ * 从连接串提取 Supabase 项目 ref(纯函数):直连主机 `db.<ref>.supabase.co` 或
+ * pooler 用户名 `postgres.<ref>`。放在引擎层:备份端(写 manifest.sourceProjectRef)
+ * 与恢复端(同源阻断)共用同一个身份判定。非 Supabase 形态返回 null。
+ */
+export function projectRefOf(connString) {
+    try {
+        const url = new URL(connString);
+        const direct = normalizeHost(url.hostname).match(/^db\.([a-z0-9]{16,})\.supabase\.co$/);
+        if (direct)
+            return direct[1];
+        // 用户名必须先解码再匹配:URL 解析器保留百分号编码,而 pg/libpq 会解码——
+        // postgres%2Eref 在驱动眼里就是 postgres.ref,不解码 = 身份判定可被编码绕过
+        const pooled = decodeURIComponent(url.username).match(/^postgres\.([a-z0-9]{16,})$/);
+        if (pooled)
+            return pooled[1];
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 从 Supabase Storage S3 端点(https://<ref>.storage.supabase.co/…)提取项目 ref。 */
+export function refFromStorageEndpoint(endpoint) {
+    try {
+        const match = normalizeHost(new URL(endpoint).hostname).match(/^([a-z0-9]{16,})\.(?:storage\.)?supabase\.co$/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function spawnPgRestore(bin, args, extraEnv = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(bin, args, {
+            stdio: ["ignore", "ignore", "pipe"],
+            env: { ...process.env, ...extraEnv },
+        });
+        let stderr = "";
+        proc.stderr.on("data", (d) => (stderr += d.toString()));
+        // 不透传原始 spawn Error:node 会把 spawnargs(含 --dbname 连接串=凭据)挂在
+        // 异常对象上,顺着 reject 流进日志/Sentry。只保留启动失败的事实与 bin 名。
+        proc.on("error", (error) => reject(new Error(`${bin} failed to start: ${error.code ?? error.message}`)));
+        proc.on("close", (code) => resolve({ code, stderr }));
+    });
+}
+// 演练沙箱是裸 Postgres,Supabase 托管的 schema/角色必然缺席。post-data 里
+// 引用它们的失败是"环境预期",不是备份坏了;其余失败才是演练要抓的。
+// 真实 Supabase 目标不适用:角色/托管 schema 恒在,post-data 全严格。
+export const SANDBOX_MANAGED_ERROR = /schema "(auth|storage|realtime|vault|extensions|graphql[a-z_]*)" does not exist|role "(authenticated|anon|service_role|supabase_[a-z_]+)" does not exist|\bauth\.uid\b|\bauth\.jwt\b/i;
+// pre-data 唯一的预期冲突(见文件头注 3)。目标空门/新容器保证没有其他冲突源,
+// 任何别的 "already exists" 都是真冲突,必须失败。
+export const SCHEMA_EXISTS_ERROR = /schema "[^"]+" already exists/i;
+const NEVER_MATCH = /(?!)/;
+/**
+ * 把 pg_restore 的 stderr 拆成单个错误块并按 allowlist 分类。
+ * 只对 ERROR 原因行分类,不看 "Command was:" 之后的语句文本——否则一个恰好
+ * 引用 auth.uid 的用户对象因"损坏/语法错误"失败时,会被误判成预期跳过。
+ */
+export function classifyBlocks(stderr, allow) {
+    const blocks = stderr
+        .split(/(?=pg_restore: error:)/)
+        .filter((b) => /pg_restore: error:/.test(b));
+    let expectedSkips = 0;
+    const failures = [];
+    for (const block of blocks) {
+        const cause = block.split(/Command was:/i)[0];
+        if (allow.test(cause)) {
+            expectedSkips += 1;
+        }
+        else {
+            failures.push(block.replace(/\s+/g, " ").trim().slice(0, 200));
+        }
+    }
+    return { expectedSkips, failures };
+}
+/**
+ * 一遍恢复的最终裁决,两条独立规则:
+ * 1. 被信号杀死(code=null)**无条件失败**——即使 stderr 里已有被 allowlist 解释的
+ *    错误块。真实目标恒有一个预期 schema 跳过,若跳过能抵扣信号死亡,中途被 OOM/kill
+ *    的半截恢复就会被报成功(评审第 7 轮抓出的假成功路径)。
+ * 2. 非零退出且零错误块(归档器致命错、非英文 locale…)同样不能谎报成功。
+ *    非零退出但每个错误都已分类 = pg_restore 对被忽略错误的正常退出形态,通过。
+ */
+export function finalizePass(code, stderr, classified) {
+    const detail = stderr.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)";
+    if (code === null) {
+        return {
+            ...classified,
+            failures: [...classified.failures, `pg_restore was killed by a signal: ${detail}`],
+        };
+    }
+    if (code !== 0 && classified.expectedSkips === 0 && classified.failures.length === 0) {
+        return { ...classified, failures: [`pg_restore exited with code ${code}: ${detail}`] };
+    }
+    return classified;
+}
+/** 标识符转义(内嵌引号翻倍)。导出:任何把目录里读到的名字拼进 SQL 的地方都必须用它。 */
+export function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * 恢复前把 manifest 记录的扩展装进目标(--schema 转储不含 CREATE EXTENSION)。
+ * 必须装进与源库相同的 schema:dump 里的类型是限定名(如 extensions.vector)。
+ * 装不上的扩展如实收集返回,由调用方按目标类型裁决:沙箱记录后继续(托管扩展
+ * 本就装不上,public 转储通常不引用),真实目标应当阻断(用户能在 dashboard 开启)。
+ */
+export async function installExtensions(connString, extensions) {
+    if (!extensions.length)
+        return [];
+    // pgConnectOptions:Supabase 主机自动带打包根 CA(node-pg 把 require 按 verify-full
+    // 处理,裸 Client 对 pooler 必报 self-signed chain);沙箱等非 Supabase 目标原样透传
+    const client = new Client(pgConnectOptions(connString));
+    await client.connect();
+    const unavailable = [];
+    try {
+        for (const ext of extensions) {
+            try {
+                await client.query(`create schema if not exists ${quoteIdent(ext.schema)}`);
+                // CASCADE 自动带上依赖扩展,免受 manifest 里的安装顺序摆布
+                await client.query(`create extension if not exists ${quoteIdent(ext.name)} schema ${quoteIdent(ext.schema)} cascade`);
+            }
+            catch {
+                unavailable.push(ext.name);
+            }
+        }
+    }
+    finally {
+        await client.end();
+    }
+    return unavailable;
+}
+/**
+ * 两遍恢复(真实首演炸出的设计,现为 drill 与真实恢复共用):
+ * 1. pre-data+data —— 表结构 + 数据。除 schema 冲突(预期)外任何错误都是硬失败。
+ * 2. post-data —— 用户自己的索引/约束/触发器必须恢复成功;allowlist 按目标类型:
+ *    沙箱豁免 Supabase 托管对象引用,真实 Supabase 目标零豁免。
+ */
+/**
+ * 凭据不进 argv(D6 同源要求):连接串里的密码对 `ps` 全程可见——拆出来经
+ * PGPASSWORD 环境变量传给 libpq,argv 里的 URL 不再携带。解析不了的连接串
+ * 原样透传(libpq 自己适配的形态,不在这里破坏)。
+ */
+export function credentialSafeDbArgs(connString) {
+    let url;
+    try {
+        url = new URL(connString);
+    }
+    catch {
+        // 非 URL(libpq keyword)形态拆不了密码——含内联密码的一律拒绝,不赌
+        if (/\bpassword\s*=/i.test(connString)) {
+            throw new Error("keyword-style connection strings with an inline password are not accepted — " +
+                "use the URL form; the password is moved into PGPASSWORD automatically");
+        }
+        return { url: connString, env: {} };
+    }
+    let password = "";
+    if (url.password) {
+        try {
+            password = decodeURIComponent(url.password);
+        }
+        catch {
+            // 编码坏了不许 fail-open(评审第 13 轮):原样放行 = 密码整段留在 argv
+            throw new Error("the connection string password contains malformed percent-encoding — " +
+                "fix the URL; refusing to pass it through argv");
+        }
+        url.password = "";
+    }
+    // ?password= 同样不许进 argv(libpq 认它)。剥参按**解码后的键名**匹配
+    // (pass%77ord= 也是 password=,评审第 15 轮),不用 URLSearchParams.delete:
+    // 它会重序列化其余参数(%20 变 +),libpq 按字面处理,options 之类会被改坏
+    const rawQuery = url.search.startsWith("?") ? url.search.slice(1) : url.search;
+    if (rawQuery) {
+        const kept = [];
+        const queryPasswords = [];
+        for (const part of rawQuery.split("&")) {
+            const eq = part.indexOf("=");
+            const rawKey = eq === -1 ? part : part.slice(0, eq);
+            let key;
+            try {
+                key = decodeURIComponent(rawKey.replace(/\+/g, "%20"));
+            }
+            catch {
+                key = rawKey;
+            }
+            if (/^password$/i.test(key)) {
+                const rawValue = eq === -1 ? "" : part.slice(eq + 1);
+                try {
+                    const value = decodeURIComponent(rawValue.replace(/\+/g, "%20"));
+                    if (value)
+                        queryPasswords.push(value);
+                }
+                catch {
+                    throw new Error("the connection string ?password= value contains malformed percent-encoding — " +
+                        "fix the URL; refusing to pass it through argv");
+                }
+            }
+            else {
+                kept.push(part);
+            }
+        }
+        if (queryPasswords.length) {
+            // authority 与查询、以及重复查询项之间不一致:libpq 的取值优先级和我们的猜测
+            // 可能不同,预检用 A 通过、pg_restore 用 B 失败的分叉不可接受——直接拒绝
+            const distinct = new Set(password ? [password, ...queryPasswords] : queryPasswords);
+            if (distinct.size > 1) {
+                throw new Error("the connection string carries two different passwords (authority/?password=) — remove one");
+            }
+            password = [...distinct][0];
+            url.search = kept.length ? `?${kept.join("&")}` : "";
+        }
+    }
+    return { url: url.toString(), env: password ? { PGPASSWORD: password } : {} };
+}
+/**
+ * 拒绝连接串里的 host/hostaddr/user 查询覆盖:驱动会让它们改写实际连接目标/租户——
+ * 身份判定(ref/主机)看的是 authority,读写却发生在别处。备份侧(源身份自记)与
+ * 恢复侧(确认门/同源阻断)共用本检查。
+ */
+export function assertNoHostOverride(connString) {
+    try {
+        const params = new URL(connString).searchParams;
+        for (const key of params.keys()) {
+            if (/^(host|hostaddr|user)$/i.test(key)) {
+                throw new Error(`connection string carries a ?${key}= override — the effective server/identity would ` +
+                    `differ from the URL authority that identity checks inspect. Use a plain connection string.`);
+            }
+        }
+    }
+    catch (error) {
+        if (error.message.includes("override"))
+            throw error;
+        // URL 解析不了的连接串由 pg 自己报错,这里放行
+    }
+}
+export async function restoreDatabaseArtifact(opts) {
+    const bin = resolvePgRestoreBin();
+    const { url, env } = credentialSafeDbArgs(opts.connString);
+    const common = ["--no-owner", "--no-privileges", "--dbname", url, opts.dumpPath];
+    const first = await spawnPgRestore(bin, ["--section=pre-data", "--section=data", ...common], env);
+    const preData = finalizePass(first.code, first.stderr, classifyBlocks(first.stderr, SCHEMA_EXISTS_ERROR));
+    if (preData.failures.length) {
+        return { preData, postData: { expectedSkips: 0, failures: [] }, ok: false };
+    }
+    const second = await spawnPgRestore(bin, ["--section=post-data", ...common], env);
+    const postData = finalizePass(second.code, second.stderr, classifyBlocks(second.stderr, opts.target === "sandbox" ? SANDBOX_MANAGED_ERROR : NEVER_MATCH));
+    return { preData, postData, ok: postData.failures.length === 0 };
+}