backupdrill 1.1.0 → 2.0.1

package/README.md

@@ -160,14 +160,20 @@ Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_UR
 
 **What this can and cannot verify, honestly:** `BACKUPDRILL_SANDBOX_URL` connects as the sandbox **superuser**, and superusers bypass row-level security — plus policies referencing Supabase-managed roles (`authenticated`, `anon`) are skipped during restore, since those roles don't exist outside the platform. So use `--check-cmd` for data and business invariants ("orders reference existing users", "the row count I care about is sane"). It is **not** an RLS behavior test — verifying RLS takes an authenticated client stack with real JWTs, which no restore sandbox can fake generically.
 
-When you actually need to recover, `restore` puts the database back into a target you name and pulls the Storage files down to a local folder:
+When you actually need to recover, `restore` puts the database back into a fresh
+target project (through the same engine the drills use, with verification) and
+uploads the Storage files back — start with `--dry-run`, then confirm by typing
+the target's project ref:
 
 ```bash
-backupdrill restore \
-  --target-database-url "postgresql://…/postgres" \
-  --storage-dir ./recovered
+# credentials via hidden prompts (nothing lands in shell history); CI can inject
+# BACKUPDRILL_TARGET_DATABASE_URL / BACKUPDRILL_TARGET_SERVICE_ROLE_KEY as managed secrets instead
+backupdrill restore --database --target-supabase-url https://<ref>.supabase.co --dry-run
+backupdrill restore --database --target-supabase-url https://<ref>.supabase.co --confirm-target <ref>
 ```
 
