backupdrill 0.2.0 → 1.0.0

package/README.md

@@ -150,13 +150,15 @@ Backups record your installed Postgres extensions in the manifest, and the drill
 
 ### Run your own checks against the restored copy
 
-The drill's structural checks (tables, rows, checksums) can't know what "working" means for *your* app — RLS behavior and business workflows only have answers in your code. `--check-cmd` hands you the restored sandbox before it's destroyed:
+The drill's structural checks (tables, rows, checksums) can't know what "working" means for *your* app — business invariants only have answers in your code. `--check-cmd` hands you the restored sandbox before it's destroyed:
 
 ```bash
 backupdrill drill --check-cmd "npm run smoke"   # BACKUPDRILL_SANDBOX_URL points at the restored copy
 ```
 
-Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_URL` set to the sandbox's connection string. Exit 0 means pass; the result shows up in the report as an `app checks` line, and a non-zero exit fails the drill (the report keeps structural and app-level failures clearly separate). Entirely optional — without the flag, nothing changes and the report has no `app checks` line. There's a 10-minute timeout, and `--keep` leaves the sandbox container running when a drill fails so you can inspect it (`docker rm -f <id>` when done).
+Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_URL` set to the sandbox's connection string. Exit 0 means pass; the result shows up in the report as an `app checks` line, and a non-zero exit fails the drill (the report keeps structural and app-level failures clearly separate). Entirely optional — without the flag, nothing changes and the report has no `app checks` line. There's a 10-minute timeout (the whole process tree is killed), and `--keep` leaves the sandbox container running when a drill fails so you can inspect it — the report JSON then includes a `keptSandbox` object with the container id and connection string (`docker rm -f <id>` when done).
+
+**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:
 
