@clearance/management 0.1.4 → 0.2.1

package/dist/ops/scripts/upgrade-apply.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Apply an upgrade plan: preflight + verified backup, then controlled apply steps.
+# Fail closed. Records rollback reference. Does not silently mutate without backup.
+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: upgrade-apply.sh --plan PLAN_ID_OR_PATH [--dir DIR] [--backup-dir DIR]
+
+Sequence (fail closed):
+  1. preflight
+  2. backup-create + backup-verify (mandatory)
+  3. required deploy/upgrades/steps/<target>/apply.sh
+  4. write version marker file + state journal
+  5. record rollbackReference = verified backup
+
+Does not drop or overwrite the active database.
+EOF
+}
+
+PLAN_DIR="${CLEARANCE_UPGRADE_DIR:-$ROOT/.clearance/upgrades}"
+BACKUP_DIR="${CLEARANCE_BACKUP_DIR:-$ROOT/.clearance/backups}"
+PLAN_REF=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --plan) PLAN_REF="$2"; shift 2 ;;
+    --dir) PLAN_DIR="$2"; shift 2 ;;
+    --backup-dir) BACKUP_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$PLAN_REF" ]] || die "--plan is required"
+
+if [[ -f "$PLAN_REF" ]]; then
+  PLAN_PATH="$PLAN_REF"
+else
+  PLAN_PATH="$PLAN_DIR/${PLAN_REF}.plan.json"
+fi
+[[ -f "$PLAN_PATH" ]] || die "plan not found"
+require_cmd node
+
+PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId)' "$PLAN_PATH")"
+[[ "$PLAN_ID" =~ ^upg_[0-9TZ]+_[a-f0-9]+$ ]] || die "plan id is unsafe"
+STATE_PATH="$PLAN_DIR/${PLAN_ID}.state.json"
+TARGET="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.targetVersion)' "$PLAN_PATH")"
+CURRENT="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.currentVersion)' "$PLAN_PATH")"
+assert_safe_version "$CURRENT" "current version"
+assert_safe_version "$TARGET" "target version"
+
+# 1. Preflight
+bash "$ROOT/scripts/upgrade-preflight.sh" --plan "$PLAN_PATH" --dir "$PLAN_DIR"
+
+# 2. Mandatory verified backup when DATABASE_URL is set (or plan has source DB)
+SOURCE_DB="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.sourceDatabase||"")' "$PLAN_PATH")"
+BACKUP_ID=""
+BACKUP_DUMP=""
+BACKUP_META=""
+BACKUP_EVIDENCE=""
+
+if [[ -n "$SOURCE_DB" || -n "${DATABASE_URL:-}" ]]; then
+  require_pg_client
+  URL="$(resolve_database_url)"
+  export DATABASE_URL="$URL"
+  CREATE_OUT="$(bash "$ROOT/scripts/backup-create.sh" --dir "$BACKUP_DIR")"
+  BACKUP_ID="$(printf '%s\n' "$CREATE_OUT" | sed -n 's/^BACKUP_ID=//p' | tail -1)"
+  BACKUP_DUMP="$(printf '%s\n' "$CREATE_OUT" | sed -n 's/^BACKUP_DUMP=//p' | tail -1)"
+  BACKUP_META="$(printf '%s\n' "$CREATE_OUT" | sed -n 's/^BACKUP_META=//p' | tail -1)"
+  BACKUP_EVIDENCE="$(printf '%s\n' "$CREATE_OUT" | sed -n 's/^BACKUP_EVIDENCE=//p' | tail -1)"
+  [[ -n "$BACKUP_ID" && -f "$BACKUP_DUMP" && -f "$BACKUP_META" && -f "$BACKUP_EVIDENCE" ]] || die "backup-create failed to produce artifacts"
+  bash "$ROOT/scripts/backup-verify.sh" --id "$BACKUP_ID" --dir "$BACKUP_DIR" >/dev/null
+  # Isolated restore verification before apply
+  bash "$ROOT/scripts/backup-restore-verify.sh" --id "$BACKUP_ID" --dir "$BACKUP_DIR" >/dev/null
+else
+  die "upgrade-apply requires DATABASE_URL / plan sourceDatabase so a verified backup can be taken"
+fi
+
+# Persist the verified rollback reference before any version-specific hook runs.
+# A missing or failing hook therefore leaves recoverable evidence in plan state.
+node -e '
+  const fs=require("fs");
+  const p=process.argv[1];
+  const backupId=process.argv[2];
+  const dump=process.argv[3];
+  const meta=process.argv[4];
+  const evidence=process.argv[5];
+  const j=JSON.parse(fs.readFileSync(p,"utf8"));
+  const at=new Date().toISOString().replace(/\.\d{3}Z$/,"Z");
+  j.status="backup_verified";
+  j.updatedAt=at;
+  j.backupId=backupId;
+  j.backupDump=dump;
+  j.backupMeta=meta;
+  j.backupEvidence=evidence;
+  j.rollbackReference={
+    type:"verified_pg_dump",
+    backupId,
+    dump,
+    meta,
+    evidence,
+    note:"Verified by checksum, archive inspection, and isolated restore before apply"
+  };
+  j.applyJournal=j.applyJournal||[];
+  j.applyJournal.push({at,event:"backup_verified",backupId});
+  fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");
+' "$STATE_PATH" "$BACKUP_ID" "$BACKUP_DUMP" "$BACKUP_META" "$BACKUP_EVIDENCE"
+
+# 3. Required version-specific apply hook (operator-supplied, fail closed if absent/non-zero)
+STEP="$ROOT/deploy/upgrades/steps/${TARGET}/apply.sh"
+if [[ -f "$STEP" ]]; then
+  printf 'upgrade-apply: running step hook %s\n' "$STEP" >&2
+  bash "$STEP" --plan "$PLAN_PATH" --from "$CURRENT" --to "$TARGET" \
+    || die "apply step hook failed (fail closed); rollbackReference=$BACKUP_ID"
+else
+  die "upgrade step hook missing: $STEP (refusing to record a no-op version transition); verified rollbackReference=$BACKUP_ID"
+fi
+
+# 4. Version marker (operational reference; not a fake health claim)
+MARKER_DIR="$PLAN_DIR/markers"
+mkdir -p "$MARKER_DIR"
+MARKER="$MARKER_DIR/${PLAN_ID}.applied"
+cat >"$MARKER" <<EOF
+{
+  "planId": $(json_escape "$PLAN_ID"),
+  "fromVersion": $(json_escape "$CURRENT"),
+  "toVersion": $(json_escape "$TARGET"),
+  "appliedAt": $(json_escape "$(iso_now)"),
+  "backupId": $(json_escape "$BACKUP_ID"),
+  "backupDump": $(json_escape "$BACKUP_DUMP"),
+  "backupMeta": $(json_escape "$BACKUP_META")
+  ,"backupEvidence": $(json_escape "$BACKUP_EVIDENCE")
+}
+EOF
+
+# 5. State update with rollback reference
+node -e '
+  const fs=require("fs");
+  const p=process.argv[1];
+  const backupId=process.argv[2];
+  const dump=process.argv[3];
+  const meta=process.argv[4];
+  const marker=process.argv[5];
+  const evidence=process.argv[6];
+  const j=JSON.parse(fs.readFileSync(p,"utf8"));
+  const at=new Date().toISOString().replace(/\.\d{3}Z$/,"Z");
+  j.status="applied";
+  j.updatedAt=at;
+  j.backupId=backupId;
+  j.backupDump=dump;
+  j.backupMeta=meta;
+  j.backupEvidence=evidence;
+  j.rollbackReference.note="Apply completed; active restore remains an explicit operator runbook action";
+  j.applyJournal=j.applyJournal||[];
+  j.applyJournal.push({at, event:"applied", marker, backupId});
+  fs.writeFileSync(p, JSON.stringify(j,null,2)+"\n");
+' "$STATE_PATH" "$BACKUP_ID" "$BACKUP_DUMP" "$BACKUP_META" "$MARKER" "$BACKUP_EVIDENCE"
+
+printf 'upgrade-apply: OK plan=%s target=%s backup=%s\n' "$PLAN_ID" "$TARGET" "$BACKUP_ID" >&2
+printf 'PLAN_ID=%s\n' "$PLAN_ID"
+printf 'BACKUP_ID=%s\n' "$BACKUP_ID"
+printf 'ROLLBACK_REF=%s\n' "$BACKUP_ID"
+printf 'APPLY_OK=1\n'

