@pixpilot/supabase-backup 0.0.0 → 1.6.0

package/README.md

@@ -1,3 +1,78 @@
-# supabase-backup
+# @pixpilot/supabase-backup
 
-## Add usage instructions here.
+Encrypted backups of application schemas plus `auth.users` and `auth.identities`.
+It is deliberately not full Supabase-project disaster recovery. Requires Node
+22+, `pg_dump`, `pg_restore`, and `age`; direct PostgreSQL or the Supabase
+Session Pooler on port 5432 is supported, while Transaction Pooler port 6543 is rejected.
+
+## Backup
+
+```bash
+SOURCE_DATABASE_URL='postgresql://…' BACKUP_AGE_RECIPIENT='age1…' \
+R2_ACCESS_KEY_ID=… R2_SECRET_ACCESS_KEY=… R2_ENDPOINT='https://<account>.r2.cloudflarestorage.com' \
+R2_BUCKET='myapp-production-backups' BACKUP_PREFIX='production/database' \
+npx @pixpilot/supabase-backup@1 backup
+```
+
+`APP_SCHEMAS` is comma-separated and defaults to `public`; `auth` is never an
+application schema. Backups fail if non-empty `auth.mfa_factors`,
+`auth.sso_providers`, or `auth.saml_providers` would be omitted. R2 must be a
+private bucket with bucket-scoped credentials; configure retention/bucket lock
+in R2, not the CLI.
+
+```bash
+npx @pixpilot/supabase-backup@1 status --max-age-hours 36
+```
+
+## Restore drill
+
+Keep `AGE_IDENTITY` outside GitHub Actions and R2 credentials. Restore verifies
+hashes, decrypts in a private temporary directory, inspects both archives, and
+does nothing unless `--apply` is present. Apply only to a fresh recovery project.
+
+```bash
+AGE_IDENTITY='AGE-SECRET-KEY-…' R2_ACCESS_KEY_ID=… R2_SECRET_ACCESS_KEY=… \
+R2_ENDPOINT=… R2_BUCKET=… TARGET_DATABASE_URL='postgresql://…' \
+npx @pixpilot/supabase-backup@1 restore --key <manifest-key> --apply \
+  --confirm-target '<host>:5432/<database>'
+```
+
+Apply restores Auth data before application data, never cleans `auth`, requires
+empty target Auth tables, and rejects a target matching `SOURCE_DATABASE_URL`.
+Verify user login and a representative application workflow manually afterward.
+
+## Reusable workflow
+
+`.github/workflows/backup.yml` is `workflow_call`, has no schedule, and never
+receives `AGE_IDENTITY`. Consumers own schedule, concurrency, configuration,
+and notifications:
+
+```yaml
+name: Database Backup
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 3 * * *'
+permissions:
+  contents: read
+concurrency:
+  group: production-database-backup
+  cancel-in-progress: false
+jobs:
+  backup:
+    uses: pixpilot/supabase-toolkit/.github/workflows/backup.yml@main
+    with:
+      backup-prefix: production/database
+      age-recipient: ${{ vars.BACKUP_AGE_RECIPIENT }}
+      r2-endpoint: ${{ vars.R2_ENDPOINT }}
+      r2-bucket: ${{ vars.R2_BUCKET }}
+      max-age-hours: 36
+      package-version: '1'
+    secrets:
+      database-url: ${{ secrets.SOURCE_DATABASE_URL }}
+      r2-access-key-id: ${{ secrets.R2_ACCESS_KEY_ID }}
+      r2-secret-access-key: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+```
+
+Do not use `secrets: inherit`. Publish matching npm and `v1` workflow releases;
+run a recovery drill immediately, quarterly, and after material Auth changes.

