feat(ledger): provision the anchor key without ever displaying it

Refs #9940.

The keygen printed the private key to stdout, so provisioning meant a human
copying a signing key out of a terminal -- where it lands in scrollback, in shell
history if piped, and in whatever captured the session. One of ours had to be
discarded for exactly that reason.

`--secret-file <path>` writes the private half directly at 0600 and prints only
the public half, which is meant to be published. Nothing to copy, nothing to
leak. Point LOOPOVER_LEDGER_ANCHOR_PRIVATE_KEY_FILE at the path -- the generic
<NAME>_FILE mechanism every self-host secret already supports -- and recreate the
container.

Refuses to overwrite an existing file: replacing a live signing key strands every
anchor published under it, which is the same reason a retired key is closed
rather than removed.

The printing mode stays for reading the shape before provisioning.

Author: JSONbored

apps/loopover-ui/content/docs/self-hosting-configuration.mdx

@@ -534,12 +534,22 @@ healthy idle instance.
 ### 1. Generate the keypair
 
 ```bash
-npm run ledger:anchor-keygen
+npm run ledger:anchor-keygen -- --secret-file /run/secrets/ledger-anchor-private-key
 ```
 
-Prints both halves already in the encodings the runtime expects, with the key id derived from the public
-half so the two cannot drift apart. It writes nothing to disk — the private key exists only in that output,
-so run it on a machine you trust and paste straight into your secret store.
+Writes the private half straight to that path at `0600` and **never prints it** — so there is nothing to
+copy and nothing to leave in scrollback, shell history, or a captured session. Only the public half is
+printed, which is what you publish anyway. Then point `LOOPOVER_LEDGER_ANCHOR_PRIVATE_KEY_FILE` at that
+path (the generic `<NAME>_FILE` mechanism every self-host secret supports) and recreate the container.
+
+It refuses to overwrite an existing file: replacing a live signing key would strand every anchor already
+published under it, and the rotation rule below exists precisely so those stay verifiable.
+
+Dropping `--secret-file` prints both halves instead, for reading the shape before you provision. Prefer the
+file mode for anything real — a private key on a terminal is a private key you now have to be careful with.
+
+Either way the key id is derived from the public half with the same function the runtime uses, so the
+published key and the anchors referencing it cannot drift apart.
 
 ### 2. Provision both halves
 

scripts/gen-ledger-anchor-keypair.ts

@@ -11,11 +11,16 @@
 // This prints both values ready to paste, deriving the keyId with the SAME function the runtime uses, so
 // the published key and the anchors that reference it cannot disagree.
 //
-//   npm run ledger:anchor-keygen
+//   npm run ledger:anchor-keygen                              # prints both halves, to copy by hand
+//   npm run ledger:anchor-keygen -- --secret-file <path>       # writes the private half, prints only the public
 //
-// PRINTS a private key to stdout. It is never written to disk, never committed, and the output is meant to
-// go straight into your secret store (`wrangler secret put`, a compose env file, a vault entry). Run it on a
-// machine you trust, and do not paste the private half into a shell history you keep.
+// PREFER `--secret-file` for real provisioning (#9940). The default mode prints a private key to stdout,
+// which then lives in terminal scrollback, in whatever captured the session, and in shell history if piped
+// -- one of ours had to be discarded for exactly that reason. With `--secret-file` the key goes straight to
+// disk at 0600 and is never displayed, so there is nothing for a human to copy and nothing to leak. Only the
+// PUBLIC half is printed, which is meant to be published.
+import { writeFileSync } from "node:fs";
+
 import { computeAnchorKeyId } from "../src/review/ledger-anchor";
 
 function toPem(base64: string, label: string): string {
@@ -61,9 +66,56 @@ export async function generateAnchorKeypair(now: string = new Date().toISOString
   };
 }
 
+/**
+ * Write the private half straight to a file, 0600, and print NOTHING of it (#9940).
+ *
+ * The default mode prints both halves for a human to copy. That is fine for a first read of the runbook and
+ * wrong for actually provisioning: the key lands in terminal scrollback, in shell history if piped, and in
+ * whatever captured the session -- one of ours had to be discarded for exactly that reason. With
+ * `--secret-file` the operator never sees the key, so there is nothing to leak by copying it, and the only
+ * thing on stdout is the PUBLIC half, which is meant to be published.
+ *
+ * Bare value, no trailing newline, no comment header: the ORB reads this file verbatim, so anything else in
+ * it becomes part of the key.
+ */
+function writePrivateKeyFile(path: string, privateKeyPem: string): void {
+  // wx: refuse to clobber. Overwriting a live signing key silently would invalidate every anchor already
+  // published under it, and the rotation rule (never remove a retired key, only close it) exists precisely
+  // because those anchors must stay verifiable forever.
+  writeFileSync(path, privateKeyPem.trim(), { encoding: "utf8", mode: 0o600, flag: "wx" });
+}
+
 async function main(): Promise<void> {
+  const secretFileFlag = process.argv.indexOf("--secret-file");
+  const secretFile: string | undefined = secretFileFlag === -1 ? undefined : process.argv[secretFileFlag + 1];
+  if (secretFileFlag !== -1 && (secretFile === undefined || secretFile.startsWith("--"))) {
+    console.error("--secret-file requires a path, e.g. --secret-file /run/secrets/ledger-anchor-private-key");
+    process.exit(2);
+  }
+
   const { keyId, publishedKeys, privateKeyPem } = await generateAnchorKeypair();
 
+  if (secretFile) {
+    try {
+      writePrivateKeyFile(secretFile, privateKeyPem);
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      console.error(
+        code === "EEXIST"
+          ? `${secretFile} already exists. Refusing to overwrite a signing key: every anchor published under it must stay verifiable. Move it aside deliberately, then re-run.`
+          : `Could not write ${secretFile}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      process.exit(1);
+    }
+    console.log("# ── LOOPOVER_LEDGER_ANCHOR_KEYS (public, safe to publish and to commit) ──");
+    console.log(`LOOPOVER_LEDGER_ANCHOR_KEYS='${publishedKeys}'`);
+    console.log("");
+    console.log(`# Private key written to ${secretFile} (0600). It was NOT printed -- nothing to copy, nothing to leak.`);
+    console.log(`# keyId ${keyId}. Point LOOPOVER_LEDGER_ANCHOR_PRIVATE_KEY_FILE at that path, then recreate the container.`);
+    return;
+  }
+
+
   console.log("# ── LOOPOVER_LEDGER_ANCHOR_KEYS (public, safe to publish and to commit) ──");
   console.log("# Serve this verbatim; it is what /v1/public/decision-ledger/anchor-key returns.");
   console.log(`LOOPOVER_LEDGER_ANCHOR_KEYS='${publishedKeys}'`);