@clearance/cli 0.1.4

package/dist/operator-auth.d.ts

@@ -0,0 +1,28 @@
+export type OperatorCredential = {
+    version: 1;
+    apiUrl: string;
+    token: string;
+};
+export type OperatorWhoami = {
+    operator: {
+        id: string;
+        type: "operator";
+        authenticated: true;
+    };
+    projectId: string;
+    environmentId: string;
+    storeBackend: "json" | "postgres";
+};
+type AuthEnvironment = Partial<Pick<NodeJS.ProcessEnv, "CLEARANCE_CLI_CONFIG_DIR" | "XDG_CONFIG_HOME" | "HOME" | "CLEARANCE_API_URL" | "CLEARANCE_OPERATOR_TOKEN" | "CLEARANCE_API_TOKEN" | "CLEARANCE_PROFILE">>;
+export declare function credentialDirectory(env?: AuthEnvironment): string;
+export declare function normalizeProfile(profile: string | undefined, env?: AuthEnvironment): string;
+export declare function credentialPath(env?: AuthEnvironment, profile?: string): string;
+export declare function normalizeApiUrl(candidate: string | undefined, env?: AuthEnvironment): string;
+export declare function environmentToken(env?: AuthEnvironment): string | undefined;
+export declare function readSavedCredential(env?: AuthEnvironment, profile?: string): Promise<OperatorCredential | undefined>;
+export declare function writeSavedCredential(credential: Omit<OperatorCredential, "version">, env?: AuthEnvironment, profile?: string): Promise<void>;
+export declare function deleteSavedCredential(env?: AuthEnvironment, profile?: string): Promise<boolean>;
+export declare function readTokenFromStdin(): Promise<string>;
+export declare function fetchWhoami(apiUrl: string, token: string): Promise<OperatorWhoami>;
+export declare function validateAndSaveCredential(apiUrl: string, token: string, env?: AuthEnvironment, profile?: string): Promise<OperatorWhoami>;
+export {};

package/dist/operator-auth.js