package/dist/cli.cjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+const require_status = require('./status-DgmkvmrB.cjs');
+
+//#region src/cli.ts
+function valueAfter(args, flag) {
+	const index = args.indexOf(flag);
+	return index === -1 ? void 0 : args[index + 1];
+}
+/** Executes the package CLI commands. */
+async function runCli(args = process.argv.slice(2)) {
+	const [command] = args;
+	if (command === "backup") {
+		await require_status.backup();
+		return;
+	}
+	if (command === "status") {
+		const raw = valueAfter(args, "--max-age-hours");
+		await require_status.status(raw === void 0 ? void 0 : Number(raw));
+		return;
+	}
+	if (command === "restore") {
+		const key = valueAfter(args, "--key");
+		if (!key) throw new require_status.BackupError("restore requires --key <manifest-key>.");
+		const confirmTarget = valueAfter(args, "--confirm-target");
+		await require_status.restore({
+			key,
+			apply: args.includes("--apply"),
+			...confirmTarget ? { confirmTarget } : {}
+		});
+		return;
+	}
+	throw new require_status.BackupError("Usage: supabase-backup <backup|status|restore> [options]");
+}
+runCli().catch((error) => {
+	process.stderr.write(`${require_status.redact(error instanceof Error ? error.message : "Unexpected backup failure.")}\n`);
+	process.exitCode = 1;
+});
+
+//#endregion
+exports.runCli = runCli;

package/dist/cli.d.cts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+//#region src/cli.d.ts
+/** Executes the package CLI commands. */
+declare function runCli(args?: string[]): Promise<void>;
+//#endregion
+export { runCli };

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+//#region src/cli.d.ts
+/** Executes the package CLI commands. */
+declare function runCli(args?: string[]): Promise<void>;
+//#endregion
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { a as backup, g as BackupError, i as redact, n as status, r as restore } from "./status-Ba7xyZV8.js";
+
+//#region src/cli.ts
+function valueAfter(args, flag) {
+	const index = args.indexOf(flag);
+	return index === -1 ? void 0 : args[index + 1];
+}
+/** Executes the package CLI commands. */
+async function runCli(args = process.argv.slice(2)) {
+	const [command] = args;
+	if (command === "backup") {
+		await backup();
+		return;
+	}
+	if (command === "status") {
+		const raw = valueAfter(args, "--max-age-hours");
+		await status(raw === void 0 ? void 0 : Number(raw));
+		return;
+	}
+	if (command === "restore") {
+		const key = valueAfter(args, "--key");
+		if (!key) throw new BackupError("restore requires --key <manifest-key>.");
+		const confirmTarget = valueAfter(args, "--confirm-target");
+		await restore({
+			key,
+			apply: args.includes("--apply"),
+			...confirmTarget ? { confirmTarget } : {}
+		});
+		return;
+	}
+	throw new BackupError("Usage: supabase-backup <backup|status|restore> [options]");
+}
+runCli().catch((error) => {
+	process.stderr.write(`${redact(error instanceof Error ? error.message : "Unexpected backup failure.")}\n`);
+	process.exitCode = 1;
+});
+
+//#endregion
+export { runCli };

package/dist/index.cjs

@@ -1,6 +1,18 @@
+const require_status = require('./status-DgmkvmrB.cjs');
 
-//#region src/index.ts
-const name = "supabase-backup";
-
-//#endregion
-exports.name = name;
+exports.BackupError = require_status.BackupError;
+exports.backup = require_status.backup;
+exports.backupObjectKeys = require_status.backupObjectKeys;
+exports.backupWithConfig = require_status.backupWithConfig;
+exports.databaseLabel = require_status.databaseLabel;
+exports.ensureDifferentDatabases = require_status.ensureDifferentDatabases;
+exports.getBackupStatus = require_status.getBackupStatus;
+exports.loadBackupConfig = require_status.loadBackupConfig;
+exports.loadRestoreConfig = require_status.loadRestoreConfig;
+exports.loadStatusConfig = require_status.loadStatusConfig;
+exports.parseDatabaseUrl = require_status.parseDatabaseUrl;
+exports.parseManifest = require_status.parseManifest;
+exports.redact = require_status.redact;
+exports.restore = require_status.restore;
+exports.status = require_status.status;
+exports.toLibpqEnvironment = require_status.toLibpqEnvironment;

package/dist/index.d.cts

