@clearance/cli 0.1.4

package/dist/ops/scripts/backup-create.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# Create a real Postgres backup (pg_dump) with checksum + metadata.
+# Never prints credentials. Never overwrites without a new backup id.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+# Dumps contain production data. Make every created directory/artifact owner-only.
+umask 077
+
+usage() {
+  cat <<'EOF'
+Usage: backup-create.sh [--dir DIR]
+
+Environment:
+  DATABASE_URL   Required. Postgres connection string for the active database.
+
+Writes:
+  DIR/<id>.sql           plain-format pg_dump
+  DIR/<id>.meta.json     checksum, counts, timestamps, source db name
+  DIR/<id>.verified.json read-only evidence binding the dump and metadata
+  Prints backup id on stdout (last line: BACKUP_ID=<id>)
+EOF
+}
+
+BACKUP_DIR="${CLEARANCE_BACKUP_DIR:-$ROOT/.clearance/backups}"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) BACKUP_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+require_pg_client
+require_cmd node
+require_cmd openssl
+URL="$(resolve_database_url)"
+require_database_url "$URL"
+
+ACTIVE_DB="$(db_name_from_url "$URL")"
+assert_safe_ident "$ACTIVE_DB" "active database name"
+
+mkdir -p "$BACKUP_DIR"
+chmod 700 "$BACKUP_DIR"
+# Unique id: bak_<utc>_<random>
+ID="bak_$(date -u +%Y%m%dT%H%M%SZ)_$(openssl rand -hex 4)"
+DUMP="$BACKUP_DIR/${ID}.sql"
+META="$BACKUP_DIR/${ID}.meta.json"
+VERIFIED="$BACKUP_DIR/${ID}.verified.json"
+EVIDENCE_TMP="$(mktemp "${TMPDIR:-/tmp}/clearance-bak-evidence.XXXXXX")"
+SNAPSHOT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/clearance-bak-snapshot.XXXXXX")"
+SNAPSHOT_IN="$SNAPSHOT_DIR/in"
+SNAPSHOT_OUT="$SNAPSHOT_DIR/out"
+SNAPSHOT_OPEN=0
+SNAPSHOT_PID=""
+cleanup_tmp() {
+  local ec=$?
+  if [[ "$SNAPSHOT_OPEN" -eq 1 ]]; then
+    printf 'ROLLBACK;\n\\q\n' >&8 2>/dev/null || true
+    exec 8>&-
+    exec 9<&-
+    wait "$SNAPSHOT_PID" 2>/dev/null || true
+  fi
+  find "$SNAPSHOT_DIR" -type p -delete 2>/dev/null || true
+  rmdir "$SNAPSHOT_DIR" 2>/dev/null || true
+  find "$EVIDENCE_TMP" -type f -delete 2>/dev/null || true
+  if [[ "$ec" -ne 0 ]]; then
+    find "$DUMP" "$META" "$VERIFIED" -type f -delete 2>/dev/null || true
+  fi
+}
+trap cleanup_tmp EXIT
+
+printf 'backup-create: dumping database=%s (url redacted=%s)\n' "$ACTIVE_DB" "$(redact_url "$URL")" >&2
+
+# Hold one exported repeatable-read snapshot across both pg_dump and the
+# resource/version evidence queries. Without this, ordinary writes between the
+# dump and count collection can make a valid backup permanently unverifiable.
+mkfifo "$SNAPSHOT_IN" "$SNAPSHOT_OUT"
+psql --no-psqlrc -qAt -v ON_ERROR_STOP=1 "$URL" <"$SNAPSHOT_IN" >"$SNAPSHOT_OUT" &
+SNAPSHOT_PID=$!
+exec 8>"$SNAPSHOT_IN"
+exec 9<"$SNAPSHOT_OUT"
+SNAPSHOT_OPEN=1
+printf 'BEGIN ISOLATION LEVEL REPEATABLE READ;\nSELECT pg_export_snapshot();\n' >&8
+IFS= read -r SNAPSHOT_ID <&9 || die "could not export backup snapshot"
+[[ "$SNAPSHOT_ID" =~ ^[0-9A-Fa-f-]+$ ]] || die "postgres returned an invalid backup snapshot id"
+if [[ "${CLEARANCE_OPS_TESTING:-0}" == "1" ]]; then
+  if [[ -n "${CLEARANCE_BACKUP_TEST_SNAPSHOT_READY_FILE:-}" ]]; then
+    : >"$CLEARANCE_BACKUP_TEST_SNAPSHOT_READY_FILE"
+  fi
+  delay="${CLEARANCE_BACKUP_TEST_DELAY_AFTER_SNAPSHOT_SECONDS:-0}"
+  [[ "$delay" =~ ^[0-9]+([.][0-9]+)?$ ]] || die "invalid backup snapshot testing delay"
+  if [[ "$delay" != "0" ]]; then sleep "$delay"; fi
+fi
+
+# Real pg_dump — plain SQL for inspectability. Fail closed on any dump error.
+# Uses matching major client via Docker when local pg_dump is older/newer than server.
+pg_dump_to_file "$URL" "$DUMP" "$SNAPSHOT_ID"
+
+printf '%s\n' \
+  'CREATE TEMP TABLE clearance_backup_counts(table_name text PRIMARY KEY, row_count bigint NOT NULL);' \
+  "SELECT format('INSERT INTO clearance_backup_counts SELECT %L, count(*) FROM %I.%I;', table_name, table_schema, table_name) FROM information_schema.tables WHERE table_schema='public' AND table_type='BASE TABLE' ORDER BY table_name;" \
+  '\gexec' \
+  "SELECT json_build_object('capturedAt', to_char(CURRENT_TIMESTAMP AT TIME ZONE 'UTC','YYYY-MM-DD\"T\"HH24:MI:SS\"Z\"'), 'tables', COALESCE((SELECT json_object_agg(table_name,row_count ORDER BY table_name) FROM clearance_backup_counts),'{}'::json))::text;" \
+  "SELECT CASE WHEN to_regclass('public.clearance_management_snapshot') IS NULL THEN 'SELECT '''' || ''__CLEARANCE_APP_VERSION__'';' ELSE 'SELECT COALESCE((SELECT data->>''releaseVersion'' FROM clearance_management_snapshot WHERE id=1),'''') || ''__CLEARANCE_APP_VERSION__'';' END;" \
+  '\gexec' \
+  "SELECT '__CLEARANCE_SNAPSHOT_END__';" >&8
+
+SNAPSHOT_EVIDENCE=""
+APP_VERSION=""
+while IFS= read -r line <&9; do
+  if [[ "$line" == "__CLEARANCE_SNAPSHOT_END__" ]]; then
+    break
+  elif [[ "$line" == *"__CLEARANCE_APP_VERSION__" ]]; then
+    APP_VERSION="${line%__CLEARANCE_APP_VERSION__}"
+  elif [[ "$line" == \{* ]]; then
+    SNAPSHOT_EVIDENCE="$line"
+  fi
+done
+[[ -n "$SNAPSHOT_EVIDENCE" ]] || die "could not collect evidence from the backup snapshot"
+printf '%s\n' "$SNAPSHOT_EVIDENCE" >"$EVIDENCE_TMP"
+printf 'COMMIT;\n\\q\n' >&8
+exec 8>&-
+exec 9<&-
+wait "$SNAPSHOT_PID"
+SNAPSHOT_OPEN=0
+
+[[ -s "$DUMP" ]] || die "pg_dump produced empty file"
+if ! grep -q 'PostgreSQL database dump' "$DUMP"; then
+  die "pg_dump output missing expected PostgreSQL dump header"
+fi
+grep -q 'PostgreSQL database dump complete' "$DUMP" \
+  || die "pg_dump output missing completion marker"
+
+CHECKSUM="$(sha256_file "$DUMP")"
+BYTES="$(wc -c <"$DUMP" | tr -d ' ')"
+PG_VER="$(grep -m1 'Dumped from database version' "$DUMP" || pg_dump --version | head -n1 || true)"
+
+# Resource counts as flat map from evidence tables
+COUNTS_JSON="$(node -e '
+    const fs=require("fs");
+    const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+    if (!j.tables || typeof j.tables !== "object" || Array.isArray(j.tables)) process.exit(2);
+    process.stdout.write(JSON.stringify(j.tables));
+  ' "$EVIDENCE_TMP")" || die "failed to serialize required backup evidence"
+
+CREATED="$(iso_now)"
+cat >"$META" <<EOF
+{
+  "id": $(json_escape "$ID"),
+  "format": "pg_dump_plain",
+  "createdAt": $(json_escape "$CREATED"),
+  "dumpFile": $(json_escape "$(basename "$DUMP")"),
+  "metaFile": $(json_escape "$(basename "$META")"),
+  "checksumSha256": $(json_escape "$CHECKSUM"),
+  "bytes": $BYTES,
+  "sourceDatabase": $(json_escape "$ACTIVE_DB"),
+  "applicationVersion": $(if [[ -n "$APP_VERSION" ]]; then json_escape "$APP_VERSION"; else printf 'null'; fi),
+  "pgDumpVersion": $(json_escape "$PG_VER"),
+  "resourceCounts": $COUNTS_JSON,
+  "tool": "scripts/backup-create.sh"
+}
+EOF
+
+# Refuse writing secrets into meta
+if grep -qiE 'password|postgresql://[^"]+:[^"]+@' "$META"; then
+  find "$DUMP" "$META" -type f -delete 2>/dev/null || true
+  die "metadata unexpectedly contained credential material; aborted"
+fi
+
+# Bind both artifacts into immutable local verification evidence. The evidence
+# is owner-readable and non-writable; backup-verify checks every digest.
+META_CHECKSUM="$(sha256_file "$META")"
+RESOURCE_FINGERPRINT="$(schema_fingerprint_from_evidence "$EVIDENCE_TMP")"
+cat >"$VERIFIED" <<EOF
+{
+  "id": $(json_escape "$ID"),
+  "verifiedAt": $(json_escape "$(iso_now)"),
+  "dumpFile": $(json_escape "$(basename "$DUMP")"),
+  "metaFile": $(json_escape "$(basename "$META")"),
+  "dumpSha256": $(json_escape "$CHECKSUM"),
+  "metaSha256": $(json_escape "$META_CHECKSUM"),
+  "resourceEvidenceSha256": $(json_escape "$RESOURCE_FINGERPRINT"),
+  "checks": ["nonempty", "pg_dump_complete", "metadata_bound", "resource_counts_captured"]
+}
+EOF
+chmod 600 "$DUMP" "$META"
+chmod 400 "$VERIFIED"
+
+printf 'backup-create: wrote %s (%s bytes, sha256=%s)\n' "$DUMP" "$BYTES" "$CHECKSUM" >&2
+printf 'BACKUP_ID=%s\n' "$ID"
+printf 'BACKUP_DUMP=%s\n' "$DUMP"
+printf 'BACKUP_META=%s\n' "$META"
+printf 'BACKUP_EVIDENCE=%s\n' "$VERIFIED"

package/dist/ops/scripts/backup-restore-verify.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Restore a verified backup into an ISOLATED temporary database, compare evidence,
+# and clean up. Never drops or overwrites the active database.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+usage() {
+  cat <<'EOF'
+Usage: backup-restore-verify.sh --id ID [--dir DIR]
+       backup-restore-verify.sh --dump PATH --meta PATH
+
+Restores into a temporary database name (clr_rv_*), queries management/runtime
+tables when present, compares row counts to backup metadata evidence, drops the
+temp database, and exits non-zero on mismatch.
+
+Refuses to target the active database name under all circumstances.
+EOF
+}
+
+BACKUP_DIR="${CLEARANCE_BACKUP_DIR:-$ROOT/.clearance/backups}"
+ID=""
+DUMP=""
+META=""
+KEEP_TEMP=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id) ID="$2"; shift 2 ;;
+    --dir) BACKUP_DIR="$2"; shift 2 ;;
+    --dump) DUMP="$2"; shift 2 ;;
+    --meta) META="$2"; shift 2 ;;
+    --keep-temp) KEEP_TEMP=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+if [[ -n "$ID" ]]; then
+  DUMP="${DUMP:-$BACKUP_DIR/${ID}.sql}"
+  META="${META:-$BACKUP_DIR/${ID}.meta.json}"
+fi
+[[ -n "$DUMP" && -f "$DUMP" ]] || die "dump required"
+[[ -n "$META" && -f "$META" ]] || die "meta required"
+
+require_pg_client
+require_cmd node
+require_cmd openssl
+URL="$(resolve_database_url)"
+require_database_url "$URL"
+ACTIVE_DB="$(db_name_from_url "$URL")"
+ADMIN_URL="$(admin_url_from_url "$URL")"
+
+# Integrity first
+bash "$ROOT/scripts/backup-verify.sh" --dump "$DUMP" --meta "$META" >/dev/null
+
+# Isolated temp DB name
+SUFFIX="$(openssl rand -hex 4)"
+TEMP_DB="clr_rv_${SUFFIX}"
+assert_safe_ident "$TEMP_DB" "temp database"
+assert_not_active_db "$TEMP_DB"
+[[ "$TEMP_DB" != "$ACTIVE_DB" ]] || die "temp db collided with active db"
+
+TEMP_URL="$(url_with_db "$URL" "$TEMP_DB")"
+CREATED=0
+RESTORED_EV=""
+
+drop_temp_database() {
+  assert_not_active_db "$TEMP_DB"
+  psql_q "$ADMIN_URL" -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${TEMP_DB}' AND pid <> pg_backend_pid();" >/dev/null 2>&1 || true
+  psql_q "$ADMIN_URL" -c "DROP DATABASE IF EXISTS \"${TEMP_DB}\";" >/dev/null 2>&1 || return 1
+  local remains
+  remains="$(psql_q "$ADMIN_URL" -At -c "SELECT count(*) FROM pg_database WHERE datname = '${TEMP_DB}'")" || return 1
+  [[ "$remains" == "0" ]]
+}
+
+cleanup() {
+  local ec=$?
+  [[ -z "$RESTORED_EV" ]] || rm -f "$RESTORED_EV"
+  if [[ "$KEEP_TEMP" -eq 1 ]]; then
+    printf 'backup-restore-verify: keeping temp database %s (active remains %s)\n' "$TEMP_DB" "$ACTIVE_DB" >&2
+    exit "$ec"
+  fi
+  if [[ "$CREATED" -eq 1 ]]; then
+    if ! drop_temp_database; then
+      printf 'backup-restore-verify: failed to clean up isolated database %s\n' "$TEMP_DB" >&2
+      ec=1
+    fi
+  fi
+  exit "$ec"
+}
+trap cleanup EXIT INT TERM
+
+printf 'backup-restore-verify: creating isolated database %s (active=%s remains untouched)\n' \
+  "$TEMP_DB" "$ACTIVE_DB" >&2
+
+psql_q "$ADMIN_URL" -c "CREATE DATABASE \"${TEMP_DB}\";"
+CREATED=1
+
+printf 'backup-restore-verify: restoring dump into isolated database\n' >&2
+psql_restore_file "$TEMP_URL" "$DUMP"
+
+# Evidence from restored DB
+RESTORED_EV="$(mktemp "${TMPDIR:-/tmp}/clearance-restore-ev.XXXXXX")"
+collect_db_evidence "$TEMP_URL" "$RESTORED_EV"
+
+# Compare table evidence and the application release captured with the backup.
+compare_backup_evidence "$META" "$RESTORED_EV"
+EXPECTED_APP_VERSION="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.applicationVersion||"")' "$META")"
+if [[ -n "$EXPECTED_APP_VERSION" ]]; then
+  require_application_release "$TEMP_URL" "$EXPECTED_APP_VERSION"
+fi
+rm -f "$RESTORED_EV"
+RESTORED_EV=""
+
+# Confirm active DB still exists and was not the restore target
+STILL="$(psql_q "$ADMIN_URL" -At -c "SELECT 1 FROM pg_database WHERE datname = '${ACTIVE_DB}'")"
+[[ "$STILL" == "1" ]] || die "active database disappeared — aborting (investigation required)"
+assert_not_active_db "$TEMP_DB"
+
+if [[ "$KEEP_TEMP" -eq 0 ]]; then
+  drop_temp_database || die "isolated restore succeeded but temporary database cleanup failed"
+  CREATED=0
+fi
+
+printf 'backup-restore-verify: OK (isolated restore compared; active db %s untouched; cleanup verified)\n' "$ACTIVE_DB"
+printf 'RESTORE_VERIFIED=1\n'