package/dist/ops/scripts/upgrade-plan.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Create an immutable upgrade plan with reference evidence and required backup slot.
+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: upgrade-plan.sh --target VERSION [--dir DIR]
+
+Writes an immutable plan JSON under DIR. Refuses to overwrite an existing plan id.
+Captures current release reference, schema evidence fingerprint, and preflight gates.
+EOF
+}
+
+PLAN_DIR="${CLEARANCE_UPGRADE_DIR:-$ROOT/.clearance/upgrades}"
+TARGET=""
+CURRENT="${CLEARANCE_RELEASE_VERSION:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --current) CURRENT="$2"; shift 2 ;;
+    --dir) PLAN_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$TARGET" ]] || die "--target VERSION is required"
+assert_safe_version "$TARGET" "target version"
+require_cmd node
+require_cmd openssl
+
+mkdir -p "$PLAN_DIR"
+PLAN_ID="upg_$(date -u +%Y%m%dT%H%M%SZ)_$(openssl rand -hex 3)"
+PLAN_PATH="$PLAN_DIR/${PLAN_ID}.plan.json"
+[[ ! -f "$PLAN_PATH" ]] || die "plan path already exists (immutable): $PLAN_PATH"
+
+URL=""
+EVIDENCE="{}"
+SOURCE_DB=""
+if [[ -n "${DATABASE_URL:-}" ]]; then
+  require_pg_client
+  URL="$(resolve_database_url)"
+  require_database_url "$URL"
+  SOURCE_DB="$(db_name_from_url "$URL")"
+  APP_RELEASE="$(application_release_version "$URL")"
+  [[ -n "$APP_RELEASE" ]] || die "database is missing the Clearance application release contract"
+  if [[ -z "$CURRENT" ]]; then
+    CURRENT="$APP_RELEASE"
+  elif [[ "$CURRENT" != "$APP_RELEASE" ]]; then
+    die "--current $CURRENT does not match application release $APP_RELEASE"
+  fi
+  EV_FILE="$(mktemp "${TMPDIR:-/tmp}/clearance-upg-ev.XXXXXX")"
+  collect_db_evidence "$URL" "$EV_FILE"
+  EVIDENCE="$(cat "$EV_FILE")"
+  FINGERPRINT="$(schema_fingerprint_from_evidence "$EV_FILE")"
+  rm -f "$EV_FILE"
+else
+  FINGERPRINT="no-database-url"
+fi
+
+if [[ -z "$CURRENT" ]]; then
+  CURRENT="$(node -e 'process.stdout.write(require(process.argv[1]).version)' "$ROOT/packages/clearance-api/package.json")"
+fi
+assert_safe_version "$CURRENT" "current version"
+
+CREATED="$(iso_now)"
+cat >"$PLAN_PATH" <<EOF
+{
+  "planId": $(json_escape "$PLAN_ID"),
+  "immutable": true,
+  "createdAt": $(json_escape "$CREATED"),
+  "currentVersion": $(json_escape "$CURRENT"),
+  "targetVersion": $(json_escape "$TARGET"),
+  "sourceDatabase": $(json_escape "${SOURCE_DB}"),
+  "schemaFingerprintSha256": $(json_escape "$FINGERPRINT"),
+  "schemaEvidence": $EVIDENCE,
+  "applicationContract": {
+    "snapshotTable": "clearance_management_snapshot",
+    "releaseVersion": $(json_escape "$CURRENT"),
+    "migrationLedger": "clearance_schema_migrations"
+  },
+  "status": "planned",
+  "requiredGates": [
+    "preflight",
+    "verified_backup",
+    "apply",
+    "post_verify"
+  ],
+  "backupId": null,
+  "backupDump": null,
+  "backupMeta": null,
+  "backupEvidence": null,
+  "rollbackReference": null,
+  "applyJournal": [],
+  "tool": "scripts/upgrade-plan.sh"
+}
+EOF
+
+# File permissions: plan is reference material
+chmod a-w "$PLAN_PATH" 2>/dev/null || true
+PLAN_SHA256="$(sha256_file "$PLAN_PATH")"
+
+# Writable side-car for status transitions (plan body stays immutable)
+STATE_PATH="$PLAN_DIR/${PLAN_ID}.state.json"
+cat >"$STATE_PATH" <<EOF
+{
+  "planId": $(json_escape "$PLAN_ID"),
+  "planPath": $(json_escape "$PLAN_PATH"),
+  "planSha256": $(json_escape "$PLAN_SHA256"),
+  "status": "planned",
+  "updatedAt": $(json_escape "$CREATED"),
+  "backupId": null,
+  "backupDump": null,
+  "backupMeta": null,
+  "backupEvidence": null,
+  "rollbackReference": null,
+  "applyJournal": []
+}
+EOF
+
+printf 'upgrade-plan: wrote immutable plan %s\n' "$PLAN_PATH" >&2
+printf 'PLAN_ID=%s\n' "$PLAN_ID"
+printf 'PLAN_PATH=%s\n' "$PLAN_PATH"
+printf 'STATE_PATH=%s\n' "$STATE_PATH"