@@ -196,6 +198,23 @@ Before switching to a **daily** schedule, read the egress-cost section above —
 
 For scheduling, automated restore drills, and alerting, use the hosted service at [backupdrill.com](https://backupdrill.com).
 
+## Versioning & stability
+
+`backupdrill` follows [semantic versioning](https://semver.org/). From **1.0.0** onwards the
+following is the stable public surface — breaking it requires a major version bump:
+
+- the commands (`backup`, `drill`, `restore`, `estimate`) and their flags
+- the `BACKUPDRILL_*` environment variables and the config-file keys
+- the layout written to your bucket, and the shape of `manifest.json`
+
+`manifest.json` carries a `schemaVersion` so the format can evolve safely. A snapshot written by
+a newer release is **refused with a clear message** rather than parsed on a best-effort basis —
+for a backup tool, silently misreading an archive is the worst possible failure. Snapshots taken
+before 1.0 have no `schemaVersion` and are treated as version 1, so older backups stay readable.
+
+The package's **JavaScript exports are internal** to the hosted BackupDrill product and are not
+covered by this promise; they may change in any release. Use the CLI if you need a stable contract.
+
 ## License
 
 MIT

package/dist/backup.js

@@ -5,9 +5,11 @@ import { promisify } from "node:util";
 import { Client } from "pg";
 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 { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
+import { pgConnectOptions, dumpUrlFor } from "./supabase-ca.js";
 const execFileAsync = promisify(execFile);
 function majorOf(serverVersionNum) {
     // server_version_num: 150004 → 15,  170002 → 17
@@ -45,7 +47,9 @@ async function pgDumpVersion(bin) {
     }
 }
 async function inspectDatabase(databaseUrl, schemas) {
-    const client = new Client({ connectionString: databaseUrl });
+    // Supabase 主机 → 用打包的根 CA 做 verify-full(pooler 证书自签、不在系统信任库);
+    // 非 Supabase(本 CLI 不限制目标)→ 保持默认,别把开源用户挡在门外
+    const client = new Client(pgConnectOptions(databaseUrl));
     await client.connect();
     try {
         const version = await client.query("show server_version");
@@ -97,13 +101,15 @@ async function dumpToS3(config, s3, key, pgDumpBin) {
         },
     });
     const schemaArgs = config.schemas.map((s) => `--schema=${s}`);
+    // pg_dump(libpq):Supabase 主机才改写成 sslmode=verify-full + sslrootcert=<打包CA临时文件>
+    const dumpDbUrl = dumpUrlFor(config.databaseUrl);
     const dump = spawn(pgDumpBin, [
         "--format=custom",
         "--no-owner",
         "--no-privileges",
         ...schemaArgs,
         "--dbname",
-        config.databaseUrl,
+        dumpDbUrl,
     ], { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
     dump.stderr.on("data", (d) => {
@@ -189,6 +195,7 @@ export async function runBackup(config) {
             `${(synced.totalBytes / 1024 / 1024).toFixed(1)} MB)`);
     }
     const manifest = {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
         tool: "backupdrill-cli",
         toolVersion: TOOL_VERSION,
         createdAt: new Date().toISOString(),

package/dist/drill.d.ts

@@ -20,6 +20,11 @@ export interface DrillReport {
     restoreSeconds: number;
     restoredTableCount: number;
     restoredRowTotal: number;
+    /** --keep 且演练失败时:被保留的沙箱(供排查/脚本消费);其余情况不存在 */
+    keptSandbox?: {
+        containerId: string;
+        connString: string;
+    };
 }
 /** post-data 第二遍恢复的结果:用户对象失败 vs Supabase 托管对象的沙箱预期跳过。 */
 interface PostDataResult {
@@ -36,8 +41,9 @@ export declare function postDataResult(code: number | null, stderr: string): Pos
 export declare const APP_CHECK_TIMEOUT_MS: number;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
- * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
- * 命令输出,只裁决退出码:0 = pass)。
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
  * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
  * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
  * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。

package/dist/drill.js

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 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 { log } from "./log.js";
@@ -313,8 +314,9 @@ async function verifyStorage(s3, config, manifest, verifyAll) {
 export const APP_CHECK_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL
- * 交给用户命令执行(RLS 行为、业务流可用性——判据只存在于应用侧,引擎不解释
- * 命令输出,只裁决退出码:0 = pass)。
+ * 交给用户命令执行,校验数据/业务不变量(判据只存在于应用侧,引擎不解释命令输出,
+ * 只裁决退出码:0 = pass)。注意这不是 RLS 行为测试:连接身份是沙箱超级用户
+ * (绕过 RLS),且引用 Supabase 托管角色的策略在恢复时已被归类跳过。
  * 子进程输出定向到 stderr:stdout 是 CLI 的机器可读 JSON 通道,不能被污染。
  * 红线:托管 worker 绝不能把用户输入传到这里(任意代码执行);此钩子只属于
  * 用户在自己机器上运行的 CLI(见 PRD §1.4 演练后应用自检钩子)。
@@ -326,10 +328,22 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
             shell: true,
             stdio: ["ignore", 2, 2],
             env: { ...process.env, BACKUPDRILL_SANDBOX_URL: connString },
-            timeout: timeoutMs,
-            killSignal: "SIGKILL",
+            // 独立进程组:超时必须杀整棵进程树。只杀 shell 的话,npm/测试运行器这类
+            // 孙进程会在沙箱销毁后继续跑(xreview 抓出的资源泄漏)。
+            detached: true,
         });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-proc.pid, "SIGKILL"); // 负 pid = 杀整个进程组
+            }
+            catch {
+                proc.kill("SIGKILL");
+            }
+        }, timeoutMs);
         proc.on("error", (error) => {
+            clearTimeout(timer);
             resolve({
                 name: "app checks",
                 pass: false,
@@ -337,12 +351,21 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
             });
         });
         proc.on("close", (code, signal) => {
+            clearTimeout(timer);
             const seconds = Math.round((Date.now() - started) / 100) / 10;
+            if (timedOut) {
+                resolve({
+                    name: "app checks",
+                    pass: false,
+                    detail: `timed out after ${timeoutMs / 1000}s — process tree killed`,
+                });
+                return;
+            }
             if (signal) {
                 resolve({
                     name: "app checks",
                     pass: false,
-                    detail: `terminated by ${signal} after ${seconds}s (timeout ${timeoutMs / 1000}s)`,
+                    detail: `terminated by ${signal} after ${seconds}s`,
                 });
                 return;
             }
@@ -362,6 +385,12 @@ export function runAppCheck(command, connString, timeoutMs = APP_CHECK_TIMEOUT_M
  * 与 S3 解耦,便于离线测试。`preChecks` 用于把下载阶段的校验(如归档校验和)带进报告。
  */
 export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], opts = {}) {
+    // 空/纯空白命令 = 危险的假配置(CI 里变量没展开的典型形态):跑了会以 exit 0
+    // 假通过,忽略会让用户以为检查在跑。拒绝,且要在起沙箱之前拒绝。
+    const appCheckCommand = opts.appCheckCommand?.trim();
+    if (opts.appCheckCommand !== undefined && !appCheckCommand) {
+        throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to report a check that would never run");
+    }
     const checks = [...preChecks];
     const pg = await startEphemeralPostgres(sandboxImage(manifest));
     let pass = false; // 异常路径视为失败,供 finally 决定 --keep 是否保留沙箱
@@ -414,12 +443,12 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
         checks.push(...verify.checks);
         // 语义层钩子:只在结构层全绿时才跑——结构已失败时再跑应用检查,只会把
         // 一次失败报成两层失败,误导排查方向。没配置则不跑、报告里不出现该行。
-        if (opts.appCheckCommand && checks.every((c) => c.pass)) {
+        if (appCheckCommand && checks.every((c) => c.pass)) {
             log.step("Running app checks…");
-            checks.push(await runAppCheck(opts.appCheckCommand, pg.connString));
+            checks.push(await runAppCheck(appCheckCommand, pg.connString));
         }
         pass = checks.every((c) => c.pass);
-        return {
+        const report = {
             snapshot,
             pass,
             checks,
@@ -427,6 +456,20 @@ export async function drillDump(dumpPath, manifest, snapshot, preChecks = [], op
             restoredTableCount: verify.tableCount,
             restoredRowTotal: verify.rowTotal,
         };
+        if (opts.keepSandboxOnFailure && !pass) {
+            // 写进报告让 --keep 可被脚本消费(拿连接串排查),不只靠人眼看日志
+            report.keptSandbox = { containerId: pg.containerId, connString: pg.connString };
+        }
+        return report;
+    }
+    catch (error) {
+        // 异常路径(恢复/校验抛出)没有报告对象可挂 keptSandbox;把沙箱坐标并入
+        // 错误信息,让脚本和人都拿得到被保留容器的清理线索
+        if (opts.keepSandboxOnFailure) {
+            error.message +=
+                ` [sandbox kept: ${pg.connString} — remove with: docker rm -f ${pg.containerId.slice(0, 12)}]`;
+        }
+        throw error;
     }
     finally {
         if (opts.keepSandboxOnFailure && !pass) {
@@ -446,7 +489,7 @@ export async function runDrill(config, opts = {}) {
     const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
     const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
     log.step(`Drilling snapshot ${snapshot}`);
-    const manifest = JSON.parse(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
+    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
     const workdir = await mkdtemp(join(tmpdir(), "backupdrill-"));
     const dumpPath = join(workdir, "dump.pgcustom");
     try {

package/dist/estimate.js

@@ -1,11 +1,12 @@
 import { Client } from "pg";
 import { measureStorage } from "./storage.js";
 import { log } from "./log.js";
+import { pgConnectOptions } from "./supabase-ca.js";
 // 超出这个月度成本就该提醒用户"备份的 egress 账单快赶上订阅费了"
 const SUBSCRIPTION_FLOOR_USD = 19;
 const GB = 1024 * 1024 * 1024;
 async function measureDbBytes(databaseUrl, schemas) {
-    const client = new Client({ connectionString: databaseUrl });
+    const client = new Client(pgConnectOptions(databaseUrl));
     await client.connect();
     try {
         // pg_total_relation_size 含索引+TOAST,是 egress 上界(真实转储经压缩、不含索引,更小)

package/dist/index.js

@@ -76,10 +76,16 @@ program
     .option("--project-name <name>", "project name used in the object key")
     .option("--verify-all-files", "checksum every Storage file, not just a sample")
     .option("--check-cmd <command>", "after structural checks pass, run your own smoke test against the restored sandbox " +
-    "(connection string in BACKUPDRILL_SANDBOX_URL; exit 0 = pass, reported as 'app checks')")
+    "(connection string in BACKUPDRILL_SANDBOX_URL; exit 0 = pass, reported as 'app checks'). " +
+    "Note: connects as the sandbox superuser, so RLS policies are NOT enforced — " +
+    "verify data and business invariants here, not RLS behavior")
     .option("--keep", "if the drill fails, keep the sandbox container running for inspection")
     .action(async (opts) => {
     try {
+        if (opts.checkCmd !== undefined && !String(opts.checkCmd).trim()) {
+            throw new Error("--check-cmd is empty (did an env var fail to expand?) — refusing to run a drill " +
+                "that would report a check that never executes");
+        }
         const config = await loadConfig({
             configPath: opts.config,
             overrides: {

package/dist/lib.d.ts

@@ -1,4 +1,5 @@
 export { runBackup } from "./backup.js";
+export { SUPABASE_ROOT_CA, pgConnectOptions } from "./supabase-ca.js";
 export { runDrill, drillDump } from "./drill.js";
 export { runRestore } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";

package/dist/lib.js

@@ -1,6 +1,9 @@
 // 库入口:把引擎函数暴露给下游复用(产品 worker 直接 import 这些,而不是重写)。
 // CLI(bin)是这套引擎的薄封装;worker 在其外加调度、凭据托管、告警、报告。
 export { runBackup } from "./backup.js";
+// verify-full:只导出**原子** API。刻意不导出裸 SUPABASE_SSL —— 它一旦和 connectionString
+// 搭配使用,URL 里的 sslmode=disable 又会把它覆盖掉,等于把这次修掉的绕过再放回去。
+export { SUPABASE_ROOT_CA, pgConnectOptions } from "./supabase-ca.js";
 export { runDrill, drillDump } from "./drill.js";
 export { runRestore } from "./restore.js";
 export { runEstimate, project } from "./estimate.js";

package/dist/manifest.d.ts

@@ -19,7 +19,18 @@ export interface ExtensionInfo {
     version: string;
     schema: string;
 }
+/**
+ * manifest.json 的格式版本。**这是留在客户桶里、可能躺很多年的持久产物**——将来改结构时,
+ * 读取端要靠它分支判断,而不是去猜 toolVersion。
+ *
+ * 约定:
+ *  - 缺失该字段的 manifest = 版本 1(1.0 之前写出的旧快照)
+ *  - 读取端遇到**更高**的版本必须明确报错,而不是按旧结构硬解析出错误结果
+ *    ——对备份工具来说,"旧程序静默误读新归档"是最不能接受的失败方式。
+ */
+export declare const MANIFEST_SCHEMA_VERSION = 1;
 export interface Manifest {
+    schemaVersion?: number;
     tool: "backupdrill-cli";
     toolVersion: string;
     createdAt: string;
@@ -51,3 +62,8 @@ export interface StorageFile {
     bytes: number;
     sha256: string;
 }
+/**
+ * 解析桶里的 manifest.json,并做**向前兼容**校验:比本程序更新的格式一律拒绝,
+ * 明确告诉用户升级,绝不按旧结构硬解析(那会静默产出错误的演练/恢复结果)。
+ */
+export declare function parseManifest(json: string): Manifest;

package/dist/manifest.js

@@ -1 +1,30 @@
-export {};
+/**
+ * manifest.json 的格式版本。**这是留在客户桶里、可能躺很多年的持久产物**——将来改结构时,
+ * 读取端要靠它分支判断,而不是去猜 toolVersion。
+ *
+ * 约定:
+ *  - 缺失该字段的 manifest = 版本 1(1.0 之前写出的旧快照)
+ *  - 读取端遇到**更高**的版本必须明确报错,而不是按旧结构硬解析出错误结果
+ *    ——对备份工具来说,"旧程序静默误读新归档"是最不能接受的失败方式。
+ */
+export const MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * 解析桶里的 manifest.json,并做**向前兼容**校验:比本程序更新的格式一律拒绝,
+ * 明确告诉用户升级,绝不按旧结构硬解析(那会静默产出错误的演练/恢复结果)。
+ */
+export function parseManifest(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(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) {
+        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.`);
+    }
+    return parsed;
+}

package/dist/restore.js

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { parseManifest } from "./manifest.js";
 import { targetClient, resolveSnapshot, getObjectText, downloadToFile, } from "./snapshots.js";
 import { resolvePgRestoreBin } from "./pgbin.js";
 import { log } from "./log.js";
@@ -28,7 +29,7 @@ export async function runRestore(config, opts) {
     const s3 = targetClient(config);
     const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
     const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
-    const manifest = JSON.parse(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
+    const manifest = parseManifest(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
     const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
     const result = {
         snapshot,

package/dist/supabase-ca.d.ts

@@ -0,0 +1,32 @@
+export declare const SUPABASE_ROOT_CA = "-----BEGIN CERTIFICATE-----\nMIIDxDCCAqygAwIBAgIUbLxMod62P2ktCiAkxnKJwtE9VPYwDQYJKoZIhvcNAQEL\nBQAwazELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5l\ndyBDYXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJh\nc2UgUm9vdCAyMDIxIENBMB4XDTIxMDQyODEwNTY1M1oXDTMxMDQyNjEwNTY1M1ow\nazELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5ldyBD\nYXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJhc2Ug\nUm9vdCAyMDIxIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQXW\nQyHOB+qR2GJobCq/CBmQ40G0oDmCC3mzVnn8sv4XNeWtE5XcEL0uVih7Jo4Dkx1Q\nDmGHBH1zDfgs2qXiLb6xpw/CKQPypZW1JssOTMIfQppNQ87K75Ya0p25Y3ePS2t2\nGtvHxNjUV6kjOZjEn2yWEcBdpOVCUYBVFBNMB4YBHkNRDa/+S4uywAoaTWnCJLUi\ncvTlHmMw6xSQQn1UfRQHk50DMCEJ7Cy1RxrZJrkXXRP3LqQL2ijJ6F4yMfh+Gyb4\nO4XajoVj/+R4GwywKYrrS8PrSNtwxr5StlQO8zIQUSMiq26wM8mgELFlS/32Uclt\nNaQ1xBRizkzpZct9DwIDAQABo2AwXjALBgNVHQ8EBAMCAQYwHQYDVR0OBBYEFKjX\nuXY32CztkhImng4yJNUtaUYsMB8GA1UdIwQYMBaAFKjXuXY32CztkhImng4yJNUt\naUYsMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAB8spzNn+4VU\ntVxbdMaX+39Z50sc7uATmus16jmmHjhIHz+l/9GlJ5KqAMOx26mPZgfzG7oneL2b\nVW+WgYUkTT3XEPFWnTp2RJwQao8/tYPXWEJDc0WVQHrpmnWOFKU/d3MqBgBm5y+6\njB81TU/RG2rVerPDWP+1MMcNNy0491CTL5XQZ7JfDJJ9CCmXSdtTl4uUQnSuv/Qx\nCea13BX2ZgJc7Au30vihLhub52De4P/4gonKsNHYdbWjg7OWKwNv/zitGDVDB9Y2\nCMTyZKG3XEu5Ghl1LEnI3QmEKsqaCLv12BnVjbkSeZsMnevJPs1Ye6TjjJwdik5P\no/bKiIz+Fq8=\n-----END CERTIFICATE-----\n";
+/** node-pg 的 ssl 配置:验签(用打包的 Supabase 根 CA)+ 验主机名(rejectUnauthorized)。 */
+export declare const SUPABASE_SSL: {
+    readonly ca: "-----BEGIN CERTIFICATE-----\nMIIDxDCCAqygAwIBAgIUbLxMod62P2ktCiAkxnKJwtE9VPYwDQYJKoZIhvcNAQEL\nBQAwazELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5l\ndyBDYXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJh\nc2UgUm9vdCAyMDIxIENBMB4XDTIxMDQyODEwNTY1M1oXDTMxMDQyNjEwNTY1M1ow\nazELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5ldyBD\nYXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJhc2Ug\nUm9vdCAyMDIxIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQXW\nQyHOB+qR2GJobCq/CBmQ40G0oDmCC3mzVnn8sv4XNeWtE5XcEL0uVih7Jo4Dkx1Q\nDmGHBH1zDfgs2qXiLb6xpw/CKQPypZW1JssOTMIfQppNQ87K75Ya0p25Y3ePS2t2\nGtvHxNjUV6kjOZjEn2yWEcBdpOVCUYBVFBNMB4YBHkNRDa/+S4uywAoaTWnCJLUi\ncvTlHmMw6xSQQn1UfRQHk50DMCEJ7Cy1RxrZJrkXXRP3LqQL2ijJ6F4yMfh+Gyb4\nO4XajoVj/+R4GwywKYrrS8PrSNtwxr5StlQO8zIQUSMiq26wM8mgELFlS/32Uclt\nNaQ1xBRizkzpZct9DwIDAQABo2AwXjALBgNVHQ8EBAMCAQYwHQYDVR0OBBYEFKjX\nuXY32CztkhImng4yJNUtaUYsMB8GA1UdIwQYMBaAFKjXuXY32CztkhImng4yJNUt\naUYsMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAB8spzNn+4VU\ntVxbdMaX+39Z50sc7uATmus16jmmHjhIHz+l/9GlJ5KqAMOx26mPZgfzG7oneL2b\nVW+WgYUkTT3XEPFWnTp2RJwQao8/tYPXWEJDc0WVQHrpmnWOFKU/d3MqBgBm5y+6\njB81TU/RG2rVerPDWP+1MMcNNy0491CTL5XQZ7JfDJJ9CCmXSdtTl4uUQnSuv/Qx\nCea13BX2ZgJc7Au30vihLhub52De4P/4gonKsNHYdbWjg7OWKwNv/zitGDVDB9Y2\nCMTyZKG3XEu5Ghl1LEnI3QmEKsqaCLv12BnVjbkSeZsMnevJPs1Ye6TjjJwdik5P\no/bKiIz+Fq8=\n-----END CERTIFICATE-----\n";
+    readonly rejectUnauthorized: true;
+};
+/**
+ * 把打包的 CA 写到临时文件并返回路径:pg_dump(libpq)的 sslrootcert 只认文件路径,不认字符串。
+ * 缓存,进程内只写一次;内容是公开 CA(非密),mode 0600 足矣。
+ */
+export declare function supabaseCaFile(): string;
+/**
+ * 把连接串强制改写成 verify-full + 我们的 CA(给 pg_dump 用)。剥掉用户自带的所有 ssl* 参数
+ * ——libpq 里 URL 参数优先级高于环境变量,残留的 sslmode=require 会盖掉我们的 verify-full。
+ */
+export declare function forceVerifyFull(databaseUrl: string, caPath: string): string;
+/** pg_dump 用:Supabase 主机才改写成 verify-full;其它原样透传。 */
+export declare function dumpUrlFor(databaseUrl: string): string;
+/**
+ * node-pg 连接选项:把"剥离连接串里的 SSL 参数"与"套上打包 CA"做成**原子**的一步。
+ *
+ * 为什么必须一起做(2026-07-22 实测,pg 8.22):连接串里的 SSL 参数**会覆盖**显式传的
+ * `ssl` 选项——`?sslmode=disable` / `?ssl=0` 会让我们的 CA 被整个丢弃、退化成不加密,
+ * `?ssl=true` 则加密但不带我们的 CA。而 sslmode 在产品的参数黑名单里是**放行**的(为兼容
+ * 存量连接串),所以不剥就等于强制 verify-full 可被用户参数静默绕过。
+ *
+ * 非 Supabase 主机(本 CLI 不限制目标)原样返回:不剥、不套,尊重用户自己的 sslmode。
+ */
+export declare function pgConnectOptions(databaseUrl: string): {
+    connectionString: string;
+    ssl?: typeof SUPABASE_SSL;
+};

package/dist/supabase-ca.js

@@ -0,0 +1,240 @@
+/**
+ * Supabase Root 2021 CA —— 打包进引擎,用于对用户 Supabase 源库连接做 verify-full。
+ *
+ * 为什么必须自带:Supabase pooler(Supavisor)的证书由 Supabase 自签 CA 签发
+ * (链:*.pooler.supabase.com ← Supabase Intermediate 2021 CA ← Supabase Root 2021 CA),
+ * **不在系统 CA 信任库里**——直接 rejectUnauthorized:true 会报 SELF_SIGNED_CERT_IN_CHAIN
+ * (2026-07-20 真机实测)。把这个自签根作为 ca 传入,node-pg / libpq(pg_dump)即可完成
+ * verify-full(验签 + 验通配主机名 *.pooler.supabase.com)。所有 Supabase 项目共用这一张根,
+ * 有效期至 2031-04(过期前需更新)。
+ *
+ * 只对**用户 Supabase 源库**连接使用(backup 探查 / pg_dump / estimate / 预检);演练用的
+ * 本地 Docker 沙箱、restore 的任意目标库不适用,勿套用。
+ */
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const SUPABASE_ROOT_CA = `-----BEGIN CERTIFICATE-----
+MIIDxDCCAqygAwIBAgIUbLxMod62P2ktCiAkxnKJwtE9VPYwDQYJKoZIhvcNAQEL
+BQAwazELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5l
+dyBDYXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJh
+c2UgUm9vdCAyMDIxIENBMB4XDTIxMDQyODEwNTY1M1oXDTMxMDQyNjEwNTY1M1ow
+azELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0RlbHdhcmUxEzARBgNVBAcMCk5ldyBD
+YXN0bGUxFTATBgNVBAoMDFN1cGFiYXNlIEluYzEeMBwGA1UEAwwVU3VwYWJhc2Ug
+Um9vdCAyMDIxIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQXW
+QyHOB+qR2GJobCq/CBmQ40G0oDmCC3mzVnn8sv4XNeWtE5XcEL0uVih7Jo4Dkx1Q
+DmGHBH1zDfgs2qXiLb6xpw/CKQPypZW1JssOTMIfQppNQ87K75Ya0p25Y3ePS2t2
+GtvHxNjUV6kjOZjEn2yWEcBdpOVCUYBVFBNMB4YBHkNRDa/+S4uywAoaTWnCJLUi
+cvTlHmMw6xSQQn1UfRQHk50DMCEJ7Cy1RxrZJrkXXRP3LqQL2ijJ6F4yMfh+Gyb4
+O4XajoVj/+R4GwywKYrrS8PrSNtwxr5StlQO8zIQUSMiq26wM8mgELFlS/32Uclt
+NaQ1xBRizkzpZct9DwIDAQABo2AwXjALBgNVHQ8EBAMCAQYwHQYDVR0OBBYEFKjX
+uXY32CztkhImng4yJNUtaUYsMB8GA1UdIwQYMBaAFKjXuXY32CztkhImng4yJNUt
+aUYsMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAB8spzNn+4VU
+tVxbdMaX+39Z50sc7uATmus16jmmHjhIHz+l/9GlJ5KqAMOx26mPZgfzG7oneL2b
+VW+WgYUkTT3XEPFWnTp2RJwQao8/tYPXWEJDc0WVQHrpmnWOFKU/d3MqBgBm5y+6
+jB81TU/RG2rVerPDWP+1MMcNNy0491CTL5XQZ7JfDJJ9CCmXSdtTl4uUQnSuv/Qx
+Cea13BX2ZgJc7Au30vihLhub52De4P/4gonKsNHYdbWjg7OWKwNv/zitGDVDB9Y2
+CMTyZKG3XEu5Ghl1LEnI3QmEKsqaCLv12BnVjbkSeZsMnevJPs1Ye6TjjJwdik5P
+o/bKiIz+Fq8=
+-----END CERTIFICATE-----
+`;
+/** node-pg 的 ssl 配置:验签(用打包的 Supabase 根 CA)+ 验主机名(rejectUnauthorized)。 */
+export const SUPABASE_SSL = { ca: SUPABASE_ROOT_CA, rejectUnauthorized: true };
+let caFilePath = null;
+/**
+ * 把打包的 CA 写到临时文件并返回路径:pg_dump(libpq)的 sslrootcert 只认文件路径,不认字符串。
+ * 缓存,进程内只写一次;内容是公开 CA(非密),mode 0600 足矣。
+ */
+export function supabaseCaFile() {
+    // 缓存的文件可能被系统 tmp 清理删掉;长驻 worker 若一直返回失效路径,之后**每次**
+    // pg_dump 都会失败直到重启。发现不存在就重建。
+    if (caFilePath && !existsSync(caFilePath))
+        caFilePath = null;
+    if (!caFilePath) {
+        // 私有随机目录(mkdtemp 建的是 0700、属主为本进程):固定的 /tmp 路径在多用户机器上
+        // 可被他人预置符号链接,或**替换成伪造 CA** —— 那我们的 pg_dump 就会去信任攻击者的
+        // 证书,等于自己开了 MITM 的门。
+        const dir = mkdtempSync(join(tmpdir(), "backupdrill-ca-"));
+        const p = join(dir, "supabase-root-ca.pem");
+        writeFileSync(p, SUPABASE_ROOT_CA, { mode: 0o600 });
+        caFilePath = p;
+        // 长驻进程(worker)整个生命周期都要用它,退出时再尽力清掉,避免反复起停堆积
+        process.once("exit", () => {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                /* 清理失败无所谓,内容是公开 CA */
+            }
+        });
+    }
+    return caFilePath;
+}
+/** 所有会影响 TLS 行为的连接串参数——必须全部剥掉,否则会盖过我们显式传的 ssl 配置。 */
+const SSL_QUERY_PARAMS = [
+    "sslmode",
+    "ssl",
+    "requiressl", // 老式开关
+    "sslrootcert",
+    "sslcert",
+    "sslkey",
+    "sslcrl",
+    "sslcrldir",
+    "sslpassword",
+    "sslcertmode",
+    "sslcompression",
+    "sslsni",
+    "sslnegotiation",
+    "ssl_min_protocol_version",
+    "ssl_max_protocol_version",
+    // PG18:把 TLS 会话密钥写到文件 —— 留着它,"强制加密"就是句空话(流量可被解密)
+    "sslkeylogfile",
+    "uselibpqcompat",
+    // GSS 会在 TLS 之前协商,带 GSS 的 libpq 构建可能先走 GSS 再谈 TLS;下面统一置 disable
+    "gssencmode",
+];
+/**
+ * 手工摘除查询参数——**不能**用 URLSearchParams:一旦碰它,URL 会按 form-urlencoded
+ * 重新序列化整个查询串,把 `%20` 写成 `+`(2026-07-22 实测)。而 libpq 把 `+` 当字面量,
+ * 于是合法的 `?options=-c%20statement_timeout%3D0` 会被改成 `-c+statement_timeout=0`
+ * 让 pg_dump 直接失败。这里逐段过滤、原样保留其余片段的编码。
+ */
+function stripSslParams(databaseUrl) {
+    const q = databaseUrl.indexOf("?");
+    if (q === -1)
+        return databaseUrl;
+    const base = databaseUrl.slice(0, q);
+    const pairs = databaseUrl
+        .slice(q + 1)
+        .split("&")
+        .filter((pair) => pair !== "");
+    const keyOf = (pair) => {
+        const raw = pair.split("=")[0] ?? "";
+        try {
+            return decodeURIComponent(raw).toLowerCase();
+        }
+        catch {
+            return raw.toLowerCase(); // 编码坏了就按原文比对
+        }
+    };
+    const valueOf = (pair) => pair.slice((pair.split("=")[0] ?? "").length + 1);
+    // 两端都是"最后一个 host 生效"。若最后一个是**空值**,实际目标回落到 authority ——
+    // 这时必须删掉**所有** host 条目:只删空的那条,会把前面的 host=other 留给 libpq,
+    // 造成探查连 authority、pg_dump 连 other 的分裂。
+    const hostValues = pairs.filter((p) => keyOf(p) === "host").map(valueOf);
+    const dropAllHosts = hostValues.length > 0 && hostValues[hostValues.length - 1] === "";
+    const kept = pairs.filter((pair) => {
+        const key = keyOf(pair);
+        if (SSL_QUERY_PARAMS.includes(key))
+            return false;
+        if (key === "host" && dropAllHosts)
+            return false;
+        return true;
+    });
+    return kept.length ? `${base}?${kept.join("&")}` : base;
+}
+/**
+ * 把连接串强制改写成 verify-full + 我们的 CA(给 pg_dump 用)。剥掉用户自带的所有 ssl* 参数
+ * ——libpq 里 URL 参数优先级高于环境变量,残留的 sslmode=require 会盖掉我们的 verify-full。
+ */
+export function forceVerifyFull(databaseUrl, caPath) {
+    const stripped = stripSslParams(databaseUrl);
+    const sep = stripped.includes("?") ? "&" : "?";
+    // gssencmode=disable:带 GSS 的 libpq 构建会在 TLS 之前尝试 GSS 协商,可能在用上我们的
+    // CA 之前就失败;我们从不用 Kerberos,显式关掉让行为跨构建确定。
+    return `${stripped}${sep}sslmode=verify-full&sslrootcert=${encodeURIComponent(caPath)}&gssencmode=disable`;
+}
+/**
+ * 按主机名决定是否启用 Supabase verify-full。
+ *
+ * 关键:本 CLI 是公开工具,**不限制**连接串必须是 Supabase(那道校验只在产品侧的
+ * shared/endpoints.ts)。若无条件套 Supabase CA,指向自建 Supabase / 其它 Postgres 的
+ * 用户会直接 TLS 失败——对开源工具是回归。因此只在目标确实是 Supabase 主机时启用;
+ * 其余情形返回 undefined,保持 pg 的默认行为(由连接串自身的 sslmode 决定)。
+ */
+const SUPABASE_HOST = /\.supabase\.(co|com|net)$/;
+/**
+ * 真正会被连接的主机。两个坑:
+ *  - libpq/pg 允许 `?host=` 覆盖 authority 里的主机 → 必须按实际目标判定,否则会出现
+ *    "给 A 套了 B 的 CA"(证书必然不匹配)或"真连 Supabase 却没套 CA"。
+ *  - DNS 末尾根点(`...supabase.com.`)是合法写法,不归一化会把合法 Supabase 主机漏判成外部库。
+ */
+const EMPTY_AUTHORITY_HOST = "backupdrill-empty-authority.invalid";
+/**
+ * 按 node-pg 的宽容度解析连接串。WHATWG URL **拒绝空 authority**
+ * (`postgresql://u:p@/db?host=…`),但 node-pg 接受并连到 host= 指定的主机
+ * ——直接 try/catch 判 null 会把这种串当成外部库放行,于是 `sslmode=disable`
+ * 原样保留、真连 Supabase 却走明文(2026-07-22 审查抓到)。
+ * 这里给空 authority 塞个占位主机让它可解析,并记住 authority 实为空。
+ */
+function parseLikePg(databaseUrl) {
+    try {
+        const url = new URL(databaseUrl);
+        return { url, authorityHost: url.hostname };
+    }
+    catch {
+        /* 可能正是 node-pg 允许、WHATWG 拒绝的空 authority */
+    }
+    const m = databaseUrl.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/?#]*)([\s\S]*)$/);
+    if (!m)
+        return null;
+    const [, scheme, authority, rest] = m;
+    // 只处理"空 authority"或"有用户名但无主机(以 @ 结尾)"这两种
+    if (authority !== "" && !authority.endsWith("@"))
+        return null;
+    try {
+        return { url: new URL(`${scheme}${authority}${EMPTY_AUTHORITY_HOST}${rest}`), authorityHost: "" };
+    }
+    catch {
+        return null;
+    }
+}
+function effectiveHost(databaseUrl) {
+    const parsed = parseLikePg(databaseUrl);
+    if (!parsed)
+        return null; // 实在解析不了就别自作主张套 CA
+    const { url, authorityHost } = parsed;
+    // 必须**与 node-pg 的解析语义逐字对齐**(2026-07-22 实测):
+    //   - 重复的 host= 取**最后一个**(URLSearchParams.get 取第一个,会判错)
+    //   - host= 为**空值**时回落到 authority 主机(当成"没写")
+    // 判错的后果不是小事:真连 Supabase 却被当成外部库 → 不剥 sslmode=disable → 明文。
+    // query 里的 host= 已被 URLSearchParams 解码;authority 主机名 WHATWG URL **不解码**,
+    // 而 node-pg 会解码(实测 `supabase%2Ecom` → `supabase.com` 并真的连上去)。不解码就会
+    // 把合法 Supabase 主机判成外部库 → 保留 sslmode=disable → 明文。坏转义按原文处理。
+    let decodedAuthority = authorityHost;
+    try {
+        decodedAuthority = decodeURIComponent(authorityHost);
+    }
+    catch {
+        /* 转义损坏:按原文比对,宁可判成外部库也不误套 CA */
+    }
+    const all = url.searchParams.getAll("host");
+    const last = all.length ? all[all.length - 1] : "";
+    const host = (last !== "" ? last : decodedAuthority).toLowerCase().replace(/\.$/, "");
+    return host || null;
+}
+function isSupabaseHost(databaseUrl) {
+    const host = effectiveHost(databaseUrl);
+    return host !== null && SUPABASE_HOST.test(host);
+}
+/** pg_dump 用:Supabase 主机才改写成 verify-full;其它原样透传。 */
+export function dumpUrlFor(databaseUrl) {
+    return isSupabaseHost(databaseUrl)
+        ? forceVerifyFull(databaseUrl, supabaseCaFile())
+        : databaseUrl;
+}
+/**
+ * node-pg 连接选项:把"剥离连接串里的 SSL 参数"与"套上打包 CA"做成**原子**的一步。
+ *
+ * 为什么必须一起做(2026-07-22 实测,pg 8.22):连接串里的 SSL 参数**会覆盖**显式传的
+ * `ssl` 选项——`?sslmode=disable` / `?ssl=0` 会让我们的 CA 被整个丢弃、退化成不加密,
+ * `?ssl=true` 则加密但不带我们的 CA。而 sslmode 在产品的参数黑名单里是**放行**的(为兼容
+ * 存量连接串),所以不剥就等于强制 verify-full 可被用户参数静默绕过。
+ *
+ * 非 Supabase 主机(本 CLI 不限制目标)原样返回:不剥、不套,尊重用户自己的 sslmode。
+ */
+export function pgConnectOptions(databaseUrl) {
+    if (!isSupabaseHost(databaseUrl))
+        return { connectionString: databaseUrl };
+    return { connectionString: stripSslParams(databaseUrl), ssl: SUPABASE_SSL };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "0.2.0",
+  "version": "1.0.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": {