+Prefer files on disk instead? Skip the Storage target and pass `--storage-dir ./recovered`.
+
 Or restore the dump by hand — into an **empty** database, without `--clean`:
 
 ```bash
@@ -180,6 +186,21 @@ carries no ACLs), leaving the restored API returning 401s. One error is expected
 harmless: `schema "public" already exists` — the target always has it. The
 `backupdrill restore` command above handles all of this (plus verification) for you.
 
+## 2.0 migration — `restore` flags changed
+
+Restore now refuses to take credentials on the command line (argv is visible to
+every process on the machine):
+
+- `--target-database-url <url>` was **removed**. Set `BACKUPDRILL_TARGET_DATABASE_URL`
+  (or let the hidden prompt ask) and pass `--database` to say you want the
+  database restored.
+- Writing to a target now requires `--confirm-target <target-ref>` — type the
+  target project's ref to confirm. Run `--dry-run` first to preview every check.
+- The service-role key for Storage upload comes from
+  `BACKUPDRILL_TARGET_SERVICE_ROLE_KEY` (or the hidden prompt), never a flag.
+
+`backup`, `drill` and `estimate` are unchanged.
+
 ## GitHub Action / scheduled backups
 
 Want this running on a schedule without paying for a server? Run it in GitHub Actions.
@@ -199,7 +220,7 @@ Before switching to a **daily** schedule, read the egress-cost section above —
 - [x] `estimate` — project your monthly Supabase egress cost before you schedule
 - [x] `drill` — restore a snapshot into an ephemeral Postgres and prove it comes back
 - [x] Storage-file integrity check inside the drill (checksums, sampled by default)
-- [x] `restore` — recover a snapshot into a target DB + pull Storage files down
+- [x] `restore` — recover a snapshot into a fresh Supabase project: database through the drill-grade engine with verification, Storage uploaded back with per-file reconciliation (local download remains an option)
 - [x] GitHub Action wrapper
 
 For scheduling, automated restore drills, and alerting, use the hosted service at [backupdrill.com](https://backupdrill.com).

package/dist/backup.js

@@ -8,6 +8,8 @@ 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 { renderRecoveryDoc } from "./recovery-doc.js";
+import { projectRefOf, refFromStorageEndpoint, assertNoHostOverride } from "./restore-engine.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 import { pgConnectOptions, dumpUrlFor } from "./supabase-ca.js";
@@ -149,6 +151,19 @@ async function dumpToS3(config, s3, key, pgDumpBin) {
     return { bytes, sha256: hash.digest("hex") };
 }
 export async function runBackup(config) {
+    // 源身份先于一切传输(评审第 12 轮):①连接串不许带 ?host=/user= 覆盖——否则
+    // 快照记的 ref 与实际读取对象脱节,恢复端的同源保护随之失真;②库与 Storage
+    // 跨项目 = 配置错误,全量 dump+同步之后才发现会白烧 egress 还留下半截快照前缀
+    assertNoHostOverride(config.databaseUrl);
+    const dbRef = projectRefOf(config.databaseUrl);
+    const storageRef = config.supabaseStorage
+        ? refFromStorageEndpoint(config.supabaseStorage.endpoint)
+        : null;
+    if (dbRef && storageRef && dbRef !== storageRef) {
+        throw new Error(`database points at Supabase project "${dbRef}" but Storage at "${storageRef}" — ` +
+            `one BackupDrill project backs up one Supabase project; fix the config before backing up.`);
+    }
+    const sourceProjectRef = dbRef ?? storageRef;
     const pgDumpBin = process.env.BACKUPDRILL_PG_DUMP || "pg_dump";
     log.step("Inspecting database…");
     const db = await inspectDatabase(config.databaseUrl, config.schemas);
@@ -214,6 +229,7 @@ export async function runBackup(config) {
         toolVersion: TOOL_VERSION,
         createdAt: new Date().toISOString(),
         projectName: config.projectName,
+        ...(sourceProjectRef ? { sourceProjectRef } : {}),
         database: {
             serverVersion: db.serverVersion,
             pgDumpVersion: pgd.raw,
@@ -226,6 +242,23 @@ export async function runBackup(config) {
         dump: { key: dumpKey, format: "custom", bytes, sha256 },
         storage: storageResult,
     };
+    // RECOVERY.md(PRD §5.9.2.1)先于 manifest 落桶:manifest 是快照的"完成标记"
+    // (演练/恢复按它找快照)——先写手册再写标记,"快照完成"就蕴含"手册在场";
+    // 手册写失败 = 备份失败(同桶同权限,与 manifest 自身的写入风险一致)。
+    await s3.send(new PutObjectCommand({
+        Bucket: config.storage.bucket,
+        Key: `${base}/RECOVERY.md`,
+        Body: renderRecoveryDoc(manifest, {
+            snapshot: timestamp,
+            bucket: config.storage.bucket,
+            endpoint: config.storage.endpoint,
+            region: config.storage.region,
+            prefix: config.storage.prefix,
+            projectName: config.projectName,
+        }),
+        ContentType: "text/markdown",
+    }));
+    log.ok(`Recovery runbook written → s3://${config.storage.bucket}/${base}/RECOVERY.md`);
     await s3.send(new PutObjectCommand({
         Bucket: config.storage.bucket,
         Key: `${base}/manifest.json`,

package/dist/index.js

@@ -4,7 +4,28 @@ import { loadConfig } from "./config.js";
 import { runBackup } from "./backup.js";
 import { runEstimate } from "./estimate.js";
 import { runDrill } from "./drill.js";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
 import { runRestore, NO_SOURCE_DATABASE } from "./restore.js";
+/** 隐藏式秘密输入(PRD §5.3.1):终端不回显;无 TTY(CI/脚本)时明确要求走环境变量。 */
+async function promptSecret(label) {
+    if (!process.stdin.isTTY) {
+        throw new Error(`${label} is required — set the environment variable (no TTY available for a prompt).`);
+    }
+    const muted = new Writable({ write: (_chunk, _enc, cb) => cb() });
+    const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+    process.stderr.write(`${label} (hidden): `);
+    try {
+        const value = (await rl.question("")).trim();
+        process.stderr.write("\n");
+        if (!value)
+            throw new Error(`${label} was empty.`);
+        return value;
+    }
+    finally {
+        rl.close();
+    }
+}
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 // Supabase egress 定价表(2026-07-10 核实,来源见 README「Egress & cost」)。
@@ -125,10 +146,18 @@ program
 });
 program
     .command("restore")
-    .description("Recover a snapshot: restore the database into a target and pull Storage files down")
+    .description("Recover a snapshot into a FRESH Supabase project: database via the drill-grade engine, " +
+    "Storage files uploaded back (or downloaded locally). Start with --dry-run.")
     .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
-    .option("--target-database-url <url>", "connection string to restore the database INTO")
-    .option("--storage-dir <path>", "local directory to write Storage files to")
+    .option("--database", "restore the database — connection string via env BACKUPDRILL_TARGET_DATABASE_URL or a hidden prompt " +
+    "(2.0: the credential-bearing --target-database-url flag was removed; argv is visible to every process)")
+    .option("--target-supabase-url <url>", "target project URL (https://<ref>.supabase.co) to upload Storage files into; " +
+    "service-role key via env BACKUPDRILL_TARGET_SERVICE_ROLE_KEY or a hidden prompt")
+    .option("--confirm-target <ref>", "type the TARGET project ref to confirm writing to it")
+    .option("--dry-run", "run every read-only preflight check and write nothing")
+    .option("--acknowledge-unverified-source", "proceed although the source identity cannot be verified (legacy snapshot without config) — " +
+    "same-source protection is inert; double-check the target first")
+    .option("--storage-dir <path>", "local directory to write Storage files to (when not uploading)")
     .option("--snapshot <timestamp>", "which snapshot to restore (default: latest)")
     .option("--bucket <name>", "bucket the backups live in")
     .option("--endpoint <url>", "S3-compatible endpoint (for R2/B2)")
@@ -160,18 +189,51 @@ program
                 overrides: { ...overrides, databaseUrl: NO_SOURCE_DATABASE },
             });
         }
