backupdrill 0.2.1 → 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.
@@ -198,6 +204,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,12 @@ 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 { inspectBucketAttrs } from "./storage-catalog.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 +48,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 +102,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) => {
@@ -180,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,
@@ -189,6 +209,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

@@ -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

@@ -4,8 +4,10 @@ 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 { 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);超限如实记录
@@ -91,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;
@@ -228,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(*) 是子分区行的总和,子分区又各自计一次;
@@ -488,7 +420,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

@@ -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

@@ -1,11 +1,12 @@
 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";
 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/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

@@ -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)。
@@ -19,7 +36,24 @@ export interface ExtensionInfo {
     version: string;
     schema: string;
 }
+/**
+ * manifest.json 的格式版本。**这是留在客户桶里、可能躺很多年的持久产物**——将来改结构时,
+ * 读取端要靠它分支判断,而不是去猜 toolVersion。
+ *
+ * 约定:
+ *  - 缺失该字段的 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 = 2;
 export interface Manifest {
+    schemaVersion?: number;
     tool: "backupdrill-cli";
     toolVersion: string;
     createdAt: string;
@@ -40,6 +74,7 @@ export interface Manifest {
         sha256: string;
     };
     storage: null | {
+        buckets?: BucketAttrs[];
         fileCount: number;
         totalBytes: number;
         files: StorageFile[];
@@ -50,4 +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;