backupdrill 1.1.0 → 2.0.0

package/dist/restore.js

@@ -1,4 +1,4 @@
-import { mkdtemp, mkdir, rm, readdir } from "node:fs/promises";
+import { mkdtemp, mkdir, rm, readdir, lstat } from "node:fs/promises";
 import { createWriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve, sep } from "node:path";
@@ -7,35 +7,37 @@ 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 { restoreDatabaseArtifact, installExtensions } from "./restore-engine.js";
+import { restoreDatabaseArtifact, installExtensions, projectRefOf, refFromStorageEndpoint, assertNoHostOverride, normalizeHost, } from "./restore-engine.js";
 import { verifyRestored } from "./drill.js";
+import { restoreStorage, planStorageRestore, } from "./storage-restore.js";
 import { pgConnectOptions } from "./supabase-ca.js";
+import { resolvePgRestoreBin } from "./pgbin.js";
+import { parsePgDumpMajor } from "./backup.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { log } from "./log.js";
-/**
- * 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) {
+const execFileAsync = promisify(execFile);
+/** 本地 pg_restore 主版本(拿不到 → null,由引擎自己的报错兜底)。 */
+async function localPgRestoreMajor() {
     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;
+        const { stdout } = await execFileAsync(resolvePgRestoreBin(), ["--version"]);
+        return parsePgDumpMajor(stdout.trim());
     }
     catch {
         return null;
     }
 }