@@ -1,4 +1,145 @@
-//#region src/index.d.ts
-declare const name = "supabase-backup";
+//#region src/config.d.ts
+interface R2Config {
+  accessKeyId: string;
+  bucket: string;
+  endpoint: string;
+  secretAccessKey: string;
+}
+interface BackupConfig extends R2Config {
+  ageRecipient: string;
+  appSchemas: string[];
+  prefix: string;
+  sourceDatabaseUrl: string;
+}
+interface RestoreConfig extends R2Config {
+  ageIdentity: string;
+  sourceDatabaseUrl?: string;
+  targetDatabaseUrl?: string;
+}
+interface StatusConfig extends R2Config {
+  prefix: string;
+}
+/** Loads and validates backup-only environment configuration. */
+declare function loadBackupConfig(env?: NodeJS.ProcessEnv): BackupConfig;
+/** Loads restore credentials while allowing dry-run archive checks without a target. */
+declare function loadRestoreConfig(env?: NodeJS.ProcessEnv, requireTarget?: boolean): RestoreConfig;
+/** Loads the R2 prefix and credentials required by the read-only health check. */
+declare function loadStatusConfig(env?: NodeJS.ProcessEnv): StatusConfig;
 //#endregion
-export { name };
+//#region src/manifest.d.ts
+declare const authTables: readonly ["auth.users", "auth.identities"];
+type AuthTable = (typeof authTables)[number];
+interface Column {
+  dataType: string;
+  name: string;
+}
+interface TableCount {
+  table: string;
+  count: number;
+}
+interface BackupManifest {
+  appChecksumObjectKey: string;
+  appEncryptedBytes: number;
+  appObjectKey: string;
+  appSchemas: string[];
+  appSha256: string;
+  appTableCounts: TableCount[];
+  authColumns: Record<AuthTable, Column[]>;
+  authChecksumObjectKey: string;
+  authEncryptedBytes: number;
+  authObjectKey: string;
+  authRowCounts: TableCount[];
+  authSha256: string;
+  authTables: AuthTable[];
+  cliVersion: string;
+  createdAt: string;
+  environment: string;
+  pgDumpVersion: string;
+  postgresServerVersion: string;
+}
+/** Generates immutable object names for one UTC backup timestamp. */
+declare function backupObjectKeys(prefix: string, createdAt: Date): Record<'app' | 'auth' | 'appChecksum' | 'authChecksum' | 'manifest', string>;
+/** Rejects malformed manifests before they can guide a restore. */
+declare function parseManifest(value: string): BackupManifest;
+//#endregion
+//#region src/process.d.ts
+interface ProgramRunner {
+  run: (command: string, args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+  }) => Promise<string>;
+}
+//#endregion
+//#region src/r2.d.ts
+interface ObjectStore {
+  get: (key: string) => Promise<Uint8Array>;
+  has: (key: string) => Promise<boolean>;
+  list: (prefix: string) => Promise<string[]>;
+  putImmutable: (key: string, body: Uint8Array) => Promise<void>;
+}
+//#endregion
+//#region src/backup.d.ts
+/** Creates encrypted, immutable app/Auth archives and publishes their manifest last. */
+declare function backup(env?: NodeJS.ProcessEnv, dependencies?: {
+  now?: Date;
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+/** Implements backup with injected dependencies for deterministic tests. */
+declare function backupWithConfig(config: BackupConfig, dependencies?: {
+  now?: Date;
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+//#endregion
+//#region src/database-url.d.ts
+interface DatabaseConnection {
+  database: string;
+  host: string;
+  password: string;
+  port: string;
+  sslmode: string;
+  user: string;
+}
+/** Parses a PostgreSQL URL without retaining it in process arguments. */
+declare function parseDatabaseUrl(value: string): DatabaseConnection;
+/** Converts a parsed URL to the libpq environment passed to PostgreSQL tools. */
+declare function toLibpqEnvironment(connection: DatabaseConnection): NodeJS.ProcessEnv;
+/** Produces a non-secret target label used for typed restore confirmation. */
+declare function databaseLabel(connection: DatabaseConnection): string;
+/** Prevents a configured source database from also being used as a restore target. */
+declare function ensureDifferentDatabases(source: DatabaseConnection | undefined, target: DatabaseConnection): void;
+//#endregion
+//#region src/errors.d.ts
+/** Error whose message is safe to display from the CLI. */
+declare class BackupError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/redact.d.ts
+/** Removes connection strings, age identities, and common credential values from text. */
+declare function redact(value: string): string;
+//#endregion
+//#region src/restore.d.ts
+interface RestoreOptions {
+  apply: boolean;
+  confirmTarget?: string;
+  key: string;
+}
+/** Downloads, verifies, decrypts, and optionally restores a single manifest. */
+declare function restore(options: RestoreOptions, env?: NodeJS.ProcessEnv, dependencies?: {
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+//#endregion
+//#region src/status.d.ts
+interface BackupStatus {
+  ageHours: number;
+  manifest: BackupManifest;
+  manifestKey: string;
+}
+/** Finds the latest complete manifest and checks its referenced archives remain available. */
+declare function getBackupStatus(prefix: string, store: ObjectStore, now?: Date): Promise<BackupStatus>;
+/** Prints a machine-safe health result and fails when no recent valid backup exists. */
+declare function status(maxAgeHours: number | undefined, env?: NodeJS.ProcessEnv): Promise<BackupStatus>;
+//#endregion
+export { BackupError, type BackupManifest, backup, backupObjectKeys, backupWithConfig, databaseLabel, ensureDifferentDatabases, getBackupStatus, loadBackupConfig, loadRestoreConfig, loadStatusConfig, parseDatabaseUrl, parseManifest, redact, restore, status, toLibpqEnvironment };

package/dist/index.d.ts

@@ -1,4 +1,145 @@
-//#region src/index.d.ts
-declare const name = "supabase-backup";
+//#region src/config.d.ts
+interface R2Config {
+  accessKeyId: string;
+  bucket: string;
+  endpoint: string;
+  secretAccessKey: string;
+}
+interface BackupConfig extends R2Config {
+  ageRecipient: string;
+  appSchemas: string[];
+  prefix: string;
+  sourceDatabaseUrl: string;
+}
+interface RestoreConfig extends R2Config {
+  ageIdentity: string;
+  sourceDatabaseUrl?: string;
+  targetDatabaseUrl?: string;
+}
+interface StatusConfig extends R2Config {
+  prefix: string;
+}
+/** Loads and validates backup-only environment configuration. */
+declare function loadBackupConfig(env?: NodeJS.ProcessEnv): BackupConfig;
+/** Loads restore credentials while allowing dry-run archive checks without a target. */
+declare function loadRestoreConfig(env?: NodeJS.ProcessEnv, requireTarget?: boolean): RestoreConfig;
+/** Loads the R2 prefix and credentials required by the read-only health check. */
+declare function loadStatusConfig(env?: NodeJS.ProcessEnv): StatusConfig;
 //#endregion
-export { name };
+//#region src/manifest.d.ts
+declare const authTables: readonly ["auth.users", "auth.identities"];
+type AuthTable = (typeof authTables)[number];
+interface Column {
+  dataType: string;
+  name: string;
+}
+interface TableCount {
+  table: string;
+  count: number;
+}
+interface BackupManifest {
+  appChecksumObjectKey: string;
+  appEncryptedBytes: number;
+  appObjectKey: string;
+  appSchemas: string[];
+  appSha256: string;
+  appTableCounts: TableCount[];
+  authColumns: Record<AuthTable, Column[]>;
+  authChecksumObjectKey: string;
+  authEncryptedBytes: number;
+  authObjectKey: string;
+  authRowCounts: TableCount[];
+  authSha256: string;
+  authTables: AuthTable[];
+  cliVersion: string;
+  createdAt: string;
+  environment: string;
+  pgDumpVersion: string;
+  postgresServerVersion: string;
+}
+/** Generates immutable object names for one UTC backup timestamp. */
+declare function backupObjectKeys(prefix: string, createdAt: Date): Record<'app' | 'auth' | 'appChecksum' | 'authChecksum' | 'manifest', string>;
+/** Rejects malformed manifests before they can guide a restore. */
+declare function parseManifest(value: string): BackupManifest;
+//#endregion
+//#region src/process.d.ts
+interface ProgramRunner {
+  run: (command: string, args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+  }) => Promise<string>;
+}
+//#endregion
+//#region src/r2.d.ts
+interface ObjectStore {
+  get: (key: string) => Promise<Uint8Array>;
+  has: (key: string) => Promise<boolean>;
+  list: (prefix: string) => Promise<string[]>;
+  putImmutable: (key: string, body: Uint8Array) => Promise<void>;
+}
+//#endregion
+//#region src/backup.d.ts
+/** Creates encrypted, immutable app/Auth archives and publishes their manifest last. */
+declare function backup(env?: NodeJS.ProcessEnv, dependencies?: {
+  now?: Date;
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+/** Implements backup with injected dependencies for deterministic tests. */
+declare function backupWithConfig(config: BackupConfig, dependencies?: {
+  now?: Date;
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+//#endregion
+//#region src/database-url.d.ts
+interface DatabaseConnection {
+  database: string;
+  host: string;
+  password: string;
+  port: string;
+  sslmode: string;
+  user: string;
+}
+/** Parses a PostgreSQL URL without retaining it in process arguments. */
+declare function parseDatabaseUrl(value: string): DatabaseConnection;
+/** Converts a parsed URL to the libpq environment passed to PostgreSQL tools. */
+declare function toLibpqEnvironment(connection: DatabaseConnection): NodeJS.ProcessEnv;
+/** Produces a non-secret target label used for typed restore confirmation. */
+declare function databaseLabel(connection: DatabaseConnection): string;
+/** Prevents a configured source database from also being used as a restore target. */
+declare function ensureDifferentDatabases(source: DatabaseConnection | undefined, target: DatabaseConnection): void;
+//#endregion
+//#region src/errors.d.ts
+/** Error whose message is safe to display from the CLI. */
+declare class BackupError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/redact.d.ts
+/** Removes connection strings, age identities, and common credential values from text. */
+declare function redact(value: string): string;
+//#endregion
+//#region src/restore.d.ts
+interface RestoreOptions {
+  apply: boolean;
+  confirmTarget?: string;
+  key: string;
+}
+/** Downloads, verifies, decrypts, and optionally restores a single manifest. */
+declare function restore(options: RestoreOptions, env?: NodeJS.ProcessEnv, dependencies?: {
+  runner?: ProgramRunner;
+  store?: ObjectStore;
+}): Promise<BackupManifest>;
+//#endregion
+//#region src/status.d.ts
+interface BackupStatus {
+  ageHours: number;
+  manifest: BackupManifest;
+  manifestKey: string;
+}
+/** Finds the latest complete manifest and checks its referenced archives remain available. */
+declare function getBackupStatus(prefix: string, store: ObjectStore, now?: Date): Promise<BackupStatus>;
+/** Prints a machine-safe health result and fails when no recent valid backup exists. */
+declare function status(maxAgeHours: number | undefined, env?: NodeJS.ProcessEnv): Promise<BackupStatus>;
+//#endregion
+export { BackupError, type BackupManifest, backup, backupObjectKeys, backupWithConfig, databaseLabel, ensureDifferentDatabases, getBackupStatus, loadBackupConfig, loadRestoreConfig, loadStatusConfig, parseDatabaseUrl, parseManifest, redact, restore, status, toLibpqEnvironment };

package/dist/index.js

@@ -1,5 +1,3 @@
-//#region src/index.ts
-const name = "supabase-backup";
+import { a as backup, c as parseManifest, d as parseDatabaseUrl, f as toLibpqEnvironment, g as BackupError, h as loadStatusConfig, i as redact, l as databaseLabel, m as loadRestoreConfig, n as status, o as backupWithConfig, p as loadBackupConfig, r as restore, s as backupObjectKeys, t as getBackupStatus, u as ensureDifferentDatabases } from "./status-Ba7xyZV8.js";
 
-//#endregion
-export { name };
+export { BackupError, backup, backupObjectKeys, backupWithConfig, databaseLabel, ensureDifferentDatabases, getBackupStatus, loadBackupConfig, loadRestoreConfig, loadStatusConfig, parseDatabaseUrl, parseManifest, redact, restore, status, toLibpqEnvironment };