settld 0.1.2 → 0.2.0

package/scripts/acceptance/full-stack.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+ACCEPTANCE_CLEAN="${ACCEPTANCE_CLEAN:-1}"
+ACCEPTANCE_PROFILE="${ACCEPTANCE_PROFILE:-app}"
+
+if ! docker info >/dev/null 2>&1; then
+  echo "acceptance: docker is not available (is the daemon running, and do you have socket access?)" >&2
+  exit 2
+fi
+
+RUN_ID="${ACCEPTANCE_RUN_ID:-$(date +%s)_$RANDOM}"
+PROJECT="${ACCEPTANCE_PROJECT_NAME:-settld_acc_${RUN_ID}}"
+SCHEMA="${ACCEPTANCE_PG_SCHEMA:-acc_${RUN_ID}}"
+ART_DIR="${ACCEPTANCE_ARTIFACT_DIR:-$(mktemp -d)}"
+
+pick_port() {
+  node --input-type=module -e "import net from 'node:net'; const s=net.createServer(); s.listen(0,'127.0.0.1',()=>{console.log(s.address().port); s.close();});"
+}
+
+API_PORT="${ACCEPTANCE_API_PORT:-$(pick_port)}"
+RECEIVER_PORT="${ACCEPTANCE_RECEIVER_PORT:-$(pick_port)}"
+MINIO_PORT="${ACCEPTANCE_MINIO_PORT:-$(pick_port)}"
+MINIO_CONSOLE_PORT="${ACCEPTANCE_MINIO_CONSOLE_PORT:-$(pick_port)}"
+
+export COMPOSE_PROJECT_NAME="${PROJECT}"
+export PROXY_PG_SCHEMA="${SCHEMA}"
+export PROXY_API_PORT="${API_PORT}"
+export PROXY_RECEIVER_PORT="${RECEIVER_PORT}"
+export PROXY_MINIO_PORT="${MINIO_PORT}"
+export PROXY_MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT}"
+export ACCEPTANCE_ARTIFACT_DIR="${ART_DIR}"
+export ACCEPTANCE_API_BASE_URL="${ACCEPTANCE_API_BASE_URL:-http://127.0.0.1:${API_PORT}}"
+export ACCEPTANCE_RECEIVER_BASE_URL="${ACCEPTANCE_RECEIVER_BASE_URL:-http://127.0.0.1:${RECEIVER_PORT}}"
+export ACCEPTANCE_MINIO_ENDPOINT="${ACCEPTANCE_MINIO_ENDPOINT:-http://127.0.0.1:${MINIO_PORT}}"
+
+mkdir -p "${ART_DIR}"
+echo "acceptance: artifacts dir: ${ART_DIR}"
+echo "acceptance: COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}"
+echo "acceptance: PROXY_PG_SCHEMA=${PROXY_PG_SCHEMA}"
+echo "acceptance: PROXY_API_PORT=${PROXY_API_PORT}"
+echo "acceptance: PROXY_RECEIVER_PORT=${PROXY_RECEIVER_PORT}"
+echo "acceptance: PROXY_MINIO_PORT=${PROXY_MINIO_PORT}"
+echo "acceptance: PROXY_MINIO_CONSOLE_PORT=${PROXY_MINIO_CONSOLE_PORT}"
+echo "acceptance: ACCEPTANCE_API_BASE_URL=${ACCEPTANCE_API_BASE_URL}"
+echo "acceptance: ACCEPTANCE_RECEIVER_BASE_URL=${ACCEPTANCE_RECEIVER_BASE_URL}"
+echo "acceptance: ACCEPTANCE_MINIO_ENDPOINT=${ACCEPTANCE_MINIO_ENDPOINT}"
+
+compose_down() {
+  local profile_args=(--profile "${ACCEPTANCE_PROFILE}")
+  local exit_code="${1:-0}"
+  if [[ "${exit_code}" != "0" ]]; then
+    echo "acceptance: failure diagnostics"
+    docker compose "${profile_args[@]}" ps || true
+    docker compose "${profile_args[@]}" logs --no-color --tail=400 >"${ART_DIR}/compose.logs.tail.txt" 2>&1 || true
+    cat "${ART_DIR}/compose.logs.tail.txt" || true
+
+    # Best-effort: if context exists, snapshot key ops endpoints for debugging.
+    if [[ -f "${ART_DIR}/context.json" ]]; then
+      node --input-type=module -e "import fs from 'node:fs'; const c=JSON.parse(fs.readFileSync(process.env.ACCEPTANCE_ARTIFACT_DIR + '/context.json','utf8')); console.log(c?.bearer ?? '');" \
+        >"${ART_DIR}/bearer.txt" 2>/dev/null || true
+      BEARER="$(cat "${ART_DIR}/bearer.txt" 2>/dev/null || true)"
+      if [[ -n "${BEARER}" ]]; then
+        BEARER="${BEARER}" TENANT="${ACCEPTANCE_TENANT_ID:-tenant_default}" PROTO="${ACCEPTANCE_PROTOCOL:-1.0}" API="${ACCEPTANCE_API_BASE_URL:-http://127.0.0.1:3000}" \
+        node --input-type=module -e "const b=process.env.BEARER; const t=process.env.TENANT; const p=process.env.PROTO; const base=process.env.API; async function get(path){const r=await fetch(base+path,{headers:{authorization:b,'x-proxy-tenant-id':t,'x-settld-protocol':p}}).catch(()=>null); if(!r){console.log(path, 'fetch_failed'); return;} const txt=await r.text(); console.log(path, r.status); console.log(txt.slice(0, 4000));} await get('/ops/status'); await get('/ops/deliveries?limit=50'); await get('/ops/dlq?type=delivery&limit=50');" \
+          >"${ART_DIR}/ops.snapshots.txt" 2>&1 || true
+        cat "${ART_DIR}/ops.snapshots.txt" || true
+      fi
+    fi
+  fi
+
+  if [[ "${ACCEPTANCE_CLEAN}" == "1" ]]; then
+    docker compose --profile "${ACCEPTANCE_PROFILE}" down -v --remove-orphans >/dev/null 2>&1 || true
+  else
+    docker compose --profile "${ACCEPTANCE_PROFILE}" down --remove-orphans >/dev/null 2>&1 || true
+  fi
+}
+
+cleanup() {
+  local code="$?"
+  compose_down "${code}"
+}
+trap cleanup EXIT
+
+compose_down 0
+
+echo "acceptance: starting docker compose (profile=${ACCEPTANCE_PROFILE})"
+docker compose --profile "${ACCEPTANCE_PROFILE}" up -d --build
+
+echo "acceptance: seeding minio buckets"
+docker compose --profile init run --rm minio-init
+
+echo "acceptance: running full-stack checks"
+node scripts/acceptance/full-stack.mjs
+
+echo "acceptance: OK"

