@redaktyn/cli 0.0.0-stage → 1.1.0

package/redaktyn-fingerprint.mjs

@@ -0,0 +1,814 @@
+#!/usr/bin/env node
+/**
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │  Redaktyn Fingerprint CLI  ·  Zero-Knowledge Secret Digest      │
+ * │  Generates HMAC-SHA256 fingerprints locally — nothing leaves    │
+ * │  your machine. Built on Node.js built-in crypto only.           │
+ * └─────────────────────────────────────────────────────────────────┘
+ *
+ * Usage (interactive wizard):
+ *   node redaktyn-fingerprint.mjs
+ *
+ * Usage (non-interactive / scripting):
+ *   node redaktyn-fingerprint.mjs \
+ *     --org-id  <uuid> \
+ *     --label   "AWS_SECRET_KEY" \
+ *     --secret  "AKIAIOSFODNN7EXAMPLE..." \
+ *     [--passphrase "your-org-passphrase"]   # prefer env var
+ *
+ *   REDAKTYN_PASSPHRASE="..." node redaktyn-fingerprint.mjs --org-id ... --label ... --secret ...
+ *
+ * Batch mode (one label:secret per line in a file):
+ *   node redaktyn-fingerprint.mjs --batch secrets.txt --org-id <uuid>
+ *
+ * Flags:
+ *   --json          Output pure JSON (default: human-readable table)
+ *   --no-color      Disable ANSI colors
+ *   --help          Show this help
+ *
+ * Required Node.js ≥ 18 (uses built-in crypto — NO npm install needed).
+ */
+
+import { createHmac, pbkdf2 as _pbkdf2, createHash, hkdfSync } from "node:crypto";
+import { promisify } from "node:util";
+import * as readline from "node:readline";
+import { readFileSync, existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const pbkdf2 = promisify(_pbkdf2);
+
+/* ═══════════════════════════════════════════════════════════════
+   ANSI colors — disabled with --no-color
+   ═══════════════════════════════════════════════════════════════ */
+const NO_COLOR = process.argv.includes("--no-color") || process.env["NO_COLOR"];
+const c = {
+  reset:   NO_COLOR ? "" : "\x1b[0m",
+  bold:    NO_COLOR ? "" : "\x1b[1m",
+  dim:     NO_COLOR ? "" : "\x1b[2m",
+  red:     NO_COLOR ? "" : "\x1b[31m",
+  green:   NO_COLOR ? "" : "\x1b[32m",
+  yellow:  NO_COLOR ? "" : "\x1b[33m",
+  blue:    NO_COLOR ? "" : "\x1b[34m",
+  magenta: NO_COLOR ? "" : "\x1b[35m",
+  cyan:    NO_COLOR ? "" : "\x1b[36m",
+  white:   NO_COLOR ? "" : "\x1b[37m",
+  gray:    NO_COLOR ? "" : "\x1b[90m",
+  bgBlue:  NO_COLOR ? "" : "\x1b[44m",
+  underline: NO_COLOR ? "" : "\x1b[4m",
+};
+
+/* ═══════════════════════════════════════════════════════════════
+   Crypto — identical algorithm to dashboard & extension
+   ═══════════════════════════════════════════════════════════════ */
+
+export const PBKDF2_ITERATIONS = 600_000; // OWASP 2024 floor — must match shared/secret-digest.ts
+const PBKDF2_KEYLEN     = 32;   // 256 bits
+
+/**
+ * Canonical normalization matching shared/secret-digest.ts:
+ * NFC unicode · CRLF→LF · strip invisible Unicode · trim · UUID hex case-fold
+ *
+ * v2 adds stripping of zero-width and invisible characters that survive NFC
+ * and can be used to bypass HMAC detection by inserting invisible chars.
+ */
+export function canonicalize(raw) {
+  let s = raw.normalize("NFC");
+  // Kept byte-identical to INVISIBLE_CHARS_CLASS in shared/secret-digest.ts —
+  // this file is standalone and cannot import it, so a guard test compares the
+  // two. They had already drifted once.
+  s = s.replace(/\r\n/g, "\n").replace(/[\r\u2028\u2029]/g, "\n");
+  // v2: strip invisible Unicode (zero-width, bidi marks, invisible operators)
+  s = s.replace(/[\u00ad\u200b-\u200f\u2060-\u2064\ufeff]/g, "");
+  s = s.trim();
+  return foldUuid(s);
+}
+
+/** UUID hex case fold: 8-4-4-4-12. Matches foldUuidHexCase() in the shared module. */
+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;
+}
+
+/**
+ * Derive HMAC key from passphrase + orgId via PBKDF2-SHA256.
+ * Matches deriveHmacKeyFromPassphrase() in shared/secret-digest.ts.
+ *
+ * There was a `--device-id` flag that mixed an extension id into the salt.
+ * Anything enrolled through it was unmatchable everywhere — the extension
+ * derives from the org id alone, as it must for one digest to be checkable on
+ * every device — so the flag could only ever produce a secret that looked
+ * enrolled and was never enforced.
+ */
+export async function deriveKey(passphrase, orgId) {
+  const salt = createHash("sha256").update(orgId, "utf8").digest();
+  return pbkdf2(passphrase, salt, PBKDF2_ITERATIONS, PBKDF2_KEYLEN, "sha256");
+}
+
+/**
+ * A project's HMAC key: HKDF-SHA256(orgKey, salt = projectId, info = the label
+ * below). Matches deriveProjectKey() in shared/secret-digest.ts byte for byte.
+ * Changing the label changes every project key, so it is the same string, not a
+ * look-alike. A project with `usesOrgKey: true` (the default one) hashes under
+ * the org key itself and must NOT be passed through this.
+ */
+export const PROJECT_KDF_LABEL = "redaktyn-project-key-v1";
+export function deriveProjectKey(orgKey, projectId) {
+  if (!projectId) throw new Error("deriveProjectKey: projectId is required");
+  return Buffer.from(hkdfSync("sha256", orgKey, Buffer.from(projectId, "utf8"),
+    Buffer.from(PROJECT_KDF_LABEL, "utf8"), PBKDF2_KEYLEN));
+}
+
+/**
+ * Whitespace-collapsed form, matching normalizeSecretPlaintextCollapsed().
+ * Note the order: collapse first, then UUID case-fold, exactly as the shared
+ * module composes them. Reversing the two changes nothing for most inputs and
+ * silently changes the digest for a UUID with stray whitespace.
+ */
+function canonicalizeCollapsed(raw) {
+  const base = raw
+    .normalize("NFC")
+    .replace(/\r\n/g, "\n")
+    .replace(/[\r\u2028\u2029]/g, "\n")
+    .replace(/[\u00ad\u200b-\u200f\u2060-\u2064\ufeff]/g, "")
+    .trim()
+    .replace(/\s/g, "");
+  return foldUuid(base);
+}
+
+/** Lowercase-folded form, matching normalizeSecretPlaintextLower(). */
+function canonicalizeLower(raw) {
+  return canonicalizeCollapsed(raw).toLowerCase();
+}
+
+function hmacHex(text, keyBuf) {
+  return createHmac("sha256", keyBuf).update(text, "utf8").digest("hex");
+}
+
+/**
+ * Keyed scan fingerprints, matching encodeScanPrefilter() in
+ * shared/scan-prefilter.ts — mirrored because this file cannot import it, and
+ * held to it by a parity test. Lets devices sign only windows that could match
+ * this secret; the seed comes from the key, which the server never holds.
+ */
+const SCAN_PREFILTER_LABEL = "redaktyn-scan-prefilter-v1";
+
+function scanPrefilterFingerprint(base, s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h = (Math.imul(h, base) + (c >= 65 && c <= 90 ? c + 32 : c) + 1) | 0;
+  }
+  return h >>> 16;
+}
+
+export function scanPrefilter(signed, keyBuf) {
+  const seed = createHmac("sha256", keyBuf).update(SCAN_PREFILTER_LABEL, "utf8").digest();
+  const base = seed.readInt32BE(0) | 1;
+  const hex4 = (s) => scanPrefilterFingerprint(base, s).toString(16).padStart(4, "0");
+  return `v1.${hex4(signed.exact)}${hex4(signed.collapsed)}${hex4(signed.lower)}`;
+}
+
+/** Shapes a computeHmac() result into the record every output path consumes. */
+export function fingerprint(label, secret, keyBuf, orgId) {
+  const r = computeHmac(secret, keyBuf);
+  return {
+    label,
+    orgId,
+    hmacHex: r.digest,
+    length: r.length,
+    hmacHexStripped: r.hmacHexStripped,
+    lengthStripped: r.lengthStripped,
+    hmacHexLower: r.hmacHexLower,
+    lengthLower: r.lengthLower,
+    scanPrefilter: r.scanPrefilter,
+    canonical: r.canonical,
+  };
+}
+
+/**
+ * Compute all three digest variants the dashboard enrolls.
+ *
+ * Emitting only `hmacHex` was not merely incomplete — a secret enrolled through
+ * this CLI would be caught when pasted verbatim and missed the moment someone
+ * added a space or changed a letter's case, because the two variants that cover
+ * those cases were never stored. The output shape mirrors POST /api/secrets.
+ */
+export function computeHmac(secret, keyBuf) {
+  const canonical = canonicalize(secret);
+  const collapsed = canonicalizeCollapsed(secret);
+  const lowered = canonicalizeLower(secret);
+  return {
+    digest: hmacHex(canonical, keyBuf),
+    canonical,
+    length: canonical.length,
+    hmacHexStripped: hmacHex(collapsed, keyBuf),
+    lengthStripped: collapsed.length,
+    hmacHexLower: hmacHex(lowered, keyBuf),
+    lengthLower: lowered.length,
+    scanPrefilter: scanPrefilter({ exact: canonical, collapsed, lower: lowered }, keyBuf),
+  };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Argument parsing
+   ═══════════════════════════════════════════════════════════════ */
+function parseArgs(argv) {
+  const out = {
+    help: false, json: false, noColor: false,
+    orgId: null, passphrase: null, secret: null, label: null,
+    batch: null,
+    allowSecretArgv: false, allowPassphraseArgv: false,
+    secretFromArgv: false, passphraseFromArgv: false,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h")               { out.help = true; }
+    else if (a === "--json")                        { out.json = true; }
+    else if (a === "--no-color")                    { out.noColor = true; }
+    else if (a === "--org-id")                      { out.orgId = argv[++i] ?? null; }
+    else if (a === "--passphrase")                  { out.passphrase = argv[++i] ?? null; out.passphraseFromArgv = true; }
+    else if (a === "--secret")                      { out.secret = argv[++i] ?? null; out.secretFromArgv = true; }
+    else if (a === "--label")                       { out.label = argv[++i] ?? null; }
+    else if (a === "--batch")                       { out.batch = argv[++i] ?? null; }
+    else if (a === "--i-know-this-leaks-to-history") { out.allowSecretArgv = true; out.allowPassphraseArgv = true; }
+  }
+  return out;
+}
+
+/**
+ * Refuse to read secrets/passphrases off argv unless the user has explicitly
+ * acknowledged the risk. argv is visible to:
+ *   • shell history (.zsh_history, .bash_history)
+ *   • `ps`, `/proc/<pid>/cmdline`, container audit logs
+ *   • CI build logs (most providers redact env vars but not argv)
+ *
+ * Recommended alternatives:
+ *   • `REDAKTYN_PASSPHRASE=… node redaktyn-fingerprint.mjs …`
+ *   • `printf '%s' "$SECRET" | node redaktyn-fingerprint.mjs --label … --org-id …`
+ *   • Interactive wizard (no flags) — secret is read from a hidden TTY prompt.
+ */
+function enforceArgvSecretsPolicy(args) {
+  const offenders = [];
+  if (args.secretFromArgv && !args.allowSecretArgv) offenders.push("--secret");
+  if (args.passphraseFromArgv && !args.allowPassphraseArgv) offenders.push("--passphrase");
+  if (offenders.length === 0) return;
+  console.error(`${c.red}${c.bold}Refusing to read sensitive material from argv: ${offenders.join(", ")}${c.reset}`);
+  console.error("");
+  console.error("  argv is recorded in shell history and is visible to other processes.");
+  console.error("  Use one of the safer paths instead:");
+  console.error("");
+  console.error(`    ${c.green}# 1) env var (passphrase)${c.reset}`);
+  console.error(`    REDAKTYN_PASSPHRASE='…' node redaktyn-fingerprint.mjs \\`);
+  console.error(`         --org-id <uuid> --label MY_KEY`);
+  console.error("");
+  console.error(`    ${c.green}# 2) stdin pipe (secret)${c.reset}`);
+  console.error(`    printf '%s' "$SECRET" | node redaktyn-fingerprint.mjs \\`);
+  console.error(`         --org-id <uuid> --label MY_KEY`);
+  console.error("");
+  console.error(`    ${c.green}# 3) interactive wizard (no flags) — hidden TTY prompts${c.reset}`);
+  console.error(`    node redaktyn-fingerprint.mjs`);
+  console.error("");
+  console.error(`  ${c.dim}If you absolutely must keep using argv (e.g. one-off in an ephemeral`);
+  console.error(`  shell where history is disabled), pass --i-know-this-leaks-to-history.${c.reset}`);
+  process.exit(2);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Terminal helpers
+   ═══════════════════════════════════════════════════════════════ */
+const WIDTH = Math.min(process.stdout.columns || 80, 80);
+
+function hr(ch = "─") { return c.gray + ch.repeat(WIDTH) + c.reset; }
+function pad(str, w)  { return str + " ".repeat(Math.max(0, w - stripAnsi(str).length)); }
+function stripAnsi(s) { return s.replace(/\x1b\[[0-9;]*m/g, ""); }
+
+function banner() {
+  const line1 = `${c.bold}${c.cyan} Redaktyn${c.reset}${c.bold} Fingerprint CLI${c.reset}`;
+  const line2 = `${c.gray} Zero-knowledge local secret digest — nothing leaves your machine${c.reset}`;
+  console.log();
+  console.log(hr("═"));
+  console.log(`  ${line1}`);
+  console.log(`  ${line2}`);
+  console.log(hr("═"));
+  console.log();
+}
+
+function step(num, label, detail) {
+  console.log(`  ${c.blue}${c.bold}[${num}]${c.reset} ${c.bold}${label}${c.reset}`);
+  if (detail) console.log(`      ${c.gray}${detail}${c.reset}`);
+}
+
+function ok(label, value) {
+  console.log(`  ${c.green}✓${c.reset}  ${c.bold}${label}${c.reset}  ${c.gray}${value}${c.reset}`);
+}
+
+function warn(msg) {
+  // stderr, not stdout. `--batch --json` writes the digest array to stdout for
+  // a caller to parse, and a skipped line printed to the same stream lands in
+  // the middle of it — one malformed line in the batch file and
+  // `JSON.parse(stdout)` throws. A warning is a diagnostic either way, so it
+  // belongs on the stream that is not the payload.
+  console.error(`  ${c.yellow}⚠${c.reset}  ${c.yellow}${msg}${c.reset}`);
+}
+
+function info(msg) {
+  console.log(`  ${c.cyan}ℹ${c.reset}  ${c.gray}${msg}${c.reset}`);
+}
+
+/** Simple terminal spinner */
+function spinner(msg) {
+  if (!process.stdout.isTTY || NO_COLOR) return { stop: (m) => m && console.log(`  ${c.green}✓${c.reset}  ${m}`) };
+  const frames = ["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"];
+  let i = 0;
+  const t = setInterval(() => {
+    process.stdout.write(`\r  ${c.cyan}${frames[i++ % frames.length]}${c.reset}  ${msg} `);
+  }, 80);
+  return {
+    stop: (doneMsg) => {
+      clearInterval(t);
+      process.stdout.write(`\r  ${c.green}✓${c.reset}  ${doneMsg ?? msg}` + " ".repeat(20) + "\n");
+    }
+  };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Masked password prompt (no readline default masking)
+   ═══════════════════════════════════════════════════════════════ */
+function promptMasked(promptText) {
+  return new Promise((resolve) => {
+    process.stdout.write(`  ${c.bold}${promptText}${c.reset} `);
+    if (!process.stdin.isTTY) {
+      let buf = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.once("data", (d) => {
+        process.stdin.pause();
+        resolve(d.trim());
+      });
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    let value = "";
+    const raw = process.stdin.setRawMode;
+    if (typeof raw === "function") process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const onData = (ch) => {
+      if (ch === "\u0003") { process.exit(); }
+      if (ch === "\r" || ch === "\n") {
+        process.stdin.removeListener("data", onData);
+        if (typeof raw === "function") process.stdin.setRawMode(false);
+        rl.close();
+        process.stdout.write("\n");
+        resolve(value);
+      } else if (ch === "\u007f" || ch === "\b") {
+        if (value.length > 0) { value = value.slice(0, -1); process.stdout.write("\b \b"); }
+      } else {
+        value += ch;
+        process.stdout.write("•");
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+/** Plain visible prompt */
+function prompt(promptText, defaultVal) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const q = defaultVal
+      ? `  ${c.bold}${promptText}${c.reset} ${c.gray}[${defaultVal}]${c.reset} `
+      : `  ${c.bold}${promptText}${c.reset} `;
+    rl.question(q, (ans) => {
+      rl.close();
+      resolve(ans.trim() || defaultVal || "");
+    });
+  });
+}
+
+/** yes/no confirmation */
+async function confirm(msg) {
+  const ans = await prompt(`${msg} ${c.gray}(y/N)${c.reset}:`);
+  return ans.toLowerCase() === "y" || ans.toLowerCase() === "yes";
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Output formatters
+   ═══════════════════════════════════════════════════════════════ */
+function printResult(result, jsonMode) {
+  if (jsonMode) {
+    // enrollPayload, not the whole record: the record carries `canonical`, the
+    // normalized plaintext. Printing it would put the secret on stdout of a
+    // tool whose entire promise is that the secret stays in memory.
+    console.log(JSON.stringify({ ...enrollPayload(result), orgId: result.orgId }, null, 2));
+    return;
+  }
+  console.log();
+  console.log(hr());
+  console.log(`  ${c.green}${c.bold}✅  Fingerprint generated successfully${c.reset}`);
+  console.log(hr());
+  console.log();
+  console.log(`  ${c.bold}Label        ${c.reset}${c.cyan}${result.label}${c.reset}`);
+  console.log(`  ${c.bold}HMAC Hex     ${c.reset}${c.yellow}${result.hmacHex}${c.reset}`);
+  console.log(`  ${c.bold}  stripped   ${c.reset}${c.gray}${result.hmacHexStripped}${c.reset}`);
+  console.log(`  ${c.bold}  lower      ${c.reset}${c.gray}${result.hmacHexLower}${c.reset}`);
+  console.log(`  ${c.bold}Length       ${c.reset}${result.length} chars ${c.gray}(stripped ${result.lengthStripped}, lower ${result.lengthLower})${c.reset}`);
+  console.log(`  ${c.bold}Org ID       ${c.reset}${c.gray}${result.orgId}${c.reset}`);
+  console.log(`  ${c.bold}Algorithm    ${c.reset}PBKDF2-SHA256 · ${PBKDF2_ITERATIONS.toLocaleString("en-US")} iters · HMAC-SHA256`);
+  console.log();
+  console.log(`  ${c.dim}── Ready to paste into dashboard ───────────────────${c.reset}`);
+  console.log();
+  console.log(`  ${c.bold}${c.blue}Copy this JSON and paste it using the "Import Digest" option:${c.reset}`);
+  console.log();
+  JSON.stringify(enrollPayload(result), null, 4)
+    .split("\n")
+    .forEach((l) => console.log(`    ${c.green}${l}${c.reset}`));
+  console.log();
+  console.log(hr());
+}
+
+/**
+ * The exact field set POST /api/secrets accepts. Kept in one place so the
+ * single-secret and batch outputs cannot disagree about which variants they
+ * include, which is how the stripped and lower digests went missing before.
+ */
+export function enrollPayload(r) {
+  return {
+    label: r.label,
+    hmacHex: r.hmacHex,
+    length: r.length,
+    hmacHexStripped: r.hmacHexStripped,
+    lengthStripped: r.lengthStripped,
+    hmacHexLower: r.hmacHexLower,
+    lengthLower: r.lengthLower,
+    ...(r.scanPrefilter ? { scanPrefilter: r.scanPrefilter } : {}),
+  };
+}
+
+function printMultiResults(results, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(results.map(enrollPayload), null, 2));
+    return;
+  }
+  console.log();
+  console.log(hr());
+  console.log(`  ${c.green}${c.bold}✅  ${results.length} fingerprint(s) generated${c.reset}`);
+  console.log(hr());
+  console.log();
+  results.forEach((r, i) => {
+    console.log(`  ${c.bold}${c.cyan}[${i + 1}] ${r.label}${c.reset}`);
+    console.log(`      hmacHex  ${c.yellow}${r.hmacHex.slice(0, 16)}…${r.hmacHex.slice(-8)}${c.reset}`);
+    console.log(`      length   ${r.length}`);
+    console.log();
+  });
+  console.log(`  ${c.bold}${c.blue}Full JSON (paste into API /api/secrets or Import Digest):${c.reset}`);
+  console.log();
+  JSON.stringify(results.map(enrollPayload), null, 4)
+    .split("\n")
+    .forEach((l) => console.log(`    ${c.green}${l}${c.reset}`));
+  console.log();
+  console.log(hr());
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Help text
+   ═══════════════════════════════════════════════════════════════ */
+function printHelp() {
+  console.log(`
+${c.bold}${c.cyan}Redaktyn Fingerprint CLI${c.reset}  —  Zero-knowledge local secret digest generator
+
+${c.bold}USAGE${c.reset}
+
+  ${c.green}Interactive wizard (recommended):${c.reset}
+    node redaktyn-fingerprint.mjs
+
+  ${c.green}Non-interactive (scripting / CI):${c.reset}
+    REDAKTYN_PASSPHRASE="..." node redaktyn-fingerprint.mjs \\
+      --org-id  "your-org-uuid" \\
+      --label   "MY_SECRET_KEY" \\
+      --secret  "raw-secret-value"
+
+  ${c.green}Batch mode (file with label:secret lines):${c.reset}
+    REDAKTYN_PASSPHRASE="..." node redaktyn-fingerprint.mjs \\
+      --batch secrets.txt --org-id "your-org-uuid"
+
+${c.bold}OPTIONS${c.reset}
+
+  --org-id      ${c.gray}<uuid>   Your organization UUID from the dashboard Settings page${c.reset}
+  --passphrase  ${c.gray}<str>    Organization passphrase (prefer REDAKTYN_PASSPHRASE env var)${c.reset}
+  --label       ${c.gray}<str>    Human-readable name for the secret (e.g. AWS_SECRET_KEY)${c.reset}
+  --secret      ${c.gray}<str>    The raw secret value to fingerprint${c.reset}
+  --batch       ${c.gray}<file>   Path to a file; each line: label:secret_value${c.reset}
+  --json                  Output pure JSON (no colors, no table)
+  --no-color              Disable ANSI colors
+  --help                  Show this help
+
+${c.bold}HOW IT WORKS${c.reset}
+
+  1. Your passphrase + org ID → PBKDF2-SHA256 (${PBKDF2_ITERATIONS.toLocaleString("en-US")} iters) → 256-bit HMAC key
+  2. Secret → NFC normalize + strip invisible Unicode + trim + UUID case-fold
+  3. HMAC-SHA256 over that, plus two bypass variants:
+       ${c.bold}hmacHex${c.reset}          exact canonical form
+       ${c.bold}hmacHexStripped${c.reset}  all whitespace removed  ("A mit@1" → "Amit@1")
+       ${c.bold}hmacHexLower${c.reset}     whitespace removed, then lowercased
+
+  All three are registered. Without them a secret is caught when pasted verbatim
+  and missed the moment someone adds a space or changes a letter's case.
+
+  ${c.yellow}Nothing is sent to any server.${c.reset} The secret and passphrase never leave this machine.
+  The digests are byte-identical to what the Redaktyn dashboard computes in your
+  browser — the algorithm is published as ${c.bold}@redaktyn/shared${c.reset} if you want to diff it.
+
+${c.bold}BATCH FILE FORMAT${c.reset}
+
+  One entry per line: ${c.cyan}LABEL:secret_value${c.reset}
+  Lines starting with # are ignored (comments).
+
+  Example:
+    # My company secrets
+    AWS_ACCESS_KEY:AKIAIOSFODNN7EXAMPLE
+    DATABASE_PASSWORD:s3cr3tPassw0rd!
+    STRIPE_SECRET:sk_live_abc123
+
+${c.bold}FINDING YOUR ORG ID${c.reset}
+
+  Dashboard → Settings → scroll to "Organization Details" → copy the UUID.
+
+${c.bold}SECURITY NOTE${c.reset}
+
+  ${c.dim}─ The CLI REFUSES to read --secret or --passphrase from argv by default
+    (argv is recorded in shell history and visible to other processes).
+  ─ Preferred: REDAKTYN_PASSPHRASE env var + stdin pipe for the secret:
+        printf '%s' "$SECRET" | REDAKTYN_PASSPHRASE='…' \\
+            node redaktyn-fingerprint.mjs --org-id <uuid> --label MY_KEY
+  ─ Override with --i-know-this-leaks-to-history only in disposable shells.
+  ─ This tool is intentionally dependency-free. Audit it: it's ~300 lines of Node.js.${c.reset}
+
+`);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Batch file parsing
+   ═══════════════════════════════════════════════════════════════ */
+function parseBatchFile(filePath) {
+  if (!existsSync(filePath)) {
+    console.error(`${c.red}Error: batch file not found: ${filePath}${c.reset}`);
+    process.exit(1);
+  }
+  const lines = readFileSync(filePath, "utf8").split("\n");
+  const entries = [];
+  for (const [index, raw] of lines.entries()) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const colonIdx = line.indexOf(":");
+    if (colonIdx < 1) {
+      // The line number, never the line. A line is malformed precisely when it
+      // has no `LABEL:` prefix, and the most likely reason for that is a bare
+      // secret on its own — so echoing it back to help the user identify it
+      // would print the secret to stderr, into scrollback and CI logs, which
+      // is the one thing this tool exists to avoid.
+      warn(`Skipping malformed line ${index + 1} (expected LABEL:value).`);
+      continue;
+    }
+    entries.push({ label: line.slice(0, colonIdx).trim(), secret: line.slice(colonIdx + 1) });
+  }
+  return entries;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   UUID validation
+   ═══════════════════════════════════════════════════════════════ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/* ═══════════════════════════════════════════════════════════════
+   Interactive wizard
+   ═══════════════════════════════════════════════════════════════ */
+async function runWizard(args) {
+  banner();
+
+  console.log(`  ${c.bold}Welcome!${c.reset} This wizard generates a zero-knowledge fingerprint of`);
+  console.log(`  your secret locally. Nothing is sent anywhere.\n`);
+
+  console.log(hr("·"));
+  console.log(`  ${c.bold}${c.magenta}STEP 1 — Organization ID${c.reset}`);
+  console.log(`  ${c.gray}Find this in: Dashboard → Settings → Organization Details${c.reset}`);
+  console.log();
+
+  let orgId = args.orgId?.trim() ?? "";
+  if (!orgId || !UUID_RE.test(orgId)) {
+    orgId = await prompt("Org ID (UUID format, e.g. a1b2c3d4-…):");
+    while (!UUID_RE.test(orgId.trim())) {
+      warn("That doesn't look like a valid UUID. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
+      orgId = await prompt("Org ID:");
+    }
+  } else {
+    ok("Org ID", orgId);
+  }
+  orgId = orgId.trim();
+
+  console.log();
+  console.log(hr("·"));
+  console.log(`  ${c.bold}${c.magenta}STEP 2 — Organization Passphrase${c.reset}`);
+  console.log(`  ${c.gray}The same passphrase your team uses when connecting the extension.${c.reset}`);
+  console.log(`  ${c.gray}Tip: set REDAKTYN_PASSPHRASE in your shell to avoid retyping.${c.reset}`);
+  console.log();
+
+  let passphrase = (process.env["REDAKTYN_PASSPHRASE"] && String(process.env["REDAKTYN_PASSPHRASE"])) ?? "";
+  if (!passphrase) {
+    passphrase = await promptMasked("Passphrase (hidden):");
+    while (!passphrase || passphrase.length < 8) {
+      warn("Passphrase must be at least 8 characters.");
+      passphrase = await promptMasked("Passphrase:");
+    }
+  } else {
+    ok("Passphrase", "••••••••  (loaded from REDAKTYN_PASSPHRASE)");
+  }
+
+  const results = [];
+  let addMore = true;
+  let secretNum = 0;
+
+  while (addMore) {
+    secretNum++;
+    console.log();
+    console.log(hr("·"));
+    console.log(`  ${c.bold}${c.magenta}STEP ${secretNum === 1 ? "3" : secretNum + 2} — Secret #${secretNum}${c.reset}`);
+    console.log();
+
+    const label = await prompt(`Label (human-readable name, e.g. AWS_SECRET_KEY${secretNum > 1 ? "" : ""}):`);
+    if (!label) { warn("Label cannot be empty — skipping."); continue; }
+
+    const secret = await promptMasked("Secret value (hidden):");
+    if (!secret) { warn("Secret cannot be empty — skipping."); continue; }
+
+    // Show crypto transparency
+    console.log();
+    console.log(`  ${c.dim}── Computing fingerprint ──────────────────────────${c.reset}`);
+    const sp = spinner("Deriving HMAC key via PBKDF2-SHA256 (600,000 iterations)…");
+
+    let key;
+    try {
+      key = await deriveKey(passphrase, orgId);
+      sp.stop("HMAC key derived  " + c.gray + "(256-bit, browser-identical)" + c.reset);
+    } catch (e) {
+      sp.stop();
+      console.error(`${c.red}Key derivation failed: ${e.message}${c.reset}`);
+      process.exit(1);
+    }
+
+    const fp = fingerprint(label, secret, key, orgId);
+
+    // Show steps
+    console.log();
+    console.log(`  ${c.dim}Step 1${c.reset}  ${c.gray}NFC normalize + trim + UUID case-fold${c.reset}`);
+    // `fp.canonical` is the normalized secret — for the overwhelming majority
+    // of real secrets (no leading/trailing whitespace, no exotic Unicode)
+    // that's byte-identical to what was just typed. enrollPayload() already
+    // excludes it from every other output path for exactly this reason; this
+    // line used to print it anyway, putting the secret on stdout (and so in
+    // terminal scrollback, session logging, and screen shares) on the
+    // wizard's own recommended, flag-free usage path.
+    console.log(`         ${c.gray}canonical form computed (${fp.canonical.length} chars) — never printed${c.reset}`);
+    console.log(`  ${c.dim}Step 2${c.reset}  ${c.gray}HMAC-SHA256(canonical, derivedKey)${c.reset}`);
+    console.log(`         ${c.yellow}${fp.hmacHex.slice(0, 16)}…${fp.hmacHex.slice(-8)}${c.reset}  ${c.gray}(64-char hex, not reversible)${c.reset}`);
+    console.log(`  ${c.dim}Step 3${c.reset}  ${c.gray}Two bypass variants: whitespace-collapsed and lowercased${c.reset}`);
+    console.log(`         ${c.gray}${fp.hmacHexStripped.slice(0, 16)}… · ${fp.hmacHexLower.slice(0, 16)}…${c.reset}`);
+    console.log(`  ${c.dim}Step 4${c.reset}  ${c.gray}Length recorded: ${fp.length} chars${c.reset}`);
+
+    results.push(fp);
+
+    console.log();
+    addMore = await confirm("Add another secret with the same passphrase?");
+  }
+
+  const jsonMode = args.json;
+  if (results.length === 1) {
+    printResult(results[0], jsonMode);
+  } else {
+    printMultiResults(results, jsonMode);
+  }
+
+  // Dashboard import tip
+  if (!jsonMode) {
+    console.log(`  ${c.bold}${c.cyan}Next steps:${c.reset}`);
+    console.log(`  ${c.gray}1. Copy the JSON above${c.reset}`);
+    console.log(`  ${c.gray}2. Dashboard → Secrets → "Import Digest" button${c.reset}`);
+    console.log(`  ${c.gray}3. Paste the JSON and click Add${c.reset}`);
+    console.log(`  ${c.gray}4. Extensions pick it up on next sync (≤5 min)${c.reset}`);
+    console.log();
+    console.log(`  ${c.dim}Your secret value was used only in-memory and is now gone.${c.reset}`);
+    console.log();
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Non-interactive / batch mode
+   ═══════════════════════════════════════════════════════════════ */
+async function runNonInteractive(args) {
+  const orgId = args.orgId?.trim();
+  if (!orgId || !UUID_RE.test(orgId)) {
+    console.error(`${c.red}Error: --org-id must be a valid UUID.${c.reset}`);
+    console.error(`  Find it in: Dashboard → Settings → Organization Details`);
+    process.exit(1);
+  }
+
+  const passphrase =
+    (process.env["REDAKTYN_PASSPHRASE"] && String(process.env["REDAKTYN_PASSPHRASE"])) ||
+    args.passphrase?.trim() || "";
+  if (!passphrase) {
+    console.error(`${c.red}Error: set REDAKTYN_PASSPHRASE env var or use --passphrase.${c.reset}`);
+    process.exit(1);
+  }
+
+  const key = await deriveKey(passphrase, orgId);
+
+  if (args.batch) {
+    const entries = parseBatchFile(args.batch);
+    if (entries.length === 0) {
+      console.error(`${c.red}Error: batch file is empty or has no valid entries.${c.reset}`);
+      process.exit(1);
+    }
+    const results = entries.map(({ label, secret }) => fingerprint(label, secret, key, orgId));
+    printMultiResults(results, args.json);
+    return;
+  }
+
+  // Single secret
+  const label = args.label?.trim();
+  const secret = args.secret;
+
+  if (!label) {
+    console.error(`${c.red}Error: --label is required in non-interactive mode.${c.reset}`);
+    process.exit(1);
+  }
+
+  let rawSecret = secret;
+  if (rawSecret == null) {
+    // Try stdin
+    if (!process.stdin.isTTY) {
+      rawSecret = await new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (d) => (data += d));
+        process.stdin.on("end", () => resolve(data.trim()));
+        process.stdin.on("error", reject);
+      });
+    }
+  }
+
+  if (!rawSecret) {
+    console.error(`${c.red}Error: --secret is required (or pipe on stdin).${c.reset}`);
+    process.exit(1);
+  }
+
+  printResult(fingerprint(label, rawSecret, key, orgId), args.json);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Entry point
+   ═══════════════════════════════════════════════════════════════ */
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  enforceArgvSecretsPolicy(args);
+
+  const isInteractive = process.stdin.isTTY &&
+    !args.orgId && !args.secret && !args.batch && !args.label &&
+    !process.env["REDAKTYN_PASSPHRASE"];
+
+  if (isInteractive) {
+    await runWizard(args);
+  } else {
+    await runNonInteractive(args);
+  }
+}
+
+/*
+  Run only when invoked directly.
+ 
+  `redaktyn-import.mjs` imports the digest helpers above rather than carrying a
+  second copy of them. Two copies of this pipeline is the one failure this file
+  already has a guard test against: a secret enrolled under one canonical form
+  and searched for under another is enrolled and unprotected at the same time.
+  Without this check, importing anything from here would run the whole CLI —
+  argv policy, wizard and all — as a side effect of asking for a function.
+*/
+const invokedDirectly =
+  !!process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  main().catch((err) => {
+    console.error(`${c.red}Fatal: ${err instanceof Error ? err.message : err}${c.reset}`);
+    process.exit(1);
+  });
+}