@redaktyn/cli 0.0.0-stage → 1.1.0

package/redaktyn-verify.mjs

@@ -0,0 +1,557 @@
+#!/usr/bin/env node
+/**
+ * redaktyn-verify — check Redaktyn's claims without taking Redaktyn's word for any of them.
+ *
+ * Zero dependencies, Node built-ins only, one file. That is a requirement, not
+ * a preference: a verifier you have to trust is not a verifier. This is meant
+ * to be read end to end before it is run, and it is short enough to do that.
+ *
+ *   redaktyn-verify recompute   derive a digest from your secret; compare to the server's
+ *   redaktyn-verify build       hash what the server served you; compare to the signed manifest
+ *   redaktyn-verify pin         record the release log head as you see it today
+ *   redaktyn-verify check       confirm the log still reproduces the head you pinned
+ *   redaktyn-verify egress      assert a captured HAR contains no field the API does not accept
+ *
+ * WHAT THESE DO NOT PROVE, stated up front so nothing here is oversold:
+ *
+ *   - Nothing establishes what the server does internally. `recompute` shows the
+ *     stored value is a one-way function of your secret; it cannot show the
+ *     server did not also write the plaintext somewhere it never sends back.
+ *     Only source access, an audit, or self-hosting settles that.
+ *   - `build` establishes that the bytes you were served match a signed manifest.
+ *     Whether that manifest describes the published source is what
+ *     `scripts/release/verify-reproducible.mjs` is for — build it yourself.
+ *   - `check` catches a rewrite of the log served to you. A server can serve a
+ *     different, internally consistent log to someone else, and nothing here
+ *     would notice. Catching that needs a witness Redaktyn does not yet have.
+ *
+ * Requires Node 18+.
+ */
+
+import { createHash, createHmac, pbkdf2 as _pbkdf2, verify as edVerify, createPublicKey } from "node:crypto";
+import { promisify } from "node:util";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+const pbkdf2 = promisify(_pbkdf2);
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   The digest pipeline. Must match @redaktyn/shared/secret-digest.ts exactly.
+   Reimplemented rather than imported: a verifier that pulls in the code it is
+   checking verifies nothing.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const PBKDF2_ITERATIONS = 600_000;
+const INVISIBLE = /[\u00ad\u200b-\u200f\u2060-\u2064\ufeff]/g;
+
+function normalize(raw) {
+  return raw
+    .normalize("NFC")
+    .replace(/\r\n/g, "\n")
+    .replace(/[\r\u2028\u2029]/g, "\n")
+    .replace(INVISIBLE, "")
+    .trim();
+}
+
+function foldUuid(s) {
+  if (
+    s.length === 36 && s[8] === "-" && s[13] === "-" && s[18] === "-" && s[23] === "-" &&
+    /^[0-9a-fA-F]{32}$/.test(s.replace(/-/g, ""))
+  ) return s.toLowerCase();
+  return s;
+}
+
+async function deriveKey(passphrase, orgId) {
+  const salt = createHash("sha256").update(orgId, "utf8").digest();
+  return pbkdf2(passphrase, salt, PBKDF2_ITERATIONS, 32, "sha256");
+}
+
+function hmac(text, key) {
+  return createHmac("sha256", key).update(text, "utf8").digest("hex");
+}
+
+function digests(secret, key) {
+  const collapsed = foldUuid(normalize(secret).replace(/\s/g, ""));
+  return {
+    hmacHex: hmac(foldUuid(normalize(secret)), key),
+    hmacHexStripped: hmac(collapsed, key),
+    hmacHexLower: hmac(collapsed.toLowerCase(), key),
+  };
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Signature and log verification
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+function verifySignature(bytes, signatureB64, publicKeyB64) {
+  const raw = Buffer.from(publicKeyB64, "base64");
+  if (raw.length !== 32) return false;
+  const key = createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, raw]),
+    format: "der",
+    type: "spki",
+  });
+  return edVerify(null, bytes, key, Buffer.from(signatureB64, "base64"));
+}
+
+/** Canonical JSON — key order pinned, so hashes are reproducible. */
+function canonicalJson(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+  return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(",")}}`;
+}
+
+const GENESIS = "0".repeat(64);
+
+function verifyChain(entries) {
+  let prev = GENESIS;
+  entries.forEach((entry, i) => {
+    if (entry.seq !== i + 1) fail(`Release log entry ${i + 1} is out of order (seq ${entry.seq}).`);
+    if (entry.prevHead !== prev) fail(`Release log entry ${entry.seq} does not follow ${entry.seq - 1}.`);
+    const { head, ...body } = entry;
+    const recomputed = createHash("sha256").update(canonicalJson(body), "utf8").digest("hex");
+    if (recomputed !== head) fail(`Release log entry ${entry.seq} was modified after it was written.`);
+    prev = head;
+  });
+  return prev;
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Plumbing
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const NO_COLOR = process.env["NO_COLOR"] != null || process.argv.includes("--no-color");
+const c = {
+  b: NO_COLOR ? "" : "\x1b[1m", d: NO_COLOR ? "" : "\x1b[2m", r: NO_COLOR ? "" : "\x1b[0m",
+  g: NO_COLOR ? "" : "\x1b[32m", y: NO_COLOR ? "" : "\x1b[33m", red: NO_COLOR ? "" : "\x1b[31m",
+};
+
+const ok = (m) => console.log(`  ${c.g}✓${c.r} ${m}`);
+const bad = (m) => console.log(`  ${c.red}✗${c.r} ${m}`);
+const warn = (m) => console.log(`  ${c.y}!${c.r} ${m}`);
+const note = (m) => console.log(`    ${c.d}${m}${c.r}`);
+
+function fail(message) {
+  console.error(`\n${c.red}${message}${c.r}`);
+  process.exit(1);
+}
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] != null ? process.argv[i + 1] : fallback;
+}
+
+function requireArg(name) {
+  const v = arg(name);
+  if (v == null) fail(`Missing required argument ${name}. Run with --help.`);
+  return v;
+}
+
+/** Base URL of the Redaktyn deployment being checked. */
+function serverBase() {
+  return (arg("--server") ?? process.env["REDAKTYN_SERVER"] ?? "").replace(/\/+$/, "") ||
+    fail("Set --server https://your-redaktyn-host (or REDAKTYN_SERVER).");
+}
+
+async function getJson(url, headers = {}) {
+  const res = await fetch(url, { headers });
+  if (!res.ok) fail(`GET ${url} → HTTP ${res.status}`);
+  return res.json();
+}
+
+async function getBytes(url) {
+  const res = await fetch(url);
+  if (!res.ok) fail(`GET ${url} → HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function promptHidden(label) {
+  return new Promise((resolve) => {
+    process.stdout.write(`  ${label} `);
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin });
+      rl.once("line", (l) => { rl.close(); resolve(l); });
+      return;
+    }
+    let value = "";
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const onData = (ch) => {
+      if (ch === "\u0003") process.exit(130);
+      if (ch === "\r" || ch === "\n") {
+        process.stdin.removeListener("data", onData);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdout.write("\n");
+        resolve(value);
+      } else if (ch === "\u007f" || ch === "\b") {
+        if (value) { value = value.slice(0, -1); process.stdout.write("\b \b"); }
+      } else {
+        value += ch;
+        process.stdout.write("•");
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+/**
+ * Where pinned log heads are recorded. Overridable so the pin can live beside
+ * a CI job or a per-customer profile rather than only in one home directory —
+ * a pin that cannot be checked into the place doing the checking never gets
+ * checked.
+ */
+const PIN_PATH =
+  process.env["REDAKTYN_VERIFY_PIN"] ?? join(homedir(), ".redaktyn-verify-pin.json");
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   recompute
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+async function cmdRecompute() {
+  const orgId = requireArg("--org-id");
+  const passphrase = process.env["REDAKTYN_PASSPHRASE"] ?? (await promptHidden("Organization passphrase:"));
+  if (!passphrase) fail("A passphrase is required — it is what the key is derived from.");
+  const secret = process.env["REDAKTYN_SECRET"] ?? (await promptHidden("Secret value:"));
+  if (!secret) fail("A secret value is required.");
+
+  console.log(`\n${c.b}Deriving key${c.r}  PBKDF2-SHA256, ${PBKDF2_ITERATIONS.toLocaleString("en-US")} iterations`);
+  const key = await deriveKey(passphrase, orgId);
+  const local = digests(secret, key);
+
+  console.log(`\n${c.b}Computed locally${c.r}`);
+  for (const [k, v] of Object.entries(local)) console.log(`  ${k.padEnd(16)} ${v}`);
+
+  const token = arg("--token") ?? process.env["REDAKTYN_TOKEN"];
+  if (!token) {
+    console.log(
+      `\n${c.d}No API token given, so nothing was compared against the server.\n` +
+        `Pass --token <admin JWT> to fetch GET /api/secrets and check whether the\n` +
+        `stored digests equal the values above.${c.r}`
+    );
+    return;
+  }
+
+  const stored = await getJson(`${serverBase()}/api/secrets`, { Authorization: `Bearer ${token}` });
+  console.log(`\n${c.b}Compared against ${stored.length} registered fingerprint(s)${c.r}`);
+
+  const match = stored.find((s) =>
+    ["hmacHex", "hmacHexStripped", "hmacHexLower"].some((k) => s[k] != null && s[k] === local[k])
+  );
+
+  if (!match) {
+    bad("No stored digest equals what was just computed.");
+    note("Either this secret has no registered fingerprint, or the passphrase differs");
+    note("from the one used to register it. A different passphrase yields an unrelated digest.");
+    process.exitCode = 1;
+    return;
+  }
+
+  ok(`Matched "${match.label}".`);
+  for (const k of ["hmacHex", "hmacHexStripped", "hmacHexLower"]) {
+    if (match[k] == null) warn(`${k} is not stored for this secret — that variant is unprotected.`);
+    else if (match[k] === local[k]) ok(`${k} identical.`);
+    else {
+      bad(`${k} differs from the local computation.`);
+      // A variant that disagrees is a real verification failure: that pass
+      // will not match this secret on a device. `bad()` only prints, so
+      // without this the command said "✗" and still exited 0 — and anything
+      // gating on the exit code, which is how this is meant to be used, read
+      // a mismatch as a pass.
+      process.exitCode = 1;
+    }
+  }
+  note("The server holds a one-way digest of this secret, not the secret.");
+  note("It does not follow that the server never received the plaintext by some");
+  note("other route — run `egress` against a capture to check what the client sends.");
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   build
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+async function cmdBuild() {
+  const base = serverBase();
+  const release = await getJson(`${base}/api/verify/release`);
+
+  if (release.released === false) {
+    warn("This deployment publishes no signed release manifest.");
+    note(release.detail ?? "");
+    note("Nothing can be verified about the served bundle. Build from source and");
+    note("compare, or ask the operator which commit is deployed.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const manifestBytes = Buffer.from(release.manifest, "utf8");
+  const manifest = JSON.parse(release.manifest);
+  console.log(`\n${c.b}Manifest${c.r}  commit ${manifest.gitCommit}  ·  ${manifest.artifactCount} artifacts`);
+
+  if (!release.signed) {
+    warn("The manifest is NOT signed — it lists hashes but attests to nothing.");
+  } else {
+    const expected = arg("--pubkey") ?? process.env["REDAKTYN_PUBKEY"];
+    const served = release.signature.publicKeyBase64;
+    if (expected == null) {
+      warn("Signature checked against the key this same server supplied.");
+      note("That only rules out accidental corruption. A server able to alter the");
+      note("manifest can alter the key beside it. Pass --pubkey <base64> with a key");
+      note("you obtained elsewhere to make this meaningful.");
+    } else if (expected !== served) {
+      bad("The server's signing key is not the key you pinned.");
+      note(`pinned  ${expected}`);
+      note(`served  ${served}`);
+      process.exitCode = 1;
+      return;
+    } else {
+      ok("Signing key matches the one you pinned.");
+    }
+    if (!verifySignature(manifestBytes, release.signature.signature, served)) {
+      bad("Ed25519 signature does not verify — the manifest has been altered.");
+      process.exitCode = 1;
+      return;
+    }
+    ok("Signature verifies over the manifest bytes.");
+  }
+
+  // Hash what this server actually serves and compare with the manifest.
+  const byPath = new Map(manifest.artifacts.map((a) => [a.path, a.sha256]));
+  const html = await getBytes(`${base}/`);
+  const checks = [["dashboard/index.html", html]];
+
+  for (const m of html.toString("utf8").matchAll(/(?:src|href)="(\/assets\/[^"]+)"/g)) {
+    checks.push([`dashboard${m[1]}`, await getBytes(`${base}${m[1]}`)]);
+  }
+
+  console.log(`\n${c.b}Served bytes vs manifest${c.r}`);
+  let mismatched = 0;
+  for (const [path, bytes] of checks) {
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    const expected = byPath.get(path);
+    if (expected == null) {
+      warn(`${path} — not in the manifest`);
+    } else if (expected === actual) {
+      ok(`${path}`);
+    } else {
+      bad(`${path} — served bytes differ from the signed hash`);
+      mismatched++;
+    }
+  }
+
+  if (mismatched > 0) {
+    process.exitCode = 1;
+    return;
+  }
+
+  note("The bundle served to you matches the manifest. To close the loop, check");
+  note("that the manifest matches the published source: clone the repo at");
+  note(`${manifest.gitCommit.slice(0, 12)} and run scripts/release/verify-reproducible.mjs.`);
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   pin / check
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+async function fetchLog(base) {
+  const text = await (await fetch(`${base}/api/verify/log`)).text();
+  if (text.trimStart().startsWith("{") && text.includes('"released":false')) {
+    fail("This deployment publishes no release log.");
+  }
+  const entries = text.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => JSON.parse(l));
+  if (entries.length === 0) fail("The release log is empty.");
+  return entries;
+}
+
+async function cmdPin() {
+  const base = serverBase();
+  const entries = await fetchLog(base);
+  const head = verifyChain(entries);
+  ok(`Chain of ${entries.length} release(s) is internally consistent.`);
+
+  const pins = existsSync(PIN_PATH) ? JSON.parse(readFileSync(PIN_PATH, "utf8")) : {};
+  pins[base] = { head, seq: entries.length, pinnedAt: new Date().toISOString() };
+  writeFileSync(PIN_PATH, JSON.stringify(pins, null, 2) + "\n");
+
+  console.log(`\n  head  ${head}`);
+  console.log(`  saved ${PIN_PATH}`);
+  note("Run `redaktyn-verify check` later. If releases up to this point are ever");
+  note("rewritten or dropped, the chain will no longer reproduce this head.");
+}
+
+async function cmdCheck() {
+  const base = serverBase();
+  if (!existsSync(PIN_PATH)) fail(`Nothing pinned yet — run \`redaktyn-verify pin --server ${base}\` first.`);
+  const pins = JSON.parse(readFileSync(PIN_PATH, "utf8"));
+  const pin = pins[base];
+  if (pin == null) fail(`No pin recorded for ${base}.`);
+
+  const entries = await fetchLog(base);
+  verifyChain(entries);
+  ok(`Chain of ${entries.length} release(s) is internally consistent.`);
+
+  if (entries.length < pin.seq) {
+    bad(`The log has shrunk: ${pin.seq} entries were pinned, ${entries.length} are served now.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const atPin = entries[pin.seq - 1];
+  if (atPin.head !== pin.head) {
+    bad(`Release ${pin.seq} has changed since you pinned it.`);
+    note(`pinned  ${pin.head}`);
+    note(`served  ${atPin.head}`);
+    note("History was rewritten. Treat every signature from this server as suspect.");
+    process.exitCode = 1;
+    return;
+  }
+
+  ok(`Release ${pin.seq} still hashes to the head you pinned on ${pin.pinnedAt.slice(0, 10)}.`);
+  if (entries.length > pin.seq) {
+    ok(`${entries.length - pin.seq} release(s) appended since, with your pin intact beneath them.`);
+  }
+  note("This detects a rewrite of the log served to you. It cannot detect a server");
+  note("that serves a different, self-consistent log to somebody else.");
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   egress
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+async function cmdEgress() {
+  const harPath = requireArg("--har");
+  if (!existsSync(harPath)) fail(`No such file: ${harPath}`);
+  const har = JSON.parse(readFileSync(harPath, "utf8"));
+  const { endpoints } = await getJson(`${serverBase()}/api/verify/fields`);
+
+  /** Matches a concrete request path against an allowlist path with :params. */
+  const routeFor = (pathname) =>
+    endpoints.find((e) => {
+      const pattern = "^" + e.path.replace(/:[^/]+/g, "[^/]+") + "$";
+      return new RegExp(pattern).test(pathname);
+    });
+
+  const entries = har?.log?.entries ?? [];
+  if (entries.length === 0) fail("That HAR contains no entries.");
+
+  let inspected = 0;
+  const violations = [];
+
+  for (const entry of entries) {
+    const req = entry.request;
+    if (req?.postData?.text == null) continue;
+    let pathname;
+    try { pathname = new URL(req.url).pathname; } catch { continue; }
+    const route = routeFor(pathname);
+    if (route == null || route.method !== req.method) continue;
+
+    let body;
+    try { body = JSON.parse(req.postData.text); } catch { continue; }
+    inspected++;
+
+    const unknownTop = Object.keys(body).filter((k) => !route.fields.includes(k));
+    for (const k of unknownTop) violations.push(`${req.method} ${pathname} → "${k}"`);
+
+    const nested = route.itemFields;
+    if (nested && Array.isArray(body[nested.field])) {
+      for (const item of body[nested.field]) {
+        if (item == null || typeof item !== "object") continue;
+        for (const k of Object.keys(item)) {
+          if (!nested.fields.includes(k)) {
+            violations.push(`${req.method} ${pathname} → ${nested.field}[].${k}`);
+          }
+        }
+      }
+    }
+  }
+
+  console.log(`\n${c.b}Inspected ${inspected} Redaktyn API request(s) in ${harPath}${c.r}`);
+  if (inspected === 0) {
+    warn("None of the captured requests hit a Redaktyn ingest endpoint.");
+    note("Record the capture while registering a fingerprint or triggering a block.");
+    return;
+  }
+
+  if (violations.length > 0) {
+    bad(`${violations.length} field(s) outside the published allowlist:`);
+    for (const v of [...new Set(violations)]) console.log(`      ${v}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  ok("Every field sent is one the API publicly declares it accepts.");
+  note("This covers the requests in your capture, to endpoints on the allowlist.");
+  note("It says nothing about requests you did not record, or about what the");
+  note("server does with the fields it does accept.");
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Entry point
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+function help() {
+  console.log(`
+${c.b}redaktyn-verify${c.r} — check Redaktyn's claims for yourself
+
+${c.b}COMMANDS${c.r}
+
+  ${c.b}recompute${c.r}  --org-id <uuid> [--token <jwt>]
+      Derives the HMAC key from your passphrase and recomputes all three
+      digests. With a token, compares them against GET /api/secrets.
+      Passphrase and secret are read from a hidden prompt, or from
+      REDAKTYN_PASSPHRASE / REDAKTYN_SECRET.
+
+  ${c.b}build${c.r}      [--pubkey <base64>]
+      Fetches the signed release manifest, verifies the Ed25519 signature,
+      then hashes the bundle this server actually serves and compares.
+      Supply --pubkey with a key obtained independently — verifying against
+      the key the same server just handed you proves very little.
+
+  ${c.b}pin${c.r}
+      Records the release log head as it stands today, in
+      ~/.redaktyn-verify-pin.json (override with REDAKTYN_VERIFY_PIN).
+
+  ${c.b}check${c.r}
+      Re-fetches the log and confirms it still reproduces your pinned head.
+
+  ${c.b}egress${c.r}     --har <file.har>
+      Asserts that every field sent to a Redaktyn ingest endpoint in the capture
+      is one the API publicly declares. Record with DevTools → Network →
+      "Export HAR" while registering a fingerprint.
+
+${c.b}COMMON${c.r}
+
+  --server <url>   Redaktyn base URL (or REDAKTYN_SERVER)
+  --no-color       Disable ANSI colour
+  --help
+
+${c.b}WHAT THIS CANNOT SHOW${c.r}
+
+  ${c.d}Nothing here establishes what the server does with data after receiving it.
+  A one-way digest proves the stored value cannot be reversed; it does not
+  prove the plaintext was never written elsewhere. That needs source access,
+  an independent audit, or a deployment you host.${c.r}
+`);
+}
+
+const command = process.argv[2];
+const commands = {
+  recompute: cmdRecompute,
+  build: cmdBuild,
+  pin: cmdPin,
+  check: cmdCheck,
+  egress: cmdEgress,
+};
+
+if (command == null || command === "--help" || command === "-h" || commands[command] == null) {
+  help();
+  process.exit(command == null || command.startsWith("-") ? 0 : 1);
+}
+
+commands[command]().catch((err) => {
+  fail(err instanceof Error ? err.message : String(err));
+});