package/scripts/audit/build-audit-packet.mjs

@@ -0,0 +1,242 @@
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function sh(cmd, args, { cwd, env, stdin } = {}) {
+  const res = spawnSync(cmd, args, { cwd, env, input: stdin, encoding: "utf8" });
+  if (res.status !== 0) {
+    const err = (res.stderr || res.stdout || "").trim();
+    throw new Error(`${cmd} ${args.join(" ")} failed (exit ${res.status})${err ? `: ${err}` : ""}`);
+  }
+  return res.stdout;
+}
+
+async function sha256FileHex(fp) {
+  const h = crypto.createHash("sha256");
+  const f = await fs.open(fp, "r");
+  try {
+    const buf = Buffer.alloc(1024 * 1024);
+    while (true) {
+      // eslint-disable-next-line no-await-in-loop
+      const { bytesRead } = await f.read(buf, 0, buf.length, null);
+      if (bytesRead === 0) break;
+      h.update(buf.subarray(0, bytesRead));
+    }
+  } finally {
+    await f.close();
+  }
+  return h.digest("hex");
+}
+
+function parseArgs(argv) {
+  let outDir = path.resolve(process.cwd(), "dist", "audit");
+  let version = "v1";
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--out") {
+      outDir = path.resolve(process.cwd(), String(argv[i + 1] ?? ""));
+      i += 1;
+      continue;
+    }
+    if (a === "--packet-version") {
+      version = String(argv[i + 1] ?? "v1");
+      i += 1;
+      continue;
+    }
+    if (a === "--help" || a === "-h") {
+      // eslint-disable-next-line no-console
+      console.error("usage: node scripts/audit/build-audit-packet.mjs [--out <dir>] [--packet-version v1]");
+      process.exit(2);
+    }
+    // eslint-disable-next-line no-console
+    console.error(`unknown arg: ${a}`);
+    process.exit(2);
+  }
+  return { outDir, version };
+}
+
+async function listFilesRecursive(root) {
+  const out = [];
+  async function walk(cur) {
+    const entries = await fs.readdir(cur, { withFileTypes: true });
+    for (const e of entries) {
+      const fp = path.join(cur, e.name);
+      if (e.isDirectory()) {
+        // eslint-disable-next-line no-await-in-loop
+        await walk(fp);
+      } else if (e.isFile()) out.push(fp);
+    }
+  }
+  await walk(root);
+  out.sort();
+  return out;
+}
+
+async function writeReadme({ dst, packetName, tool }) {
+  const text = `# Settld Audit Packet (${packetName})
+
+This archive is intended to be a self-contained “evidence bundle” for a hostile/skeptical reader.
+
+## Contents
+
+- \`spec/\` — protocol specs (including threat model + invariants checklist)
+- \`protocol-vectors/\` — canonical protocol vectors
+- \`conformance/\` — the conformance pack tarball + checksums
+- \`tool.json\` — tool provenance summary for the build that produced this packet
+- \`SHA256SUMS\` — checksums for files in this packet
+
+## How to validate (minimum)
+
+1. Verify checksums (example):
+
+\`\`\`sh
+(cd ${packetName} && sha256sum -c SHA256SUMS)
+\`\`\`
+
+2. Install the released verifier CLI (\`settld-verify\`).
+
+- If published to npm, install a pinned version.
+- Otherwise, download the release npm tarball for \`settld-artifact-verify\` and install it locally.
+
+3. Run conformance pack (requires \`settld-verify\` in PATH):
+
+\`\`\`sh
+tar -xzf conformance/conformance-v1.tar.gz
+node conformance-v1/run.mjs
+\`\`\`
+
+## Tool provenance
+
+This packet was built from:
+
+\`\`\`json
+${JSON.stringify(tool, null, 2)}
+\`\`\`
+`;
+  await fs.writeFile(dst, text, "utf8");
+}
+
+async function main() {
+  const { outDir, version } = parseArgs(process.argv.slice(2));
+  await fs.mkdir(outDir, { recursive: true });
+
+  const repoRoot = process.cwd();
+
+  const toolVersion = (() => {
+    try {
+      const v = String((sh(process.execPath, ["-e", "const fs=require('fs'); console.log(String(fs.readFileSync('SETTLD_VERSION','utf8')).trim())"]).trim()) ?? "");
+      return v || null;
+    } catch {
+      return null;
+    }
+  })();
+  const toolCommit = (() => {
+    try {
+      const v = sh("git", ["rev-parse", "HEAD"], { cwd: repoRoot }).trim();
+      return v || null;
+    } catch {
+      return null;
+    }
+  })();
+
+  const packetName = `settld-audit-packet-${version}`;
+  const stagingRoot = await fs.mkdtemp(path.join(outDir, `${packetName}-staging-`));
+  const packetRoot = path.join(stagingRoot, packetName);
+  await fs.mkdir(packetRoot, { recursive: true });
+
+  try {
+    // 1) Copy specs (docs/spec/*)
+    await fs.cp(path.join(repoRoot, "docs", "spec"), path.join(packetRoot, "spec"), { recursive: true });
+
+    // 2) Copy protocol vectors
+    await fs.mkdir(path.join(packetRoot, "protocol-vectors"), { recursive: true });
+    await fs.copyFile(
+      path.join(repoRoot, "test", "fixtures", "protocol-vectors", "v1.json"),
+      path.join(packetRoot, "protocol-vectors", "v1.json")
+    );
+
+    // 3) Build conformance pack tarball and checksum
+    const conformanceOutDir = path.join(packetRoot, "conformance");
+    await fs.mkdir(conformanceOutDir, { recursive: true });
+    await fs.rm(path.join(stagingRoot, "conformance-v1"), { recursive: true, force: true });
+    await fs.mkdir(path.join(stagingRoot, "conformance-v1"), { recursive: true });
+    await fs.cp(path.join(repoRoot, "conformance", "v1"), path.join(stagingRoot, "conformance-v1"), { recursive: true });
+    const conformanceTgz = path.join(conformanceOutDir, "conformance-v1.tar.gz");
+    {
+      const tarPath = path.join(conformanceOutDir, "conformance-v1.tar");
+      sh("tar", ["--sort=name", "--mtime=2026-02-02 00:00:00Z", "--owner=0", "--group=0", "--numeric-owner", "-cf", tarPath, "-C", stagingRoot, "conformance-v1"]);
+      const res = spawnSync("gzip", ["-n", "-9", "-c", tarPath]);
+      if (res.status !== 0) throw new Error("gzip failed");
+      await fs.writeFile(conformanceTgz, res.stdout);
+      await fs.rm(tarPath, { force: true });
+    }
+    const conformanceSum = await sha256FileHex(conformanceTgz);
+    await fs.writeFile(path.join(conformanceOutDir, "conformance-v1-SHA256SUMS"), `${conformanceSum}  conformance-v1.tar.gz\n`, "utf8");
+
+    // 4) Tool provenance summary
+    const tool = {
+      schemaVersion: "AuditToolSummary.v1",
+      tool: { name: "settld-verify", version: toolVersion, commit: toolCommit },
+      repo: { commit: toolCommit }
+    };
+    await fs.writeFile(path.join(packetRoot, "tool.json"), JSON.stringify(tool, null, 2) + "\n", "utf8");
+
+    // 5) Packet README
+    await writeReadme({
+      dst: path.join(packetRoot, "README.md"),
+      packetName,
+      tool
+    });
+
+    // 6) SHA256SUMS for all files in packet (excluding SHA256SUMS itself)
+    const files = (await listFilesRecursive(packetRoot)).filter((fp) => path.basename(fp) !== "SHA256SUMS");
+    const lines = [];
+    for (const fp of files) {
+      // eslint-disable-next-line no-await-in-loop
+      const sum = await sha256FileHex(fp);
+      const rel = path.relative(packetRoot, fp).replaceAll(path.sep, "/");
+      lines.push(`${sum}  ${rel}`);
+    }
+    await fs.writeFile(path.join(packetRoot, "SHA256SUMS"), lines.join("\n") + "\n", "utf8");
+
+    // 7) Deterministic zip build (sorted entries, fixed timestamp)
+    const zipPath = path.join(outDir, `${packetName}.zip`);
+    const py = `
+import os, sys, zipfile
+from datetime import datetime
+
+root = sys.argv[1]
+out = sys.argv[2]
+
+fixed = (2026, 2, 2, 0, 0, 0)
+
+paths = []
+for dirpath, dirnames, filenames in os.walk(root):
+  dirnames.sort()
+  filenames.sort()
+  for fn in filenames:
+    fp = os.path.join(dirpath, fn)
+    rel = os.path.relpath(fp, root).replace(os.sep, "/")
+    paths.append((fp, rel))
+
+with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as z:
+  for fp, rel in paths:
+    zi = zipfile.ZipInfo(rel, date_time=fixed)
+    # Normalize perms to 0644 for determinism.
+    zi.external_attr = (0o100644 << 16)
+    with open(fp, "rb") as f:
+      z.writestr(zi, f.read())
+`;
+    sh("python3", ["-c", py, packetRoot, zipPath]);
+    const zipSum = await sha256FileHex(zipPath);
+    await fs.writeFile(path.join(outDir, `${packetName}.zip.sha256`), `${zipSum}  ${path.basename(zipPath)}\n`, "utf8");
+
+    // eslint-disable-next-line no-console
+    console.log(`wrote ${zipPath}`);
+  } finally {
+    await fs.rm(stagingRoot, { recursive: true, force: true });
+  }
+}
+
+await main();

