@pixpilot/supabase-backup 0.0.0 → 1.6.0

package/dist/status-Ba7xyZV8.js

@@ -0,0 +1,594 @@
+import { mkdtemp, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Client } from "pg";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+
+//#region src/errors.ts
+/** Error whose message is safe to display from the CLI. */
+var BackupError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BackupError";
+	}
+};
+
+//#endregion
+//#region src/auth.ts
+const unsupportedTables = [
+	"mfa_factors",
+	"sso_providers",
+	"saml_providers"
+];
+/** Connects for read-only metadata checks; dump and restore still use libpq environment variables. */
+async function connectForPreflight(connection) {
+	const client = new Client({
+		host: connection.host,
+		port: Number(connection.port),
+		user: connection.user,
+		password: connection.password,
+		database: connection.database,
+		ssl: connection.sslmode === "disable" ? false : { rejectUnauthorized: false }
+	});
+	try {
+		await client.connect();
+		return client;
+	} catch {
+		throw new BackupError("Database preflight connection failed.");
+	}
+}
+/** Fails when non-empty durable Auth features would be omitted from the backup. */
+async function ensureSupportedAuthState(db) {
+	const result = await db.query("SELECT table_name FROM information_schema.tables WHERE table_schema = 'auth' AND table_name IN ('mfa_factors', 'sso_providers', 'saml_providers')");
+	for (const { table_name } of result.rows) {
+		const safeName = unsupportedTables.find((name) => name === table_name);
+		if (!safeName) continue;
+		if ((await db.query(`SELECT EXISTS (SELECT 1 FROM auth.${safeName} LIMIT 1) AS has_rows`)).rows[0]?.has_rows) throw new BackupError(`Unsupported durable Auth state detected in auth.${safeName}. Add explicit support before backing up this project.`);
+	}
+}
+/** Reads Auth column names/types for compatibility checks recorded in the manifest. */
+async function getAuthColumns(db) {
+	const rows = await db.query("SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = 'auth' AND table_name IN ('users', 'identities') ORDER BY table_name, ordinal_position");
+	const result = {
+		"auth.users": [],
+		"auth.identities": []
+	};
+	for (const row of rows.rows) {
+		const table = `auth.${row.table_name}`;
+		if (table in result) result[table].push({
+			name: row.column_name,
+			dataType: row.data_type
+		});
+	}
+	if (Object.values(result).some((columns) => columns.length === 0)) throw new BackupError("Required Auth tables are missing.");
+	return result;
+}
+/** Verifies target Auth columns/types can accept the backed-up data. */
+async function ensureAuthCompatible(db, expected) {
+	const actual = await getAuthColumns(db);
+	for (const table of Object.keys(expected)) for (const column of expected[table]) {
+		const target = actual[table].find((candidate) => candidate.name === column.name);
+		if (!target || target.dataType !== column.dataType) throw new BackupError(`Target ${table} is incompatible at column '${column.name}'. Use a Supabase project with matching Auth schema.`);
+	}
+}
+/** Returns row counts for tables included in backup/restore validation. */
+async function getTableCounts(db, tables) {
+	const result = [];
+	for (const table of tables) {
+		if (!/^(auth\.(users|identities)|[A-Za-z_][\w$]*\.[A-Za-z_][\w$]*)$/u.test(table)) throw new BackupError("Invalid table identifier.");
+		const [schema, name] = table.split(".");
+		if (schema === void 0 || name === void 0) throw new BackupError("Invalid table identifier.");
+		const count = await db.query(`SELECT COUNT(*)::text AS count FROM "${schema}"."${name}"`);
+		result.push({
+			table,
+			count: Number(count.rows[0]?.count || 0)
+		});
+	}
+	return result;
+}
+/** Requires empty target Auth tables before modifying them. */
+async function ensureAuthTablesEmpty(db) {
+	if ((await getTableCounts(db, ["auth.users", "auth.identities"])).some(({ count }) => count !== 0)) throw new BackupError("Target auth.users and auth.identities must be empty for recovery restore.");
+}
+/** Finds application table names for post-restore count validation. */
+async function getApplicationTables(db, schemas) {
+	const values = schemas.map((schema) => `'${schema.replace(/'/gu, "''")}'`).join(", ");
+	return (await db.query(`SELECT table_schema, table_name FROM information_schema.tables WHERE table_type = 'BASE TABLE' AND table_schema IN (${values}) ORDER BY table_schema, table_name`)).rows.map(({ table_schema, table_name }) => `${table_schema}.${table_name}`);
+}
+/** Confirms restored table counts match the source manifest. */
+async function ensureCountsMatch(db, expected) {
+	const actual = await getTableCounts(db, expected.map(({ table }) => table));
+	for (const expectedCount of expected) {
+		const current = actual.find(({ table }) => table === expectedCount.table);
+		if (!current || current.count !== expectedCount.count) throw new BackupError(`Restore validation failed for ${expectedCount.table}: row count does not match the backup manifest.`);
+	}
+}
+
+//#endregion
+//#region src/config.ts
+function required(env, name) {
+	const value = env[name]?.trim();
+	if (!value) throw new BackupError(`${name} is required.`);
+	return value;
+}
+function r2Config(env) {
+	return {
+		accessKeyId: required(env, "R2_ACCESS_KEY_ID"),
+		secretAccessKey: required(env, "R2_SECRET_ACCESS_KEY"),
+		endpoint: required(env, "R2_ENDPOINT"),
+		bucket: required(env, "R2_BUCKET")
+	};
+}
+/** Loads and validates backup-only environment configuration. */
+function loadBackupConfig(env = process.env) {
+	const appSchemas = (env["APP_SCHEMAS"] || "public").split(",").map((schema) => schema.trim()).filter(Boolean);
+	if (!appSchemas.length || appSchemas.includes("auth") || appSchemas.some((schema) => !/^[A-Za-z_][\w$]*$/u.test(schema))) throw new BackupError("APP_SCHEMAS must contain valid application schemas and must not include auth.");
+	const prefix = required(env, "BACKUP_PREFIX").replace(/^\/+|\/+$/gu, "");
+	if (!prefix || prefix.includes("..")) throw new BackupError("BACKUP_PREFIX must be a non-empty object-key prefix.");
+	return {
+		...r2Config(env),
+		ageRecipient: required(env, "BACKUP_AGE_RECIPIENT"),
+		sourceDatabaseUrl: required(env, "SOURCE_DATABASE_URL"),
+		prefix,
+		appSchemas
+	};
+}
+/** Loads restore credentials while allowing dry-run archive checks without a target. */
+function loadRestoreConfig(env = process.env, requireTarget = false) {
+	const targetDatabaseUrl = env["TARGET_DATABASE_URL"]?.trim();
+	if (requireTarget && !targetDatabaseUrl) throw new BackupError("TARGET_DATABASE_URL is required with --apply.");
+	return {
+		...r2Config(env),
+		ageIdentity: required(env, "AGE_IDENTITY"),
+		...targetDatabaseUrl ? { targetDatabaseUrl } : {},
+		...env["SOURCE_DATABASE_URL"]?.trim() ? { sourceDatabaseUrl: env["SOURCE_DATABASE_URL"].trim() } : {}
+	};
+}
+/** Loads the R2 prefix and credentials required by the read-only health check. */
+function loadStatusConfig(env = process.env) {
+	const prefix = required(env, "BACKUP_PREFIX").replace(/^\/+|\/+$/gu, "");
+	if (!prefix || prefix.includes("..")) throw new BackupError("BACKUP_PREFIX must be a non-empty object-key prefix.");
+	return {
+		...r2Config(env),
+		prefix
+	};
+}
+
+//#endregion
+//#region src/database-url.ts
+/** Parses a PostgreSQL URL without retaining it in process arguments. */
+function parseDatabaseUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new BackupError("Database URL must be a valid PostgreSQL URL.");
+	}
+	if (!["postgres:", "postgresql:"].includes(url.protocol) || !url.hostname || !url.pathname.slice(1)) throw new BackupError("Database URL must include protocol, host, and database name.");
+	const port = url.port || "5432";
+	if (port === "6543") throw new BackupError("Port 6543 is the Transaction Pooler and cannot be used for backup or restore. Use direct PostgreSQL or the Session Pooler on port 5432.");
+	return {
+		host: url.hostname,
+		port,
+		user: decodeURIComponent(url.username),
+		password: decodeURIComponent(url.password),
+		database: decodeURIComponent(url.pathname.slice(1)),
+		sslmode: url.searchParams.get("sslmode") || "require"
+	};
+}
+/** Converts a parsed URL to the libpq environment passed to PostgreSQL tools. */
+function toLibpqEnvironment(connection) {
+	return {
+		PGHOST: connection.host,
+		PGPORT: connection.port,
+		PGUSER: connection.user,
+		PGPASSWORD: connection.password,
+		PGDATABASE: connection.database,
+		PGSSLMODE: connection.sslmode
+	};
+}
+/** Produces a non-secret target label used for typed restore confirmation. */
+function databaseLabel(connection) {
+	return `${connection.host}:${connection.port}/${connection.database}`;
+}
+/** Prevents a configured source database from also being used as a restore target. */
+function ensureDifferentDatabases(source, target) {
+	if (source && databaseLabel(source) === databaseLabel(target) && source.user === target.user) throw new BackupError("TARGET_DATABASE_URL resolves to SOURCE_DATABASE_URL. Restore into a fresh recovery target instead.");
+}
+
+//#endregion
+//#region src/files.ts
+/** Creates a private temporary directory and always removes it after the callback. */
+async function withTemporaryDirectory(callback) {
+	const directory = await mkdtemp(join(tmpdir(), "supabase-backup-"));
+	try {
+		return await callback(directory);
+	} finally {
+		await rm(directory, {
+			force: true,
+			recursive: true
+		});
+	}
+}
+/** Computes the SHA-256 digest of a file. */
+async function sha256File(path) {
+	return createHash("sha256").update(await readFile(path)).digest("hex");
+}
+/** Ensures a dump exists and is not empty before inspecting it. */
+async function ensureNonEmptyFile(path) {
+	try {
+		if ((await stat(path)).size === 0) throw new Error("empty");
+	} catch {
+		throw new BackupError("Archive is missing or empty.");
+	}
+}
+/** Writes a private secret file used only as an age identity input. */
+async function writePrivateFile(path, contents) {
+	await writeFile(path, contents, { mode: 384 });
+}
+
+//#endregion
+//#region src/manifest.ts
+const authTables = ["auth.users", "auth.identities"];
+/** Generates immutable object names for one UTC backup timestamp. */
+function backupObjectKeys(prefix, createdAt) {
+	const iso = createdAt.toISOString().replace(/\.\d{3}Z$/u, "Z").replace(/:/gu, "-");
+	const base = `${prefix}/${createdAt.toISOString().slice(0, 10).replace(/-/gu, "/")}/${iso}`;
+	return {
+		app: `${base}.app.dump.age`,
+		auth: `${base}.auth.dump.age`,
+		appChecksum: `${base}.app.sha256`,
+		authChecksum: `${base}.auth.sha256`,
+		manifest: `${base}.json`
+	};
+}
+/** Rejects malformed manifests before they can guide a restore. */
+function parseManifest(value) {
+	let manifest;
+	try {
+		manifest = JSON.parse(value);
+	} catch {
+		throw new BackupError("Backup manifest is not valid JSON.");
+	}
+	const item = manifest;
+	if (!item.createdAt || !item.appObjectKey || !item.appChecksumObjectKey || !item.authObjectKey || !item.authChecksumObjectKey || !/^[a-f0-9]{64}$/u.test(item.appSha256 || "") || !/^[a-f0-9]{64}$/u.test(item.authSha256 || "") || !Array.isArray(item.authTables) || !item.authColumns || !item.appTableCounts || !item.authRowCounts) throw new BackupError("Backup manifest is incomplete or invalid.");
+	return item;
+}
+
+//#endregion
+//#region src/process.ts
+/** Runs a required system program without printing its potentially sensitive output. */
+const systemRunner = { async run(command, args, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			env: {
+				...process.env,
+				...options.env
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.once("error", () => reject(new BackupError(`Required system tool '${command}' is unavailable.`)));
+		child.once("close", (code) => code === 0 ? resolve(stdout.trim()) : reject(new BackupError(`${command} failed; no secrets or command output were logged.`)));
+	});
+} };
+
+//#endregion
+//#region src/r2.ts
+/** R2 object store using S3-compatible, path-style requests. */
+var R2Store = class {
+	client;
+	constructor(config) {
+		this.config = config;
+		this.client = new S3Client({
+			credentials: {
+				accessKeyId: config.accessKeyId,
+				secretAccessKey: config.secretAccessKey
+			},
+			endpoint: config.endpoint,
+			forcePathStyle: true,
+			region: "auto"
+		});
+	}
+	async has(key) {
+		try {
+			await this.client.send(new HeadObjectCommand({
+				Bucket: this.config.bucket,
+				Key: key
+			}));
+			return true;
+		} catch (error) {
+			if (error.$metadata?.httpStatusCode === 404) return false;
+			throw new BackupError("R2 object lookup failed.");
+		}
+	}
+	async putImmutable(key, body) {
+		if (await this.has(key)) throw new BackupError(`Refusing to overwrite existing R2 object '${key}'.`);
+		try {
+			await this.client.send(new PutObjectCommand({
+				Bucket: this.config.bucket,
+				Key: key,
+				Body: body,
+				IfNoneMatch: "*"
+			}));
+		} catch {
+			throw new BackupError(`R2 upload failed for '${key}'.`);
+		}
+	}
+	async get(key) {
+		try {
+			return await (await this.client.send(new GetObjectCommand({
+				Bucket: this.config.bucket,
+				Key: key
+			}))).Body.transformToByteArray();
+		} catch {
+			throw new BackupError(`R2 download failed for '${key}'.`);
+		}
+	}
+	async list(prefix) {
+		try {
+			const keys = [];
+			let token;
+			do {
+				const page = await this.client.send(new ListObjectsV2Command({
+					Bucket: this.config.bucket,
+					Prefix: prefix,
+					ContinuationToken: token
+				}));
+				keys.push(...(page.Contents || []).flatMap((entry) => entry.Key ? [entry.Key] : []));
+				token = page.NextContinuationToken;
+			} while (token);
+			return keys;
+		} catch {
+			throw new BackupError("R2 object listing failed.");
+		}
+	}
+};
+
+//#endregion
+//#region src/backup.ts
+const packageVersion = "1.0.0";
+/** Creates encrypted, immutable app/Auth archives and publishes their manifest last. */
+async function backup(env = process.env, dependencies = {}) {
+	return backupWithConfig(loadBackupConfig(env), dependencies);
+}
+/** Implements backup with injected dependencies for deterministic tests. */
+async function backupWithConfig(config, dependencies = {}) {
+	const runner = dependencies.runner || systemRunner;
+	const store = dependencies.store || new R2Store(config);
+	const connection = parseDatabaseUrl(config.sourceDatabaseUrl);
+	const preflight = await connectForPreflight(connection);
+	let serverVersion;
+	let authColumns;
+	let appTableCounts;
+	let authRowCounts;
+	try {
+		await ensureSupportedAuthState(preflight);
+		serverVersion = (await preflight.query("SHOW server_version")).rows[0]?.version || "unknown";
+		authColumns = await getAuthColumns(preflight);
+		appTableCounts = await getTableCounts(preflight, await getApplicationTables(preflight, config.appSchemas));
+		authRowCounts = await getTableCounts(preflight, [...authTables]);
+	} finally {
+		await preflight.end();
+	}
+	const createdAt = dependencies.now || /* @__PURE__ */ new Date();
+	const keys = backupObjectKeys(config.prefix, createdAt);
+	for (const key of Object.values(keys)) if (await store.has(key)) throw new BackupError(`Refusing to overwrite existing R2 object '${key}'.`);
+	return withTemporaryDirectory(async (directory) => {
+		const appDump = join(directory, "app.dump");
+		const authDump = join(directory, "auth.dump");
+		const appEncrypted = `${appDump}.age`;
+		const authEncrypted = `${authDump}.age`;
+		const pgEnv = toLibpqEnvironment(connection);
+		await runner.run("pg_dump", [
+			"--format=custom",
+			...config.appSchemas.map((schema) => `--schema=${schema}`),
+			"--no-owner",
+			"--no-privileges",
+			`--file=${appDump}`
+		], { env: pgEnv });
+		await runner.run("pg_dump", [
+			"--format=custom",
+			"--data-only",
+			...authTables.map((table) => `--table=${table}`),
+			"--no-owner",
+			"--no-privileges",
+			`--file=${authDump}`
+		], { env: pgEnv });
+		for (const archive of [appDump, authDump]) {
+			await ensureNonEmptyFile(archive);
+			await runner.run("pg_restore", ["--list", archive]);
+		}
+		await runner.run("age", [
+			"--recipient",
+			config.ageRecipient,
+			"--output",
+			appEncrypted,
+			appDump
+		]);
+		await unlink(appDump);
+		await runner.run("age", [
+			"--recipient",
+			config.ageRecipient,
+			"--output",
+			authEncrypted,
+			authDump
+		]);
+		await unlink(authDump);
+		const [appSha256, authSha256, appBytes, authBytes, pgDumpVersion] = await Promise.all([
+			sha256File(appEncrypted),
+			sha256File(authEncrypted),
+			stat(appEncrypted).then((file) => file.size),
+			stat(authEncrypted).then((file) => file.size),
+			runner.run("pg_dump", ["--version"])
+		]);
+		const manifest = {
+			createdAt: createdAt.toISOString(),
+			environment: config.prefix.split("/")[0] || "default",
+			appObjectKey: keys.app,
+			appChecksumObjectKey: keys.appChecksum,
+			authObjectKey: keys.auth,
+			authChecksumObjectKey: keys.authChecksum,
+			appSha256,
+			authSha256,
+			appEncryptedBytes: appBytes,
+			authEncryptedBytes: authBytes,
+			appSchemas: config.appSchemas,
+			authTables: [...authTables],
+			pgDumpVersion,
+			postgresServerVersion: serverVersion,
+			cliVersion: packageVersion,
+			authColumns,
+			appTableCounts,
+			authRowCounts
+		};
+		await store.putImmutable(keys.app, await readFile(appEncrypted));
+		await store.putImmutable(keys.auth, await readFile(authEncrypted));
+		await store.putImmutable(keys.appChecksum, Buffer.from(`${appSha256}  ${keys.app.split("/").at(-1)}\n`));
+		await store.putImmutable(keys.authChecksum, Buffer.from(`${authSha256}  ${keys.auth.split("/").at(-1)}\n`));
+		await store.putImmutable(keys.manifest, Buffer.from(`${JSON.stringify(manifest)}\n`));
+		for (const key of Object.values(keys)) if (!await store.has(key)) throw new BackupError("R2 verification failed after upload; manifest cannot be trusted.");
+		return manifest;
+	});
+}
+
+//#endregion
+//#region src/redact.ts
+/** Removes connection strings, age identities, and common credential values from text. */
+function redact(value) {
+	return value.replace(/postgres(?:ql)?:\/\/[^\s'"`]+/giu, "[redacted database URL]").replace(/AGE-SECRET-KEY-[\w-]+/giu, "[redacted age identity]").replace(/(?:password|secret|token|access_key)\s*[=:]\s*[^\s,]+/giu, "$1=[redacted]");
+}
+
+//#endregion
+//#region src/restore.ts
+/** Downloads, verifies, decrypts, and optionally restores a single manifest. */
+async function restore(options, env = process.env, dependencies = {}) {
+	if (!options.key.endsWith(".json") || options.key.includes("..")) throw new BackupError("--key must be an immutable backup manifest key ending in .json.");
+	const config = loadRestoreConfig(env, options.apply);
+	const store = dependencies.store || new R2Store(config);
+	const runner = dependencies.runner || systemRunner;
+	const manifest = parseManifest(Buffer.from(await store.get(options.key)).toString("utf8"));
+	const target = config.targetDatabaseUrl ? parseDatabaseUrl(config.targetDatabaseUrl) : void 0;
+	if (target) ensureDifferentDatabases(config.sourceDatabaseUrl ? parseDatabaseUrl(config.sourceDatabaseUrl) : void 0, target);
+	if (options.apply) {
+		if (!target) throw new BackupError("TARGET_DATABASE_URL is required with --apply.");
+		if (options.confirmTarget !== databaseLabel(target)) throw new BackupError(`Restore confirmation must exactly equal '${databaseLabel(target)}'.`);
+	}
+	return withTemporaryDirectory(async (directory) => {
+		const appEncrypted = join(directory, "app.dump.age");
+		const authEncrypted = join(directory, "auth.dump.age");
+		const appDump = join(directory, "app.dump");
+		const authDump = join(directory, "auth.dump");
+		const identity = join(directory, "identity.txt");
+		const [appChecksum, authChecksum] = await Promise.all([
+			store.get(manifest.appChecksumObjectKey),
+			store.get(manifest.authChecksumObjectKey),
+			writePrivateFile(appEncrypted, await store.get(manifest.appObjectKey)),
+			writePrivateFile(authEncrypted, await store.get(manifest.authObjectKey)),
+			writePrivateFile(identity, config.ageIdentity)
+		]);
+		const [actualAppSha, actualAuthSha] = await Promise.all([sha256File(appEncrypted), sha256File(authEncrypted)]);
+		if (actualAppSha !== manifest.appSha256 || actualAuthSha !== manifest.authSha256 || !Buffer.from(appChecksum).toString("utf8").startsWith(manifest.appSha256) || !Buffer.from(authChecksum).toString("utf8").startsWith(manifest.authSha256)) throw new BackupError("Encrypted archive checksum verification failed.");
+		await runner.run("age", [
+			"--decrypt",
+			"--identity",
+			identity,
+			"--output",
+			appDump,
+			appEncrypted
+		]);
+		await runner.run("age", [
+			"--decrypt",
+			"--identity",
+			identity,
+			"--output",
+			authDump,
+			authEncrypted
+		]);
+		for (const archive of [appDump, authDump]) {
+			await ensureNonEmptyFile(archive);
+			await runner.run("pg_restore", ["--list", archive]);
+		}
+		if (!target) {
+			process.stdout.write(`Restore plan (no changes): manifest ${options.key}; app schemas ${manifest.appSchemas.join(", ")}; Auth tables ${manifest.authTables.join(", ")}. Supply TARGET_DATABASE_URL to run compatibility preflight.\n`);
+			return manifest;
+		}
+		const targetDb = await connectForPreflight(target);
+		try {
+			await ensureAuthCompatible(targetDb, manifest.authColumns);
+			if (!options.apply) {
+				process.stdout.write(`Restore plan (no changes): target ${databaseLabel(target)}; Auth tables ${manifest.authTables.join(", ")} then application schemas ${manifest.appSchemas.join(", ")}.\n`);
+				return manifest;
+			}
+			await ensureAuthTablesEmpty(targetDb);
+			const pgEnv = toLibpqEnvironment(target);
+			for (const table of manifest.authTables) await runner.run("pg_restore", [
+				"--data-only",
+				"--no-owner",
+				"--no-privileges",
+				"--exit-on-error",
+				`--table=${table}`,
+				authDump
+			], { env: pgEnv });
+			await runner.run("pg_restore", [
+				"--no-owner",
+				"--no-privileges",
+				"--clean",
+				"--if-exists",
+				"--exit-on-error",
+				appDump
+			], { env: pgEnv });
+			await ensureCountsMatch(targetDb, manifest.authRowCounts);
+			await ensureCountsMatch(targetDb, manifest.appTableCounts);
+		} finally {
+			await targetDb.end();
+		}
+		process.stdout.write(`Restore database phase complete for ${databaseLabel(target)}. Manually verify an existing user can authenticate and run a representative application workflow before declaring recovery complete.\n`);
+		return manifest;
+	});
+}
+
+//#endregion
+//#region src/status.ts
+/** Finds the latest complete manifest and checks its referenced archives remain available. */
+async function getBackupStatus(prefix, store, now = /* @__PURE__ */ new Date()) {
+	const keys = (await store.list(`${prefix}/`)).filter((key) => key.endsWith(".json")).sort().reverse();
+	for (const manifestKey of keys) {
+		let manifest;
+		try {
+			manifest = parseManifest(Buffer.from(await store.get(manifestKey)).toString("utf8"));
+		} catch {
+			continue;
+		}
+		if (!await store.has(manifest.appObjectKey) || !await store.has(manifest.authObjectKey) || !await store.has(manifest.appChecksumObjectKey) || !await store.has(manifest.authChecksumObjectKey)) throw new BackupError(`Latest backup manifest '${manifestKey}' references missing R2 objects.`);
+		const ageHours = (now.getTime() - new Date(manifest.createdAt).getTime()) / 36e5;
+		if (!Number.isFinite(ageHours) || ageHours < 0) continue;
+		return {
+			manifest,
+			manifestKey,
+			ageHours
+		};
+	}
+	throw new BackupError("No valid completed backup manifest exists.");
+}
+/** Prints a machine-safe health result and fails when no recent valid backup exists. */
+async function status(maxAgeHours, env = process.env) {
+	if (maxAgeHours !== void 0 && (!Number.isFinite(maxAgeHours) || maxAgeHours < 0)) throw new BackupError("--max-age-hours must be a non-negative number.");
+	const config = loadStatusConfig(env);
+	const result = await getBackupStatus(config.prefix, new R2Store(config));
+	if (maxAgeHours !== void 0 && result.ageHours > maxAgeHours) throw new BackupError(`Latest backup is ${result.ageHours.toFixed(1)} hours old, exceeding ${maxAgeHours} hours.`);
+	process.stdout.write(`Backup healthy: ${result.manifest.createdAt} (${result.ageHours.toFixed(1)} hours old)\nManifest: ${result.manifestKey}\n`);
+	return result;
+}
+
+//#endregion
+export { backup as a, parseManifest as c, parseDatabaseUrl as d, toLibpqEnvironment as f, BackupError as g, loadStatusConfig as h, redact as i, databaseLabel as l, loadRestoreConfig as m, status as n, backupWithConfig as o, loadBackupConfig as p, restore as r, backupObjectKeys as s, getBackupStatus as t, ensureDifferentDatabases as u };