package/dist/ops/scripts/backup-verify.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Verify a Clearance Postgres backup archive: checksum + dump structure + metadata.
+# Does not connect to the live database and never restores.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+usage() {
+  cat <<'EOF'
+Usage: backup-verify.sh --id ID [--dir DIR]
+       backup-verify.sh --dump PATH [--meta PATH] [--evidence PATH]
+
+Inspects archive integrity only (checksum, pg_dump markers, metadata consistency).
+Does not restore and does not touch the active database.
+EOF
+}
+
+BACKUP_DIR="${CLEARANCE_BACKUP_DIR:-$ROOT/.clearance/backups}"
+ID=""
+DUMP=""
+META=""
+EVIDENCE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id) ID="$2"; shift 2 ;;
+    --dir) BACKUP_DIR="$2"; shift 2 ;;
+    --dump) DUMP="$2"; shift 2 ;;
+    --meta) META="$2"; shift 2 ;;
+    --evidence) EVIDENCE="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+if [[ -n "$ID" ]]; then
+  DUMP="${DUMP:-$BACKUP_DIR/${ID}.sql}"
+  META="${META:-$BACKUP_DIR/${ID}.meta.json}"
+  EVIDENCE="${EVIDENCE:-$BACKUP_DIR/${ID}.verified.json}"
+fi
+
+[[ -n "$DUMP" ]] || die "provide --id or --dump"
+require_cmd node
+[[ -f "$DUMP" ]] || die "dump file missing: $DUMP"
+[[ -s "$DUMP" ]] || die "dump file empty: $DUMP"
+
+if [[ -z "$META" && -n "$ID" ]]; then
+  META="$BACKUP_DIR/${ID}.meta.json"
+fi
+[[ -n "$META" && -f "$META" ]] || die "metadata file missing (expected alongside dump)"
+if [[ -z "$EVIDENCE" ]]; then
+  EVIDENCE="${DUMP%.sql}.verified.json"
+fi
+[[ -f "$EVIDENCE" ]] || die "immutable verification evidence missing: $EVIDENCE"
+
+# Checksum
+ACTUAL="$(sha256_file "$DUMP")"
+EXPECTED="$(node -e '
+  const fs=require("fs");
+  const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+  if(!j.checksumSha256) process.exit(2);
+  process.stdout.write(j.checksumSha256);
+' "$META")" || die "metadata missing checksumSha256"
+
+[[ "$ACTUAL" == "$EXPECTED" ]] || die "checksum mismatch (archive may be corrupted)"
+
+# Archive structure inspection (plain pg_dump)
+grep -q 'PostgreSQL database dump' "$DUMP" || die "archive missing PostgreSQL dump header"
+grep -q 'PostgreSQL database dump complete' "$DUMP" || die "archive missing PostgreSQL dump completion marker"
+# At least one CREATE or COPY / table structure signal
+if ! grep -qE '^(CREATE TABLE|COPY |CREATE SCHEMA)' "$DUMP"; then
+  printf 'backup-verify: archive contains no table definitions (valid empty database)\n' >&2
+fi
+
+# Metadata consistency
+node -e '
+  const fs=require("fs");
+  const meta=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+  const dumpBase=require("path").basename(process.argv[2]);
+  if(!meta.id) { console.error("meta missing id"); process.exit(1); }
+  if(meta.format !== "pg_dump_plain") { console.error("unsupported format"); process.exit(1); }
+  if(meta.dumpFile && meta.dumpFile !== dumpBase) {
+    console.error("meta.dumpFile does not match dump basename");
+    process.exit(1);
+  }
+  if(typeof meta.bytes === "number") {
+    const st=fs.statSync(process.argv[2]);
+    if(st.size !== meta.bytes) {
+      console.error("meta.bytes does not match dump size");
+      process.exit(1);
+    }
+  }
+  // Fail closed: meta must not embed credentials
+  const raw=fs.readFileSync(process.argv[1],"utf8");
+  if(/password\s*[:=]/i.test(raw) || /postgres(ql)?:\/\/[^/\s"]+:[^@\s"]+@/i.test(raw)) {
+    console.error("metadata appears to contain credentials");
+    process.exit(1);
+  }
+' "$META" "$DUMP"
+
+# Verification evidence is content-addressed. This catches metadata rewriting
+# as well as dump corruption, even when only one checksum was updated.
+node -e '
+  const fs=require("fs");
+  const path=require("path");
+  const crypto=require("crypto");
+  const ev=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+  const dump=process.argv[2];
+  const meta=process.argv[3];
+  const sha=(p)=>crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+  if(!ev.id || !ev.verifiedAt || !Array.isArray(ev.checks)) process.exit(2);
+  if(ev.dumpFile!==path.basename(dump) || ev.metaFile!==path.basename(meta)) process.exit(3);
+  if(ev.dumpSha256!==sha(dump) || ev.metaSha256!==sha(meta)) process.exit(4);
+  if((fs.statSync(process.argv[1]).mode & 0o222)!==0) process.exit(5);
+' "$EVIDENCE" "$DUMP" "$META" || die "immutable backup verification evidence mismatch"
+
+printf 'backup-verify: OK id=%s sha256=%s\n' "$(basename "$DUMP" .sql)" "$ACTUAL"
+printf 'BACKUP_VERIFIED=1\n'
+printf 'BACKUP_EVIDENCE=%s\n' "$EVIDENCE"