package/dist/ops/scripts/upgrade-preflight.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Preflight checks for an upgrade plan. Fail closed.
+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: upgrade-preflight.sh --plan PLAN_ID_OR_PATH [--dir DIR]
+EOF
+}
+
+PLAN_DIR="${CLEARANCE_UPGRADE_DIR:-$ROOT/.clearance/upgrades}"
+PLAN_REF=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --plan) PLAN_REF="$2"; shift 2 ;;
+    --dir) PLAN_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$PLAN_REF" ]] || die "--plan is required"
+
+if [[ -f "$PLAN_REF" ]]; then
+  PLAN_PATH="$PLAN_REF"
+else
+  PLAN_PATH="$PLAN_DIR/${PLAN_REF}.plan.json"
+  [[ -f "$PLAN_PATH" ]] || PLAN_PATH="$PLAN_DIR/${PLAN_REF}"
+fi
+[[ -f "$PLAN_PATH" ]] || die "plan not found: $PLAN_REF"
+require_cmd node
+
+PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId)' "$PLAN_PATH")"
+[[ "$PLAN_ID" =~ ^upg_[0-9TZ]+_[a-f0-9]+$ ]] || die "plan id is unsafe"
+CURRENT="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.currentVersion)' "$PLAN_PATH")"
+TARGET="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.targetVersion)' "$PLAN_PATH")"
+assert_safe_version "$CURRENT" "current version"
+assert_safe_version "$TARGET" "target version"
+STATE_PATH="$PLAN_DIR/${PLAN_ID}.state.json"
+[[ -f "$STATE_PATH" ]] || die "state sidecar missing for plan $PLAN_ID"
+STATE_PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId||"")' "$STATE_PATH")"
+[[ "$STATE_PLAN_ID" == "$PLAN_ID" ]] || die "state sidecar plan id mismatch"
+
+EXPECTED_PLAN_SHA="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planSha256||"")' "$STATE_PATH")"
+[[ -n "$EXPECTED_PLAN_SHA" ]] || die "state sidecar missing immutable plan checksum"
+ACTUAL_PLAN_SHA="$(sha256_file "$PLAN_PATH")"
+[[ "$ACTUAL_PLAN_SHA" == "$EXPECTED_PLAN_SHA" ]] || die "immutable plan checksum mismatch (re-plan required)"
+
+errors=0
+fail() { printf 'preflight fail: %s\n' "$*" >&2; errors=$((errors + 1)); }
+ok() { printf 'preflight ok: %s\n' "$*"; }
+
+# Plan immutability: refuse if plan body changed vs fingerprint of required fields
+node -e '
+  const j=require(process.argv[1]);
+  if(!j.immutable) process.exit(2);
+  if(!j.planId || !j.currentVersion || !j.targetVersion) process.exit(3);
+  if(j.currentVersion === j.targetVersion) {
+    console.error("target equals current — nothing to upgrade (fail closed for empty apply)");
+    process.exit(4);
+  }
+' "$PLAN_PATH" || fail "plan invalid or target equals current"
+
+# Database reachable when plan recorded a source database
+SOURCE_DB="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.sourceDatabase||"")' "$PLAN_PATH")"
+if [[ -n "$SOURCE_DB" ]]; then
+  require_pg_client
+  URL="$(resolve_database_url)"
+  require_database_url "$URL"
+  ACTIVE="$(db_name_from_url "$URL")"
+  if [[ "$ACTIVE" != "$SOURCE_DB" ]]; then
+    fail "active database '$ACTIVE' does not match plan sourceDatabase '$SOURCE_DB'"
+  else
+    ok "active database matches plan ($ACTIVE)"
+  fi
+  if ! psql_q "$URL" -c 'SELECT 1' >/dev/null 2>&1; then
+    fail "cannot connect to DATABASE_URL"
+  else
+    ok "database connectivity"
+  fi
+  if require_application_release "$URL" "$CURRENT"; then
+    ok "application release contract matches plan ($CURRENT)"
+  else
+    fail "application release contract does not match plan currentVersion"
+  fi
+  if bash "$ROOT/scripts/scim-legacy-preflight.sh" >/dev/null; then
+    ok "legacy personal/global SCIM credential inventory is empty"
+  else
+    fail "legacy personal/global SCIM credentials remain; inventory and revoke before upgrade"
+  fi
+  # Schema fingerprint drift warning as hard fail for preflight
+  EV="$(mktemp "${TMPDIR:-/tmp}/clearance-pre-ev.XXXXXX")"
+  collect_db_evidence "$URL" "$EV"
+  NOW_FP="$(schema_fingerprint_from_evidence "$EV")"
+  rm -f "$EV"
+  PLAN_FP="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.schemaFingerprintSha256||"")' "$PLAN_PATH")"
+  if [[ -n "$PLAN_FP" && "$PLAN_FP" != "no-database-url" && "$PLAN_FP" != "$NOW_FP" ]]; then
+    fail "schema fingerprint changed since plan was created (re-plan required)"
+  else
+    ok "schema fingerprint matches plan"
+  fi
+else
+  ok "plan has no source database (offline plan)"
+fi
+
+# Production env optional: if CLEARANCE_STRICT_SECRETS=1, require strong secrets
+if [[ "${CLEARANCE_STRICT_SECRETS:-}" == "1" ]]; then
+  if ! bash "$ROOT/scripts/validate-production-env.sh" >/dev/null 2>&1; then
+    fail "CLEARANCE_STRICT_SECRETS=1 but validate-production-env failed"
+  else
+    ok "production env validation"
+  fi
+fi
+
+if [[ "$errors" -ne 0 ]]; then
+  die "upgrade-preflight failed ($errors checks)"
+fi
+
+node -e '
+  const fs=require("fs");
+  const p=process.argv[1];
+  const j=JSON.parse(fs.readFileSync(p,"utf8"));
+  j.status="preflight_ok";
+  j.updatedAt=new Date().toISOString().replace(/\.\d{3}Z$/,"Z");
+  j.applyJournal=j.applyJournal||[];
+  j.applyJournal.push({at:j.updatedAt, event:"preflight_ok"});
+  fs.writeFileSync(p, JSON.stringify(j,null,2)+"\n");
+' "$STATE_PATH"
+
+printf 'upgrade-preflight: OK plan=%s\n' "$PLAN_ID"
+printf 'PREFLIGHT_OK=1\n'