@redaktyn/cli 0.0.0-stage → 1.1.0

package/redaktyn-import.mjs

@@ -0,0 +1,1652 @@
+#!/usr/bin/env node
+/**
+ * ┌─────────────────────────────────────────────────────────────────┐
+ * │  Redaktyn Import CLI  ·  Bulk enrollment from files and vaults   │
+ * │  Digests are computed here. Values never leave this machine.     │
+ * └─────────────────────────────────────────────────────────────────┘
+ *
+ * Enrollment used to mean typing every secret into the dashboard by hand, so
+ * coverage was whatever the admin remembered. The values are already sitting
+ * somewhere — a dotenv file, Vault, AWS Secrets Manager, Doppler, 1Password —
+ * and every one of those can already print JSON. So this reads that, computes
+ * the HMAC digests locally, and sends only digests.
+ *
+ * Input modes:
+ *   --env <file>     dotenv (supports `export `, quotes, comments, multi-line)
+ *   --json <file>    JSON object of secrets
+ *   --yaml <file>    flat `key: value` YAML only — refuses anything nested
+ *   --stdin          JSON on stdin; this is what makes every vault work today
+ *
+ * Vault recipes (all of these pipe into --stdin):
+ *   vault kv get -format=json secret/prod | redaktyn-import --stdin
+ *   aws secretsmanager get-secret-value --secret-id prod \
+ *     --query SecretString --output text | redaktyn-import --stdin
+ *   doppler secrets download --no-file --format json | redaktyn-import --stdin
+ *   op item get prod --format json | redaktyn-import --stdin
+ *
+ * Nothing is written without --apply. Without it the command prints the plan
+ * and exits, because this tool changes what gets blocked for a whole org.
+ *
+ * Environment:
+ *   REDAKTYN_SERVER_URL   API base URL
+ *   REDAKTYN_PASSPHRASE   org passphrase — used locally for HMAC, never sent
+ *   REDAKTYN_TOKEN        OWNER/ADMIN JWT (an extension token cannot enroll)
+ *   REDAKTYN_ORG_ID       optional; must agree with the JWT when both are set
+ *
+ * Requires Node.js >= 18.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import * as readline from "node:readline";
+import { pathToFileURL } from "node:url";
+
+import {
+  canonicalize,
+  computeHmac,
+  deriveKey,
+  deriveProjectKey,
+  enrollPayload,
+} from "./redaktyn-fingerprint.mjs";
+
+/* ═══════════════════════════════════════════════════════════════
+   Colors
+   ═══════════════════════════════════════════════════════════════ */
+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",
+  cyan: NO_COLOR ? "" : "\x1b[36m",
+  gray: NO_COLOR ? "" : "\x1b[90m",
+};
+
+/** Usage and configuration errors: message, exit 2, no stack trace. */
+class UsageError extends Error {}
+
+/* ═══════════════════════════════════════════════════════════════
+   Scan budget — mirrors extension/src/security-config.ts
+   ═══════════════════════════════════════════════════════════════ */
+
+/**
+ * Must equal MAX_SCAN_WINDOWS in extension/src/security-config.ts. A guard test
+ * compares the two.
+ *
+ * This is not a soft performance number. Over this budget the extension returns
+ * `too_large` and refuses the scan, which hard-blocks in sensitive contexts —
+ * so enrolling enough secrets of enough different lengths does not slow pastes
+ * down, it stops them working. An import is the only operation that can cross
+ * the line in one step, which is why it reports the ceiling.
+ */
+const MAX_SCAN_WINDOWS = 1_500_000;
+
+/**
+ * Ceiling thresholds, chosen from measurements rather than taste.
+ * `bench-scan-latency.bench.test.ts` ("bulk-import-load") records:
+ *
+ *     100 secrets · 300 window lengths ... ceiling  5,068 chars, 7.7 s at it
+ *     200 secrets · 600 window lengths ... ceiling  2,618 chars, 7.4 s at it
+ *
+ * Those are secrets without a scan prefilter. Everything this command enrols
+ * carries one, and fifty such secrets leave a ceiling in the megabytes.
+ *
+ * A ceiling under 50k means a large file paste is already refused, and under
+ * 10k means ordinary ones are. Every org above a few secrets has *some* ceiling,
+ * so it is always reported and only escalated when it starts to bite.
+ */
+const PASTE_CEILING_WARN_CHARS = 50_000;
+const PASTE_CEILING_ALARM_CHARS = 10_000;
+
+/** Must equal MAX_TOTAL_SCAN_CHARS in extension/src/security-config.ts. */
+const MAX_TOTAL_SCAN_CHARS = 5 * 1024 * 1024;
+
+/** Must equal SCAN_PREFILTER_WINDOWS_PER_SIGNATURE in shared/scan-budget.ts. */
+const SCAN_PREFILTER_WINDOWS_PER_SIGNATURE = 256;
+/** Must equal SCAN_PREFILTER_SPACE in shared/scan-prefilter.ts. */
+const SCAN_PREFILTER_SPACE = 65_536;
+const SCAN_PREFILTER_PATTERN = /^v1\.[0-9a-f]{12}$/;
+
+const hasScanPrefilter = (s) =>
+  typeof s.scanPrefilter === "string" && SCAN_PREFILTER_PATTERN.test(s.scanPrefilter);
+
+/**
+ * Every sweep a scan runs: one per distinct window length per pass (exact,
+ * whitespace-collapse, case-fold), and whether the scan prefilter applies.
+ *
+ * Per pass, never de-duplicated across passes: the three lengths of one secret
+ * are usually equal, but the passes run over three different texts, so each
+ * costs its own sweep. A length is prefiltered only when every secret at it
+ * carries a valid prefilter, because the extension sweeps the whole length in
+ * full otherwise. Mirrors scanSweeps() in shared/scan-budget.ts.
+ */
+function scanSweeps(secrets, assumeFingerprinted = false) {
+  const passes = [new Map(), new Map(), new Map()];
+  const add = (pass, windowLen, prefiltered) => {
+    if (!(windowLen > 0)) return;
+    const seen = passes[pass].get(windowLen);
+    passes[pass].set(
+      windowLen,
+      seen
+        ? { windowLen, prefiltered: seen.prefiltered && prefiltered, entries: seen.entries + 1 }
+        : { windowLen, prefiltered, entries: 1 }
+    );
+  };
+  for (const s of secrets) {
+    const prefiltered = assumeFingerprinted || hasScanPrefilter(s);
+    if (s.hmacHex) add(0, s.length, prefiltered);
+    if (typeof s.hmacHexStripped === "string") add(1, s.lengthStripped, prefiltered);
+    if (typeof s.hmacHexLower === "string") add(2, s.lengthLower, prefiltered);
+  }
+  return passes.flatMap((p) => [...p.values()]);
+}
+
+/**
+ * What the extension's admission check charges for a text of `textChars`
+ * characters, with no discount for the text's shape. Mirrors
+ * projectedScanCost() in shared/scan-budget.ts.
+ */
+function projectedScanCost(textChars, sweeps) {
+  let cost = 0;
+  for (const sweep of sweeps) {
+    const examined = Math.max(0, textChars - sweep.windowLen + 1);
+    cost += sweep.prefiltered
+      ? Math.ceil(examined / SCAN_PREFILTER_WINDOWS_PER_SIGNATURE) +
+        Math.ceil((examined * sweep.entries) / SCAN_PREFILTER_SPACE)
+      : examined;
+  }
+  return cost;
+}
+
+/** Largest text the extension is guaranteed to scan, capped at its hard limit. */
+function maxScannablePasteCharsFor(sweeps) {
+  if (sweeps.length === 0) return Infinity;
+  if (projectedScanCost(MAX_TOTAL_SCAN_CHARS, sweeps) <= MAX_SCAN_WINDOWS) return MAX_TOTAL_SCAN_CHARS;
+  let lo = 0;
+  let hi = MAX_TOTAL_SCAN_CHARS;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (projectedScanCost(mid, sweeps) <= MAX_SCAN_WINDOWS) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+
+/**
+ * The paste ceiling a set of secrets leaves, and what re-enrolling the ones
+ * without a scan prefilter would buy back.
+ */
+export function scanBudgetForSecrets(secrets) {
+  const sweeps = scanSweeps(secrets);
+  const ceiling = maxScannablePasteCharsFor(sweeps);
+  return {
+    windowLengths: sweeps.length,
+    ceiling,
+    legacySecrets: secrets.filter((s) => s.hmacHex && !hasScanPrefilter(s)).length,
+    ceilingIfReenrolled: maxScannablePasteCharsFor(scanSweeps(secrets, true)),
+    atCharacterCap: ceiling === MAX_TOTAL_SCAN_CHARS,
+  };
+}
+
+/**
+ * Whether the server stores scan prefilters. A server that does returns the
+ * field on every row, null when absent; one deployed before it omits the key.
+ * An empty vault cannot say, so it is assumed current and the write path falls
+ * back if the field is refused.
+ */
+function serverStoresScanPrefilter(existing) {
+  return (
+    existing.length === 0 ||
+    existing.some((s) => s && Object.prototype.hasOwnProperty.call(s, "scanPrefilter"))
+  );
+}
+
+/** A 400 refusing `scanPrefilter` and nothing else: an older server. */
+function refusesOnlyScanPrefilter(r) {
+  const fields = r.data && Array.isArray(r.data.unknownFields) ? r.data.unknownFields : null;
+  return (
+    r.status === 400 &&
+    r.data?.code === "UNKNOWN_FIELD" &&
+    fields !== null &&
+    fields.length === 1 &&
+    fields[0] === "scanPrefilter"
+  );
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Argument parsing
+   ═══════════════════════════════════════════════════════════════ */
+function parseArgs(argv) {
+  const out = {
+    help: false,
+    env: null,
+    jsonFile: null,
+    yaml: null,
+    stdin: false,
+    source: null,
+    apply: false,
+    yes: false,
+    minLength: null,
+    allowWeak: false,
+    only: [],
+    exclude: [],
+    server: null,
+    orgId: null,
+    project: null,
+    reportJson: false,
+    noColor: false,
+  };
+  const need = (i, flag) => {
+    const v = argv[i];
+    if (v === undefined || v.startsWith("--")) {
+      throw new UsageError(`${flag} needs a value`);
+    }
+    return v;
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--env") out.env = need(++i, "--env");
+    else if (a === "--json") out.jsonFile = need(++i, "--json");
+    else if (a === "--yaml") out.yaml = need(++i, "--yaml");
+    else if (a === "--stdin") out.stdin = true;
+    else if (a === "--source") out.source = need(++i, "--source");
+    else if (a === "--apply") out.apply = true;
+    else if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--min-length") out.minLength = Number(need(++i, "--min-length"));
+    else if (a === "--allow-weak") out.allowWeak = true;
+    else if (a === "--only") out.only.push(need(++i, "--only"));
+    else if (a === "--exclude") out.exclude.push(need(++i, "--exclude"));
+    else if (a === "--server") out.server = need(++i, "--server");
+    else if (a === "--org-id") out.orgId = need(++i, "--org-id");
+    else if (a === "--project") out.project = need(++i, "--project");
+    else if (a === "--report-json") out.reportJson = true;
+    else if (a === "--no-color") out.noColor = true;
+    else throw new UsageError(`Unknown flag: ${a}`);
+  }
+  if (out.minLength !== null && (!Number.isInteger(out.minLength) || out.minLength < 1)) {
+    throw new UsageError("--min-length must be a positive integer");
+  }
+  return out;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Input parsing — dotenv
+   ═══════════════════════════════════════════════════════════════ */
+
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+
+/**
+ * dotenv parser.
+ *
+ * Scans by index rather than by line because a double-quoted value may span
+ * lines, and a PEM private key in a .env file is exactly that shape. Splitting
+ * on newlines first would read the first line of the key as the whole value and
+ * enroll a digest of a truncated secret, which looks enrolled and matches
+ * nothing.
+ *
+ * @returns Entries in file order (duplicates kept; the caller applies last-wins)
+ *   plus human-readable problems for lines that were skipped.
+ */
+export function parseDotenv(text) {
+  const src = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const entries = [];
+  const problems = [];
+  let i = 0;
+  let line = 1;
+
+  const skipToNextLine = () => {
+    const nl = src.indexOf("\n", i);
+    i = nl === -1 ? src.length : nl + 1;
+  };
+  const countNewlines = (from, to) => {
+    let n = 0;
+    for (let k = from; k < to; k++) if (src[k] === "\n") n++;
+    return n;
+  };
+
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === "\n") {
+      line++;
+      i++;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      i++;
+      continue;
+    }
+    if (ch === "#") {
+      skipToNextLine();
+      line++;
+      continue;
+    }
+
+    const declLine = line;
+
+    let j = i;
+    while (j < src.length && src[j] !== "=" && src[j] !== "\n") j++;
+    if (j >= src.length || src[j] === "\n") {
+      problems.push({ line: declLine, message: "no '=' on this line — skipped" });
+      i = j + 1;
+      line++;
+      continue;
+    }
+
+    let key = src.slice(i, j).trim();
+    if (/^export\s/.test(key)) key = key.replace(/^export\s+/, "").trim();
+    i = j + 1;
+
+    while (i < src.length && (src[i] === " " || src[i] === "\t")) i++;
+
+    let value = "";
+    let usable = true;
+    const quote = src[i];
+
+    if (quote === '"' || quote === "'") {
+      const valueStart = ++i;
+      const resumeAfterLine = src.indexOf("\n", i);
+      let closed = false;
+      while (i < src.length) {
+        const ch2 = src[i];
+        // Escapes are a double-quote feature in dotenv; inside single quotes a
+        // backslash is a literal backslash, and a key with a Windows path or a
+        // regex in it would otherwise be silently altered.
+        if (ch2 === "\\" && quote === '"' && i + 1 < src.length) {
+          const next = src[i + 1];
+          value += next === "n" ? "\n" : next === "t" ? "\t" : next === "r" ? "\r" : next;
+          i += 2;
+          continue;
+        }
+        if (ch2 === quote) {
+          i++;
+          closed = true;
+          break;
+        }
+        value += ch2;
+        i++;
+      }
+      if (closed) {
+        line += countNewlines(valueStart, i);
+        skipToNextLine();
+        line++;
+      } else {
+        // An unterminated quote scans to end of file, so continuing from there
+        // would drop every key below it without saying so. Resuming on the next
+        // line loses only the broken entry, which is the one already reported.
+        problems.push({ line: declLine, message: "unterminated quote — skipped this entry" });
+        usable = false;
+        i = resumeAfterLine === -1 ? src.length : resumeAfterLine + 1;
+        line++;
+      }
+    } else {
+      const nl = src.indexOf("\n", i);
+      const end = nl === -1 ? src.length : nl;
+      let raw = src.slice(i, end);
+      // Only whitespace-then-# is a comment. `pass#word` is a password.
+      const hash = raw.search(/\s#/);
+      if (hash !== -1) raw = raw.slice(0, hash);
+      value = raw.trim();
+      i = end === src.length ? end : end + 1;
+      line++;
+    }
+
+    if (!usable) continue;
+    if (!KEY_PATTERN.test(key)) {
+      problems.push({ line: declLine, message: `unusable key name ${JSON.stringify(key)} — skipped` });
+      continue;
+    }
+    entries.push({ key, value, line: declLine });
+  }
+
+  return { entries, problems };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Input parsing — JSON (and every vault CLI that speaks it)
+   ═══════════════════════════════════════════════════════════════ */
+
+/**
+ * Keys that mark an envelope rather than a secret. Unwrapping only happens when
+ * the document's own keys are a subset of these, so a real `.env` that happens
+ * to contain a key called `data` is not mistaken for a Vault response.
+ */
+const ENVELOPE_KEYS = new Set([
+  "data",
+  "metadata",
+  "lease_id",
+  "lease_duration",
+  "lease_renewable",
+  "renewable",
+  "request_id",
+  "warnings",
+  "auth",
+  "wrap_info",
+  "mount_type",
+]);
+
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Peels vendor envelopes off a parsed JSON document.
+ *
+ * Vault nests under `data.data`, AWS hands back the payload as a JSON string in
+ * `SecretString`, and 1Password uses a `fields` array. Handling these here is
+ * what lets `--stdin` work with every vault without a single vendor SDK.
+ *
+ * @returns `{ shape, doc }` where shape names what was recognised, for the log.
+ */
+export function unwrapSecretsDocument(doc) {
+  if (!isPlainObject(doc)) {
+    throw new UsageError("Expected a JSON object of secrets, got " + describeJson(doc));
+  }
+
+  if (typeof doc["SecretString"] === "string") {
+    let inner;
+    try {
+      inner = JSON.parse(doc["SecretString"]);
+    } catch {
+      throw new UsageError(
+        "SecretString is not JSON. For a single-value secret pass it to redaktyn-fingerprint instead."
+      );
+    }
+    return unwrapSecretsDocument(inner);
+  }
+
+  if (Array.isArray(doc["fields"])) {
+    const map = {};
+    for (const f of doc["fields"]) {
+      if (!isPlainObject(f)) continue;
+      const key = f["label"] ?? f["id"];
+      if (typeof key !== "string" || typeof f["value"] !== "string") continue;
+      map[key] = f["value"];
+    }
+    return { shape: "1password-item", doc: map };
+  }
+
+  const own = Object.keys(doc);
+  const envelope = own.length > 0 && own.every((k) => ENVELOPE_KEYS.has(k));
+  if (envelope && isPlainObject(doc["data"])) {
+    const inner = doc["data"];
+    // Vault KV v2 puts the secrets one level deeper and a metadata block beside
+    // them; KV v1 has them right here.
+    if (isPlainObject(inner["data"]) && "metadata" in inner) {
+      return { shape: "vault-kv2", doc: inner["data"] };
+    }
+    return { shape: "vault-kv1", doc: inner };
+  }
+
+  return { shape: "flat", doc };
+}
+
+function describeJson(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "an array";
+  return typeof v;
+}
+
+/**
+ * Flattens an unwrapped document to entries.
+ *
+ * Non-string scalars are stringified rather than dropped so the preview reports
+ * a verdict for them; the filter is where `PORT=8080` gets rejected, and a value
+ * that vanished before the filter is a value the admin never got told about.
+ */
+export function entriesFromJsonDocument(doc) {
+  const entries = [];
+  const problems = [];
+  for (const [key, raw] of Object.entries(doc)) {
+    if (typeof raw === "string") {
+      entries.push({ key, value: raw });
+      continue;
+    }
+    if (typeof raw === "number" || typeof raw === "boolean") {
+      entries.push({ key, value: String(raw) });
+      continue;
+    }
+    if (isPlainObject(raw)) {
+      // Doppler and friends wrap each value in an object.
+      const field = ["value", "raw", "computed", "computedValue"].find(
+        (f) => typeof raw[f] === "string"
+      );
+      if (field) {
+        entries.push({ key, value: raw[field] });
+        continue;
+      }
+      problems.push({ key, message: "nested object with no value/raw/computed field — skipped" });
+      continue;
+    }
+    problems.push({ key, message: `${describeJson(raw)} is not a secret value — skipped` });
+  }
+  return { entries, problems };
+}
+
+export function parseJsonSecrets(text) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    throw new UsageError(`Input is not valid JSON: ${e.message}`);
+  }
+  const { shape, doc: unwrapped } = unwrapSecretsDocument(doc);
+  const { entries, problems } = entriesFromJsonDocument(unwrapped);
+  return { entries, problems, shape };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Input parsing — flat YAML subset
+   ═══════════════════════════════════════════════════════════════ */
+
+/**
+ * Flat `key: value` YAML only.
+ *
+ * Real YAML is not parseable with a regex, and the failure mode of pretending
+ * otherwise is the worst one available here: a nested document read as flat
+ * produces keys mapped to empty or partial values, and enrolls digests of
+ * things that are not the secrets. So anything with indentation, a list, or a
+ * key with no inline value is refused outright.
+ */
+export function parseFlatYaml(text) {
+  const entries = [];
+  const problems = [];
+  const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+
+  lines.forEach((raw, idx) => {
+    const line = idx + 1;
+    if (raw.trim() === "" || raw.trim().startsWith("#")) return;
+    if (raw.trim() === "---" || raw.trim() === "...") return;
+
+    if (/^\s/.test(raw)) {
+      throw new UsageError(
+        `${line}: this YAML is indented, so it is not flat key/value. ` +
+          `Refusing rather than guessing — convert it to JSON and use --json.`
+      );
+    }
+    if (/^-\s/.test(raw.trim()) || raw.trim() === "-") {
+      throw new UsageError(`${line}: YAML lists are not supported. Use --json.`);
+    }
+    if (/^[|>]/.test(raw.trim())) {
+      throw new UsageError(`${line}: YAML block scalars are not supported. Use --json.`);
+    }
+
+    const m = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*:\s?(.*)$/.exec(raw);
+    if (!m) {
+      problems.push({ line, message: "not a `key: value` line — skipped" });
+      return;
+    }
+    const key = m[1];
+    let value = m[2] ?? "";
+
+    if (value.trim() === "" || value.trim() === "|" || value.trim() === ">") {
+      throw new UsageError(
+        `${line}: "${key}" has no inline value, which in YAML means a nested block or null. ` +
+          `Refusing rather than registering an empty fingerprint.`
+      );
+    }
+
+    const t = value.trim();
+    if ((t.startsWith('"') && t.endsWith('"') && t.length > 1) ||
+        (t.startsWith("'") && t.endsWith("'") && t.length > 1)) {
+      value = t.slice(1, -1);
+      if (t[0] === '"') value = value.replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\(.)/g, "$1");
+    } else {
+      const hash = t.search(/\s#/);
+      value = (hash === -1 ? t : t.slice(0, hash)).trim();
+    }
+
+    entries.push({ key, value, line });
+  });
+
+  return { entries, problems };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Junk filter
+   ═══════════════════════════════════════════════════════════════ */
+
+export const DEFAULT_MIN_LENGTH = 12;
+
+/**
+ * Values that are configuration or placeholders whatever their length. Enrolling
+ * one of these is not a harmless extra: every paste containing the word would be
+ * blocked, and zero false positives is the whole product.
+ */
+const PLACEHOLDER_VALUES = new Set([
+  "changeme",
+  "change-me",
+  "change_me",
+  "replaceme",
+  "replace-me",
+  "your-secret-here",
+  "your_secret_here",
+  "yoursecrethere",
+  "development",
+  "production",
+  "staging",
+  "localhost",
+  "password",
+  "passw0rd",
+  "secret",
+  "topsecret",
+  "undefined",
+  "none",
+  "null",
+  "n/a",
+  "todo",
+  "tbd",
+  "example",
+  "test",
+  "dummy",
+  "placeholder",
+]);
+
+function shannonBitsPerChar(s) {
+  if (s.length === 0) return 0;
+  const counts = new Map();
+  for (const ch of s) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  let h = 0;
+  for (const n of counts.values()) {
+    const p = n / s.length;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+
+/**
+ * URLs are the one case where "looks like config" and "is a secret" overlap: a
+ * Slack or Discord webhook is a URL and nothing else, and a Postgres DSN carries
+ * its password inline. So a URL is kept when it embeds a credential or a
+ * token-shaped path segment, and rejected when it is just an address.
+ *
+ * @returns null when the value is not a URL at all.
+ */
+function urlVerdict(value) {
+  if (!/:\/\//.test(value)) return null;
+  let u;
+  try {
+    u = new URL(value);
+  } catch {
+    return null;
+  }
+  if (u.password) return { ok: true };
+  const parts = [
+    ...u.pathname.split("/"),
+    ...[...u.searchParams.values()],
+    u.hash.replace(/^#/, ""),
+  ].filter(Boolean);
+  if (parts.some((p) => p.length >= 16 && shannonBitsPerChar(p) >= 2.5)) return { ok: true };
+  return { ok: false, reason: "URL with no embedded credential or token" };
+}
+
+/**
+ * Decides whether a value looks like a secret worth enforcing.
+ *
+ * Advisory by design: every rejection is printed with its reason and can be
+ * overridden with --allow-weak or --min-length. The bias is toward rejecting,
+ * because a missed secret can be enrolled tomorrow while a bad enrollment
+ * starts blocking legitimate pastes org-wide the moment it syncs.
+ *
+ * @param value - Canonical form, as digested
+ */
+export function junkVerdict(value, { minLength = DEFAULT_MIN_LENGTH } = {}) {
+  if (value.length === 0) return { ok: false, reason: "empty value" };
+  if (value.length < minLength) {
+    return { ok: false, reason: `only ${value.length} chars (minimum ${minLength})` };
+  }
+  if (/^\d+$/.test(value)) return { ok: false, reason: "all digits — port, id or timestamp" };
+  if (/^(true|false|yes|no|on|off|null|nil|none|undefined|enabled|disabled)$/i.test(value)) {
+    return { ok: false, reason: "boolean or empty-ish flag" };
+  }
+  if (/^v?\d+(\.\d+){1,3}([-+][0-9A-Za-z.-]+)?$/.test(value)) {
+    return { ok: false, reason: "version number" };
+  }
+  if (PLACEHOLDER_VALUES.has(value.toLowerCase())) {
+    return { ok: false, reason: "placeholder or environment name" };
+  }
+  if (/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(value)) {
+    return { ok: false, reason: "email address" };
+  }
+  if (/^(\/[^\s]*|\.{1,2}\/[^\s]*|~\/[^\s]*|[A-Za-z]:[\\/][^\s]*)$/.test(value)) {
+    return { ok: false, reason: "filesystem path" };
+  }
+  const url = urlVerdict(value);
+  if (url && !url.ok) return { ok: false, reason: url.reason };
+  if (!url) {
+    const distinct = new Set(value).size;
+    if (distinct < 5) return { ok: false, reason: `only ${distinct} distinct characters` };
+    if (shannonBitsPerChar(value) < 2.0) {
+      return { ok: false, reason: "very low character diversity" };
+    }
+  }
+  return { ok: true };
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Source selection and key filtering
+   ═══════════════════════════════════════════════════════════════ */
+
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new UsageError("--stdin was passed but nothing is piped in.");
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function readFileOrDie(path, flag) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (e) {
+    throw new UsageError(`${flag} ${path}: ${e.code === "ENOENT" ? "no such file" : e.message}`);
+  }
+}
+
+/** `import:<source>`; capped so the tag stays inside the server's 80-char limit. */
+export function sourceTag(source) {
+  return `import:${source}`;
+}
+
+export function normalizeSource(raw) {
+  const cleaned = String(raw)
+    .replace(/^[./]+/, "")
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return cleaned || "import";
+}
+
+function matchesAny(key, patterns) {
+  return patterns.some((p) => {
+    if (p.includes("*")) {
+      const re = new RegExp("^" + p.split("*").map(escapeRegex).join(".*") + "$", "i");
+      return re.test(key);
+    }
+    return key.toLowerCase() === p.toLowerCase();
+  });
+}
+
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/* ═══════════════════════════════════════════════════════════════
+   Diff
+   ═══════════════════════════════════════════════════════════════ */
+
+/**
+ * Classifies each candidate against what the org already enforces.
+ *
+ * Identity is `label` inside the import's own source tag, so two imports from
+ * two vaults never fight over the same row. Three deliberate choices:
+ *
+ *  - A value already enrolled under any label is a SKIP, not a CREATE. POST
+ *    rejects a duplicate digest with 409, so attempting it would turn a normal
+ *    situation into a failed run.
+ *  - A same-label secret that is *not* from this source is a CONFLICT, reported
+ *    and left alone. Rotating it would silently take over a hand-enrolled secret.
+ *  - A secret from this source that is no longer in the file is reported and
+ *    never removed. A vault read can fail or return a subset, and the failure
+ *    mode of acting on that is org-wide loss of protection.
+ */
+export function diffAgainstServer({ candidates, existing, source }) {
+  const tag = sourceTag(source);
+  const byDigest = new Map();
+  for (const s of existing) if (s.hmacHex) byDigest.set(s.hmacHex, s);
+
+  const owned = existing.filter((s) => Array.isArray(s.tags) && s.tags.includes(tag));
+  const ownedByLabel = new Map(owned.map((s) => [s.label, s]));
+  const otherByLabel = new Map();
+  for (const s of existing) {
+    if (owned.includes(s)) continue;
+    if (!otherByLabel.has(s.label)) otherByLabel.set(s.label, s);
+  }
+
+  const plan = [];
+  const seenLabels = new Set();
+
+  for (const cand of candidates) {
+    const { key, digests } = cand;
+    seenLabels.add(key);
+
+    const mine = ownedByLabel.get(key);
+    if (mine) {
+      if (mine.hmacHex === digests.digest && variantsMatch(mine, digests)) {
+        plan.push({ key, action: "skip", reason: "already registered and unchanged", id: mine.id, length: digests.length });
+      } else {
+        const clash = byDigest.get(digests.digest);
+        if (clash && clash.id !== mine.id) {
+          plan.push({
+            key,
+            action: "conflict",
+            reason: `new value is already registered as "${clash.label}"`,
+            id: mine.id,
+            length: digests.length,
+          });
+        } else {
+          const reason =
+            mine.hmacHex === digests.digest ? "value unchanged; adding missing variants" : "value changed";
+          plan.push({ key, action: "rotate", reason, id: mine.id, length: digests.length });
+        }
+      }
+      continue;
+    }
+
+    const sameDigest = byDigest.get(digests.digest);
+    if (sameDigest) {
+      plan.push({
+        key,
+        action: "skip",
+        reason: `already registered as "${sameDigest.label}"`,
+        id: sameDigest.id,
+        length: digests.length,
+      });
+      continue;
+    }
+
+    const sameLabel = otherByLabel.get(key);
+    if (sameLabel) {
+      plan.push({
+        key,
+        action: "conflict",
+        reason: "a secret with this label exists outside this import source",
+        id: sameLabel.id,
+        length: digests.length,
+      });
+      continue;
+    }
+
+    plan.push({ key, action: "create", reason: "new", length: digests.length });
+  }
+
+  const missing = owned
+    .filter((s) => !seenLabels.has(s.label))
+    .map((s) => ({ label: s.label, id: s.id, status: s.status }));
+
+  return { plan, missing };
+}
+
+/**
+ * True when the stored bypass variants already equal the ones just computed.
+ *
+ * Without this, a secret enrolled by an older client that stored only the exact
+ * digest would compare equal on `hmacHex` and be skipped forever, so the
+ * whitespace and case-fold passes would never start covering it.
+ *
+ * The scan prefilter is compared for the same reason: a row enrolled before it
+ * existed is otherwise skipped forever and keeps costing devices a full sweep.
+ * Re-importing is the one way an existing secret can gain it, because this is
+ * the one tool that holds the plaintext again.
+ */
+function variantsMatch(existing, digests) {
+  return (
+    existing.hmacHexStripped === digests.hmacHexStripped &&
+    existing.hmacHexLower === digests.hmacHexLower &&
+    existing.scanPrefilter === digests.scanPrefilter
+  );
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   HTTP
+   ═══════════════════════════════════════════════════════════════ */
+
+const trimSlashes = (u) => u.replace(/\/+$/, "");
+
+async function apiRequest(serverUrl, token, method, path, body) {
+  let res;
+  try {
+    res = await fetch(`${trimSlashes(serverUrl)}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (e) {
+    throw new UsageError(`Cannot reach ${trimSlashes(serverUrl)}: ${e.message}`);
+  }
+  const text = await res.text();
+  let data = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = null;
+    }
+  }
+  return { status: res.status, ok: res.ok, data, text };
+}
+
+/**
+ * Resolve --project to a row of GET /api/projects: exact id, else a
+ * case-insensitive exact name. Refuses an unknown, ambiguous or closed project
+ * before anything is hashed, because the server would otherwise file digests
+ * under a key no device on that project derives.
+ */
+async function resolveProject(serverUrl, token, wanted) {
+  const r = await apiRequest(serverUrl, token, "GET", "/api/projects");
+  if (!r.ok || !Array.isArray(r.data)) {
+    throw new UsageError(`GET /api/projects failed: ${r.status} ${String(r.text).slice(0, 200)}`);
+  }
+  const lower = wanted.trim().toLowerCase();
+  const byId = r.data.filter((p) => p.id === wanted.trim());
+  const matches = byId.length ? byId : r.data.filter((p) => String(p.name).toLowerCase() === lower);
+  if (matches.length === 0) {
+    throw new UsageError(`No project named or numbered "${wanted}". Known: ${r.data.map((p) => p.name).join(", ") || "none"}.`);
+  }
+  if (matches.length > 1) {
+    throw new UsageError(`"${wanted}" matches ${matches.length} projects. Pass the project id instead.`);
+  }
+  if (matches[0].status === "CLOSED") {
+    throw new UsageError(`Project "${matches[0].name}" is closed. Reopen it before enrolling into it.`);
+  }
+  return matches[0];
+}
+
+async function fetchExistingSecrets(serverUrl, token) {
+  const r = await apiRequest(serverUrl, token, "GET", "/api/secrets");
+  if (r.status === 401) {
+    throw new UsageError(
+      "Server rejected the token (401). REDAKTYN_TOKEN must be a current OWNER or ADMIN login token."
+    );
+  }
+  if (r.status === 403) {
+    throw new UsageError(
+      "This token is not allowed to manage secrets (403). Importing needs an OWNER or ADMIN token."
+    );
+  }
+  if (!r.ok) throw new UsageError(`GET /api/secrets failed: ${r.status} ${r.text.slice(0, 200)}`);
+  if (!Array.isArray(r.data)) throw new UsageError("GET /api/secrets did not return a list.");
+  return r.data;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Token checks
+   ═══════════════════════════════════════════════════════════════ */
+
+export function decodeJwtPayload(token) {
+  try {
+    const p = token.split(".")[1];
+    if (!p) return null;
+    const padded = p + "=".repeat((4 - (p.length % 4)) % 4);
+    const json = Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refuses an extension token before anything is computed.
+ *
+ * `redaktyn-scan` runs on a device token, so that is the variable already
+ * exported in most shells that have used this CLI. An extension token can read
+ * the secret list, which means the whole dry-run would look like it worked and
+ * only the first write would fail — after the operator had approved the plan.
+ */
+export function tokenRoleProblem(payload) {
+  if (!payload) return null;
+  if (payload.type === "extension") {
+    return (
+      "REDAKTYN_TOKEN is an extension device token. Those can sync fingerprints but not register them.\n" +
+      "  Get an OWNER or ADMIN login token instead:\n" +
+      "    curl -s -X POST \"$REDAKTYN_SERVER_URL/api/auth/login\" \\\n" +
+      "      -H 'Content-Type: application/json' \\\n" +
+      "      -d '{\"email\":\"you@example.com\",\"password\":\"…\"}' | jq -r .token"
+    );
+  }
+  const role = payload.role;
+  if (typeof role === "string" && !["OWNER", "ADMIN"].includes(role.toUpperCase())) {
+    return `This token has role ${role}. Importing needs OWNER or ADMIN.`;
+  }
+  return null;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Output
+   ═══════════════════════════════════════════════════════════════ */
+
+const ACTION_STYLE = {
+  create: { label: "CREATE", color: c.green },
+  rotate: { label: "ROTATE", color: c.yellow },
+  skip: { label: "skip", color: c.gray },
+  conflict: { label: "CONFLICT", color: c.red },
+  rejected: { label: "rejected", color: c.gray },
+};
+
+function truncateKey(key, width) {
+  return key.length <= width ? key.padEnd(width) : key.slice(0, width - 1) + "…";
+}
+
+/**
+ * Prints the plan.
+ *
+ * Values are never printed — not truncated, not masked, not for rejected keys.
+ * A preview is the thing an operator screenshots or pipes into a CI log, and a
+ * tool whose whole claim is that plaintext stays local cannot be the one to put
+ * plaintext on a terminal.
+ */
+function printPlan({ rows, missing, source, dryRun, budget, projectName = null }) {
+  const width = Math.min(process.stdout.columns || 80, 100);
+  const keyWidth = 34;
+
+  console.log("");
+  console.log(`${c.bold}Redaktyn import${c.reset} ${c.dim}· source tag ${sourceTag(source)}${projectName ? ` · project ${projectName}` : ""}${c.reset}`);
+  console.log(c.dim + "─".repeat(width) + c.reset);
+  console.log(
+    `${c.dim}${"KEY".padEnd(keyWidth)}  ${"LEN".padStart(5)}  ${"ACTION".padEnd(9)}  WHY${c.reset}`
+  );
+
+  for (const row of rows) {
+    const style = ACTION_STYLE[row.action] ?? { label: row.action, color: "" };
+    console.log(
+      `${truncateKey(row.key, keyWidth)}  ${String(row.length ?? "-").padStart(5)}  ` +
+        `${style.color}${style.label.padEnd(9)}${c.reset}  ${c.dim}${row.reason ?? ""}${c.reset}`
+    );
+  }
+
+  console.log(c.dim + "─".repeat(width) + c.reset);
+
+  const counts = tally(rows);
+  const summary = [
+    counts.create ? `${c.green}${counts.create} to create${c.reset}` : null,
+    counts.rotate ? `${c.yellow}${counts.rotate} to rotate${c.reset}` : null,
+    counts.skip ? `${counts.skip} unchanged` : null,
+    counts.rejected ? `${counts.rejected} filtered out` : null,
+    counts.conflict ? `${c.red}${counts.conflict} conflicting${c.reset}` : null,
+  ].filter(Boolean);
+  console.log("  " + (summary.length ? summary.join(c.dim + " · " + c.reset) : "nothing to do"));
+
+  if (missing.length > 0) {
+    console.log("");
+    console.log(
+      `${c.yellow}${missing.length} secret(s) tagged ${sourceTag(source)} are not in this input.${c.reset}`
+    );
+    console.log(`${c.dim}  Reported only — import never removes anything. Retire them in the dashboard if they are gone.${c.reset}`);
+    for (const m of missing.slice(0, 20)) {
+      console.log(`${c.dim}  · ${m.label}${c.reset}`);
+    }
+    if (missing.length > 20) console.log(`${c.dim}  · … ${missing.length - 20} more${c.reset}`);
+  }
+
+  printBudget(budget);
+
+  if (dryRun) {
+    console.log("");
+    console.log(`${c.bold}Dry run — nothing was sent.${c.reset} ${c.dim}Re-run with --apply to register.${c.reset}`);
+  }
+  console.log("");
+}
+
+/**
+ * Reports the paste ceiling this import leaves behind.
+ *
+ * Always printed, because every enrolled secret moves it and an operator
+ * running a bulk import is the only person in a position to trade coverage
+ * against it. Escalated when it reaches sizes people actually paste.
+ */
+function printBudget(budget) {
+  if (!budget || budget.ceiling === Infinity) return;
+  const pretty = budget.ceiling.toLocaleString("en-US");
+  const legacyNote = (tone) => {
+    if (!(budget.legacySecrets > 0) || !(budget.ceilingIfReenrolled > budget.ceiling)) return;
+    const n = budget.legacySecrets;
+    console.log(
+      `${tone}  ${n} enrolled secret${n === 1 ? " has" : "s have"} no scan prefilter (enrolled before 2026-10-07 or by an` +
+        ` older client),${c.reset}`
+    );
+    console.log(
+      `${tone}  so every paste is checked against ${n === 1 ? "it" : "them"} the slow way. They are outside this import;` +
+        ` re-enrolling ${n === 1 ? "it" : "them"}${c.reset}`
+    );
+    console.log(
+      `${tone}  from the dashboard, or importing ${n === 1 ? "it" : "them"}, raises this to ~` +
+        `${budget.ceilingIfReenrolled.toLocaleString("en-US")} chars.${c.reset}`
+    );
+  };
+
+  if (budget.ceiling < PASTE_CEILING_ALARM_CHARS) {
+    console.log("");
+    console.log(`${c.red}${c.bold}Scan budget: pastes over ~${pretty} characters will be refused${c.reset}`);
+    console.log(
+      `  ${budget.windowLengths} distinct window lengths after this import. Detection slides one pass per`
+    );
+    console.log(
+      `  length, so past that size the extension ${c.bold}refuses to scan${c.reset} rather than hang —`
+    );
+    console.log(`  which is a hard block in sensitive contexts. A paste at the ceiling takes up to ~8s.`);
+    legacyNote("");
+    console.log(`${c.dim}  Register the high-value secrets only, or split them across workspaces.${c.reset}`);
+    return;
+  }
+
+  if (budget.ceiling < PASTE_CEILING_WARN_CHARS) {
+    console.log("");
+    console.log(
+      `${c.yellow}Scan budget:${c.reset} ${budget.windowLengths} window lengths after this import; ` +
+        `pastes above ~${pretty} chars are refused.`
+    );
+    legacyNote("");
+    return;
+  }
+
+  console.log(
+    budget.atCharacterCap
+      ? `${c.dim}  Scan budget: every paste up to the extension's ${pretty}-char hard limit is scanned.${c.reset}`
+      : `${c.dim}  Scan budget: ${budget.windowLengths} window lengths, pastes up to ~${pretty} chars.${c.reset}`
+  );
+  legacyNote(c.dim);
+}
+
+function tally(rows) {
+  const counts = { create: 0, rotate: 0, skip: 0, conflict: 0, rejected: 0 };
+  for (const r of rows) counts[r.action] = (counts[r.action] ?? 0) + 1;
+  return counts;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Confirmation
+   ═══════════════════════════════════════════════════════════════ */
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) {
+    throw new UsageError("--apply needs a terminal to confirm on, or --yes to skip the prompt.");
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise((resolve) => rl.question(`${question} `, resolve));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptHidden(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  return new Promise((resolve) => {
+    const onData = (chunk) => {
+      // Repaint the prompt without the typed characters. readline has already
+      // echoed them, so this erases the line rather than trying to prevent it.
+      const s = String(chunk);
+      if (!s.includes("\n") && !s.includes("\r")) {
+        readline.clearLine(process.stdout, 0);
+        readline.cursorTo(process.stdout, 0);
+        process.stdout.write(question + " ");
+      }
+    };
+    process.stdin.on("data", onData);
+    rl.question(`${question} `, (answer) => {
+      process.stdin.off("data", onData);
+      rl.close();
+      process.stdout.write("\n");
+      resolve(answer);
+    });
+  });
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Apply
+   ═══════════════════════════════════════════════════════════════ */
+
+/**
+ * The exact field set the secrets API accepts, built through the shared
+ * enrollPayload() so this cannot drift into sending only the exact digest and
+ * quietly losing the whitespace and case-fold coverage.
+ *
+ * Named fields rather than a spread of the compute result, which also carries
+ * `canonical` — the plaintext. It would be dropped by enrollPayload anyway, but
+ * a tool that promises values stay local should not pass them into a request
+ * builder at all.
+ */
+function digestBody(label, d) {
+  return enrollPayload({
+    label,
+    hmacHex: d.digest,
+    length: d.length,
+    hmacHexStripped: d.hmacHexStripped,
+    lengthStripped: d.lengthStripped,
+    hmacHexLower: d.hmacHexLower,
+    lengthLower: d.lengthLower,
+    scanPrefilter: d.scanPrefilter,
+  });
+}
+
+async function applyPlan({ rows, byKey, serverUrl, token, source, projectId = null }) {
+  const results = [];
+  const tag = sourceTag(source);
+  let sendPrefilter = true;
+
+  for (const row of rows) {
+    if (row.action !== "create" && row.action !== "rotate") continue;
+    const cand = byKey.get(row.key);
+
+    const send = (withPrefilter) => {
+      const { scanPrefilter, ...rest } = cand.digests;
+      const payload = digestBody(row.key, withPrefilter ? { ...rest, scanPrefilter } : rest);
+      // The digest replacement body is strict and has no `label` — replacing a
+      // fingerprint is deliberately not a rename — so the label is dropped here
+      // rather than sent and rejected as an unrecognised key.
+      const { label: _label, ...digestsOnly } = payload;
+      // The server refuses a digest filed under a project it was not hashed for,
+      // so the project travels with every write.
+      const scope = projectId ? { projectId } : {};
+      return row.action === "create"
+        ? apiRequest(serverUrl, token, "POST", "/api/secrets", { ...payload, ...scope, tags: [tag] })
+        : apiRequest(serverUrl, token, "PUT", `/api/secrets/${row.id}/digest`, { ...digestsOnly, ...scope });
+    };
+
+    let r = await send(sendPrefilter);
+    if (sendPrefilter && cand.digests.scanPrefilter && refusesOnlyScanPrefilter(r)) {
+      // Only reachable on an empty vault, where the plan could not tell the
+      // server's age from its rows. Nothing was written by the refused request.
+      sendPrefilter = false;
+      printOlderServerNotice();
+      r = await send(false);
+    }
+
+    if (r.ok) {
+      results.push({ key: row.key, action: row.action, ok: true });
+      console.log(`  ${c.green}✓${c.reset} ${row.action === "create" ? "created" : "rotated"} ${row.key}`);
+      continue;
+    }
+
+    const reason = explainWriteFailure(r);
+    results.push({ key: row.key, action: row.action, ok: false, status: r.status, reason });
+    console.log(`  ${c.red}✗${c.reset} ${row.key}: ${reason}`);
+  }
+
+  return results;
+}
+
+function printOlderServerNotice() {
+  console.log(
+    `${c.yellow}!${c.reset} This server does not store scan prefilters yet, so secrets are registered without one.`
+  );
+  console.log(
+    `${c.dim}  They are protected exactly the same, but every paste checks them the slow way. Re-run this${c.reset}`
+  );
+  console.log(`${c.dim}  import once the server is updated; it adds the prefilter to each of them.${c.reset}`);
+}
+
+function explainWriteFailure(r) {
+  if (r.status === 409) {
+    return "another secret in this workspace already has this fingerprint";
+  }
+  if (r.status === 403) return "token is not OWNER or ADMIN";
+  if (r.status === 401) return "token expired or invalid";
+  if (r.status === 404) return "secret no longer exists — re-run to re-plan";
+  const msg = r.data && typeof r.data.error === "string" ? r.data.error : r.text.slice(0, 160);
+  return `${r.status} ${msg}`;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Help
+   ═══════════════════════════════════════════════════════════════ */
+function printHelp() {
+  console.log(`
+${c.bold}redaktyn-import${c.reset} — register fingerprints in bulk from files or any vault CLI
+
+${c.bold}Digests are computed on this machine.${c.reset} Values are never sent, never
+printed, and never written to the report.
+
+${c.bold}Input (choose one)${c.reset}
+  --env <file>        dotenv file (export prefix, quotes, comments, multi-line)
+  --json <file>       JSON object of secrets
+  --yaml <file>       flat "key: value" YAML only; refuses anything nested
+  --stdin             JSON piped in — this is how vault CLIs are consumed
+
+${c.bold}Vault recipes${c.reset}
+  vault kv get -format=json secret/prod         | redaktyn-import --stdin
+  doppler secrets download --no-file --format json | redaktyn-import --stdin
+  op item get prod --format json                 | redaktyn-import --stdin
+  aws secretsmanager get-secret-value --secret-id prod \\
+      --query SecretString --output text         | redaktyn-import --stdin
+
+${c.bold}Options${c.reset}
+  --source <name>     Provenance tag, stored as import:<name>
+                      (default: input file name, or "stdin")
+  --apply             Actually register. Without it this is a dry run.
+  --yes               Skip the confirmation prompt (for CI)
+  --min-length <n>    Minimum value length to accept (default ${DEFAULT_MIN_LENGTH})
+  --allow-weak        Register values the junk filter rejected
+  --only <key|glob>   Only these keys (repeatable)
+  --exclude <key|glob> Skip these keys (repeatable)
+  --server <url>      Override REDAKTYN_SERVER_URL
+  --org-id <uuid>     Override org id (must match the token)
+  --project <name|id> Enrol into this project (hashed under the project's key and
+                      compared only with that project's secrets). Default: the
+                      organisation's default project.
+  --report-json       Machine-readable plan on stdout, no table
+  --no-color          Disable ANSI colors
+
+${c.bold}Environment${c.reset}
+  REDAKTYN_SERVER_URL   API base URL
+  REDAKTYN_PASSPHRASE   org passphrase (local HMAC only, never sent)
+  REDAKTYN_TOKEN        OWNER/ADMIN JWT — an extension token cannot register
+  REDAKTYN_ORG_ID       optional; must agree with the token
+
+${c.bold}Exit codes${c.reset}
+  0  plan printed, or every write succeeded
+  1  one or more writes failed
+  2  usage, auth or parse error
+`);
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Main
+   ═══════════════════════════════════════════════════════════════ */
+
+async function loadInput(args) {
+  const modes = [
+    args.env && "env",
+    args.jsonFile && "json",
+    args.yaml && "yaml",
+    args.stdin && "stdin",
+  ].filter(Boolean);
+
+  if (modes.length === 0) {
+    throw new UsageError("Nothing to import. Pass one of --env, --json, --yaml or --stdin (see --help).");
+  }
+  if (modes.length > 1) {
+    throw new UsageError(`Pick one input mode, got: ${modes.map((m) => "--" + m).join(", ")}`);
+  }
+
+  const mode = modes[0];
+  if (mode === "env") {
+    const parsed = parseDotenv(readFileOrDie(args.env, "--env"));
+    return { ...parsed, mode, defaultSource: basename(args.env) };
+  }
+  if (mode === "json") {
+    const parsed = parseJsonSecrets(readFileOrDie(args.jsonFile, "--json"));
+    return { ...parsed, mode, defaultSource: basename(args.jsonFile) };
+  }
+  if (mode === "yaml") {
+    const parsed = parseFlatYaml(readFileOrDie(args.yaml, "--yaml"));
+    return { ...parsed, mode, defaultSource: basename(args.yaml) };
+  }
+  const text = await readStdin();
+  if (text.trim() === "") throw new UsageError("Nothing arrived on stdin.");
+  const parsed = parseJsonSecrets(text);
+  return { ...parsed, mode, defaultSource: "stdin" };
+}
+
+async function resolveCredentials(args) {
+  const serverUrl = args.server || process.env["REDAKTYN_SERVER_URL"] || process.env["REDAKTYN_SERVER"];
+  const token = process.env["REDAKTYN_TOKEN"] || process.env["REDAKTYN_JWT"];
+
+  if (!serverUrl) throw new UsageError("Set REDAKTYN_SERVER_URL (or pass --server).");
+  if (!token) {
+    // Named explicitly: REDAKTYN_DEVICE_TOKEN is deliberately not accepted, so
+    // a shell set up for redaktyn-scan does not silently supply a token that
+    // cannot write.
+    throw new UsageError("Set REDAKTYN_TOKEN to an OWNER or ADMIN login token.");
+  }
+
+  const payload = decodeJwtPayload(token);
+  const roleProblem = tokenRoleProblem(payload);
+  if (roleProblem) throw new UsageError(roleProblem);
+
+  const orgId = args.orgId || payload?.orgId || payload?.org_id || process.env["REDAKTYN_ORG_ID"];
+  if (!orgId) {
+    throw new UsageError("Could not determine the org id from the token. Pass --org-id.");
+  }
+  const envOrgId = args.orgId || process.env["REDAKTYN_ORG_ID"];
+  if (envOrgId && payload?.orgId && envOrgId !== payload.orgId) {
+    throw new UsageError("The org id given does not match the token's org id.");
+  }
+
+  let passphrase = process.env["REDAKTYN_PASSPHRASE"];
+  if (!passphrase) {
+    if (!process.stdin.isTTY) {
+      throw new UsageError(
+        "Set REDAKTYN_PASSPHRASE. It is used locally to derive the HMAC key and is never sent."
+      );
+    }
+    passphrase = await promptHidden("Org passphrase:");
+  }
+  if (!passphrase) throw new UsageError("No passphrase given.");
+
+  return { serverUrl, token, orgId, passphrase };
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+
+  const input = await loadInput(args);
+  const source = normalizeSource(args.source ?? input.defaultSource);
+
+  // Last-wins on duplicate keys, matching how a shell sources a dotenv file.
+  const deduped = new Map();
+  for (const e of input.entries) deduped.set(e.key, e);
+  const duplicates = input.entries.length - deduped.size;
+
+  let selected = [...deduped.values()];
+  if (args.only.length > 0) selected = selected.filter((e) => matchesAny(e.key, args.only));
+  if (args.exclude.length > 0) selected = selected.filter((e) => !matchesAny(e.key, args.exclude));
+
+  if (selected.length === 0) {
+    throw new UsageError(
+      `No usable keys found in the input (${input.mode}). ` +
+        (input.problems?.length ? `${input.problems.length} line(s) were skipped — see above.` : "")
+    );
+  }
+
+  const { serverUrl, token, orgId, passphrase } = await resolveCredentials(args);
+
+  const minLength = args.minLength ?? DEFAULT_MIN_LENGTH;
+  const orgKey = await deriveKey(passphrase, orgId);
+  const project = args.project ? await resolveProject(serverUrl, token, args.project) : null;
+  // A project with its own key hashes under HKDF(orgKey, projectId); the default
+  // project carries the org key itself. Filing a digest under the wrong one lists
+  // as ACTIVE and matches nothing, which is why the server also checks.
+  const key = project && !project.usesOrgKey ? deriveProjectKey(orgKey, project.id) : orgKey;
+
+  const candidates = [];
+  const rejected = [];
+  for (const entry of selected) {
+    if (entry.key.length > 200) {
+      // The server caps labels at 200 chars, so this would be a 400 during
+      // apply, after the operator had already approved the plan.
+      rejected.push({ key: entry.key, action: "rejected", reason: "key longer than 200 characters" });
+      continue;
+    }
+    const canonical = canonicalize(entry.value);
+    const verdict = junkVerdict(canonical, { minLength });
+    if (!verdict.ok && !args.allowWeak) {
+      rejected.push({ key: entry.key, action: "rejected", reason: verdict.reason, length: canonical.length });
+      continue;
+    }
+    const digests = computeHmac(entry.value, key);
+    candidates.push({
+      key: entry.key,
+      digests,
+      weak: !verdict.ok,
+      weakReason: verdict.reason,
+    });
+  }
+
+  let existing = await fetchExistingSecrets(serverUrl, token);
+  // Compared only with the chosen project's own secrets: the same label in
+  // another project is a different secret under a different key.
+  if (project) existing = existing.filter((s) => s && s.projectId === project.id);
+  // Against a server deployed before the scan prefilter, sending it would 400
+  // every write, and comparing it would re-plan every row as a rotation on
+  // every run. Planned as that server will store it: without.
+  const prefilterSupported = serverStoresScanPrefilter(existing);
+  if (!prefilterSupported) {
+    for (const cand of candidates) delete cand.digests.scanPrefilter;
+  }
+  const { plan, missing } = diffAgainstServer({ candidates, existing, source });
+
+  const byKey = new Map(candidates.map((cd) => [cd.key, cd]));
+  for (const row of plan) {
+    const cand = byKey.get(row.key);
+    if (cand?.weak && (row.action === "create" || row.action === "rotate")) {
+      row.reason = `${row.reason} (weak: ${cand.weakReason}, allowed by --allow-weak)`;
+    }
+  }
+
+  const rows = [...plan, ...rejected].sort(
+    (a, b) => actionRank(a.action) - actionRank(b.action) || a.key.localeCompare(b.key)
+  );
+
+  // Projected budget counts what the org would look like after the writes, since
+  // that is the number that decides whether pastes still get scanned.
+  const projected = projectAfterImport({ existing, plan, byKey });
+  const budget = scanBudgetForSecrets(projected);
+
+  const writes = plan.filter((r) => r.action === "create" || r.action === "rotate");
+
+  if (args.reportJson) {
+    console.log(
+      JSON.stringify(
+        {
+          source,
+          sourceTag: sourceTag(source),
+          mode: input.mode,
+          shape: input.shape ?? null,
+          dryRun: !args.apply,
+          minLength,
+          allowWeak: args.allowWeak,
+          duplicateKeys: duplicates,
+          inputProblems: input.problems ?? [],
+          counts: tally(rows),
+          plan: rows.map((r) => ({
+            key: r.key,
+            action: r.action,
+            reason: r.reason ?? null,
+            length: r.length ?? null,
+          })),
+          missing,
+          scanBudget: {
+            windowLengths: budget.windowLengths,
+            maxPasteChars: budget.ceiling === Infinity ? null : budget.ceiling,
+            warn: budget.ceiling < PASTE_CEILING_WARN_CHARS,
+            atCharacterCap: budget.atCharacterCap,
+            legacySecrets: budget.legacySecrets,
+            maxPasteCharsIfReenrolled:
+              budget.ceilingIfReenrolled === Infinity ? null : budget.ceilingIfReenrolled,
+            serverStoresScanPrefilter: prefilterSupported,
+          },
+        },
+        null,
+        2
+      )
+    );
+    if (!args.apply) return 0;
+  } else {
+    for (const p of input.problems ?? []) {
+      const where = p.line !== undefined ? `line ${p.line}` : p.key;
+      console.log(`${c.yellow}!${c.reset} ${where}: ${p.message}`);
+    }
+    if (duplicates > 0) {
+      console.log(`${c.dim}${duplicates} duplicate key(s) in the input; the last value of each was used.${c.reset}`);
+    }
+    if (!prefilterSupported) printOlderServerNotice();
+    printPlan({ rows, missing, source, dryRun: !args.apply, budget, projectName: project ? project.name : null });
+  }
+
+  if (!args.apply) return 0;
+
+  if (writes.length === 0) {
+    console.log(`${c.dim}Nothing to write.${c.reset}`);
+    return 0;
+  }
+
+  if (!args.yes) {
+    const counts = tally(plan);
+    const ok = await confirm(
+      `Register ${counts.create} new and rotate ${counts.rotate} existing fingerprint(s) for this org? [y/N]`
+    );
+    if (!ok) {
+      console.log("Aborted.");
+      return 0;
+    }
+  }
+
+  console.log("");
+  const results = await applyPlan({ rows: writes, byKey, serverUrl, token, source, projectId: project ? project.id : null });
+  const failed = results.filter((r) => !r.ok);
+
+  console.log("");
+  console.log(
+    failed.length === 0
+      ? `${c.green}${results.length} fingerprint(s) registered.${c.reset}`
+      : `${c.red}${failed.length} of ${results.length} failed.${c.reset}`
+  );
+  printBudget(budget);
+  console.log("");
+
+  return failed.length === 0 ? 0 : 1;
+}
+
+const ACTION_ORDER = ["create", "rotate", "conflict", "skip", "rejected"];
+const actionRank = (a) => {
+  const i = ACTION_ORDER.indexOf(a);
+  return i === -1 ? ACTION_ORDER.length : i;
+};
+
+/**
+ * The secret list as it would be after the plan is applied, for the budget
+ * projection. Rotations replace lengths rather than adding them, which matters:
+ * re-importing the same file must not look like it doubles the scan cost.
+ */
+function projectAfterImport({ existing, plan, byKey }) {
+  const out = existing.map((s) => ({ ...s }));
+  const byId = new Map(out.map((s) => [s.id, s]));
+
+  for (const row of plan) {
+    const cand = byKey.get(row.key);
+    if (!cand) continue;
+    const d = cand.digests;
+    if (row.action === "create") {
+      out.push({
+        id: `pending:${row.key}`,
+        label: row.key,
+        hmacHex: d.digest,
+        length: d.length,
+        hmacHexStripped: d.hmacHexStripped,
+        lengthStripped: d.lengthStripped,
+        hmacHexLower: d.hmacHexLower,
+        lengthLower: d.lengthLower,
+        scanPrefilter: d.scanPrefilter,
+        tags: [],
+      });
+      continue;
+    }
+    if (row.action === "rotate") {
+      const target = byId.get(row.id);
+      if (!target) continue;
+      target.hmacHex = d.digest;
+      target.length = d.length;
+      target.hmacHexStripped = d.hmacHexStripped;
+      target.lengthStripped = d.lengthStripped;
+      target.hmacHexLower = d.hmacHexLower;
+      target.lengthLower = d.lengthLower;
+      target.scanPrefilter = d.scanPrefilter;
+    }
+  }
+  return out;
+}
+
+const invokedDirectly =
+  !!process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      if (err instanceof UsageError) {
+        console.error(`${c.red}${err.message}${c.reset}`);
+        process.exit(2);
+      }
+      console.error(`${c.red}Fatal: ${err instanceof Error ? err.message : err}${c.reset}`);
+      process.exit(1);
+    });
+}