talon-agent 5.14.0 → 5.18.2

package/src/core/agent-runtime/backend-registry.ts

@@ -76,6 +76,14 @@ export interface BackendFactory {
   id: string;
   /** Display label used in `/status` and agent logs (e.g. "Kilo"). */
   label: string;
+  /**
+   * Can this backend run a guest-scoped turn (a non-operator sender) with
+   * nothing but the hub's conversation-only tools? `"enforced"` means its
+   * own built-ins (shell, file tools) are dropped for guest turns;
+   * `"refused"` means they can't be, so the weaver refuses guest turns on
+   * it. Absent is treated as `"refused"` — fail closed.
+   */
+  guestToolScope?: "enforced" | "refused";
   /** Initialise the backend; called exactly once per Talon process. */
   init(config: TalonConfig, ctx: BackendInitContext): Promise<BackendInstance>;
   /**
@@ -136,6 +144,14 @@ export function clearBackends(): void {
   backends.clear();
 }
 
+/**
+ * Whether guest-scoped turns may run on this backend. Unknown ids and
+ * factories that don't declare `guestToolScope` fail closed.
+ */
+export function backendEnforcesGuestScope(id: string): boolean {
+  return backends.get(id)?.guestToolScope === "enforced";
+}
+
 /** Whether a backend with this id is currently registered. */
 export function hasBackend(id: string): boolean {
   return backends.has(id);

package/src/core/backup/archive/crypt.ts

@@ -0,0 +1,429 @@
+/**
+ * Encryption at rest — the form a part takes before it may leave the box.
+ *
+ * A part holds config.json (bot tokens, API keys), the secrets folder and
+ * private memory, so a remote copy must be unreadable without the
+ * operator's passphrase. Node's built-in crypto only:
+ *
+ *   - Key: scrypt(passphrase, salt) → 32 bytes. N = 2^17, r = 8, p = 1
+ *     (~128 MiB and a fraction of a second per part), a fresh random
+ *     16-byte salt per part. The parameters live in the header, so they
+ *     can be raised later without breaking old parts.
+ *   - Cipher: AES-256-GCM over fixed-size chunks (1 MiB by default).
+ *     A single GCM stream would only authenticate at the very end, after
+ *     every plaintext byte had already been handed to the tar extractor;
+ *     chunking means nothing is released until its own tag has verified.
+ *
+ * Layout (all integers big-endian):
+ *
+ *   header  "TALONENC1" | kdf=1 (u8) | log2 N (u8) | r (u8) | p (u8)
+ *           | chunk size (u32) | salt (16) | base IV (12)          45 bytes
+ *   record  flag (u8, 1 = final) | length (u32) | ciphertext | tag (16)
+ *
+ * Record i is sealed with nonce = base IV XOR i (in the low 64 bits) and
+ * with additional data = the whole header | i (u64) | flag. So the header
+ * is authenticated by every record, records cannot be reordered or
+ * replayed, and the final flag makes truncation at a record boundary
+ * detectable. The last record is always present (possibly empty) and
+ * nothing may follow it.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  scrypt,
+} from "node:crypto";
+import { createReadStream } from "node:fs";
+import { open } from "node:fs/promises";
+import { pipeline, Transform, type TransformCallback } from "node:stream";
+import type { Readable } from "node:stream";
+import { TalonError } from "../../errors.js";
+
+/** File signature; the trailing 1 is the format version. */
+export const ENCRYPTION_MAGIC = Buffer.from("TALONENC1", "ascii");
+/** Suffix appended to the name of an encrypted part. */
+export const ENCRYPTED_SUFFIX = ".enc";
+
+const KDF_SCRYPT = 1;
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const RECORD_HEAD = 5;
+const FLAG_FINAL = 1;
+const DEFAULT_LOG2N = 17;
+const DEFAULT_CHUNK = 1024 * 1024;
+const MAX_CHUNK = 16 * 1024 * 1024;
+
+/** Total header length in bytes. */
+export const HEADER_BYTES =
+  ENCRYPTION_MAGIC.length + 4 + 4 + SALT_BYTES + IV_BYTES;
+
+export type EncryptionHeader = {
+  log2N: number;
+  r: number;
+  p: number;
+  chunkSize: number;
+  salt: Buffer;
+  iv: Buffer;
+};
+
+/** Knobs for tests; production always uses the defaults. */
+export type EncryptOptions = { log2N?: number; chunkSize?: number };
+
+function formatError(detail: string): TalonError {
+  return new TalonError(`Encrypted backup: ${detail}`, {
+    reason: "bad_request",
+  });
+}
+
+function authError(): TalonError {
+  return formatError(
+    "authentication failed — wrong passphrase, or the file was modified",
+  );
+}
+
+export function encodeHeader(header: EncryptionHeader): Buffer {
+  const buf = Buffer.alloc(HEADER_BYTES);
+  let at = ENCRYPTION_MAGIC.copy(buf, 0);
+  buf[at++] = KDF_SCRYPT;
+  buf[at++] = header.log2N;
+  buf[at++] = header.r;
+  buf[at++] = header.p;
+  at = buf.writeUInt32BE(header.chunkSize, at);
+  at += header.salt.copy(buf, at);
+  header.iv.copy(buf, at);
+  return buf;
+}
+
+function hasEncryptionMagic(buf: Uint8Array): boolean {
+  return (
+    buf.length >= ENCRYPTION_MAGIC.length &&
+    Buffer.from(buf.subarray(0, ENCRYPTION_MAGIC.length)).equals(
+      ENCRYPTION_MAGIC,
+    )
+  );
+}
+
+/** Parse and bound-check a header. Throws on anything unexpected. */
+export function parseHeader(buf: Buffer): EncryptionHeader {
+  if (buf.length < HEADER_BYTES || !hasEncryptionMagic(buf)) {
+    throw formatError("not an encrypted Talon backup (bad header)");
+  }
+  let at = ENCRYPTION_MAGIC.length;
+  const kdf = buf[at++];
+  const [log2N, r, p] = [buf[at++], buf[at++], buf[at++]];
+  const chunkSize = buf.readUInt32BE(at);
+  at += 4;
+  if (kdf !== KDF_SCRYPT) throw formatError(`unknown key derivation ${kdf}`);
+  if (!scryptParamsInRange({ log2N, r, p })) {
+    throw formatError("scrypt parameters out of range");
+  }
+  if (chunkSize < 1 || chunkSize > MAX_CHUNK) {
+    throw formatError("chunk size out of range");
+  }
+  const salt = Buffer.from(buf.subarray(at, at + SALT_BYTES));
+  const iv = Buffer.from(
+    buf.subarray(at + SALT_BYTES, at + SALT_BYTES + IV_BYTES),
+  );
+  return { log2N, r, p, chunkSize, salt, iv };
+}
+
+/** scrypt cost parameters, as recorded next to whatever they protect. */
+export type ScryptParams = { log2N: number; r: number; p: number };
+
+/** The scrypt parameters every new part and manifest is written with. */
+export const DEFAULT_SCRYPT: ScryptParams = {
+  log2N: DEFAULT_LOG2N,
+  r: 8,
+  p: 1,
+};
+
+/** True when stored parameters are inside the range this build accepts. */
+export function scryptParamsInRange({ log2N, r, p }: ScryptParams): boolean {
+  return log2N >= 10 && log2N <= 20 && r >= 1 && r <= 32 && p >= 1 && p <= 16;
+}
+
+/** scrypt → 32-byte key, with enough maxmem for the given parameters. */
+export function deriveScryptKey(
+  passphrase: string,
+  salt: Buffer,
+  params: ScryptParams,
+): Promise<Buffer> {
+  const N = 2 ** params.log2N;
+  const maxmem = 2 * 128 * N * params.r * params.p + 1024 * 1024;
+  return new Promise((resolve, reject) => {
+    scrypt(
+      passphrase,
+      salt,
+      KEY_BYTES,
+      { N, r: params.r, p: params.p, maxmem },
+      (err, key) => (err ? reject(err) : resolve(key)),
+    );
+  });
+}
+
+function deriveKey(
+  passphrase: string,
+  header: EncryptionHeader,
+): Promise<Buffer> {
+  return deriveScryptKey(passphrase, header.salt, header);
+}
+
+function nonceFor(iv: Buffer, counter: number): Buffer {
+  const nonce = Buffer.from(iv);
+  nonce.writeBigUInt64BE(nonce.readBigUInt64BE(4) ^ BigInt(counter), 4);
+  return nonce;
+}
+
+function aadFor(header: Buffer, counter: number, flag: number): Buffer {
+  const tail = Buffer.alloc(9);
+  tail.writeBigUInt64BE(BigInt(counter), 0);
+  tail[8] = flag;
+  return Buffer.concat([header, tail]);
+}
+
+/** A FIFO of buffers that concatenates only when a caller takes bytes. */
+class ByteQueue {
+  private parts: Buffer[] = [];
+  length = 0;
+
+  push(chunk: Buffer): void {
+    if (chunk.length === 0) return;
+    this.parts.push(chunk);
+    this.length += chunk.length;
+  }
+
+  peek(n: number): Buffer {
+    const first = this.parts[0];
+    if (first && first.length >= n) return first.subarray(0, n);
+    return this.flatten().subarray(0, n);
+  }
+
+  take(n: number): Buffer {
+    const all = this.flatten();
+    const rest = all.subarray(n);
+    this.parts = rest.length > 0 ? [rest] : [];
+    this.length = rest.length;
+    return all.subarray(0, n);
+  }
+
+  private flatten(): Buffer {
+    if (this.parts.length !== 1) {
+      this.parts = [Buffer.concat(this.parts, this.length)];
+    }
+    return this.parts[0];
+  }
+}
+
+/** Plaintext in, header + sealed records out. */
+class EncryptStream extends Transform {
+  private readonly queue = new ByteQueue();
+  private readonly headerBytes: Buffer;
+  private counter = 0;
+  private started = false;
+
+  constructor(
+    private readonly key: Buffer,
+    private readonly header: EncryptionHeader,
+  ) {
+    super();
+    this.headerBytes = encodeHeader(header);
+  }
+
+  override _transform(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    done: TransformCallback,
+  ): void {
+    this.start();
+    this.queue.push(chunk);
+    // Strictly greater: at least one byte stays behind for the final record.
+    while (this.queue.length > this.header.chunkSize) {
+      this.seal(this.queue.take(this.header.chunkSize), 0);
+    }
+    done();
+  }
+
+  override _flush(done: TransformCallback): void {
+    this.start();
+    this.seal(this.queue.take(this.queue.length), FLAG_FINAL);
+    done();
+  }
+
+  private start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.push(this.headerBytes);
+  }
+
+  private seal(plain: Buffer, flag: number): void {
+    const cipher = createCipheriv(
+      "aes-256-gcm",
+      this.key,
+      nonceFor(this.header.iv, this.counter),
+    );
+    cipher.setAAD(aadFor(this.headerBytes, this.counter, flag));
+    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const head = Buffer.alloc(RECORD_HEAD);
+    head[0] = flag;
+    head.writeUInt32BE(body.length, 1);
+    this.push(Buffer.concat([head, body, cipher.getAuthTag()]));
+    this.counter += 1;
+  }
+}
+
+/** Records in (header already consumed), verified plaintext out. */
+class DecryptStream extends Transform {
+  private readonly queue = new ByteQueue();
+  private readonly headerBytes: Buffer;
+  private counter = 0;
+  private finished = false;
+
+  constructor(
+    private readonly key: Buffer,
+    private readonly header: EncryptionHeader,
+  ) {
+    super();
+    this.headerBytes = encodeHeader(header);
+  }
+
+  override _transform(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    done: TransformCallback,
+  ): void {
+    this.queue.push(chunk);
+    try {
+      this.drain();
+      done();
+    } catch (err) {
+      done(err as Error);
+    }
+  }
+
+  override _flush(done: TransformCallback): void {
+    if (!this.finished || this.queue.length > 0) {
+      done(formatError("truncated or has trailing bytes"));
+      return;
+    }
+    done();
+  }
+
+  private drain(): void {
+    while (this.queue.length >= RECORD_HEAD) {
+      if (this.finished) throw formatError("data after the final record");
+      const head = this.queue.peek(RECORD_HEAD);
+      const flag = head[0];
+      const length = head.readUInt32BE(1);
+      if (flag > FLAG_FINAL || length > this.header.chunkSize) {
+        throw authError();
+      }
+      const total = RECORD_HEAD + length + TAG_BYTES;
+      if (this.queue.length < total) return;
+      const record = this.queue.take(total);
+      this.open(
+        record.subarray(RECORD_HEAD, RECORD_HEAD + length),
+        record.subarray(RECORD_HEAD + length),
+        flag,
+      );
+    }
+  }
+
+  private open(body: Buffer, tag: Buffer, flag: number): void {
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      this.key,
+      nonceFor(this.header.iv, this.counter),
+    );
+    decipher.setAAD(aadFor(this.headerBytes, this.counter, flag));
+    decipher.setAuthTag(tag);
+    let plain: Buffer;
+    try {
+      plain = Buffer.concat([decipher.update(body), decipher.final()]);
+    } catch {
+      throw authError();
+    }
+    this.counter += 1;
+    if (flag === FLAG_FINAL) this.finished = true;
+    if (plain.length > 0) this.push(plain);
+  }
+}
+
+/** An encrypting transform with a fresh salt, IV and derived key. */
+export async function createEncryptor(
+  passphrase: string,
+  options: EncryptOptions = {},
+): Promise<Transform> {
+  const header: EncryptionHeader = {
+    log2N: options.log2N ?? DEFAULT_LOG2N,
+    r: 8,
+    p: 1,
+    chunkSize: options.chunkSize ?? DEFAULT_CHUNK,
+    salt: randomBytes(SALT_BYTES),
+    iv: randomBytes(IV_BYTES),
+  };
+  return new EncryptStream(await deriveKey(passphrase, header), header);
+}
+
+/** The first bytes of a file — enough to recognise the format. */
+async function readPrefix(path: string, bytes: number): Promise<Buffer> {
+  const handle = await open(path, "r");
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await handle.read(buf, 0, bytes, 0);
+    return buf.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+/** True when the file starts with the encryption signature. */
+export async function isEncryptedFile(path: string): Promise<boolean> {
+  return hasEncryptionMagic(await readPrefix(path, ENCRYPTION_MAGIC.length));
+}
+
+/**
+ * Stream the verified plaintext of an encrypted file. Errors (wrong
+ * passphrase, tampering, truncation) surface on the returned stream.
+ */
+export async function openDecrypted(
+  path: string,
+  passphrase: string,
+): Promise<Readable> {
+  const header = parseHeader(await readPrefix(path, HEADER_BYTES));
+  const key = await deriveKey(passphrase, header);
+  return pipeline(
+    createReadStream(path, { start: HEADER_BYTES }),
+    new DecryptStream(key, header),
+    () => {
+      /* errors are delivered to whoever reads the returned stream */
+    },
+  );
+}
+
+/** Decrypt the whole file and discard it: throws unless every record verifies. */
+export async function verifyDecryptable(
+  path: string,
+  passphrase: string,
+): Promise<void> {
+  const stream = await openDecrypted(path, passphrase);
+  for await (const _chunk of stream) {
+    /* authentication is the point; the bytes are not needed */
+  }
+}
+
+/** Whether this passphrase opens the file's first record. */
+export async function passphraseOpens(
+  path: string,
+  passphrase: string,
+): Promise<boolean> {
+  try {
+    const stream = await openDecrypted(path, passphrase);
+    for await (const _chunk of stream) break;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/backup/archive/manifest-auth.ts

@@ -0,0 +1,98 @@
+/**
+ * Manifest authentication — proof that a manifest was written by someone
+ * holding the backup passphrase.
+ *
+ * Every encrypted part authenticates itself, but the manifest decides
+ * which parts a restore extracts, where the `extra/<n>` trees land and
+ * which digests count as "correct". It travels with the parts to every
+ * remote target, so whoever controls the remote controls the manifest:
+ * without a MAC they could drop the state part, re-point an extra path,
+ * or swap an encrypted part for a plaintext one of their own and fix the
+ * digest to match.
+ *
+ * The MAC is HMAC-SHA256 under a scrypt-derived key (fresh salt per
+ * manifest, parameters stored beside it) over a canonical JSON encoding
+ * of every field except the ones that legitimately change after the
+ * snapshot is written — `pinned` and the per-target `remote` map — and
+ * the `auth` block itself.
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type { Manifest, ManifestAuth } from "../types.js";
+import {
+  DEFAULT_SCRYPT,
+  deriveScryptKey,
+  scryptParamsInRange,
+  type ScryptParams,
+} from "./crypt.js";
+
+const SALT_BYTES = 16;
+/** Domain separation: this key signs manifests and nothing else. */
+const CONTEXT = "talon-backup-manifest-v1\0";
+
+/** JSON with object keys sorted at every depth and undefined dropped. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item ?? null)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** The bytes the MAC covers: everything that must not change after writing. */
+function signedBytes(manifest: Manifest): Buffer {
+  const {
+    remote: _remote,
+    pinned: _pinned,
+    auth: _auth,
+    ...covered
+  } = manifest;
+  return Buffer.from(CONTEXT + canonicalJson(covered), "utf8");
+}
+
+function mac(key: Buffer, manifest: Manifest): Buffer {
+  return createHmac("sha256", key).update(signedBytes(manifest)).digest();
+}
+
+/** A fresh `auth` block for this manifest under this passphrase. */
+export async function signManifest(
+  manifest: Manifest,
+  passphrase: string,
+  params: ScryptParams = DEFAULT_SCRYPT,
+): Promise<ManifestAuth> {
+  const salt = randomBytes(SALT_BYTES);
+  const key = await deriveScryptKey(passphrase, salt, params);
+  return {
+    v: 1,
+    alg: "hmac-sha256",
+    kdf: "scrypt",
+    ...params,
+    salt: salt.toString("base64"),
+    mac: mac(key, manifest).toString("base64"),
+  };
+}
+
+/**
+ * True only when the manifest carries a well-formed `auth` block whose MAC
+ * verifies under this passphrase. Any malformed field is a failure, never
+ * an exception — the caller decides what an unauthenticated manifest means.
+ */
+export async function verifyManifest(
+  manifest: Manifest,
+  passphrase: string,
+): Promise<boolean> {
+  const auth = manifest.auth;
+  if (!auth || auth.v !== 1 || auth.alg !== "hmac-sha256") return false;
+  if (auth.kdf !== "scrypt" || !scryptParamsInRange(auth)) return false;
+  const salt = Buffer.from(String(auth.salt), "base64");
+  const expected = Buffer.from(String(auth.mac), "base64");
+  if (salt.length !== SALT_BYTES || expected.length !== 32) return false;
+  const key = await deriveScryptKey(passphrase, salt, auth);
+  return timingSafeEqual(mac(key, manifest), expected);
+}

package/src/core/backup/passphrase.ts

@@ -0,0 +1,130 @@
+/**
+ * Where the backup passphrase comes from — and the rule that plaintext
+ * never leaves the machine.
+ *
+ * Two sources, first match wins:
+ *
+ *   1. `TALON_BACKUP_PASSPHRASE` in the environment.
+ *   2. `backup.encryption.passphraseFile` — a file holding the passphrase
+ *      (one line; surrounding whitespace ignored). `talon backup keygen`
+ *      writes one with mode 600.
+ *
+ * With neither, snapshots stay plaintext and local-only: `upload.ts`
+ * refuses to hand an unencrypted part to any remote target. When
+ * `backup.encryption` is present but yields no passphrase, a snapshot
+ * fails instead of silently falling back to plaintext.
+ *
+ * The passphrase file lives outside every snapshot root on purpose — a
+ * key stored inside the backup it unlocks is no key at all. Keep a copy
+ * somewhere off this machine (a password manager): without it, encrypted
+ * snapshots cannot be restored.
+ */
+
+import { randomBytes } from "node:crypto";
+import { readFile, stat, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { logWarn } from "../../util/log.js";
+import { TalonError } from "../errors.js";
+import { expandUserPath } from "./plan.js";
+import type { BackupSettings } from "./types.js";
+
+export const PASSPHRASE_ENV = "TALON_BACKUP_PASSPHRASE";
+/** Short enough to be a typo or an empty file, not a passphrase. */
+const MIN_PASSPHRASE_LENGTH = 12;
+
+function passphraseError(message: string): TalonError {
+  return new TalonError(message, { reason: "bad_request" });
+}
+
+function checked(passphrase: string, source: string): string {
+  if (passphrase.length < MIN_PASSPHRASE_LENGTH) {
+    throw passphraseError(
+      `Backup passphrase from ${source} is shorter than ${MIN_PASSPHRASE_LENGTH} characters`,
+    );
+  }
+  return passphrase;
+}
+
+async function readPassphraseFile(raw: string): Promise<string> {
+  const path = expandUserPath(raw);
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    throw passphraseError(
+      `Cannot read backup.encryption.passphraseFile ${path}: ${(err as NodeJS.ErrnoException).code ?? String(err)}`,
+    );
+  }
+  const mode = (await stat(path)).mode;
+  if (process.platform !== "win32" && (mode & 0o077) !== 0) {
+    logWarn("backup", `${path} is readable by other users — chmod 600 it`);
+  }
+  return checked(text.trim(), path);
+}
+
+/**
+ * Absolute path of the configured passphrase file, or null. The snapshot
+ * builder uses it to keep the key out of every part.
+ */
+export function passphraseFilePath(
+  settings: Pick<BackupSettings, "encryption">,
+): string | null {
+  const file = settings.encryption?.passphraseFile;
+  return file ? expandUserPath(file) : null;
+}
+
+/**
+ * The passphrase this deployment encrypts with, or null when encryption
+ * is not configured. Throws when it is configured but unusable.
+ */
+export async function resolvePassphrase(
+  settings: Pick<BackupSettings, "encryption">,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | null> {
+  const fromEnv = env[PASSPHRASE_ENV]?.trim();
+  if (fromEnv) return checked(fromEnv, PASSPHRASE_ENV);
+  const file = settings.encryption?.passphraseFile;
+  if (file) return readPassphraseFile(file);
+  if (settings.encryption) {
+    throw passphraseError(
+      `backup.encryption is set but no passphrase was found: set backup.encryption.passphraseFile or ${PASSPHRASE_ENV}`,
+    );
+  }
+  return null;
+}
+
+/** Like `resolvePassphrase`, for callers that cannot go on without one. */
+export async function requirePassphrase(
+  settings: Pick<BackupSettings, "encryption">,
+  what: string,
+): Promise<string> {
+  const passphrase = await resolvePassphrase(settings);
+  if (passphrase) return passphrase;
+  throw passphraseError(
+    `${what} is encrypted — set backup.encryption.passphraseFile or ${PASSPHRASE_ENV} to decrypt it`,
+  );
+}
+
+/**
+ * Write a new random passphrase (256 bits, base64url) to `rawPath` with
+ * mode 600. Refuses to overwrite: replacing a key orphans every snapshot
+ * encrypted with it. Returns the absolute path; never the passphrase.
+ */
+export async function generatePassphraseFile(rawPath: string): Promise<string> {
+  const path = expandUserPath(rawPath);
+  await mkdir(dirname(path), { recursive: true });
+  try {
+    await writeFile(path, `${randomBytes(32).toString("base64url")}\n`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+      throw passphraseError(
+        `${path} already exists — refusing to overwrite a backup key`,
+      );
+    }
+    throw err;
+  }
+  return path;
+}