+/** 归档可读性要求:pg_restore 必须 ≥ max(写入工具版本, 源服务端版本)——格式跟随写入工具。 */
+export function requiredRestoreToolMajor(manifest) {
+    return Math.max(parsePgDumpMajor(manifest.database.pgDumpVersion) ?? 0, parseInt(manifest.database.serverVersion, 10) || 0);
+}
+/**
+ * restore 无源库配置时的占位连接串(纯 flag 驱动、没有 backupdrill.config.json 的场景)。
+ * 同源阻断门对它不生效——没有可比对的源;有真实源配置时阻断门照常工作。
+ */
+export const NO_SOURCE_DATABASE = "postgresql://unused";
+// projectRefOf 上移到引擎层(备份端写 manifest.sourceProjectRef 也要用);此处转出口
+export { projectRefOf } from "./restore-engine.js";
 /**
  * 两个连接串是否指向同一数据库租户(纯函数,可测)。
  * Supabase 双方以项目 ref 为准(直连/pooler 形态互认);其余退回 host+user 比对
@@ -52,12 +54,121 @@ export function sameDatabaseTarget(a, b) {
         const ub = new URL(b);
         if (!ua.hostname || !ub.hostname)
             return false;
-        return ua.hostname === ub.hostname && ua.username === ub.username;
+        // 用户名按驱动语义(解码后)比较,与 projectRefOf 同一口径
+        return (normalizeHost(ua.hostname) === normalizeHost(ub.hostname) &&
+            decodeURIComponent(ua.username) === decodeURIComponent(ub.username));
     }
     catch {
         return false;
     }
 }
+/**
+ * 从目标 Project URL(https://<ref>.supabase.co)提取 ref。 */
+export function refFromSupabaseUrl(supabaseUrl) {
+    try {
+        const match = normalizeHost(new URL(supabaseUrl).hostname).match(/^([a-z0-9]{16,})\.supabase\.co$/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 目标 Storage URL 的严格校验:必须是 https 且恰为 <ref>.supabase.co 源(无路径/查询)。
+ * service-role key 会作为请求头发往这个地址——校验必须发生在**第一次 fetch 之前**,
+ * 否则任意主机(或明文 http)都能收到 key(评审第 8 轮)。返回规范化 origin。
+ */
+export function validateStorageTargetOrigin(supabaseUrl) {
+    let url;
+    try {
+        url = new URL(supabaseUrl);
+    }
+    catch {
+        throw new Error(`--target-supabase-url is not a valid URL: ${supabaseUrl}`);
+    }
+    const ref = normalizeHost(url.hostname).match(/^([a-z0-9]{16,})\.supabase\.co$/);
+    if (url.protocol !== "https:" || !ref || (url.pathname !== "/" && url.pathname !== "") || url.search) {
+        throw new Error(`--target-supabase-url must be exactly https://<project-ref>.supabase.co — got "${supabaseUrl}". ` +
+            `The service-role key is only ever sent to a verified Supabase project origin.`);
+    }
+    return url.origin;
+}
+// assertNoHostOverride 上移到引擎层(备份侧的源身份自记也要用);此处转出口
+export { assertNoHostOverride } from "./restore-engine.js";
+/**
+ * 备份配置能导出的全部源项目 ref:数据库连接串 + Storage 读取端点
+ * (https://<ref>.storage.supabase.co/...)。storage-only 恢复没有目标库连接串,
+ * 同源阻断必须同样覆盖"目标 Storage = 源项目"的组合(评审第 8 轮)。
+ */
+export function sourceProjectRefs(config, manifest) {
+    const refs = new Set();
+    if (config.databaseUrl !== NO_SOURCE_DATABASE) {
+        const ref = projectRefOf(config.databaseUrl);
+        if (ref)
+            refs.add(ref);
+    }
+    const endpoint = config.supabaseStorage?.endpoint;
+    if (endpoint) {
+        const ref = refFromStorageEndpoint(endpoint);
+        if (ref)
+            refs.add(ref);
+    }
+    // manifest 自记的源 ref(评审第 9 轮):纯 flag 恢复没有 config 可比对,
+    // 快照自己就是最后一道源身份来源
+    if (manifest?.sourceProjectRef)
+        refs.add(manifest.sourceProjectRef);
+    return refs;
+}
+/**
+ * 请求与快照内容必须相交(评审第 15 轮,纯函数可测):什么都不会做的调用
+ * 不得走到"Restore complete"——自动化会把 no-op 记成一次成功恢复。
+ */
+export function assertRequestApplies(manifest, wantsDatabase, wantsStorageUpload) {
+    if (wantsStorageUpload && manifest.storage === null) {
+        throw new Error("this snapshot is database-only — there is no Storage to upload. Drop --target-supabase-url " +
+            "(and pass --database if the database restore is what you want).");
+    }
+    if (!wantsDatabase && !wantsStorageUpload && manifest.storage === null) {
+        throw new Error("nothing to do: no database restore was requested (--database) and this snapshot has no " +
+            "Storage files to download.");
+    }
+}
+/**
+ * 正式执行的确认门(PRD §5.3.3):用户必须键入目标 project ref(或非 Supabase 目标的
+ * 主机名)与实际连接目标一致。误把生产源当目标是恢复流程里代价最不对称的失误,
+ * 这道门要求人把目标身份亲手打一遍。
+ */
+export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSupabaseUrl) {
+    const dbRef = targetDatabaseUrl ? projectRefOf(targetDatabaseUrl) : null;
+    const apiRef = targetSupabaseUrl ? refFromSupabaseUrl(targetSupabaseUrl) : null;
+    // 两个入口都给了且指向不同项目 → 直接硬错,和确认无关
+    if (dbRef && apiRef && dbRef !== apiRef) {
+        throw new Error(`the target database URL points at project "${dbRef}" but --target-supabase-url at "${apiRef}" — ` +
+            `these are different projects; fix one of them.`);
+    }
+    // 外部(非 Supabase)库目标 + Supabase Storage 目标:一个确认值盖不住两个不相干
+    // 的目标(评审第 12 轮)——这种混搭直接拒绝,分两次跑各自确认
+    if (targetDatabaseUrl && !dbRef && apiRef) {
+        throw new Error("the database target is not a Supabase project while the Storage target is — one confirmation " +
+            "cannot cover two unrelated targets. Run the database restore and the Storage restore separately.");
+    }
+    let expected = dbRef ?? apiRef;
+    if (!expected && targetDatabaseUrl) {
+        try {
+            expected = new URL(targetDatabaseUrl).hostname || null;
+        }
+        catch {
+            expected = null;
+        }
+    }
+    if (!expected) {
+        throw new Error("cannot derive the target's identity from the given URLs — refusing to write without a confirmable target.");
+    }
+    if (confirmTarget !== expected) {
+        throw new Error(`restore writes to target "${expected}" — confirm by re-running with --confirm-target ${expected} ` +
+            `(use --dry-run first to preview all checks without writing).`);
+    }
+}
 /**
  * 空目标门(PRD §5.3.3 / 决策 D5):目标 schema 里存在任何用户对象即拒绝写入。
  * "空"的定义来自 R0 spike:不是"schema 不存在"(Supabase 恒有 public),而是
@@ -81,7 +192,9 @@ async function assertEmptyTarget(targetUrl, schemas) {
         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.`);
+                `(or empty these schemas) and retry. If a previous run already restored the ` +
+                `database and only Storage was interrupted, re-run WITHOUT the database target ` +
+                `to retry Storage alone.`);
         }
     }
     finally {
@@ -89,9 +202,127 @@ async function assertEmptyTarget(targetUrl, schemas) {
     }
 }
 /**
- * 把一份快照恢复出来:数据库经统一引擎还原进 --target-database-url(与演练同一条
- * pg_restore 路径与错误分类),恢复后跑同一套表级验证;Storage 文件下载到本地目录
- * (回传到新 Supabase 项目的自动化是 P0-D,未到)。这是 US-5 恢复向导的 CLI 形态。
+ * dry-run 只读预检(PRD §5.3.2):零写入,把正式执行会撞的墙全部提前撞一遍。
+ * 逐项打印,任何 blocker 汇总后抛出(退出码非零 = "现在执行不会成功")。
+ */
+async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
+    const blockers = [];
+    const db = manifest.database;
+    const mb = (n) => (n / 1024 / 1024).toFixed(1);
+    log.ok(`coverage: schemas ${db.schemas.join(", ")} — ${db.tableCount} tables, ` +
+        `~${db.estimatedRowTotal.toLocaleString()} rows, dump ${mb(manifest.dump.bytes)} MB`);
+    log.ok(manifest.storage
+        ? `storage: ${manifest.storage.fileCount} files, ${mb(manifest.storage.totalBytes)} MB` +
+            (manifest.storage.buckets ? `, ${manifest.storage.buckets.length} bucket(s) with attributes` : ", bucket attributes not captured")
+        : "storage: none (database-only snapshot)");
+    log.warn("not covered: Auth users/sessions, secret values, Edge Functions, most platform settings");
+    // 双目标一致性(dry-run 也要查,不能绿灯放行到正式执行才拒):库与 Storage
+    // 两个入口指向不同项目 = 配置错了一个
+    const dbRef = targetUrl ? projectRefOf(targetUrl) : null;
+    const apiRef = storageTarget ? refFromSupabaseUrl(storageTarget.supabaseUrl) : null;
+    if (dbRef && apiRef && dbRef !== apiRef) {
+        blockers.push(`database URL targets "${dbRef}" but Storage URL targets "${apiRef}"`);
+        log.error(`target consistency: database → ${dbRef}, storage → ${apiRef} — different projects`);
+    }
+    else if (dbRef || apiRef) {
+        log.ok(`target project: ${dbRef ?? apiRef}`);
+    }
+    if (targetUrl) {
+        if (config.databaseUrl !== NO_SOURCE_DATABASE && sameDatabaseTarget(config.databaseUrl, targetUrl)) {
+            blockers.push("target database is the backup SOURCE (same project)");
+            log.error("target identity: SAME AS SOURCE — would be blocked");
+        }
+        else {
+            log.ok("target identity: distinct from source");
+        }
+        try {
+            await assertEmptyTarget(targetUrl, db.schemas);
+            log.ok(`target schemas (${db.schemas.join(", ")}) are empty`);
+        }
+        catch (error) {
+            blockers.push(error.message);
+            log.error(`empty-target check: ${error.message}`);
+        }
+        const client = new Client(pgConnectOptions(targetUrl));
+        await client.connect();
+        try {
+            // SHOW 的结果列名是 server_version;用 current_setting 显式起别名,
+            // 否则取错列得 NaN,而 NaN < x 恒 false = 版本降级永远查不出来
+            const version = await client.query("select current_setting('server_version') as v");
+            const targetMajor = parseInt(version.rows[0].v, 10);
+            const sourceMajor = parseInt(db.serverVersion, 10);
+            if (!Number.isFinite(targetMajor)) {
+                blockers.push(`cannot determine target PostgreSQL version (got "${version.rows[0].v}")`);
+                log.error("postgres version: undeterminable — refusing to guess");
+            }
+            else if (targetMajor < sourceMajor) {
+                blockers.push(`target PostgreSQL ${targetMajor} < source ${sourceMajor}`);
+                log.error(`postgres version: target ${targetMajor} < source ${sourceMajor} — would fail`);
+            }
+            else {
+                log.ok(`postgres version: target ${targetMajor} ≥ source ${sourceMajor}`);
+            }
+            const toolMajor = await localPgRestoreMajor();
+            const requiredMajor = requiredRestoreToolMajor(manifest);
+            if (toolMajor === null) {
+                blockers.push("local pg_restore missing or version unparseable");
+                log.error("pg_restore tool: not found / version unparseable — set BACKUPDRILL_PG_RESTORE");
+            }
+            else if (toolMajor < requiredMajor) {
+                blockers.push(`local pg_restore v${toolMajor} < archive requirement v${requiredMajor}`);
+                log.error(`pg_restore tool: local v${toolMajor} cannot read a v${requiredMajor} archive`);
+            }
+            else {
+                log.ok(`pg_restore tool: local v${toolMajor} ≥ archive requirement v${requiredMajor}`);
+            }
+            const extensions = db.extensions ?? [];
+            if (extensions.length) {
+                const available = await client.query(`select name from pg_available_extensions where name = any($1::text[])`, [extensions.map((e) => e.name)]);
+                const availableNames = new Set(available.rows.map((r) => r.name));
+                const missing = extensions.filter((e) => !availableNames.has(e.name)).map((e) => e.name);
+                if (missing.length) {
+                    blockers.push(`extensions unavailable on target: ${missing.join(", ")}`);
+                    log.error(`extensions: ${missing.join(", ")} unavailable — enable in dashboard first`);
+                }
+                else {
+                    log.ok(`extensions: all ${extensions.length} available on target`);
+                }
+            }
+        }
+        finally {
+            await client.end();
+        }
+    }
+    else {
+        log.warn("no target database URL — database restore would be skipped");
+    }
+    if (storageTarget) {
+        // 完整的 Storage 只读计划(评审第 16 轮):dry-run 不止测可达性,把桶校验、
+        // 残留净度、残留哈希全部提前撞一遍
+        try {
+            const plan = await planStorageRestore(storageTarget, manifest);
+            log.ok(`storage plan: ${plan.bucketsToCreate.length} bucket(s) to create, ` +
+                `${plan.verifiedResidue} verified residue file(s)`);
+            for (const warning of plan.warnings)
+                log.warn(warning);
+        }
+        catch (error) {
+            blockers.push(`storage plan: ${error.message}`);
+            log.error(`storage plan: ${error.message}`);
+        }
+    }
+    else if (manifest.storage) {
+        log.warn("no Storage target credentials — files would be downloaded locally, not uploaded");
+    }
+    if (blockers.length) {
+        throw new Error(`dry run found ${blockers.length} blocker(s):\n  - ${blockers.join("\n  - ")}`);
+    }
+    log.ok("dry run passed — nothing was written; re-run with --confirm-target to execute");
+}
+/**
+ * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
+ * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),
+ * 否则下载到本地目录。这是 US-5 恢复向导的 CLI 形态。
  */
 export async function runRestore(config, opts) {
     const s3 = targetClient(config);
@@ -99,13 +330,74 @@ export async function runRestore(config, opts) {
     const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
     const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
     const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    // Storage 目标构造即校验(https + 恰为 <ref>.supabase.co):service key 只发往
+    // 已验证的 Supabase 项目源;目标库连接串拒绝 host 覆盖(身份判定=实际写入目标)
+    // 两个字段必须成对:只给其一时静默退回"本地下载"会让库级调用方把受保护文件
+    // 写进 worker 本地目录还以为回传成功了(评审第 9 轮)
+    if (!!opts.targetSupabaseUrl !== !!opts.targetServiceRoleKey) {
+        throw new Error("targetSupabaseUrl and targetServiceRoleKey must be provided together — " +
+            "refusing to silently fall back to a local download.");
+    }
+    const storageTarget = opts.targetSupabaseUrl && opts.targetServiceRoleKey
+        ? {
+            supabaseUrl: validateStorageTargetOrigin(opts.targetSupabaseUrl),
+            serviceRoleKey: opts.targetServiceRoleKey,
+        }
+        : null;
+    if (opts.targetDatabaseUrl)
+        assertNoHostOverride(opts.targetDatabaseUrl);
+    // 同源阻断(统一收口):目标(库或 Storage)的 ref 命中任何源项目 ref → 拒绝。
+    // 覆盖 storage-only 组合:目标 Storage = 备份读取源的项目时,upsert 会改写源。
+    const sourceRefs = sourceProjectRefs(config, manifest);
+    const targetRefs = [
+        opts.targetDatabaseUrl ? projectRefOf(opts.targetDatabaseUrl) : null,
+        opts.targetSupabaseUrl ? refFromSupabaseUrl(opts.targetSupabaseUrl) : null,
+    ].filter((r) => r !== null);
+    for (const ref of targetRefs) {
+        if (sourceRefs.has(ref)) {
+            throw new Error(`target project "${ref}" is the backup SOURCE — restoring onto the source is blocked. ` +
+                `Point the restore at a fresh Supabase project.`);
+        }
+    }
+    // 源身份必须**对每类目标可比**才算已知(评审第 10/14 轮):
+    //  - 库目标:有真实源连接串即可(host+user 逐一可比),或有 ref;
+    //  - Storage 目标:只有 ref 能比(无关的外部 DATABASE_URL 不构成 Storage 侧身份)。
+    // 不可比 + 未显式认知风险 = 拒绝,不 fail-open。
+    const refIdentityKnown = sourceRefs.size > 0;
+    const dbIdentityComparable = config.databaseUrl !== NO_SOURCE_DATABASE || refIdentityKnown;
+    const unverifiable = (opts.targetDatabaseUrl && !dbIdentityComparable) || (storageTarget && !refIdentityKnown);
+    if (unverifiable && !opts.acknowledgeUnverifiedSource) {
+        throw new Error("source identity cannot be verified for every requested target (legacy snapshot without a " +
+            "comparable source record) — same-source protection would be inert. Restore with the original " +
+            "backup config (-c backupdrill.config.json), or pass --acknowledge-unverified-source after " +
+            "double-checking the target is NOT the original project.");
+    }
     const result = {
         snapshot,
         restoredToDatabase: false,
         storageFilesWritten: 0,
     };
+    assertRequestApplies(manifest, !!opts.targetDatabaseUrl, !!storageTarget);
+    // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
+    if (opts.dryRun) {
+        log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
+        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget);
+        result.dryRun = true;
+        return result;
+    }
+    // 正式执行的确认门(PRD §5.3.3):任何目标写入(库或 Storage)之前
+    if (opts.targetDatabaseUrl || storageTarget) {
+        assertConfirmedTarget(opts.confirmTarget, opts.targetDatabaseUrl, opts.targetSupabaseUrl);
+    }
     const workdir = await mkdtemp(join(tmpdir(), "backupdrill-restore-"));
     try {
+        // 0. Storage 只读计划先行(评审第 16 轮):可预见的 Storage 冲突必须在数据库
+        // 写入之前发现——"库好了、Storage 拒了"的半截目标是本序修掉的形态。
+        // 执行阶段(下方 2a)会重新计划:库恢复耗时内目标可能变化,复验是正确成本。
+        if (storageTarget && manifest.storage) {
+            log.step("Planning Storage restore (read-only, before any database write)…");
+            await planStorageRestore(storageTarget, manifest);
+        }
         // 1. 数据库(写入前依次过安全门:同源阻断 → 空目标 → 归档校验 → 扩展预装)
         if (opts.targetDatabaseUrl) {
             const targetUrl = opts.targetDatabaseUrl;
@@ -114,11 +406,44 @@ export async function runRestore(config, opts) {
             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 " +
+                    "restoring onto the source project is blocked. Point BACKUPDRILL_TARGET_DATABASE_URL " +
                     "at a fresh Supabase project.");
             }
             log.step("Checking target is empty…");
             await assertEmptyTarget(targetUrl, manifest.database.schemas);
+            // 版本预检不只属于 dry-run:跳过 dry-run 直接执行时,目标比源旧照样会
+            // 半途炸掉或部分恢复(评审第 8 轮)——写入前必须拦住
+            const versionClient = new Client(pgConnectOptions(targetUrl));
+            await versionClient.connect();
+            let targetMajor;
+            try {
+                const res = await versionClient.query("select current_setting('server_version') as v");
+                targetMajor = parseInt(res.rows[0].v, 10);
+            }
+            finally {
+                await versionClient.end();
+            }
+            const sourceMajor = parseInt(manifest.database.serverVersion, 10);
+            if (!Number.isFinite(targetMajor) || targetMajor < sourceMajor) {
+                throw new Error(`target PostgreSQL (${Number.isFinite(targetMajor) ? targetMajor : "undeterminable"}) is older ` +
+                    `than the source (${sourceMajor}) — pg_restore would fail or partially restore. ` +
+                    `Create the target on PostgreSQL ${sourceMajor} or newer.`);
+            }
+            // 本地工具闸(评审第 10 轮):dump 归档格式跟随写入工具版本,老 pg_restore
+            // 读不了新归档——不查的话会先装完扩展再在恢复中途才炸
+            const toolMajor = await localPgRestoreMajor();
+            const requiredMajor = requiredRestoreToolMajor(manifest);
+            // 查不到版本(pg_restore 缺失/输出不可解析)= fail-closed:不能先装扩展改了目标,
+            // 才发现根本没有可用的恢复工具(评审第 11 轮)
+            if (toolMajor === null) {
+                throw new Error(`cannot determine the local pg_restore version — install postgresql client ${requiredMajor}+ ` +
+                    `and/or point BACKUPDRILL_PG_RESTORE at it before restoring.`);
+            }
+            if (toolMajor < requiredMajor) {
+                throw new Error(`local pg_restore is v${toolMajor} but this archive needs v${requiredMajor}+ ` +
+                    `(archive format follows the writing tool). Install postgresql client ${requiredMajor}+ ` +
+                    `and/or point BACKUPDRILL_PG_RESTORE at it.`);
+            }
             log.step("Downloading dump…");
             const dumpPath = join(workdir, "dump.pgcustom");
             const { sha256 } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
@@ -158,13 +483,60 @@ export async function runRestore(config, opts) {
                 `${verified.rowTotal.toLocaleString()} rows)`);
         }
         else {
-            log.warn("No --target-database-url given; skipping database restore.");
+            log.warn("No database target (--database + BACKUPDRILL_TARGET_DATABASE_URL); skipping database restore.");
+        }
+        // 2a. Storage → 目标项目回传(P0-D:给了目标 Storage 凭据时)
+        if (manifest.storage && storageTarget) {
+            const summary = await restoreStorage({ s3, bucket: config.storage.bucket, base }, storageTarget, manifest);
+            result.storageSummary = summary;
+            result.storageFilesWritten = summary.filesUploaded;
+            log.ok(`Storage restored: ${summary.filesUploaded}/${manifest.storage.files.length} files uploaded` +
+                (summary.filesSkippedIdentical
+                    ? `, ${summary.filesSkippedIdentical} already present (identical size)`
+                    : "") +
+                ` (${(summary.bytesUploaded / 1024 / 1024).toFixed(1)} MB), ` +
+                `buckets created ${summary.bucketsCreated.length} / existing ${summary.bucketsExisting.length}`);
+            if (summary.bucketsWithoutAttrs.length) {
+                log.warn(`bucket attributes not captured for: ${summary.bucketsWithoutAttrs.join(", ")} — ` +
+                    `created with defaults; review public/size/MIME settings by hand`);
+            }
+            for (const failed of summary.filesFailed.slice(0, 5)) {
+                log.warn(`file failed: ${failed.file} — ${failed.reason}`);
+            }
+            if (summary.filesFailed.length > 5) {
+                log.warn(`…and ${summary.filesFailed.length - 5} more file failure(s)`);
+            }
+            for (const drift of summary.bucketAttrDrift) {
+                log.warn(`bucket attribute drift: ${drift}`);
+            }
+            for (const note of summary.metadataNotes) {
+                log.warn(`metadata: ${note}`);
+            }
+            if (summary.retries)
+                log.warn(`transient failures retried: ${summary.retries}`);
+            const rec = summary.reconcile;
+            (rec.matches ? log.ok : log.error)(`reconcile: ${rec.verified}/${manifest.storage.files.length} file(s) present with matching size` +
+                (rec.missing.length ? `; MISSING: ${rec.missing.slice(0, 5).join(", ")}` : "") +
+                (rec.sizeMismatched.length ? `; SIZE MISMATCH: ${rec.sizeMismatched.slice(0, 5).join(", ")}` : "") +
+                (rec.extras ? `; ${rec.extras} extra object(s) on target not in this snapshot` : ""));
+            if (summary.checksumSample.checked) {
+                (summary.checksumSample.mismatched.length === 0 ? log.ok : log.error)(`checksum sample: ${summary.checksumSample.checked} file(s) re-hashed from target` +
+                    (summary.checksumSample.mismatched.length
+                        ? `, MISMATCH: ${summary.checksumSample.mismatched.join(", ")}`
+                        : ", all match"));
+            }
+            log.warn(summary.ownerNote);
         }
-        // 2. Storage 文件 → 本地目录
-        if (manifest.storage && manifest.storage.files.length) {
+        else if (manifest.storage && manifest.storage.files.length) {
             const outDir = opts.storageDir ?? join(process.cwd(), `restored-storage-${snapshot}`);
             // 输出目录必须是新的/空的:路径锚定检查是词法层面的,防不住目录里**已有**的
             // 符号链接把写入引到别处;保证目录从空开始 = 所有子路径都由本进程创建,无链接可循
+            // 根路径若已存在,必须是真目录:mkdir/readdir/词法锚定都会跟随根上的符号链接,
+            // 一条预置的 link 就能把"新目录"指到别处(评审第 12 轮)
+            const rootStat = await lstat(outDir).catch(() => null);
+            if (rootStat && !rootStat.isDirectory()) {
+                throw new Error(`storage output path exists and is not a real directory: ${outDir}`);
+            }
             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`);

package/dist/storage-restore.d.ts

@@ -0,0 +1,79 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import type { Manifest, StorageFile } from "./manifest.js";
+export interface StorageRestoreTarget {
+    supabaseUrl: string;
+    serviceRoleKey: string;
+}
+export interface ReconcileReport {
+    /** manifest 文件在目标上逐键找到且尺寸一致的数量 */
+    verified: number;
+    missing: string[];
+    sizeMismatched: string[];
+    /** 目标上存在但 manifest 没有的对象数——非快照内容混在恢复目标里 = 不是干净恢复,计入失败裁决 */
+    extras: number;
+    matches: boolean;
+}
+export interface StorageRestoreSummary {
+    bucketsCreated: string[];
+    bucketsExisting: string[];
+    /** manifest 未捕获属性的 bucket(以默认设置创建,如实上报,不猜测) */
+    bucketsWithoutAttrs: string[];
+    /** 既有 bucket 与 manifest 属性不一致的描述(warn 级:可能是用户有意配置) */
+    bucketAttrDrift: string[];
+    filesUploaded: number;
+    bytesUploaded: number;
+    /** 目标已有同 key 同尺寸对象而跳过的数量(重试残留;字节级抽样校验覆盖) */
+    filesSkippedIdentical: number;
+    filesFailed: {
+        file: string;
+        reason: string;
+    }[];
+    /** 429/5xx/超时后的成功重试次数(可观测性:PRD §10.3) */
+    retries: number;
+    reconcile: ReconcileReport;
+    checksumSample: {
+        checked: number;
+        mismatched: string[];
+    };
+    /** 元数据降级说明(如 TUS 路径不保真的字段)——如实上报,不静默丢 */
+    metadataNotes: string[];
+    /** PRD §5.4.3:owner 语义边界,报告必须显示 */
+    ownerNote: string;
+}
+/** bucket 名单 = manifest.buckets(含空桶)∪ files 里出现过的桶(v1 快照没有 buckets 字段) */
+export declare function bucketsToRestore(manifest: Manifest): {
+    name: string;
+    attrs: boolean;
+}[];
+export declare const STANDARD_UPLOAD_LIMIT_BYTES: number;
+/**
+ * TUS 启用阈值:默认 = 6MB(Supabase 官方对 resumable 的建议线)——大文件从零重传
+ * 的标准上传既脆弱又贵;env 可覆盖(验证时压低,特殊网络环境可调高)。
+ */
+export declare function tusThresholdBytes(): number;
+/**
+ * 递归遍历目标 bucket 的全部对象(list API 是目录级的:id === null 的条目是"目录")。
+ * 返回 key → size。不依赖目标 DB 凭据 → storage-only 恢复也有完整对账。
+ */
+export declare function walkTargetObjects(target: StorageRestoreTarget, bucket: string, counters?: {
+    retries: number;
+}): Promise<Map<string, number>>;
+/**
+ * 写前净度检查(纯函数,可测):既有桶里只允许"本快照的同尺寸残留"。
+ * 任何外来对象或尺寸冲突都在**写第一个字节之前**整体拒绝——部分写入的脏目标
+ * 比干净失败难收拾得多(评审第 14 轮)。
+ */
+export declare function targetResidueViolations(files: StorageFile[], preexisting: Map<string, Map<string, number>>): string[];
+/** 逐键对账(纯函数,可测):manifest 每个文件都必须在目标出现且尺寸一致;多余对象另计。 */
+export declare function reconcileFiles(files: StorageFile[], actualByBucket: Map<string, Map<string, number>>): ReconcileReport;
+/** dry-run / 执行前预检的公开形态:一次性 scratch 摘要,只返回计划概要与警告。 */
+export declare function planStorageRestore(target: StorageRestoreTarget, manifest: Manifest): Promise<{
+    bucketsToCreate: string[];
+    verifiedResidue: number;
+    warnings: string[];
+}>;
+export declare function restoreStorage(source: {
+    s3: S3Client;
+    bucket: string;
+    base: string;
+}, target: StorageRestoreTarget, manifest: Manifest): Promise<StorageRestoreSummary>;