import { defineCommand } from "citty"; import consola from "consola"; import { createHash } from "node:crypto"; import { createReadStream } from "node:fs"; import { spawn, type SpawnOptions } from "node:child_process"; import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, stat } from "node:fs/promises"; import { tmpdir } from "node:os"; import { isAbsolute, join, relative, resolve, sep } from "node:path"; import { extract as extractTar } from "tar"; import { S3Client } from "@aws-sdk/client-s3"; import { downloadObjectToFile } from "./s3-upload.js"; import { decryptFile } from "./encryption.js"; import { deserializeManifest, type BackupManifest, type ComponentEntry } from "./manifest.js"; import { resolveBackupConfig, type BackupEnv } from "./env.js"; export interface RunRestoreOptions { /** S3 key (e.g. `backup-2026-...tar.gz.age`) or just a backup id (the CLI prefixes/suffixes). */ snapshot: string; env?: BackupEnv; client?: S3Client; /** Override the target Postgres DSN; defaults to env.DIRECT_URL / DATABASE_URL. */ targetDatabaseUrl?: string; /** Skip restoring storage objects. */ skipStorage?: boolean; /** Override pg_restore binary (tests). */ pgRestoreBinary?: string; /** Spawn override for tests. */ spawnFn?: typeof spawn; } export interface RunRestoreResult { manifest: BackupManifest; archivePath: string; } export async function runRestoreBackup(opts: RunRestoreOptions): Promise { const env = opts.env ?? (process.env as unknown as BackupEnv); const config = resolveBackupConfig(env); const client = opts.client ?? new S3Client(config.s3); const tempRoot = await mkdtemp(join(tmpdir(), "backup-restore-")); try { const downloadPath = join(tempRoot, "download.bin"); consola.info(`Downloading s3://${config.backupBucket}/${opts.snapshot}`); await downloadObjectToFile({ client, bucket: config.backupBucket, key: opts.snapshot, destPath: downloadPath }); const decryptedPath = join(tempRoot, "archive.tar.gz"); if (config.encryption.method !== "none") { consola.info(`Decrypting via ${config.encryption.method}`); await decryptFile({ config: config.encryption, inputPath: downloadPath, outputPath: decryptedPath }); } else { await rename(downloadPath, decryptedPath); } const extractDir = join(tempRoot, "extracted"); await mkdir(extractDir, { recursive: true }); await extractTar({ file: decryptedPath, cwd: extractDir }); const entries = await readdir(extractDir); if (entries.length !== 1) { throw new Error(`Unexpected archive layout; got ${entries.length} top-level entries`); } const stageDir = await resolveExtractedStageDirectory(extractDir, entries[0]); const manifestPath = await resolveContainedRegularFile(stageDir, "manifest.json", "backup manifest"); const manifestRaw = await readFile(manifestPath, "utf8"); const manifest = deserializeManifest(manifestRaw); const dbUrl = opts.targetDatabaseUrl ?? config.databaseUrl; if (manifest.components.postgres) { const dumpPath = await verifyBackupComponent(stageDir, manifest.components.postgres, "Postgres dump"); consola.info("Restoring Postgres dump"); await pgRestore({ connectionString: dbUrl, dumpPath, binary: opts.pgRestoreBinary, spawnFn: opts.spawnFn, }); } if (manifest.components.storage && !opts.skipStorage) { const storagePath = await verifyBackupComponent(stageDir, manifest.components.storage, "storage archive", { verifySize: false }); // Storage restore is operator-driven via re-upload from the staged tar. // Implementation lives in storage.ts in a follow-up if/when staging // verifies the create flow against a real bucket. For now we surface // a clear hint so the operator can manually re-import. consola.warn( `Storage tar at ${storagePath} not auto-uploaded; re-upload via aws s3 sync or use --target-bucket in a future revision.`, ); } return { manifest, archivePath: decryptedPath }; } finally { await rm(tempRoot, { recursive: true, force: true }); } } async function resolveExtractedStageDirectory(extractDir: string, entry: string): Promise { const extractRoot = await realpath(extractDir); const candidate = resolve(extractRoot, entry); assertContainedPath(extractRoot, candidate, "backup stage directory"); const candidateStat = await lstat(candidate); if (candidateStat.isSymbolicLink() || !candidateStat.isDirectory()) { throw new Error("Backup stage entry must be a real directory"); } const resolvedCandidate = await realpath(candidate); assertContainedPath(extractRoot, resolvedCandidate, "backup stage directory"); return resolvedCandidate; } async function resolveContainedRegularFile(rootDir: string, relativePath: string, label: string): Promise { const root = await realpath(rootDir); const candidate = resolve(root, relativePath); assertContainedPath(root, candidate, label); const resolvedCandidate = await realpath(candidate); assertContainedPath(root, resolvedCandidate, label); const candidateStat = await stat(resolvedCandidate); if (!candidateStat.isFile()) { throw new Error(`${label} must be a regular file`); } return resolvedCandidate; } function assertContainedPath(root: string, candidate: string, label: string): void { const relativePath = relative(root, candidate); if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) { throw new Error(`${label} escapes the extracted backup directory`); } } export async function verifyBackupComponent( stageDir: string, component: ComponentEntry, label: string, options: { verifySize?: boolean } = {}, ): Promise { const componentPath = await resolveContainedRegularFile(stageDir, component.path, label); const componentStat = await stat(componentPath); if (options.verifySize !== false && componentStat.size !== component.sizeBytes) { throw new Error(`${label} size mismatch: expected ${component.sizeBytes} bytes, got ${componentStat.size}`); } const hash = createHash("sha256"); for await (const chunk of createReadStream(componentPath)) { hash.update(chunk as Buffer); } const actualChecksum = hash.digest("hex"); if (actualChecksum !== component.checksum.value) { throw new Error(`${label} checksum mismatch`); } return componentPath; } async function rename(from: string, to: string): Promise { const fs = await import("node:fs/promises"); await fs.rename(from, to); } interface PgRestoreArgs { connectionString: string; dumpPath: string; binary?: string; spawnFn?: typeof spawn; /** Optional `--schema` override used by `backup:verify` to isolate the restore. */ schemaOnly?: string; } export async function pgRestore(args: PgRestoreArgs): Promise { const spawner = args.spawnFn ?? spawn; const binary = args.binary ?? "pg_restore"; const cliArgs = ["--clean", "--if-exists", "--no-owner", "--no-privileges", "--dbname", args.connectionString]; if (args.schemaOnly) { cliArgs.push("--schema", args.schemaOnly); } cliArgs.push(args.dumpPath); const spawnOptions: SpawnOptions = { stdio: ["ignore", "pipe", "pipe"] }; const child = spawner(binary, cliArgs, spawnOptions); const stderrChunks: Buffer[] = []; child.stderr?.on("data", (c: Buffer) => stderrChunks.push(c)); const exitCode: number | null = await new Promise((resolve, reject) => { child.once("error", reject); child.once("close", (code: number | null) => resolve(code)); }); if (exitCode !== 0) { throw new Error(`pg_restore exited with code ${exitCode ?? ""}: ${Buffer.concat(stderrChunks).toString("utf8")}`); } } export const restoreBackupCommand = defineCommand({ meta: { name: "restore", description: "Restore Postgres + Storage from a backup archive in S3.", }, args: { snapshot: { type: "positional", required: true, description: "S3 key of the backup archive." }, yes: { type: "boolean", description: "Skip confirmation prompt.", default: false }, "skip-storage": { type: "boolean", description: "Do not restore storage objects.", default: false }, "target-db": { type: "string", description: "Override Postgres DSN for the restore." }, }, async run({ args }) { if (!args.yes) { const confirmed = await consola.prompt( `This will overwrite the target Postgres database with backup ${args.snapshot}. Continue?`, { type: "confirm" }, ); if (!confirmed) { consola.warn("Restore cancelled."); return; } } const result = await runRestoreBackup({ snapshot: String(args.snapshot), skipStorage: Boolean(args["skip-storage"]), targetDatabaseUrl: args["target-db"] ? String(args["target-db"]) : undefined, }); consola.success(`Restored ${result.manifest.backupId}.`); }, });