+        // 凭据形态(决策 D6,2.0 起):env 或隐藏式交互输入,绝不经 argv。
+        // --database 只表达意图,秘密自身不上命令行
+        // 秘密只随各自的意图旗标读取(评审第 9/10 轮):环境变量残留不能把 storage-only
+        // 变成意外的数据库恢复,也不能把无 Storage 目标的运行拖进凭据配对检查;
+        // 空串按缺失处理(误 export 空值不许静默吞掉一个显式请求)
+        let targetDatabaseUrl;
+        if (opts.database) {
+            targetDatabaseUrl =
+                process.env.BACKUPDRILL_TARGET_DATABASE_URL?.trim() ||
+                    (await promptSecret("Target database connection string (BACKUPDRILL_TARGET_DATABASE_URL)"));
+        }
+        let targetServiceRoleKey;
+        if (opts.targetSupabaseUrl) {
+            targetServiceRoleKey =
+                process.env.BACKUPDRILL_TARGET_SERVICE_ROLE_KEY?.trim() ||
+                    (await promptSecret("Target service-role key (BACKUPDRILL_TARGET_SERVICE_ROLE_KEY)"));
+        }
         const result = await runRestore(config, {
-            targetDatabaseUrl: opts.targetDatabaseUrl,
+            targetDatabaseUrl,
+            targetSupabaseUrl: opts.targetSupabaseUrl,
+            targetServiceRoleKey,
+            confirmTarget: opts.confirmTarget,
+            dryRun: opts.dryRun,
+            acknowledgeUnverifiedSource: opts.acknowledgeUnverifiedSource,
             storageDir: opts.storageDir,
             snapshot: opts.snapshot,
         });
+        // stdout = 机器可读通道(人读日志全在 stderr):完整结构化结果供脚本/报告消费
+        console.log(JSON.stringify(result));
+        if (result.dryRun)
+            return; // 预检自行打印结论;走到这里 = 零 blocker
         const failedChecks = (result.databaseChecks ?? []).filter((c) => !c.pass);
+        const rec = result.storageSummary?.reconcile;
+        const storageProblems = (result.storageSummary?.filesFailed.length ?? 0) +
+            (result.storageSummary?.checksumSample.mismatched.length ?? 0) +
+            // 属性漂移进裁决(评审第 10 轮):访问行为与快照不一致不算干净恢复
+            (result.storageSummary?.bucketAttrDrift.length ?? 0) +
+            (rec ? rec.missing.length + rec.sizeMismatched.length + rec.extras : 0);
         const summary = `snapshot ${result.snapshot}: ` +
             `database ${result.restoredToDatabase ? "restored" : "skipped"}, ` +
-            `${result.storageFilesWritten} Storage files written` +
+            `${result.storageFilesWritten} Storage files ${result.storageSummary ? "uploaded to target" : "written"}` +
             (result.storageDir ? ` to ${result.storageDir}` : "");
-        if (failedChecks.length) {
-            log.error(`Restore finished with ${failedChecks.length} FAILED verification check(s) — ${summary}`);
+        if (failedChecks.length || storageProblems) {
+            log.error(`Restore finished with issues (${failedChecks.length} failed check(s), ` +
+                `${storageProblems} storage problem(s)) — ${summary}`);
             process.exitCode = 1;
         }
         else {

package/dist/manifest.d.ts

@@ -58,6 +58,7 @@ export interface Manifest {
     toolVersion: string;
     createdAt: string;
     projectName: string;
+    sourceProjectRef?: string;
     database: {
         serverVersion: string;
         pgDumpVersion: string;

package/dist/manifest.js

@@ -29,6 +29,10 @@ function optionalString(value, what) {
         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");
@@ -45,6 +49,10 @@ function assertManifestShape(m) {
     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");
     }

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

@@ -1,5 +1,16 @@
 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;
@@ -56,6 +67,12 @@ 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;

package/dist/restore-engine.js

@@ -11,7 +11,44 @@
 import { spawn } from "node:child_process";
 import { Client } from "pg";
 import { resolvePgRestoreBin } from "./pgbin.js";
-import { pgConnectOptions } from "./supabase-ca.js";
+import { pgConnectOptions, dumpUrlFor } 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, {
@@ -124,21 +161,103 @@ export async function installExtensions(connString, extensions) {
  * 原样透传(libpq 自己适配的形态,不在这里破坏)。
  */
 export function credentialSafeDbArgs(connString) {
+    let url;
     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 } };
+        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);
+    // TLS 全链路 verify-full(创始人承诺项):pg_restore 与 pg_dump 同一改写——
+    // Supabase 主机强制 verify-full + 打包根 CA(libpq 的 require 不验证书,
+    // 中间人可拿到连接与数据);沙箱/外部主机原样透传。先改写 SSL 再拆密码。
+    const { url, env } = credentialSafeDbArgs(dumpUrlFor(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));