@@ -0,0 +1,310 @@
+import { randomBytes } from "node:crypto";
+import { chmod, lstat, mkdir, open, rename, unlink, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { constants } from "node:fs";
+import { ClearanceError } from "@clearance/management";
+const CREDENTIAL_FILENAME = "operator-credentials.json";
+const CREDENTIAL_VERSION = 1;
+const WHOAMI_TIMEOUT_MS = 5_000;
+const MAX_STDIN_TOKEN_BYTES = 16 * 1024;
+const MIN_TOKEN_BYTES = 16;
+const MAX_CREDENTIAL_FILE_BYTES = 32 * 1024;
+function error(code, message, remediation, retryable = false) {
+    return new ClearanceError({
+        code,
+        message,
+        stage: "operator-auth",
+        remediation,
+        retryable,
+    });
+}
+function credentialIoError(cause) {
+    if (cause instanceof ClearanceError)
+        return cause;
+    return error("CLI_CREDENTIAL_IO", "Saved credential storage could not be accessed safely.", "Check CLEARANCE_CLI_CONFIG_DIR permissions and try again.");
+}
+function fileMode(mode) {
+    return mode & 0o777;
+}
+async function requirePrivateDirectory(path, create) {
+    try {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw error("CLI_CREDENTIAL_DIRECTORY_UNSAFE", "Credential directory is not a regular private directory.", "Remove the unsafe credential directory and run clearance login again.");
+        }
+        if (fileMode(stat.mode) !== 0o700) {
+            throw error("CLI_CREDENTIAL_DIRECTORY_UNSAFE", "Credential directory permissions must be 0700.", "Restrict the credential directory to its owner and run clearance login again.");
+        }
+        return;
+    }
+    catch (cause) {
+        if (cause instanceof ClearanceError)
+            throw cause;
+        if (cause.code !== "ENOENT" || !create)
+            throw cause;
+    }
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const beforeChmod = await lstat(path);
+    if (beforeChmod.isSymbolicLink() || !beforeChmod.isDirectory()) {
+        throw error("CLI_CREDENTIAL_DIRECTORY_UNSAFE", "Credential directory could not be secured.", "Set a private CLEARANCE_CLI_CONFIG_DIR and retry.");
+    }
+    await chmod(path, 0o700);
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fileMode(stat.mode) !== 0o700) {
+        throw error("CLI_CREDENTIAL_DIRECTORY_UNSAFE", "Credential directory could not be secured.", "Set a private CLEARANCE_CLI_CONFIG_DIR and retry.");
+    }
+}
+async function requirePrivateCredentialFile(path) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink() || !stat.isFile() || fileMode(stat.mode) !== 0o600) {
+        throw error("CLI_CREDENTIAL_FILE_UNSAFE", "Saved credential file is not a regular file with mode 0600.", "Remove the unsafe credential file and log in again.");
+    }
+}
+export function credentialDirectory(env = process.env) {
+    const explicit = env.CLEARANCE_CLI_CONFIG_DIR?.trim();
+    if (explicit)
+        return resolve(explicit);
+    const xdg = env.XDG_CONFIG_HOME?.trim();
+    if (xdg)
+        return resolve(xdg, "clearance");
+    return join(env.HOME?.trim() || homedir(), ".config", "clearance");
+}
+export function normalizeProfile(profile, env = process.env) {
+    const value = profile?.trim() || env.CLEARANCE_PROFILE?.trim() || "default";
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(value)) {
+        throw error("CLI_PROFILE_INVALID", "Clearance profile names must be lowercase letters, numbers, or hyphens.", "Choose a profile slug such as default, staging, or production-us.");
+    }
+    return value;
+}
+export function credentialPath(env = process.env, profile) {
+    const selected = normalizeProfile(profile, env);
+    const filename = selected === "default" ? CREDENTIAL_FILENAME : `operator-credentials.${selected}.json`;
+    return join(credentialDirectory(env), filename);
+}
+function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+export function normalizeApiUrl(candidate, env = process.env) {
+    const value = candidate?.trim() || env.CLEARANCE_API_URL?.trim() || "http://localhost:3200";
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw error("CLI_API_URL_INVALID", "Clearance API URL is invalid.", "Pass a valid --url or set CLEARANCE_API_URL.");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw error("CLI_API_URL_INVALID", "Clearance API URL must use HTTPS or local HTTP.", "Use an HTTPS URL or a localhost loopback HTTP URL.");
+    }
+    if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+        throw error("CLI_API_URL_INSECURE", "Remote Clearance API URLs must use HTTPS.", "Use HTTPS for remote APIs; HTTP is allowed only for localhost loopback.");
+    }
+    if (url.username || url.password || url.search || url.hash || (url.pathname !== "/" && url.pathname !== "")) {
+        throw error("CLI_API_URL_INVALID", "Clearance API URL must be an origin without credentials, path, query, or fragment.", "Pass the API origin, for example https://api.example.com.");
+    }
+    return url.origin;
+}
+export function environmentToken(env = process.env) {
+    return env.CLEARANCE_OPERATOR_TOKEN?.trim() || env.CLEARANCE_API_TOKEN?.trim() || undefined;
+}
+function validateOperatorToken(token) {
+    const size = Buffer.byteLength(token, "utf8");
+    if (size < MIN_TOKEN_BYTES || size > MAX_STDIN_TOKEN_BYTES || /\s/.test(token)) {
+        throw error("CLI_TOKEN_INVALID", "Operator token is invalid.", "Provide a bearer token between 16 bytes and 16 KiB without whitespace.");
+    }
+    return token;
+}
+function parseCredential(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw error("CLI_CREDENTIAL_INVALID", "Saved credential file is not valid JSON.", "Log in again to create a new credential file.");
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).length !== 3 ||
+        !["version", "apiUrl", "token"].every((key) => Object.prototype.hasOwnProperty.call(value, key))) {
+        throw error("CLI_CREDENTIAL_INVALID", "Saved credential file has an invalid schema.", "Log in again to create a new credential file.");
+    }
+    const credential = value;
+    if (credential.version !== CREDENTIAL_VERSION ||
+        typeof credential.apiUrl !== "string" ||
+        typeof credential.token !== "string") {
+        throw error("CLI_CREDENTIAL_INVALID", "Saved credential file has an invalid schema.", "Log in again to create a new credential file.");
+    }
+    try {
+        validateOperatorToken(credential.token);
+    }
+    catch {
+        throw error("CLI_CREDENTIAL_INVALID", "Saved credential file has an invalid schema.", "Log in again to create a new credential file.");
+    }
+    return {
+        version: CREDENTIAL_VERSION,
+        apiUrl: normalizeApiUrl(credential.apiUrl, {}),
+        token: credential.token,
+    };
+}
+export async function readSavedCredential(env = process.env, profile) {
+    const directory = credentialDirectory(env);
+    const path = credentialPath(env, profile);
+    try {
+        await requirePrivateDirectory(directory, false);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw credentialIoError(cause);
+    }
+    try {
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || fileMode(stat.mode) !== 0o600 || stat.size > MAX_CREDENTIAL_FILE_BYTES) {
+                throw error("CLI_CREDENTIAL_FILE_UNSAFE", "Saved credential file is not a regular, bounded file with mode 0600.", "Remove the unsafe credential file and log in again.");
+            }
+            return parseCredential(await handle.readFile("utf8"));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw credentialIoError(cause);
+    }
+}
+export async function writeSavedCredential(credential, env = process.env, profile) {
+    const directory = credentialDirectory(env);
+    const selectedProfile = normalizeProfile(profile, env);
+    const path = credentialPath(env, selectedProfile);
+    try {
+        await requirePrivateDirectory(directory, true);
+    }
+    catch (cause) {
+        throw credentialIoError(cause);
+    }
+    try {
+        await requirePrivateCredentialFile(path);
+    }
+    catch (cause) {
+        if (cause.code !== "ENOENT")
+            throw credentialIoError(cause);
+    }
+    const normalized = {
+        version: CREDENTIAL_VERSION,
+        apiUrl: normalizeApiUrl(credential.apiUrl, {}),
+        token: validateOperatorToken(credential.token),
+    };
+    const temporary = join(directory, `.${selectedProfile}.${CREDENTIAL_FILENAME}.${randomBytes(16).toString("hex")}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(`${JSON.stringify(normalized)}\n`, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, path);
+        await requirePrivateCredentialFile(path);
+    }
+    catch (cause) {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw credentialIoError(cause);
+    }
+}
+export async function deleteSavedCredential(env = process.env, profile) {
+    const directory = credentialDirectory(env);
+    const path = credentialPath(env, profile);
+    try {
+        await requirePrivateDirectory(directory, false);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return false;
+        throw credentialIoError(cause);
+    }
+    try {
+        await requirePrivateCredentialFile(path);
+        await unlink(path);
+        return true;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return false;
+        throw credentialIoError(cause);
+    }
+}
+export async function readTokenFromStdin() {
+    let input = "";
+    for await (const chunk of process.stdin) {
+        input += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        if (Buffer.byteLength(input, "utf8") > MAX_STDIN_TOKEN_BYTES) {
+            throw error("CLI_TOKEN_INVALID", "Operator token input is too large.", "Provide one bearer token on standard input.");
+        }
+    }
+    return validateOperatorToken(input.trim());
+}
+function parseWhoami(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw error("CLI_WHOAMI_INVALID_RESPONSE", "Clearance API returned an invalid whoami response.", "Upgrade the Clearance API or check the configured API URL.");
+    }
+    const response = value;
+    const operator = response.operator;
+    if (!operator ||
+        operator.id !== "operator" ||
+        operator.type !== "operator" ||
+        operator.authenticated !== true ||
+        typeof response.projectId !== "string" ||
+        !response.projectId ||
+        typeof response.environmentId !== "string" ||
+        !response.environmentId ||
+        (response.storeBackend !== "json" && response.storeBackend !== "postgres")) {
+        throw error("CLI_WHOAMI_INVALID_RESPONSE", "Clearance API returned an invalid whoami response.", "Upgrade the Clearance API or check the configured API URL.");
+    }
+    return {
+        operator: { id: "operator", type: "operator", authenticated: true },
+        projectId: response.projectId,
+        environmentId: response.environmentId,
+        storeBackend: response.storeBackend,
+    };
+}
+export async function fetchWhoami(apiUrl, token) {
+    const validatedToken = validateOperatorToken(token);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WHOAMI_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${normalizeApiUrl(apiUrl, {})}/v1/whoami`, {
+            headers: { authorization: `Bearer ${validatedToken}`, accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (response.status === 401) {
+            throw error("CLI_AUTH_UNAUTHORIZED", "Clearance API rejected the operator credential.", "Provide a valid operator token and try again.");
+        }
+        if (!response.ok) {
+            throw error("CLI_WHOAMI_FAILED", "Clearance API could not verify the operator credential.", "Check the API URL and operator access, then try again.", response.status >= 500);
+        }
+        return parseWhoami(await response.json());
+    }
+    catch (cause) {
+        if (cause instanceof ClearanceError)
+            throw cause;
+        if (cause.name === "AbortError") {
+            throw error("CLI_API_TIMEOUT", "Clearance API verification timed out.", "Check API reachability and try again.", true);
+        }
+        throw error("CLI_API_UNREACHABLE", "Clearance API could not be reached.", "Check the API URL and network connection, then try again.", true);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function validateAndSaveCredential(apiUrl, token, env = process.env, profile) {
+    const whoami = await fetchWhoami(apiUrl, token);
+    await writeSavedCredential({ apiUrl, token }, env, profile);
+    return whoami;
+}

package/dist/ops/deploy/compose/docker-compose.production.yml

@@ -0,0 +1,129 @@
+# Production overlay for Clearance.
+#
+# Usage (after validating secrets):
+#   scripts/validate-production-env.sh
+#   docker compose -f docker-compose.yml -f deploy/compose/docker-compose.production.yml config
+#   docker compose -f docker-compose.yml -f deploy/compose/docker-compose.production.yml up -d
+#
+# Fail-closed rules:
+# - NODE_ENV is forced to production
+# - DATABASE_URL must be a complete, operator-supplied connection string
+#   (no shell construction of password-bearing URLs — avoids @:/#? interpolation breakage)
+# - Every secret is required with no defaults
+# - Postgres is NOT published to the host by default (ports reset)
+# - Credential encryption key + key id are mandatory
+# - No VAR-with-default secret fallbacks (only fail-closed ${VAR:?...} forms)
+services:
+  postgres:
+    environment:
+      POSTGRES_USER: ${CLEARANCE_DB_USER:?set CLEARANCE_DB_USER}
+      POSTGRES_PASSWORD: ${CLEARANCE_DB_PASSWORD:?set CLEARANCE_DB_PASSWORD}
+      POSTGRES_DB: ${CLEARANCE_DB_NAME:?set CLEARANCE_DB_NAME}
+    # Production default: internal network only. Host publish requires a local override file.
+    ports: !reset []
+    volumes:
+      - clearance_pg:/var/lib/postgresql/data
+    healthcheck:
+      # $$ defers expansion to the container shell (avoids host-side compose interpolation)
+      test: ["CMD-SHELL", "pg_isready -U \"$$POSTGRES_USER\" -d \"$$POSTGRES_DB\""]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    restart: always
+    stop_grace_period: 30s
+
+  api:
+    build: !reset null
+    image: "${CLEARANCE_IMAGE_REPOSITORY:?set CLEARANCE_IMAGE_REPOSITORY}@${CLEARANCE_IMAGE_DIGEST:?set signed CLEARANCE_IMAGE_DIGEST}"
+    environment:
+      NODE_ENV: production
+      CLEARANCE_STRICT_SECRETS: "1"
+      CLEARANCE_API_PORT: "3200"
+      CLEARANCE_OPERATOR_TOKEN: ${CLEARANCE_OPERATOR_TOKEN:?set CLEARANCE_OPERATOR_TOKEN}
+      CLEARANCE_SECRET: ${CLEARANCE_SECRET:?set CLEARANCE_SECRET}
+      CLEARANCE_CREDENTIAL_KEY: ${CLEARANCE_CREDENTIAL_KEY:?set CLEARANCE_CREDENTIAL_KEY}
+      CLEARANCE_CREDENTIAL_KEY_ID: ${CLEARANCE_CREDENTIAL_KEY_ID:?set CLEARANCE_CREDENTIAL_KEY_ID}
+      CLEARANCE_BASE_URL: ${CLEARANCE_BASE_URL:?set CLEARANCE_BASE_URL}
+      CLEARANCE_CONSOLE_URL: ${CLEARANCE_CONSOLE_URL:?set CLEARANCE_CONSOLE_URL}
+      CLEARANCE_CORS_ORIGINS: ${CLEARANCE_CORS_ORIGINS:?set CLEARANCE_CORS_ORIGINS}
+      # Full connection string required — do not embed raw passwords via compose interpolation.
+      DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL to a full postgres URL with percent-encoded password}
+      # Fail-closed override of the dev base file: this profile publishes the
+      # API port, so x-forwarded-for from arbitrary clients must NOT be
+      # trusted for rate-limit keying. Hardcoded (this overlay forbids
+      # ${VAR:-default} interpolation); edit this line to "1" only if your
+      # deployment makes the API reachable EXCLUSIVELY via trusted proxies
+      # (e.g. the console BFF or a fronting load balancer).
+      CLEARANCE_TRUSTED_PROXY: "0"
+    # Replace the base loopback mapping instead of merging a second binding.
+    ports: !override
+      - "127.0.0.1:${CLEARANCE_API_PORT:?set CLEARANCE_API_PORT}:3200"
+    restart: always
+    stop_grace_period: 30s
+
+  console:
+    build: !reset null
+    image: "${CLEARANCE_IMAGE_REPOSITORY:?set CLEARANCE_IMAGE_REPOSITORY}@${CLEARANCE_IMAGE_DIGEST:?set signed CLEARANCE_IMAGE_DIGEST}"
+    environment:
+      NODE_ENV: production
+      CLEARANCE_STRICT_SECRETS: "1"
+      CLEARANCE_CONSOLE_PORT: "3100"
+      CLEARANCE_API_URL: http://api:3200
+      CLEARANCE_OPERATOR_TOKEN: ${CLEARANCE_OPERATOR_TOKEN:?set CLEARANCE_OPERATOR_TOKEN}
+      CLEARANCE_CONSOLE_ADMIN_USER: ${CLEARANCE_CONSOLE_ADMIN_USER:?set CLEARANCE_CONSOLE_ADMIN_USER}
+      CLEARANCE_CONSOLE_ADMIN_PASSWORD: ${CLEARANCE_CONSOLE_ADMIN_PASSWORD:?set CLEARANCE_CONSOLE_ADMIN_PASSWORD}
+      CLEARANCE_CONSOLE_SESSION_SECRET: ${CLEARANCE_CONSOLE_SESSION_SECRET:?set CLEARANCE_CONSOLE_SESSION_SECRET}
+    # Replace the base loopback mapping instead of merging a second binding.
+    ports: !override
+      - "127.0.0.1:${CLEARANCE_CONSOLE_PORT:?set CLEARANCE_CONSOLE_PORT}:3100"
+    restart: always
+    stop_grace_period: 30s
+
+  sample-b2b:
+    build: !reset null
+    image: "${CLEARANCE_IMAGE_REPOSITORY:?set CLEARANCE_IMAGE_REPOSITORY}@${CLEARANCE_IMAGE_DIGEST:?set signed CLEARANCE_IMAGE_DIGEST}"
+    environment:
+      NODE_ENV: production
+      CLEARANCE_STRICT_SECRETS: "1"
+      SAMPLE_APP_PORT: "3000"
+      CLEARANCE_SECRET: ${CLEARANCE_SECRET:?set CLEARANCE_SECRET}
+      CLEARANCE_BASE_URL: ${CLEARANCE_BASE_URL:?set CLEARANCE_BASE_URL}
+      # Optional social providers. The application fails startup on incomplete pairs.
+      CLEARANCE_GITHUB_CLIENT_ID: ${CLEARANCE_GITHUB_CLIENT_ID-}
+      CLEARANCE_GITHUB_CLIENT_SECRET: ${CLEARANCE_GITHUB_CLIENT_SECRET-}
+      CLEARANCE_GOOGLE_CLIENT_ID: ${CLEARANCE_GOOGLE_CLIENT_ID-}
+      CLEARANCE_GOOGLE_CLIENT_SECRET: ${CLEARANCE_GOOGLE_CLIENT_SECRET-}
+      DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL to a full postgres URL with percent-encoded password}
+    # Replace the base loopback mapping instead of merging a second binding.
+    ports: !override
+      - "127.0.0.1:${CLEARANCE_SAMPLE_PORT:?set CLEARANCE_SAMPLE_PORT}:3000"
+    restart: always
+
+  # One-shot scheduled job. Invoke from cron/systemd:
+  # docker compose ... --profile backup run --rm backup
+  # The script fails closed unless CLEARANCE_BACKUP_COPY_COMMAND succeeds.
+  backup:
+    profiles: ["backup"]
+    build: !reset null
+    image: "${CLEARANCE_BACKUP_IMAGE_REPOSITORY:?set CLEARANCE_BACKUP_IMAGE_REPOSITORY}@${CLEARANCE_BACKUP_IMAGE_DIGEST:?set signed CLEARANCE_BACKUP_IMAGE_DIGEST}"
+    command: ["bash", "scripts/backup-scheduled.sh", "--dir", "/backups"]
+    environment:
+      DATABASE_URL: ${DATABASE_URL:?set DATABASE_URL to a full postgres URL with percent-encoded password}
+      CLEARANCE_BACKUP_COPY_COMMAND: ${CLEARANCE_BACKUP_COPY_COMMAND-}
+      CLEARANCE_BACKUP_RETENTION_DAYS: ${CLEARANCE_BACKUP_RETENTION_DAYS-30}
+      CLEARANCE_BACKUP_RESTORE_VERIFY: "1"
+    volumes:
+      - clearance_backups:/backups
+    tmpfs:
+      - /tmp
+    read_only: true
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+volumes:
+  clearance_pg:
+    name: ${CLEARANCE_PG_VOLUME:?set CLEARANCE_PG_VOLUME to an explicit volume name}
+  clearance_backups:
+    name: ${CLEARANCE_BACKUP_VOLUME:?set CLEARANCE_BACKUP_VOLUME to an explicit volume name}

package/dist/ops/deploy/upgrades/README.md

@@ -0,0 +1,24 @@
+# Upgrade step hooks
+
+`scripts/upgrade-apply.sh` requires a hook:
+
+```text
+deploy/upgrades/steps/<targetVersion>/apply.sh
+```
+
+The currently supported transition is `0.1.4` to `0.2.0`. Its shipped hook is
+`deploy/upgrades/steps/0.2.0/apply.sh`; it verifies the release marker is at
+`0.1.4`, advances it to `0.2.0`, and verifies the result. The Clearance CLI
+packages this hook under `dist/ops/deploy/upgrades/steps/0.2.0/apply.sh`.
+
+## Contract
+
+- Invoked only after preflight and a **verified** Postgres backup (with isolated restore verification).
+- Args: `--plan PATH --from CURRENT --to TARGET`
+- Exit non-zero to fail closed (no silent partial apply).
+- Must not drop or overwrite the active database; destructive changes require explicit operator runbooks.
+- Rollback reference is always the verified backup id recorded in the plan state sidecar.
+
+Without a hook, apply fails after creating and verifying its rollback backup. It never records a no-op version transition as applied.
+
+`scripts/upgrade-rollback.sh` is a rollback **drill**: it verifies the deterministic backup reference through an isolated restore and leaves the active environment unchanged. An actual rollback remains an operator-runbook action until active restore automation is designed and tested separately.

package/dist/ops/deploy/upgrades/steps/0.2.0/apply.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Shipped 0.1.4 -> 0.2.0 database transition.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+# shellcheck source=scripts/lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+PLAN=""
+FROM=""
+TO=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --plan) PLAN="$2"; shift 2 ;;
+    --from) FROM="$2"; shift 2 ;;
+    --to) TO="$2"; shift 2 ;;
+    *) die "unknown upgrade hook argument: $1" ;;
+  esac
+done
+
+[[ -f "$PLAN" ]] || die "upgrade plan is missing"
+[[ "$FROM" == "0.1.4" && "$TO" == "0.2.0" ]] \
+  || die "this hook only supports 0.1.4 to 0.2.0"
+
+require_pg_client
+require_cmd node
+URL="$(resolve_database_url)"
+PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId)' "$PLAN")"
+PLAN_SHA="$(sha256_file "$PLAN")"
+[[ "$PLAN_ID" =~ ^upg_[0-9TZ]+_[a-f0-9]+$ ]] || die "unsafe plan id"
+require_application_release "$URL" "$FROM"
+
+# This is the application-owned migration contract: the durable management
+# snapshot used by the running API advances atomically with an append-only
+# migration ledger. It cannot pass against the old test-only ops marker.
+psql_q "$URL" \
+  -v from_version="$FROM" -v to_version="$TO" \
+  -v plan_id="$PLAN_ID" -v plan_sha="$PLAN_SHA" <<'SQL' >/dev/null
+BEGIN;
+CREATE TABLE IF NOT EXISTS clearance_schema_migrations (
+  version text PRIMARY KEY,
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  plan_id text NOT NULL,
+  plan_sha256 text NOT NULL,
+  from_version text
+);
+INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
+VALUES (:'from_version', 'application-baseline', :'plan_sha', NULL)
+ON CONFLICT (version) DO NOTHING;
+UPDATE clearance_management_snapshot
+SET data = jsonb_set(data, '{releaseVersion}', to_jsonb(:'to_version'::text), false),
+    revision = revision + 1,
+    updated_at = now()
+WHERE id = 1 AND data->>'releaseVersion' = :'from_version';
+INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
+VALUES (:'to_version', :'plan_id', :'plan_sha', :'from_version');
+COMMIT;
+SQL
+
+require_application_release "$URL" "$TO"
+ledger_plan="$(psql_q "$URL" -At -c "SELECT plan_id FROM clearance_schema_migrations WHERE version = '${TO}'")"
+[[ "$ledger_plan" == "$PLAN_ID" ]] || die "migration ledger did not record plan $PLAN_ID"