backupdrill 1.0.0 → 1.1.0

package/README.md

@@ -168,12 +168,18 @@ backupdrill restore \
   --storage-dir ./recovered
 ```
 
-Or restore the dump by hand:
+Or restore the dump by hand — into an **empty** database, without `--clean`:
 
 ```bash
-pg_restore --clean --if-exists --no-owner --dbname "<target-connection-string>" dump.pgcustom
+pg_restore --no-owner --no-privileges --dbname "<target-connection-string>" dump.pgcustom
 ```
 
+Don't use `--clean` against a Supabase project: dropping and recreating the `public`
+schema silently wipes Supabase's default grants for `anon`/`authenticated` (the dump
+carries no ACLs), leaving the restored API returning 401s. One error is expected and
+harmless: `schema "public" already exists` — the target always has it. The
+`backupdrill restore` command above handles all of this (plus verification) for you.
+
 ## GitHub Action / scheduled backups
 
 Want this running on a schedule without paying for a server? Run it in GitHub Actions.

package/dist/backup.js

@@ -7,6 +7,7 @@ import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 import { Upload } from "@aws-sdk/lib-storage";
 import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 import { syncStorage } from "./storage.js";
+import { inspectBucketAttrs } from "./storage-catalog.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 import { pgConnectOptions, dumpUrlFor } from "./supabase-ca.js";
@@ -186,7 +187,20 @@ export async function runBackup(config) {
             bucket: config.storage.bucket,
             base, // syncStorage 内部会加 /storage/<bucket>/<key>
         });
+        // v2 bucket 属性采集,通道 = 已有的只读库连接(per-file 元数据已随 GetObject
+        // 响应在 syncStorage 内原子捕获)。失败只降级不报错:storage schema 读不到
+        // (如收紧的 backup_reader 角色)时,manifest 缺 buckets 字段,恢复端把缺失
+        // 如实标 not captured(PRD §5.1.3)。
+        let bucketAttrs;
+        try {
+            bucketAttrs = await inspectBucketAttrs(config.databaseUrl, synced.buckets);
+        }
+        catch (error) {
+            log.warn(`Bucket attributes not captured (${error.message}); ` +
+                `this manifest will record them as absent — restore will say so instead of guessing.`);
+        }
         storageResult = {
+            ...(bucketAttrs ? { buckets: bucketAttrs } : {}),
             fileCount: synced.fileCount,
             totalBytes: synced.totalBytes,
             files: synced.files,

package/dist/drill.d.ts

@@ -31,13 +31,16 @@ interface PostDataResult {
     supabaseSkipped: number;
     failures: string[];
 }
-/** 把 pg_restore 的 stderr 拆成单个错误块并分类(Supabase 托管 vs 用户对象)。 */
+/** 兼容层:历史签名保留,分类逻辑的单一权威在统一引擎(restore-engine.ts)。 */
 export declare function classifyPostDataErrors(stderr: string): PostDataResult;
-/**
- * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
- * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
- */
+/** 兼容层:见 restore-engine.ts finalizePass(非零退出且零错误块 = 通用失败)。 */
 export declare function postDataResult(code: number | null, stderr: string): PostDataResult;
+/** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
+export declare function verifyRestored(connString: string, manifest: Manifest): Promise<{
+    checks: DrillCheck[];
+    tableCount: number;
+    rowTotal: number;
+}>;
 export declare const APP_CHECK_TIMEOUT_MS: number;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL

package/dist/drill.js

@@ -6,7 +6,8 @@ import { promisify } from "node:util";
 import { Client } from "pg";
 import { parseManifest } from "./manifest.js";
 import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
-import { resolvePgRestoreBin } from "./pgbin.js";
+import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, } from "./restore-engine.js";
+import { pgConnectOptions } from "./supabase-ca.js";
 import { log } from "./log.js";
 const execFileAsync = promisify(execFile);
 // Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
@@ -92,114 +93,42 @@ async function startEphemeralPostgres(image) {
         throw error;
     }
 }
-function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
-/**
- * 恢复前把 manifest 记录的扩展装进沙箱(--schema 转储不含 CREATE EXTENSION)。
- * 必须装进与源库相同的 schema:dump 里的类型是限定名(如 extensions.vector)。
- * 装不上的扩展如实收集返回,**不在这里失败**——Supabase 项目普遍装着沙箱镜像
- * 没有的托管扩展(pg_graphql、supabase_vault…),public 转储通常并不引用它们;
- * 只有恢复真的因此失败时才升级为分类错误(见 drillDump)。
- */
-async function installExtensions(connString, extensions) {
-    if (!extensions.length)
-        return [];
-    const client = new Client({ connectionString: 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;
-}
-function spawnPgRestore(bin, args) {
-    return new Promise((resolve, reject) => {
-        const proc = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
-        let stderr = "";
-        proc.stderr.on("data", (d) => (stderr += d.toString()));
-        proc.on("error", reject);
-        proc.on("close", (code) => resolve({ code, stderr }));
-    });
-}
 // 只有这些特征说明恢复失败源于沙箱缺扩展(限定类型/schema 解析不到、扩展装不上)。
 // 真实 Supabase 项目的 manifest 几乎必然含沙箱装不上的托管扩展(pg_graphql 等),
 // 若不按特征过滤,任何硬失败(归档损坏、OOM…)都会被误归因到沙箱。
 const MISSING_EXTENSION_ERROR = /type "[^"]+" does not exist|schema "[^"]+" does not exist|extension "[^"]+" is not available/i;
-// 演练沙箱是裸 Postgres,Supabase 托管的 schema/角色必然缺席。post-data 里
-// 引用它们的失败是"环境预期",不是备份坏了;其余失败才是演练要抓的。
-const SUPABASE_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;
-/** 把 pg_restore 的 stderr 拆成单个错误块并分类(Supabase 托管 vs 用户对象)。 */
+/** 兼容层:历史签名保留,分类逻辑的单一权威在统一引擎(restore-engine.ts)。 */
 export function classifyPostDataErrors(stderr) {
-    const blocks = stderr
-        .split(/(?=pg_restore: error:)/)
-        .filter((b) => /pg_restore: error:/.test(b));
-    let supabaseSkipped = 0;
-    const failures = [];
-    for (const block of blocks) {
-        // 只对 ERROR 原因行分类,不看 "Command was:" 之后的语句文本——否则一个恰好
-        // 引用 auth.uid 的用户对象因"损坏/语法错误"失败时,会被误判成预期跳过。
-        const cause = block.split(/Command was:/i)[0];
-        if (SUPABASE_MANAGED_ERROR.test(cause)) {
-            supabaseSkipped += 1;
-        }
-        else {
-            failures.push(block.replace(/\s+/g, " ").trim().slice(0, 200));
-        }
-    }
-    return { supabaseSkipped, failures };
+    const classified = classifyBlocks(stderr, SANDBOX_MANAGED_ERROR);
+    return { supabaseSkipped: classified.expectedSkips, failures: classified.failures };
 }
-/**
- * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
- * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
- */
+/** 兼容层:见 restore-engine.ts finalizePass(非零退出且零错误块 = 通用失败)。 */
 export function postDataResult(code, stderr) {
-    const result = classifyPostDataErrors(stderr);
-    if (code !== 0 && result.supabaseSkipped === 0 && result.failures.length === 0) {
-        result.failures.push(`pg_restore post-data exited with ${code === null ? "a signal" : `code ${code}`}: ` +
-            (stderr.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)"));
-    }
-    return result;
+    const classified = finalizePass(code, stderr, classifyBlocks(stderr, SANDBOX_MANAGED_ERROR));
+    return { supabaseSkipped: classified.expectedSkips, failures: classified.failures };
 }
 /**
- * 两遍恢复(真实首演炸出的设计):
- * 1. pre-data+data —— 表结构 + 数据。任何错误都是硬失败:数据回不来 = 演练失败。
- * 2. post-data —— 用户自己的索引/约束/触发器**必须**恢复成功(它们是"备份完整"的
- *    一部分,一刀切跳过会让坏备份漏网);只有引用 Supabase 托管对象的失败
- *    (policy TO authenticated、FK → auth.users)才归类为沙箱预期,记入报告而非失败。
+ * 沙箱恢复 = 统一引擎(target: "sandbox")。pre-data 失败按硬失败抛出——数据回不来
+ * = 演练失败,且错误文本要供缺扩展归因(MISSING_EXTENSION_ERROR)使用;post-data
+ * 的托管对象跳过如实返回。pre-data 的 schema 冲突跳过(dump 自带 CREATE SCHEMA,
+ * 容器恒有 public)是非事件,不计入报告。
  */
 async function pgRestore(dumpPath, connString) {
-    const pgRestoreBin = resolvePgRestoreBin();
-    const common = ["--no-owner", "--no-privileges", "--dbname", connString, dumpPath];
-    const first = await spawnPgRestore(pgRestoreBin, [
-        "--clean",
-        "--if-exists",
-        "--section=pre-data",
-        "--section=data",
-        ...common,
-    ]);
-    // pg_restore 对无害告警会返回非 0;仅在明确 error 时判失败
-    if (first.code !== 0 && /error:/i.test(first.stderr)) {
-        throw new Error(`pg_restore failed: ${first.stderr.trim()}`);
+    const result = await restoreDatabaseArtifact({ dumpPath, connString, target: "sandbox" });
+    if (result.preData.failures.length) {
+        throw new Error(`pg_restore failed: ${result.preData.failures.join(" | ")}`);
     }
-    const second = await spawnPgRestore(pgRestoreBin, ["--section=post-data", ...common]);
-    return postDataResult(second.code, second.stderr);
+    return {
+        supabaseSkipped: result.postData.expectedSkips,
+        failures: result.postData.failures,
+    };
 }
 // ── 校验 ────────────────────────────────────────────────────────────
-async function verifyRestored(connString, manifest) {
-    const client = new Client({ connectionString: connString });
+/** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
+export async function verifyRestored(connString, manifest) {
+    // pgConnectOptions:真实 Supabase 目标(restore 复用本函数)需要打包根 CA;
+    // 沙箱的 docker 连接串非 Supabase 主机,原样透传,行为不变
+    const client = new Client(pgConnectOptions(connString));
     await client.connect();
     try {
         const schemas = manifest.database.schemas;
@@ -229,7 +158,9 @@ async function verifyRestored(connString, manifest) {
                 unpopulatedMatviews.add(key);
                 continue;
             }
-            const c = await client.query(`select count(*)::bigint as n from "${t.schema}"."${t.name}"`);
+            // 名字来自恢复出的库(= 来自 dump = 桶里的数据):必须走标识符转义,
+            // 内嵌引号的合法名不炸,构造名不注入
+            const c = await client.query(`select count(*)::bigint as n from ${quoteIdent(t.schema)}.${quoteIdent(t.name)}`);
             const n = Number(c.rows[0].n);
             counts.set(key, n);
             // 分区父表的 count(*) 是子分区行的总和,子分区又各自计一次;

package/dist/index.js

@@ -4,7 +4,7 @@ import { loadConfig } from "./config.js";
 import { runBackup } from "./backup.js";
 import { runEstimate } from "./estimate.js";
 import { runDrill } from "./drill.js";
-import { runRestore } from "./restore.js";
+import { runRestore, NO_SOURCE_DATABASE } from "./restore.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 // Supabase egress 定价表(2026-07-10 核实,来源见 README「Egress & cost」)。
@@ -137,28 +137,46 @@ program
     .option("--project-name <name>", "project name used in the object key")
     .action(async (opts) => {
     try {
-        const config = await loadConfig({
-            configPath: opts.config,
-            overrides: {
-                projectName: opts.projectName,
-                databaseUrl: "postgresql://unused", // restore 读桶,不连源库
-                storage: {
-                    bucket: opts.bucket,
-                    endpoint: opts.endpoint,
-                    region: opts.region,
-                    prefix: opts.prefix,
-                },
+        // 源库连接串不再无条件屏蔽:配置/环境里有真实源时,runRestore 的同源阻断门
+        // 要拿它比对;纯 flag 驱动(无任何源配置)才退回占位符
+        const overrides = {
+            projectName: opts.projectName,
+            storage: {
+                bucket: opts.bucket,
+                endpoint: opts.endpoint,
+                region: opts.region,
+                prefix: opts.prefix,
             },
-        });
+        };
+        let config;
+        try {
+            config = await loadConfig({ configPath: opts.config, overrides });
+        }
+        catch (error) {
+            if (!/databaseUrl/.test(error.message))
+                throw error;
+            config = await loadConfig({
+                configPath: opts.config,
+                overrides: { ...overrides, databaseUrl: NO_SOURCE_DATABASE },
+            });
+        }
         const result = await runRestore(config, {
             targetDatabaseUrl: opts.targetDatabaseUrl,
             storageDir: opts.storageDir,
             snapshot: opts.snapshot,
         });
-        log.ok(`Restore complete — snapshot ${result.snapshot}: ` +
+        const failedChecks = (result.databaseChecks ?? []).filter((c) => !c.pass);
+        const summary = `snapshot ${result.snapshot}: ` +
             `database ${result.restoredToDatabase ? "restored" : "skipped"}, ` +
             `${result.storageFilesWritten} Storage files written` +
-            (result.storageDir ? ` to ${result.storageDir}` : ""));
+            (result.storageDir ? ` to ${result.storageDir}` : "");
+        if (failedChecks.length) {
+            log.error(`Restore finished with ${failedChecks.length} FAILED verification check(s) — ${summary}`);
+            process.exitCode = 1;
+        }
+        else {
+            log.ok(`Restore complete — ${summary}`);
+        }
     }
     catch (error) {
         log.error(error.message);

package/dist/lib.d.ts

@@ -6,7 +6,7 @@ export { runEstimate, project } from "./estimate.js";
 export { loadConfig } from "./config.js";
 export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
 export type { BackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
-export type { ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
+export type { BucketAttrs, ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
 export type { DrillReport, DrillCheck } from "./drill.js";
 export type { RestoreResult } from "./restore.js";
 export type { EgressPricing, EgressProjection } from "./estimate.js";

package/dist/manifest.d.ts

@@ -7,6 +7,23 @@ export interface TableStat {
     schema: string;
     name: string;
     estimatedRows: number;
+    primaryKeyColumns?: string[];
+    exactRows?: number;
+    sampleHash?: string;
+    sampleAlgorithm?: string;
+    freshnessColumn?: string;
+    freshnessValue?: string;
+}
+/**
+ * 源 bucket 的可恢复属性(v2,读自源库 storage.buckets——S3 兼容端点拿不到这些)。
+ * 值为 null = 源端就没设置;字段整体缺失 = 当次备份没捕获到(如 storage schema 无读权限),
+ * 恢复端遇缺失须如实标 "not captured",不得猜测(PRD §5.1.3)。
+ */
+export interface BucketAttrs {
+    name: string;
+    public?: boolean | null;
+    fileSizeLimit?: number | null;
+    allowedMimeTypes?: string[] | null;
 }
 /**
  * 源库安装的非内置扩展(pg_extension,排除必装的 plpgsql)。
@@ -27,8 +44,14 @@ export interface ExtensionInfo {
  *  - 缺失该字段的 manifest = 版本 1(1.0 之前写出的旧快照)
  *  - 读取端遇到**更高**的版本必须明确报错,而不是按旧结构硬解析出错误结果
  *    ——对备份工具来说,"旧程序静默误读新归档"是最不能接受的失败方式。
+ *
+ * 版本史:
+ *  - 1:初始格式。
+ *  - 2(恢复闭环 PRD §5.1):storage 增加 buckets 属性清单(public/大小/MIME 限制),
+ *    files 增加 contentType/cacheControl/metadata 等恢复所需元数据;tables 预留
+ *    验证升级字段(本期不生成)。全部为**可加字段**——v2 读取端兼容 v1 快照。
  */
-export declare const MANIFEST_SCHEMA_VERSION = 1;
+export declare const MANIFEST_SCHEMA_VERSION = 2;
 export interface Manifest {
     schemaVersion?: number;
     tool: "backupdrill-cli";
@@ -51,6 +74,7 @@ export interface Manifest {
         sha256: string;
     };
     storage: null | {
+        buckets?: BucketAttrs[];
         fileCount: number;
         totalBytes: number;
         files: StorageFile[];
@@ -61,9 +85,15 @@ export interface StorageFile {
     key: string;
     bytes: number;
     sha256: string;
+    contentType?: string;
+    cacheControl?: string;
+    contentEncoding?: string;
+    metadata?: Record<string, unknown>;
+    lastModified?: string;
 }
 /**
  * 解析桶里的 manifest.json,并做**向前兼容**校验:比本程序更新的格式一律拒绝,
  * 明确告诉用户升级,绝不按旧结构硬解析(那会静默产出错误的演练/恢复结果)。
+ * 版本关之后再做结构校验(assertManifestShape)——两类失败要给出不同的处置指引。
  */
 export declare function parseManifest(json: string): Manifest;

package/dist/manifest.js

@@ -6,11 +6,147 @@
  *  - 缺失该字段的 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) {
+    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");
+    }
+    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 +156,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/restore-engine.d.ts

@@ -0,0 +1,63 @@
+import type { ExtensionInfo } from "./manifest.js";
+export type RestoreTargetKind = "sandbox" | "supabase";
+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;
+};
+export declare function restoreDatabaseArtifact(opts: {
+    dumpPath: string;
+    connString: string;
+    target: RestoreTargetKind;
+}): Promise<EngineResult>;

package/dist/restore-engine.js

@@ -0,0 +1,151 @@
+// 统一数据库恢复引擎(恢复闭环 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";
+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) {
+    try {
+        const url = new URL(connString);
+        if (!url.password)
+            return { url: connString, env: {} };
+        const password = decodeURIComponent(url.password);
+        url.password = "";
+        return { url: url.toString(), env: { PGPASSWORD: password } };
+    }
+    catch {
+        return { url: connString, env: {} };
+    }
+}
+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 };
+}

package/dist/restore.d.ts

@@ -1,13 +1,40 @@
 import type { BackupConfig } from "./config.js";
+import { type DrillCheck } from "./drill.js";
 export interface RestoreResult {
     snapshot: string;
     restoredToDatabase: boolean;
+    /** 表级验证结果(与演练同一套 verifyRestored);未恢复数据库时不存在 */
+    databaseChecks?: DrillCheck[];
+    /**
+     * 验证总裁决(= databaseChecks 全 pass)。库级调用方(worker)必须看它,
+     * 不能只看 restoredToDatabase——"恢复完成"与"恢复通过验证"是两个事实。
+     */
+    databaseVerified?: boolean;
     storageFilesWritten: number;
     storageDir?: string;
 }
 /**
- * 把一份快照恢复出来:数据库还原进 --target-database-url;Storage 文件下载到本地目录
- * (拿回文件后你可以按需回传到新 Supabase 项目)。这是 US-5 恢复向导的 DIY 版本。
+ * restore 无源库配置时的占位连接串(纯 flag 驱动、没有 backupdrill.config.json 的场景)。
+ * 同源阻断门对它不生效——没有可比对的源;有真实源配置时阻断门照常工作。
+ */
+export declare const NO_SOURCE_DATABASE = "postgresql://unused";
+/**
+ * 从连接串提取 Supabase 项目 ref(纯函数):直连主机 `db.<ref>.supabase.co` 或
+ * pooler 用户名 `postgres.<ref>`。两种形态指向同一租户——只比 host/user 会漏掉
+ * "源填直连、目标填 pooler"的同项目组合(评审第 7 轮)。非 Supabase 形态返回 null。
+ */
+export declare function projectRefOf(connString: string): string | null;
+/**
+ * 两个连接串是否指向同一数据库租户(纯函数,可测)。
+ * Supabase 双方以项目 ref 为准(直连/pooler 形态互认);其余退回 host+user 比对
+ * ——只比 host 不够:pooler 主机是区域级共享的,租户身份在用户名里。
+ * 任一解析失败 → false(pg 侧会给出自己的连接错误,这里不误伤)。
+ */
+export declare function sameDatabaseTarget(a: string, b: string): boolean;
+/**
+ * 把一份快照恢复出来:数据库经统一引擎还原进 --target-database-url(与演练同一条
+ * pg_restore 路径与错误分类),恢复后跑同一套表级验证;Storage 文件下载到本地目录
+ * (回传到新 Supabase 项目的自动化是 P0-D,未到)。这是 US-5 恢复向导的 CLI 形态。
  */
 export declare function runRestore(config: BackupConfig, opts: {
     targetDatabaseUrl?: string;

package/dist/restore.js

@@ -1,29 +1,97 @@
-import { spawn } from "node:child_process";
-import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, rm, readdir } from "node:fs/promises";
 import { createWriteStream } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
+import { join, dirname, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { Client } from "pg";
 import { parseManifest } from "./manifest.js";
 import { targetClient, resolveSnapshot, getObjectText, downloadToFile, } from "./snapshots.js";
-import { resolvePgRestoreBin } from "./pgbin.js";
+import { restoreDatabaseArtifact, installExtensions } from "./restore-engine.js";
+import { verifyRestored } from "./drill.js";
+import { pgConnectOptions } from "./supabase-ca.js";
 import { log } from "./log.js";
-function pgRestore(dumpPath, targetUrl) {
-    const bin = resolvePgRestoreBin();
-    return new Promise((resolve, reject) => {
-        const proc = spawn(bin, ["--clean", "--if-exists", "--no-owner", "--no-privileges", "--dbname", targetUrl, dumpPath], { stdio: ["ignore", "ignore", "pipe"] });
-        let stderr = "";
-        proc.stderr.on("data", (d) => (stderr += d.toString()));
-        proc.on("error", reject);
-        proc.on("close", (code) => code === 0 || !/error:/i.test(stderr)
-            ? resolve()
-            : reject(new Error(`pg_restore failed: ${stderr.trim()}`)));
-    });
+/**
+ * restore 无源库配置时的占位连接串(纯 flag 驱动、没有 backupdrill.config.json 的场景)。
+ * 同源阻断门对它不生效——没有可比对的源;有真实源配置时阻断门照常工作。
+ */
+export const NO_SOURCE_DATABASE = "postgresql://unused";
+/**
+ * 从连接串提取 Supabase 项目 ref(纯函数):直连主机 `db.<ref>.supabase.co` 或
+ * pooler 用户名 `postgres.<ref>`。两种形态指向同一租户——只比 host/user 会漏掉
+ * "源填直连、目标填 pooler"的同项目组合(评审第 7 轮)。非 Supabase 形态返回 null。
+ */
+export function projectRefOf(connString) {
+    try {
+        const url = new URL(connString);
+        const direct = url.hostname.match(/^db\.([a-z0-9]{16,})\.supabase\.co$/);
+        if (direct)
+            return direct[1];
+        const pooled = url.username.match(/^postgres\.([a-z0-9]{16,})$/);
+        if (pooled)
+            return pooled[1];
+        return null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
- * 把一份快照恢复出来:数据库还原进 --target-database-url;Storage 文件下载到本地目录
- * (拿回文件后你可以按需回传到新 Supabase 项目)。这是 US-5 恢复向导的 DIY 版本。
+ * 两个连接串是否指向同一数据库租户(纯函数,可测)。
+ * Supabase 双方以项目 ref 为准(直连/pooler 形态互认);其余退回 host+user 比对
+ * ——只比 host 不够:pooler 主机是区域级共享的,租户身份在用户名里。
+ * 任一解析失败 → false(pg 侧会给出自己的连接错误,这里不误伤)。
+ */
+export function sameDatabaseTarget(a, b) {
+    const refA = projectRefOf(a);
+    const refB = projectRefOf(b);
+    if (refA !== null && refB !== null)
+        return refA === refB;
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        if (!ua.hostname || !ub.hostname)
+            return false;
+        return ua.hostname === ub.hostname && ua.username === ub.username;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 空目标门(PRD §5.3.3 / 决策 D5):目标 schema 里存在任何用户对象即拒绝写入。
+ * "空"的定义来自 R0 spike:不是"schema 不存在"(Supabase 恒有 public),而是
+ * schema 内零用户对象——关系、函数/过程、独立类型(enum/domain/range/composite)
+ * 全部计入:只查关系时,"目标里只有函数"会放行,然后在 pre-data 中途撞冲突,
+ * 留下半截目标(评审第 7 轮)。
+ */
+async function assertEmptyTarget(targetUrl, schemas) {
+    const client = new Client(pgConnectOptions(targetUrl));
+    await client.connect();
+    try {
+        const res = await client.query(`select
+         (select count(*) from pg_class c join pg_namespace n on n.oid = c.relnamespace
+           where n.nspname = any($1::text[]) and c.relkind in ('r','p','m','v','S','f','c'))
+       + (select count(*) from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+           where n.nspname = any($1::text[]))
+       + (select count(*) from pg_type t join pg_namespace n on n.oid = t.typnamespace
+           where n.nspname = any($1::text[]) and t.typtype in ('e','d','r'))
+         as n`, [schemas]);
+        const objectCount = Number(res.rows[0].n);
+        if (objectCount > 0) {
+            throw new Error(`target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
+                `restore only writes into an empty target. Create a fresh Supabase project ` +
+                `(or empty these schemas) and retry.`);
+        }
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * 把一份快照恢复出来:数据库经统一引擎还原进 --target-database-url(与演练同一条
+ * pg_restore 路径与错误分类),恢复后跑同一套表级验证;Storage 文件下载到本地目录
+ * (回传到新 Supabase 项目的自动化是 P0-D,未到)。这是 US-5 恢复向导的 CLI 形态。
  */
 export async function runRestore(config, opts) {
     const s3 = targetClient(config);
@@ -38,15 +106,56 @@ export async function runRestore(config, opts) {
     };
     const workdir = await mkdtemp(join(tmpdir(), "backupdrill-restore-"));
     try {
-        // 1. 数据库
+        // 1. 数据库(写入前依次过安全门:同源阻断 → 空目标 → 归档校验 → 扩展预装)
         if (opts.targetDatabaseUrl) {
+            const targetUrl = opts.targetDatabaseUrl;
+            // 同源阻断(PRD §9.3):恢复绝不写回备份的源库。误把生产源当目标是
+            // 恢复流程里代价最不对称的失误。
+            if (config.databaseUrl !== NO_SOURCE_DATABASE &&
+                sameDatabaseTarget(config.databaseUrl, targetUrl)) {
+                throw new Error("target database resolves to the same host and user as the backup source — " +
+                    "restoring onto the source project is blocked. Point --target-database-url " +
+                    "at a fresh Supabase project.");
+            }
+            log.step("Checking target is empty…");
+            await assertEmptyTarget(targetUrl, manifest.database.schemas);
             log.step("Downloading dump…");
             const dumpPath = join(workdir, "dump.pgcustom");
-            await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
+            const { sha256 } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
+            // 归档完整性是恢复的前提:哈希不符还继续,只会把"备份坏了"变成一堆误导性
+            // 恢复错误(演练侧同一裁决:integrity FAIL 即短路)
+            if (sha256 !== manifest.dump.sha256) {
+                throw new Error(`archive integrity check failed: downloaded sha256 ${sha256.slice(0, 12)}… ` +
+                    `does not match manifest ${manifest.dump.sha256.slice(0, 12)}… — refusing to restore a corrupted dump`);
+            }
+            // 扩展预装:沙箱装不上只能记录(环境局限),真实目标装不上必须阻断——
+            // 用户在 dashboard 一键可开,恢复残缺副本则要人工收拾(引擎头注的裁决分工)
+            const extensions = manifest.database.extensions ?? [];
+            if (extensions.length) {
+                log.step(`Installing ${extensions.length} extension(s) on target…`);
+                const unavailable = await installExtensions(targetUrl, extensions);
+                if (unavailable.length) {
+                    throw new Error(`target cannot install extension(s): ${unavailable.join(", ")} — enable them in ` +
+                        `the Supabase dashboard (Database → Extensions) and retry.`);
+                }
+            }
             log.step("Restoring database into target…");
-            await pgRestore(dumpPath, opts.targetDatabaseUrl);
+            const engine = await restoreDatabaseArtifact({ dumpPath, connString: targetUrl, target: "supabase" });
+            if (!engine.ok) {
+                const failures = [...engine.preData.failures, ...engine.postData.failures];
+                throw new Error(`database restore failed: ${failures.join(" | ")}`);
+            }
             result.restoredToDatabase = true;
-            log.ok(`Database restored (${manifest.database.tableCount} tables)`);
+            // 与演练同一套表级验证:两条路径对同一快照必须同一结论(PRD §5.2 验收)
+            log.step("Verifying restored tables…");
+            const verified = await verifyRestored(targetUrl, manifest);
+            result.databaseChecks = verified.checks;
+            result.databaseVerified = verified.checks.every((c) => c.pass);
+            for (const check of verified.checks) {
+                (check.pass ? log.ok : log.warn)(`${check.name}: ${check.detail}`);
+            }
+            log.ok(`Database restored (${verified.tableCount} tables, ` +
+                `${verified.rowTotal.toLocaleString()} rows)`);
         }
         else {
             log.warn("No --target-database-url given; skipping database restore.");
@@ -54,9 +163,20 @@ export async function runRestore(config, opts) {
         // 2. Storage 文件 → 本地目录
         if (manifest.storage && manifest.storage.files.length) {
             const outDir = opts.storageDir ?? join(process.cwd(), `restored-storage-${snapshot}`);
+            // 输出目录必须是新的/空的:路径锚定检查是词法层面的,防不住目录里**已有**的
+            // 符号链接把写入引到别处;保证目录从空开始 = 所有子路径都由本进程创建,无链接可循
+            await mkdir(outDir, { recursive: true });
+            if ((await readdir(outDir)).length > 0) {
+                throw new Error(`storage output directory is not empty: ${outDir} — restore only writes into a fresh directory`);
+            }
             log.step(`Downloading ${manifest.storage.files.length} Storage files → ${outDir}`);
             for (const f of manifest.storage.files) {
                 const dest = join(outDir, f.bucket, f.key);
+                // 纵深防御:parseManifest 已拒绝穿越段,这里仍锚定最终路径必须落在 outDir 内
+                // ——两道防线独立失效才会发生"篡改的 manifest 写穿输出目录"
+                if (!resolve(dest).startsWith(resolve(outDir) + sep)) {
+                    throw new Error(`unsafe storage path escapes output directory: ${f.bucket}/${f.key}`);
+                }
                 await mkdir(dirname(dest), { recursive: true });
                 const res = await s3.send(new GetObjectCommand({
                     Bucket: config.storage.bucket,

package/dist/storage-catalog.d.ts

@@ -0,0 +1,19 @@
+import type { BucketAttrs } from "./manifest.js";
+interface BucketRow {
+    id: string;
+    name: string;
+    public: boolean | null;
+    file_size_limit: string | number | null;
+    allowed_mime_types: string[] | null;
+}
+/**
+ * 行 → manifest 形状的纯映射,含完整性关口:查询结果必须覆盖每一个请求的 bucket。
+ * storage.buckets 上的 RLS 或并发删除会**静默**少返回行——把不完整清单写进 manifest,
+ * 恢复端就会漏建 bucket 还以为自己全知。缺任何一个 → 抛错,由调用方整体降级为"未捕获"。
+ * 请求标识来自 S3 层(ListBuckets),优先按 buckets.id 匹配(id 与 name 允许不同),
+ * 无中再退 name。null 属性原样保留(= 源端未设置,不是猜测值)。
+ */
+export declare function bucketAttrsFromRows(requestedBuckets: string[], bucketRows: BucketRow[]): BucketAttrs[];
+/** 查询源库的 bucket 属性。bucketNames 含空 bucket(恢复端要能重建它们)。 */
+export declare function inspectBucketAttrs(databaseUrl: string, bucketNames: string[]): Promise<BucketAttrs[]>;
+export {};

package/dist/storage-catalog.js

@@ -0,0 +1,50 @@
+// Bucket 属性采集(Manifest v2,恢复闭环 PRD §5.1.3):public / 大小限制 / MIME 限制。
+// 通道 = 源库 storage.buckets —— S3 兼容端点看不到这些属性,而备份本来就持有只读库连接,
+// 零新增凭据(R0 spike 实证)。per-file 元数据不在这里:它随 syncStorage 的 GetObject
+// 响应原子捕获(见 storage.ts fileMetadataFromS3)。
+// 任何失败都由调用方降级为"未捕获"(manifest 缺 buckets 字段),绝不弄失败一次备份。
+import { Client } from "pg";
+import { pgConnectOptions } from "./supabase-ca.js";
+/**
+ * 行 → manifest 形状的纯映射,含完整性关口:查询结果必须覆盖每一个请求的 bucket。
+ * storage.buckets 上的 RLS 或并发删除会**静默**少返回行——把不完整清单写进 manifest,
+ * 恢复端就会漏建 bucket 还以为自己全知。缺任何一个 → 抛错,由调用方整体降级为"未捕获"。
+ * 请求标识来自 S3 层(ListBuckets),优先按 buckets.id 匹配(id 与 name 允许不同),
+ * 无中再退 name。null 属性原样保留(= 源端未设置,不是猜测值)。
+ */
+export function bucketAttrsFromRows(requestedBuckets, bucketRows) {
+    const attrs = [];
+    const missing = [];
+    for (const req of requestedBuckets) {
+        const row = bucketRows.find((r) => r.id === req) ?? bucketRows.find((r) => r.name === req);
+        if (!row) {
+            missing.push(req);
+            continue;
+        }
+        attrs.push({
+            name: req, // 快照对象布局用的标识(S3 层名),恢复端按它重建
+            public: row.public,
+            fileSizeLimit: row.file_size_limit === null ? null : Number(row.file_size_limit),
+            allowedMimeTypes: row.allowed_mime_types,
+        });
+    }
+    if (missing.length) {
+        throw new Error(`storage.buckets returned no row for: ${missing.join(", ")} ` +
+            `(RLS filtering or concurrent deletion) — refusing a partial bucket capture`);
+    }
+    return attrs;
+}
+/** 查询源库的 bucket 属性。bucketNames 含空 bucket(恢复端要能重建它们)。 */
+export async function inspectBucketAttrs(databaseUrl, bucketNames) {
+    const client = new Client(pgConnectOptions(databaseUrl));
+    await client.connect();
+    try {
+        const bucketRows = await client.query(`select id, name, public, file_size_limit, allowed_mime_types
+         from storage.buckets where id = any($1::text[]) or name = any($1::text[])
+        order by name`, [bucketNames]);
+        return bucketAttrsFromRows(bucketNames, bucketRows.rows);
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/storage.d.ts

@@ -1,6 +1,20 @@
-import { S3Client } from "@aws-sdk/client-s3";
+import { S3Client, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
 import type { SupabaseStorageConfig } from "./config.js";
 import type { StorageFile } from "./manifest.js";
+/**
+ * 从 GetObject 响应提取文件的可恢复元数据。Supabase 的 S3 handler 把这些头直接
+ * 从 storage.objects.metadata / user_metadata 取出(content-type、cache-control、
+ * x-amz-meta-*,源码实证 2026-07-24)——所以这份元数据与刚流过的字节**原子一致**,
+ * 不存在"拷完再查 DB"的并发漂移窗口,也不依赖 DB 上 storage schema 的读权限。
+ * 缺席的头不落字段(= 源端未设置/未提供),不猜测。
+ */
+export declare function fileMetadataFromS3(got: GetObjectCommandOutput): {
+    contentType?: string;
+    cacheControl?: string;
+    contentEncoding?: string;
+    metadata?: Record<string, string>;
+    lastModified?: string;
+};
 /**
  * 仅列举、不下载 —— 用于接入时的容量/egress 估算,几乎不产生 egress。
  */
@@ -21,4 +35,5 @@ export declare function syncStorage(cfg: SupabaseStorageConfig, target: {
     fileCount: number;
     totalBytes: number;
     files: StorageFile[];
+    buckets: string[];
 }>;

package/dist/storage.js

@@ -37,6 +37,30 @@ async function* listObjects(client, bucket) {
         token = res.IsTruncated ? res.NextContinuationToken : undefined;
     } while (token);
 }
+/**
+ * 从 GetObject 响应提取文件的可恢复元数据。Supabase 的 S3 handler 把这些头直接
+ * 从 storage.objects.metadata / user_metadata 取出(content-type、cache-control、
+ * x-amz-meta-*,源码实证 2026-07-24)——所以这份元数据与刚流过的字节**原子一致**,
+ * 不存在"拷完再查 DB"的并发漂移窗口,也不依赖 DB 上 storage schema 的读权限。
+ * 缺席的头不落字段(= 源端未设置/未提供),不猜测。
+ */
+export function fileMetadataFromS3(got) {
+    const meta = {};
+    if (got.ContentType)
+        meta.contentType = got.ContentType;
+    if (got.CacheControl)
+        meta.cacheControl = got.CacheControl;
+    if (got.ContentEncoding)
+        meta.contentEncoding = got.ContentEncoding;
+    // MissingMeta > 0 = 服务端明确声明有元数据条目没能放进 x-amz-meta 头(非法头名等)。
+    // 记一份自知残缺的 metadata 违反"未捕获就不写"原则 → 整个字段省略,如实缺席。
+    if (got.Metadata && Object.keys(got.Metadata).length && !(got.MissingMeta && got.MissingMeta > 0)) {
+        meta.metadata = got.Metadata;
+    }
+    if (got.LastModified)
+        meta.lastModified = got.LastModified.toISOString();
+    return meta;
+}
 /**
  * 仅列举、不下载 —— 用于接入时的容量/egress 估算,几乎不产生 egress。
  */
@@ -95,10 +119,17 @@ export async function syncStorage(cfg, target) {
                 await upload.abort().catch(() => { });
                 throw error;
             }
-            files.push({ bucket, key: obj.key, bytes, sha256: hash.digest("hex") });
+            files.push({
+                bucket,
+                key: obj.key,
+                bytes,
+                sha256: hash.digest("hex"),
+                ...fileMetadataFromS3(got),
+            });
             totalBytes += bytes;
         }
         log.step(`  ${bucket}: ${files.filter((f) => f.bucket === bucket).length} files`);
     }
-    return { fileCount: files.length, totalBytes, files };
+    // buckets 含空 bucket(files 推不出来)——manifest v2 的 bucket 属性采集要按它查
+    return { fileCount: files.length, totalBytes, files, buckets };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Open-source CLI to back up a Supabase project — Postgres database and Storage files — to your own S3/R2/B2 bucket, with a checksummed manifest.",
   "type": "module",
   "bin": {