package/scripts/backup-pg.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -z "${DATABASE_URL:-}" ]]; then
+  echo "DATABASE_URL is required" >&2
+  exit 2
+fi
+
+OUT_DIR="${OUT_DIR:-./backups}"
+TS="$(date -u +%Y%m%dT%H%M%SZ)"
+DEST="${OUT_DIR%/}/backup_${TS}"
+
+mkdir -p "$DEST"
+
+sanitize_url() {
+  # Best-effort: redact password in postgres://user:pass@host/db
+  local url="$1"
+  if [[ "$url" =~ ^([^:]+://[^:@]+):[^@]+@(.*)$ ]]; then
+    echo "${BASH_REMATCH[1]}:[REDACTED]@${BASH_REMATCH[2]}"
+  else
+    echo "[REDACTED]"
+  fi
+}
+
+echo "Backing up to $DEST" >&2
+
+pg_dump --format=custom --no-owner --no-privileges --file "$DEST/db.dump" "$DATABASE_URL"
+
+if command -v shasum >/dev/null 2>&1; then
+  shasum -a 256 "$DEST/db.dump" >"$DEST/db.dump.sha256"
+elif command -v sha256sum >/dev/null 2>&1; then
+  sha256sum "$DEST/db.dump" >"$DEST/db.dump.sha256"
+fi
+
+cat >"$DEST/meta.json" <<EOF
+{
+  "createdAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "databaseUrl": "$(sanitize_url "$DATABASE_URL")",
+  "pgSchema": "${PROXY_PG_SCHEMA:-public}",
+  "notes": "pg_dump custom format; restore with scripts/restore-pg.sh"
+}
+EOF
+
+echo "Done: $DEST" >&2
+

package/scripts/backup-restore/README.md

@@ -0,0 +1,18 @@
+# Backup/Restore verification (PG)
+
+This folder contains a deterministic backup/restore drill:
+
+- Seed a known workload into Postgres (PG store).
+- Capture a small set of state digests (counts + stable hashes).
+- Take a logical backup (`pg_dump`).
+- Restore into a fresh database.
+- Recompute state digests and compare.
+
+Entry point: `scripts/backup-restore-test.sh`.
+
+Requirements:
+
+- `STORE=pg`
+- `DATABASE_URL` and `RESTORE_DATABASE_URL` set
+- `pg_dump` and `psql` available on PATH
+

package/scripts/backup-restore/capture-state.mjs

@@ -0,0 +1,130 @@
+/**
+ * Captures a small, stable digest of Postgres state for backup/restore verification.
+ *
+ * Prints JSON to stdout.
+ */
+import pg from "pg";
+import { canonicalJsonStringify } from "../../src/core/canonical-json.js";
+import { sha256Hex } from "../../src/core/crypto.js";
+import { normalizeTenantId } from "../../src/core/tenancy.js";
+
+const DATABASE_URL = process.env.DATABASE_URL;
+if (!DATABASE_URL) throw new Error("DATABASE_URL is required");
+const TENANT_ID = normalizeTenantId(process.env.TENANT_ID ?? "tenant_default");
+const SCHEMA = (() => {
+  const raw = String(process.env.PROXY_PG_SCHEMA ?? "public").trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw)) {
+    throw new Error("PROXY_PG_SCHEMA must match [A-Za-z_][A-Za-z0-9_]*");
+  }
+  return raw;
+})();
+
+function digestRows(rows) {
+  return sha256Hex(canonicalJsonStringify(rows));
+}
+
+const { Client } = pg;
+const client = new Client({ connectionString: DATABASE_URL });
+await client.connect();
+await client.query(`SET search_path TO "${SCHEMA}", public`);
+
+const tenantCountRes = await client.query("SELECT COUNT(DISTINCT tenant_id)::int AS n FROM snapshots");
+const jobCountRes = await client.query("SELECT COUNT(*)::int AS n FROM snapshots WHERE tenant_id = $1 AND aggregate_type = 'job'", [TENANT_ID]);
+const ledgerEntryCountRes = await client.query("SELECT COUNT(*)::int AS n FROM ledger_entries WHERE tenant_id = $1", [TENANT_ID]);
+const allocationCountRes = await client.query("SELECT COUNT(*)::int AS n FROM ledger_allocations WHERE tenant_id = $1", [TENANT_ID]);
+const artifactCountRes = await client.query("SELECT COUNT(*)::int AS n FROM artifacts WHERE tenant_id = $1", [TENANT_ID]);
+const partyStatementCountRes = await client.query("SELECT COUNT(*)::int AS n FROM party_statements WHERE tenant_id = $1", [TENANT_ID]);
+
+const artifactsRes = await client.query(
+  `
+    SELECT artifact_id, artifact_type, artifact_hash
+    FROM artifacts
+    WHERE tenant_id = $1
+      AND artifact_type IN ('SettlementStatement.v1','MonthlyStatement.v1','PartyStatement.v1','PayoutInstruction.v1')
+    ORDER BY artifact_type ASC, artifact_id ASC
+  `,
+  [TENANT_ID]
+);
+const artifactsDigest = digestRows(
+  artifactsRes.rows.map((r) => ({
+    artifactId: String(r.artifact_id),
+    artifactType: String(r.artifact_type),
+    artifactHash: String(r.artifact_hash)
+  }))
+);
+
+const ledgerEntriesRes = await client.query(
+  `
+    SELECT entry_id, entry_json
+    FROM ledger_entries
+    WHERE tenant_id = $1
+    ORDER BY entry_id ASC
+  `,
+  [TENANT_ID]
+);
+const ledgerDigest = digestRows(
+  ledgerEntriesRes.rows.map((r) => ({
+    entryId: String(r.entry_id),
+    entry: r.entry_json ?? null
+  }))
+);
+
+const allocRes = await client.query(
+  `
+    SELECT entry_id, posting_id, account_id, party_id, party_role, currency, amount_cents
+    FROM ledger_allocations
+    WHERE tenant_id = $1
+    ORDER BY entry_id ASC, posting_id ASC, party_id ASC
+  `,
+  [TENANT_ID]
+);
+const allocationsDigest = digestRows(
+  allocRes.rows.map((r) => ({
+    entryId: String(r.entry_id),
+    postingId: String(r.posting_id),
+    accountId: r.account_id === null ? null : String(r.account_id),
+    partyId: String(r.party_id),
+    partyRole: String(r.party_role),
+    currency: String(r.currency),
+    amountCents: Number(r.amount_cents)
+  }))
+);
+
+const monthEventsRes = await client.query(
+  `
+    SELECT aggregate_id, seq, event_json
+    FROM events
+    WHERE tenant_id = $1 AND aggregate_type = 'month'
+    ORDER BY aggregate_id ASC, seq ASC
+  `,
+  [TENANT_ID]
+);
+const monthEventsDigest = digestRows(
+  monthEventsRes.rows.map((r) => ({
+    monthId: String(r.aggregate_id),
+    seq: Number(r.seq),
+    event: r.event_json ?? null
+  }))
+);
+
+await client.end();
+
+const state = {
+  tenantId: TENANT_ID,
+  counts: {
+    tenants: Number(tenantCountRes.rows?.[0]?.n ?? 0),
+    jobs: Number(jobCountRes.rows?.[0]?.n ?? 0),
+    ledgerEntries: Number(ledgerEntryCountRes.rows?.[0]?.n ?? 0),
+    allocations: Number(allocationCountRes.rows?.[0]?.n ?? 0),
+    artifacts: Number(artifactCountRes.rows?.[0]?.n ?? 0),
+    partyStatements: Number(partyStatementCountRes.rows?.[0]?.n ?? 0)
+  },
+  digests: {
+    artifacts: artifactsDigest,
+    ledgerEntries: ledgerDigest,
+    allocations: allocationsDigest,
+    monthEvents: monthEventsDigest
+  }
+};
+
+process.stdout.write(JSON.stringify(state, null, 2) + "\n");

package/scripts/backup-restore/client.mjs

@@ -0,0 +1,97 @@
+import { Readable } from "node:stream";
+
+import { createApi } from "../../src/api/app.js";
+import { createPgStore } from "../../src/db/store-pg.js";
+import { authKeyId, authKeySecret, hashAuthKeySecretLegacy } from "../../src/core/auth.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "../../src/core/tenancy.js";
+
+function makeReq({ method, path, headers, body }) {
+  const chunks = body === undefined ? [] : [Buffer.from(JSON.stringify(body), "utf8")];
+  const req = Readable.from(chunks);
+  req.method = method;
+  req.url = path;
+  req.headers = headers ?? {};
+  return req;
+}
+
+function makeRes() {
+  const headers = new Map();
+  return {
+    statusCode: 200,
+    setHeader(name, value) {
+      headers.set(String(name).toLowerCase(), String(value));
+    },
+    end(payload) {
+      this.body = payload ?? "";
+      this.headers = headers;
+      this.ended = true;
+    }
+  };
+}
+
+function hasAuthHeader(headers) {
+  const keys = Object.keys(headers ?? {});
+  for (const k of keys) {
+    const key = String(k).toLowerCase();
+    if (key === "authorization" || key === "x-proxy-api-key" || key === "x-proxy-ops-token") return true;
+  }
+  return false;
+}
+
+async function ensureAuth({ store, tenantId, scopes }) {
+  tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+  const keyId = authKeyId();
+  const secret = authKeySecret();
+  const secretHash = hashAuthKeySecretLegacy(secret);
+  const createdAt = new Date().toISOString();
+  await store.putAuthKey({
+    tenantId,
+    authKey: { keyId, secretHash, scopes, status: "active", description: "backup-restore-drill", createdAt }
+  });
+  const token = `${keyId}.${secret}`;
+  return { token, authorization: `Bearer ${token}` };
+}
+
+export async function createBackupRestoreApiClient({
+  databaseUrl,
+  schema = null,
+  tenantId = DEFAULT_TENANT_ID,
+  scopes = ["ops_write", "finance_write", "audit_read"],
+  protocol = "1.0",
+  now = null
+} = {}) {
+  if (!databaseUrl) throw new Error("databaseUrl is required");
+  tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+  const store = await createPgStore({
+    databaseUrl,
+    schema: schema ?? (process.env.PROXY_PG_SCHEMA ?? "public"),
+    migrateOnStartup: true
+  });
+  const api = createApi({ store, ...(typeof now === "function" ? { now } : null) });
+
+  const auth = await ensureAuth({ store, tenantId, scopes });
+
+  async function request({ method, path, headers = {}, body } = {}) {
+    const reqHeaders = {
+      "x-proxy-tenant-id": tenantId,
+      "x-settld-protocol": protocol,
+      ...(headers ?? {})
+    };
+    if (body !== undefined) reqHeaders["content-type"] = "application/json";
+    if (!hasAuthHeader(reqHeaders)) reqHeaders.authorization = auth.authorization;
+    const req = makeReq({ method, path, headers: reqHeaders, body });
+    const res = makeRes();
+    await api.handle(req, res);
+    const text = typeof res.body === "string" ? res.body : Buffer.from(res.body ?? "").toString("utf8");
+    const contentType = res.headers?.get?.("content-type") ? String(res.headers.get("content-type")) : "";
+    const isJson = contentType.includes("application/json") || contentType.includes("+json");
+    const json = isJson && text ? JSON.parse(text) : null;
+    return { statusCode: res.statusCode, json, body: text, headers: res.headers };
+  }
+
+  async function close() {
+    await store.close?.();
+  }
+
+  return { store, api, request, close, tenantId };
+}