@metamynd/agentsafe-signer 0.13.0

package/governance-envelope.mjs

@@ -0,0 +1,69 @@
+// GENERATED from backend/src/features/policy/mandate/governance-envelope.ts — do not edit. Regenerate: npm run build:signer-core
+
+// src/features/policy/mandate/governance-envelope.ts
+import { createHash } from "node:crypto";
+var ENVELOPE_VERSION = "1.0";
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+function envelopeIntegrityHash(env) {
+  const { integrity: _omit, ...rest } = env;
+  return createHash("sha256").update(stableStringify(rest)).digest("hex");
+}
+function buildGovernanceEnvelope(input) {
+  const base = {
+    envelopeId: `env:${input.nonce}`,
+    version: ENVELOPE_VERSION,
+    createdAt: input.issuedAt,
+    agent: { did: input.agentDid },
+    action: {
+      actionId: `act:${input.nonce}`,
+      actionType: input.action,
+      amount: input.amount,
+      currency: input.currency,
+      merchant: input.merchant ?? null,
+      ...input.materiality ? { materiality: input.materiality } : {}
+    },
+    ...input.trace ? { trace: input.trace } : {},
+    ...input.itinerary ? { context: input.itinerary } : {}
+  };
+  return {
+    ...base,
+    integrity: {
+      payloadHash: envelopeIntegrityHash(base),
+      signature: input.signature,
+      signatureType: "Ed25519"
+    }
+  };
+}
+function envelopeHashFor(input) {
+  return buildGovernanceEnvelope(input).integrity.payloadHash;
+}
+function authorizeInputFromEnvelope(env) {
+  const nonce = env.envelopeId.startsWith("env:") ? env.envelopeId.slice(4) : env.envelopeId;
+  return {
+    agentDid: env.agent.did,
+    action: env.action.actionType,
+    amount: env.action.amount ?? 0,
+    currency: env.action.currency ?? "",
+    merchant: env.action.merchant ?? void 0,
+    itinerary: env.context,
+    trace: env.trace,
+    materiality: env.action.materiality,
+    nonce,
+    issuedAt: env.createdAt,
+    signature: env.integrity.signature ?? ""
+  };
+}
+export {
+  ENVELOPE_VERSION,
+  authorizeInputFromEnvelope,
+  buildGovernanceEnvelope,
+  envelopeHashFor,
+  envelopeIntegrityHash,
+  stableStringify
+};

package/kek-backends.mjs

@@ -0,0 +1,192 @@
+// kek-backends.mjs — OS-keychain-backed KEK storage, replacing the passphrase+scrypt placeholder
+// from the first implementation pass. Shells out to each platform's own standard tool rather than
+// adding a native-module dependency (matches this package's zero-npm-dependency discipline):
+// Windows DPAPI via PowerShell, macOS Keychain via `security`, Linux via `systemd-creds` (fits
+// the Tier 2 systemd-service deployment model this daemon targets) with `secret-tool` as a
+// fallback for desktop sessions. Passphrase+scrypt remains the last-resort fallback when none of
+// these are available — explicitly weaker, never silent about which one is actually in use.
+//
+// VERIFIED in this implementation pass: only the Windows DPAPI backend, on this development
+// machine (Windows). The macOS and Linux backends are implemented against each tool's documented
+// CLI syntax but have NOT been run against a real macOS or Linux host — see README.md "Status".
+import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { deriveKek, loadOrCreateSalt } from './keystore.mjs';
+
+const KEK_BYTES = 32;
+
+function toolAvailable(cmd, args) {
+  try {
+    execFileSync(cmd, args, { stdio: 'ignore', windowsHide: true });
+    return true;
+  } catch (err) {
+    // ENOENT = tool not installed. Any other failure (e.g. a probe command that legitimately
+    // exits non-zero) still proves the tool EXISTS, which is all this check needs to know.
+    return err.code !== 'ENOENT';
+  }
+}
+
+// --- Windows: DPAPI, via PowerShell (no native addon, no extra dependency) ------------------
+
+const DPAPI_PROTECT_SCRIPT = `
+Add-Type -AssemblyName System.Security
+$b64 = [Console]::In.ReadToEnd()
+$bytes = [Convert]::FromBase64String($b64)
+$protected = [System.Security.Cryptography.ProtectedData]::Protect($bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser)
+[Console]::Out.Write([Convert]::ToBase64String($protected))
+`.trim();
+
+const DPAPI_UNPROTECT_SCRIPT = `
+Add-Type -AssemblyName System.Security
+$b64 = [Console]::In.ReadToEnd()
+$bytes = [Convert]::FromBase64String($b64)
+$plain = [System.Security.Cryptography.ProtectedData]::Unprotect($bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser)
+[Console]::Out.Write([Convert]::ToBase64String($plain))
+`.trim();
+
+function dpapiRun(script, inputB64) {
+  return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    input: inputB64,
+    encoding: 'utf8',
+    windowsHide: true,
+  }).trim();
+}
+
+const windowsDpapiBackend = {
+  name: 'dpapi',
+  available() {
+    return process.platform === 'win32';
+  },
+  getOrCreateKek(stateDir) {
+    const blobPath = path.join(stateDir, 'kek.dpapi');
+    if (fs.existsSync(blobPath)) {
+      const protectedB64 = fs.readFileSync(blobPath, 'utf8');
+      const plainB64 = dpapiRun(DPAPI_UNPROTECT_SCRIPT, protectedB64);
+      return Buffer.from(plainB64, 'base64');
+    }
+    const kek = crypto.randomBytes(KEK_BYTES);
+    const protectedB64 = dpapiRun(DPAPI_PROTECT_SCRIPT, kek.toString('base64'));
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(blobPath, protectedB64, { mode: 0o600 });
+    return kek;
+  },
+};
+
+// --- macOS: Keychain, via `security` --------------------------------------------------------
+// NOT verified against a real macOS host in this pass — implemented per `man security`'s
+// documented add-generic-password/find-generic-password behavior.
+
+function keychainAccount(stateDir) {
+  return 'agentsafe-signer-' + crypto.createHash('sha256').update(path.resolve(stateDir)).digest('hex').slice(0, 16);
+}
+
+const macosKeychainBackend = {
+  name: 'macos-keychain',
+  available() {
+    return process.platform === 'darwin' && toolAvailable('security', ['help']);
+  },
+  getOrCreateKek(stateDir) {
+    const service = 'AgentSafe Signer';
+    const account = keychainAccount(stateDir);
+    try {
+      const existing = execFileSync('security', ['find-generic-password', '-a', account, '-s', service, '-w'], { encoding: 'utf8' }).trim();
+      return Buffer.from(existing, 'base64');
+    } catch {
+      const kek = crypto.randomBytes(KEK_BYTES);
+      execFileSync('security', ['add-generic-password', '-a', account, '-s', service, '-w', kek.toString('base64'), '-U']);
+      return kek;
+    }
+  },
+};
+
+// --- Linux: systemd-creds first (fits the Tier 2 service model), secret-tool as a desktop
+// fallback. Neither verified against a real Linux host in this pass.
+
+function credName(stateDir) {
+  return 'agentsafe-signer-kek-' + crypto.createHash('sha256').update(path.resolve(stateDir)).digest('hex').slice(0, 16);
+}
+
+const systemdCredsBackend = {
+  name: 'systemd-creds',
+  available() {
+    return process.platform === 'linux' && toolAvailable('systemd-creds', ['--version']);
+  },
+  getOrCreateKek(stateDir) {
+    const name = credName(stateDir);
+    const blobPath = path.join(stateDir, 'kek.cred');
+    if (fs.existsSync(blobPath)) {
+      const encrypted = fs.readFileSync(blobPath, 'utf8');
+      const plainB64 = execFileSync('systemd-creds', ['decrypt', `--name=${name}`, '-', '-'], { input: encrypted, encoding: 'utf8' }).trim();
+      return Buffer.from(plainB64, 'base64');
+    }
+    const kek = crypto.randomBytes(KEK_BYTES);
+    const encrypted = execFileSync('systemd-creds', ['encrypt', `--name=${name}`, '-', '-'], { input: kek.toString('base64'), encoding: 'utf8' });
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(blobPath, encrypted, { mode: 0o600 });
+    return kek;
+  },
+};
+
+const secretToolBackend = {
+  name: 'secret-tool',
+  available() {
+    return process.platform === 'linux' && toolAvailable('secret-tool', ['--version']);
+  },
+  getOrCreateKek(stateDir) {
+    const account = credName(stateDir);
+    const attrs = ['service', 'agentsafe-signer', 'account', account];
+    try {
+      const existing = execFileSync('secret-tool', ['lookup', ...attrs], { encoding: 'utf8' }).trim();
+      if (!existing) throw new Error('not found');
+      return Buffer.from(existing, 'base64');
+    } catch {
+      const kek = crypto.randomBytes(KEK_BYTES);
+      execFileSync('secret-tool', ['store', '--label=AgentSafe Signer KEK', ...attrs], { input: kek.toString('base64') + '\n' });
+      return kek;
+    }
+  },
+};
+
+// --- Fallback: passphrase + scrypt (the whole KeyStore from the first pass) -----------------
+
+function passphraseFallback(stateDir) {
+  const passphrase = process.env.AGENTSAFE_SIGNER_PASSPHRASE;
+  if (!passphrase) {
+    throw new Error(
+      'No OS-keychain backend is available on this platform/host, and AGENTSAFE_SIGNER_PASSPHRASE ' +
+        'is not set. Set it to a real secret from your own secret manager to use the weaker ' +
+        'passphrase fallback, or run on a platform with a supported keychain backend.',
+    );
+  }
+  const saltHex = loadOrCreateSalt(stateDir);
+  return deriveKek(passphrase, saltHex);
+}
+
+const PLATFORM_BACKENDS = [windowsDpapiBackend, macosKeychainBackend, systemdCredsBackend, secretToolBackend];
+
+/**
+ * Resolves the KEK for `stateDir`, preferring a real OS-keychain backend over the passphrase
+ * fallback, and always reporting which one was actually used — an operator should be able to see
+ * what's protecting their key, not have to assume.
+ * @returns {{ kek: Buffer, backend: string }}
+ */
+export function resolveKek(stateDir) {
+  for (const backend of PLATFORM_BACKENDS) {
+    if (!backend.available()) continue;
+    try {
+      return { kek: backend.getOrCreateKek(stateDir), backend: backend.name };
+    } catch (err) {
+      // `available()` only proves the tool exists and runs (e.g. `systemd-creds --version`) — it
+      // can't cheaply prove the backend actually WORKS in this environment. systemd-creds needs a
+      // host/TPM secret that a container or restricted host may not have even though the binary
+      // itself is present; caught for real on a GitHub Actions runner ("Failed to determine local
+      // credential host secret: Permission denied"), not assumed. A backend that is present but
+      // unusable is not meaningfully different from one that is absent — fall through to the next
+      // one rather than crashing the whole daemon over it.
+      console.error(`[agentsafe-signer] KEK backend "${backend.name}" is available but failed (${err.message}); trying the next one.`);
+    }
+  }
+  return { kek: passphraseFallback(stateDir), backend: 'passphrase' };
+}

package/keystore.mjs

@@ -0,0 +1,108 @@
+// keystore.mjs — encrypted-at-rest Ed25519 key storage. The KEK itself is supplied by the
+// caller (daemon.mjs/cli.mjs), not derived here: this module only ever handles encrypt/decrypt
+// of the private key, never how the KEK was obtained. See README.md "Status" for what backs the
+// KEK today (a passphrase, not yet a real OS-keychain integration) and what that gap means.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { withLockedCopy } from './secure-memory.mjs';
+
+export const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, keylen: 32 };
+
+/** Derive a 32-byte KEK from a passphrase + salt. Salt is not secret — safe to store alongside the encrypted key. */
+export function deriveKek(passphrase, saltHex) {
+  return crypto.scryptSync(passphrase, Buffer.from(saltHex, 'hex'), SCRYPT_PARAMS.keylen, {
+    N: SCRYPT_PARAMS.N,
+    r: SCRYPT_PARAMS.r,
+    p: SCRYPT_PARAMS.p,
+  });
+}
+
+export function loadOrCreateSalt(stateDir) {
+  const saltPath = path.join(stateDir, 'salt.hex');
+  if (fs.existsSync(saltPath)) return fs.readFileSync(saltPath, 'utf8').trim();
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const saltHex = crypto.randomBytes(16).toString('hex');
+  fs.writeFileSync(saltPath, saltHex, { mode: 0o600 });
+  return saltHex;
+}
+
+export class KeyStoreError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+
+/**
+ * Encrypted-at-rest Ed25519 private key. Never exposes the private key itself — `sign()` is the
+ * only operation that touches it, and it's decrypted fresh for each call and zeroed immediately
+ * after (see sign()'s own `finally`), not held decrypted between calls.
+ */
+export class KeyStore {
+  #kek;
+  #dir;
+  #record = null;
+
+  constructor({ dir, kek }) {
+    this.#dir = dir;
+    this.#kek = kek;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    this.#load();
+  }
+
+  get #keystorePath() {
+    return path.join(this.#dir, 'keystore.enc.json');
+  }
+
+  #load() {
+    if (!fs.existsSync(this.#keystorePath)) return;
+    this.#record = JSON.parse(fs.readFileSync(this.#keystorePath, 'utf8'));
+  }
+
+  hasKey() {
+    return this.#record !== null;
+  }
+
+  publicKeyHex() {
+    return this.#record?.publicKeyHex ?? null;
+  }
+
+  /** Generates a new Ed25519 keypair inside this store. Refuses to overwrite an existing key. */
+  generate({ allowRekey = false } = {}) {
+    if (this.hasKey() && !allowRekey) throw new KeyStoreError('KEY_ALREADY_EXISTS');
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    const privateDer = privateKey.export({ format: 'der', type: 'pkcs8' });
+    const publicKeyHex = publicKey.export({ format: 'der', type: 'spki' }).toString('hex');
+    // withLockedCopy mlocks the DER bytes for the brief window they're plaintext here, and zeroes
+    // `privateDer` itself immediately — see secure-memory.mjs for why this needs a real dependency.
+    const { iv, authTag, ciphertext } = withLockedCopy(privateDer, (locked) => {
+      const iv = crypto.randomBytes(12);
+      const cipher = crypto.createCipheriv('aes-256-gcm', this.#kek, iv);
+      const ciphertext = Buffer.concat([cipher.update(locked), cipher.final()]);
+      return { iv, authTag: cipher.getAuthTag(), ciphertext };
+    });
+    const record = {
+      publicKeyHex,
+      iv: iv.toString('hex'),
+      authTag: authTag.toString('hex'),
+      ciphertext: ciphertext.toString('hex'),
+    };
+    fs.writeFileSync(this.#keystorePath, JSON.stringify(record), { mode: 0o600 });
+    this.#record = record;
+    return publicKeyHex;
+  }
+
+  /** Signs `messageBuffer` with the stored private key. The decrypted key never leaves this function. */
+  sign(messageBuffer) {
+    if (!this.hasKey()) throw new KeyStoreError('NOT_PROVISIONED');
+    const { iv, authTag, ciphertext } = this.#record;
+    const decipher = crypto.createDecipheriv('aes-256-gcm', this.#kek, Buffer.from(iv, 'hex'));
+    decipher.setAuthTag(Buffer.from(authTag, 'hex'));
+    const privateDer = Buffer.concat([decipher.update(Buffer.from(ciphertext, 'hex')), decipher.final()]);
+    return withLockedCopy(privateDer, (locked) => {
+      const privateKey = crypto.createPrivateKey({ key: locked, format: 'der', type: 'pkcs8' });
+      return crypto.sign(null, messageBuffer, privateKey).toString('hex');
+    });
+  }
+}

package/log-anchor.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// log-anchor.mjs — the separate, optional, LIVE-NETWORK half of T11 (docs/design/agent-key-
+// custody-local-signer-daemon-plan.md). log-checkpoint.mjs already produces local, chained
+// checkpoints with zero network dependency; this script reads whichever ones aren't anchored yet
+// (pendingAnchors), asks the already-running daemon to sign an anchor request for each one
+// (sign-log-checkpoint — only the daemon holds the key), and POSTs the signed request to the
+// backend's /evidence/signer-checkpoint endpoint, which verifies the signature against the
+// agent's own DID and anchors the checkpoint hash via HCS.
+//
+// Deliberately a SEPARATE process from daemon.mjs, not a daemon feature: the daemon stays
+// local-first / offline-capable by design — this is the one piece of the whole system that
+// genuinely needs a live network connection, and keeping it a separate, operator-scheduled script
+// (cron, a systemd timer) means a daemon that never gets anchored still signs and logs correctly;
+// anchoring is a bonus property, not a dependency of normal operation.
+//
+//   node log-anchor.mjs --state-dir ./.signer --api-url https://api.example.com/v1
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pendingAnchors, markAnchored } from './log-checkpoint.mjs';
+import { parseArgs, daemonRequest } from './daemon-client.mjs';
+
+async function anchorOne(checkpoint, { socketPath, apiUrl, agentDid }) {
+  const nonce = crypto.randomUUID();
+  const issuedAt = new Date().toISOString();
+  const { signature } = await daemonRequest(socketPath, 'sign-log-checkpoint', {
+    checkpointHash: checkpoint.checkpointHash,
+    previousCheckpointHash: checkpoint.previousCheckpointHash,
+    entryCount: checkpoint.entryCount,
+    nonce,
+    issuedAt,
+  });
+
+  const body = {
+    agentDid,
+    checkpointHash: checkpoint.checkpointHash,
+    previousCheckpointHash: checkpoint.previousCheckpointHash,
+    entryCount: checkpoint.entryCount,
+    nonce,
+    issuedAt,
+    signature,
+  };
+  const res = await fetch(new URL('/evidence/signer-checkpoint', apiUrl), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json?.success) {
+    throw new Error(`anchor request failed (HTTP ${res.status}): ${json?.message ?? 'no response body'}`);
+  }
+  return json.data; // { txId, ref, network, anchoredAt, alreadyAnchored }
+}
+
+/**
+ * Anchors every pending local checkpoint for the daemon at `socketPath`/`stateDir`. Exported so
+ * cli.mjs's `log-anchor` subcommand and this file's own direct-invocation `main()` share one
+ * implementation rather than drifting. Returns the number of checkpoints that failed to anchor
+ * (0 = fully caught up); never throws for an individual checkpoint's failure — each is
+ * independent, and a later run retries whatever didn't get marked anchored this time.
+ */
+export async function runLogAnchor({ stateDir, socketPath, apiUrl }) {
+  const pending = pendingAnchors(stateDir);
+  if (pending.length === 0) {
+    console.log('[log-anchor] nothing pending — every local checkpoint is already anchored.');
+    return 0;
+  }
+
+  // Ask the already-running daemon who it is, rather than requiring a redundant --identity flag
+  // that could drift from the daemon's own bound agentDid.
+  const { identity: agentDid } = await daemonRequest(socketPath, 'get-identity', {});
+  if (!agentDid) {
+    console.error('[log-anchor] the daemon has no bound identity yet (not provisioned) — nothing to anchor as.');
+    return pending.length;
+  }
+
+  let failed = 0;
+  for (const checkpoint of pending) {
+    try {
+      const data = await anchorOne(checkpoint, { socketPath, apiUrl, agentDid });
+      markAnchored(stateDir, checkpoint.checkpointHash, { txId: data.txId, ref: data.ref });
+      console.log(`[log-anchor] checkpoint ${checkpoint.index} (${checkpoint.checkpointHash.slice(0, 12)}…) -> ${data.txId}${data.alreadyAnchored ? ' (already anchored)' : ''}`);
+    } catch (err) {
+      failed++;
+      console.error(`[log-anchor] checkpoint ${checkpoint.index} FAILED: ${err.message}`);
+    }
+  }
+  return failed;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const stateDir = args['state-dir'] ?? path.join(process.cwd(), '.agentsafe-signer');
+  const socketPath = args['socket-path'] ?? path.join(stateDir, 'signer.sock');
+  const apiUrl = args['api-url'] ?? process.env.AGENTSAFE_SIGNER_API_URL;
+  if (!apiUrl) {
+    console.error('Usage: agentsafe-signer log-anchor requires --api-url <backend base url> (or AGENTSAFE_SIGNER_API_URL)');
+    process.exit(1);
+  }
+  const failed = await runLogAnchor({ stateDir, socketPath, apiUrl });
+  if (failed > 0) process.exit(1);
+}
+
+// Only run as a CLI when invoked directly (`node log-anchor.mjs`), not when cli.mjs imports
+// runLogAnchor from this same file. path.resolve(), not a raw string/URL compare — Windows path
+// separators and drive-letter casing make a direct import.meta.url-vs-argv[1] string comparison
+// unreliable there.
+if (process.argv[1] && path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1])) {
+  main().catch((err) => {
+    console.error('[log-anchor] fatal:', err);
+    process.exit(1);
+  });
+}

package/log-checkpoint.mjs

@@ -0,0 +1,191 @@
+// log-checkpoint.mjs — periodic, local, tamper-evident checkpointing of the daemon's own
+// signer.log (docs/design/agent-key-custody-local-signer-daemon-plan.md, T11: "periodically
+// hash-chaining the log ... would give tamper-evidence without inventing a new mechanism").
+//
+// Fully offline and dependency-free: this only proves the log wasn't altered SINCE a checkpoint
+// was taken (a privileged local attacker who tampers with an already-checkpointed line will break
+// that checkpoint's own Merkle root, or the hash-chain link to it, and verifyLogCheckpoints below
+// will say exactly where). It does NOT, on its own, stop an attacker who controls both the log
+// AND the checkpoint file from rewriting both consistently — that is what externally anchoring a
+// checkpointHash (log-anchor.mjs, a separate optional step, needs live network + backend) is for.
+// This module never touches the network.
+import fs from 'node:fs';
+import path from 'node:path';
+import { sha256Hex, merkleRoot } from './merkle.mjs';
+
+/** The `previousCheckpointHash` for checkpoint index 0 — a fixed, documented constant so the
+ *  very first checkpoint's chain link is still well-defined and verifiable, not an arbitrary or
+ *  attacker-choosable value. */
+export const GENESIS_HASH = sha256Hex('agentsafe-signer-log-checkpoint-genesis');
+
+function checkpointsPath(stateDir) {
+  return path.join(stateDir, 'signer.log.checkpoints.jsonl');
+}
+
+function logPath(stateDir) {
+  return path.join(stateDir, 'signer.log');
+}
+
+function readCheckpoints(stateDir) {
+  const p = checkpointsPath(stateDir);
+  if (!fs.existsSync(p)) return [];
+  return fs
+    .readFileSync(p, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line));
+}
+
+/**
+ * The exact byte range of the log to include in the next checkpoint: from the last checkpoint's
+ * `toOffset` (or 0) up to the end of the last COMPLETE line currently in the file. Stopping at the
+ * last complete line — never the raw file size — means a checkpoint can never include a line that
+ * was only partially flushed, even though `fs.appendFileSync`'s single synchronous write call
+ * makes a torn write for one JSON line essentially impossible in practice; this is a defensive
+ * bound, not a response to an observed failure.
+ */
+function pendingRange(stateDir, fromOffset) {
+  const p = logPath(stateDir);
+  if (!fs.existsSync(p)) return null;
+  const buf = fs.readFileSync(p);
+  if (buf.length <= fromOffset) return null;
+  const region = buf.subarray(fromOffset);
+  const lastNewline = region.lastIndexOf(0x0a);
+  if (lastNewline === -1) return null; // no complete line since the last checkpoint yet
+  const toOffset = fromOffset + lastNewline + 1;
+  const lines = region
+    .subarray(0, lastNewline + 1)
+    .toString('utf8')
+    .split('\n')
+    .filter((line) => line.length > 0);
+  if (lines.length === 0) return null;
+  return { toOffset, lines };
+}
+
+/**
+ * Computes and appends the next checkpoint over whatever new, complete log lines have accumulated
+ * since the last one. Returns the new checkpoint record, or `null` if there was nothing new to
+ * checkpoint (never appends an empty/no-op checkpoint — a chain of identical, content-free links
+ * would be dead weight, not evidence of anything).
+ *
+ * Each leaf is the hash of a log line's exact stored BYTES, not a re-parsed/re-serialized version
+ * of it — hashing the raw bytes catches any byte-level edit (e.g. changing one field's value
+ * in-place without touching key order), not just a naive attacker's attempt to reorder JSON keys.
+ */
+export function takeCheckpoint(stateDir) {
+  const existing = readCheckpoints(stateDir);
+  const fromOffset = existing.length > 0 ? existing[existing.length - 1].toOffset : 0;
+  const previousCheckpointHash = existing.length > 0 ? existing[existing.length - 1].checkpointHash : GENESIS_HASH;
+
+  const pending = pendingRange(stateDir, fromOffset);
+  if (!pending) return null;
+
+  const leaves = pending.lines.map((line) => sha256Hex(line));
+  const root = merkleRoot(leaves);
+  const checkpointHash = sha256Hex(`${previousCheckpointHash}:${root}`);
+
+  const checkpoint = {
+    index: existing.length,
+    fromOffset,
+    toOffset: pending.toOffset,
+    entryCount: leaves.length,
+    merkleRoot: root,
+    previousCheckpointHash,
+    checkpointHash,
+    createdAt: new Date().toISOString(),
+  };
+
+  fs.appendFileSync(checkpointsPath(stateDir), JSON.stringify(checkpoint) + '\n', { mode: 0o600 });
+  return checkpoint;
+}
+
+/**
+ * Recomputes every checkpoint directly from the raw log bytes at its recorded offsets and confirms
+ * both properties a tamper-evident chain needs: (1) the batch's Merkle root still matches what is
+ * actually stored in the log at that byte range, and (2) each checkpoint's own hash correctly
+ * chains from the previous one (or GENESIS_HASH, for the first). Returns as soon as the first
+ * mismatch is found — a tampered log doesn't need every subsequent checkpoint checked to know it's
+ * been tampered with.
+ */
+export function verifyLogCheckpoints(stateDir) {
+  const checkpoints = readCheckpoints(stateDir);
+  if (checkpoints.length === 0) return { ok: true, checkedCount: 0 };
+
+  const buf = fs.existsSync(logPath(stateDir)) ? fs.readFileSync(logPath(stateDir)) : Buffer.alloc(0);
+  let previousCheckpointHash = GENESIS_HASH;
+
+  for (let i = 0; i < checkpoints.length; i++) {
+    const cp = checkpoints[i];
+
+    if (cp.previousCheckpointHash !== previousCheckpointHash) {
+      return { ok: false, checkedCount: i, failedIndex: i, reason: 'chain link does not match the previous checkpoint\'s own hash' };
+    }
+
+    if (buf.length < cp.toOffset) {
+      return { ok: false, checkedCount: i, failedIndex: i, reason: 'log file is shorter than this checkpoint recorded — truncated or replaced' };
+    }
+    const region = buf.subarray(cp.fromOffset, cp.toOffset).toString('utf8');
+    const lines = region.split('\n').filter((line) => line.length > 0);
+    const recomputedRoot = merkleRoot(lines.map((line) => sha256Hex(line)));
+    if (recomputedRoot !== cp.merkleRoot) {
+      return { ok: false, checkedCount: i, failedIndex: i, reason: 'Merkle root no longer matches the log content at this checkpoint\'s byte range — a covered line was modified' };
+    }
+
+    const recomputedCheckpointHash = sha256Hex(`${cp.previousCheckpointHash}:${cp.merkleRoot}`);
+    if (recomputedCheckpointHash !== cp.checkpointHash) {
+      return { ok: false, checkedCount: i, failedIndex: i, reason: 'checkpointHash does not match its own recorded previousCheckpointHash + merkleRoot — the checkpoint record itself was edited' };
+    }
+
+    previousCheckpointHash = cp.checkpointHash;
+  }
+
+  return { ok: true, checkedCount: checkpoints.length };
+}
+
+function anchorsPath(stateDir) {
+  return path.join(stateDir, 'signer.log.anchors.jsonl');
+}
+
+function readAnchors(stateDir) {
+  const p = anchorsPath(stateDir);
+  if (!fs.existsSync(p)) return new Map();
+  const map = new Map();
+  for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    const record = JSON.parse(line);
+    map.set(record.checkpointHash, record); // last write for a given hash wins, matching a re-anchor after a retry
+  }
+  return map;
+}
+
+/**
+ * Records the result of successfully anchoring one checkpoint. Deliberately a SEPARATE, append-
+ * only file rather than rewriting checkpoints.jsonl in place: `takeCheckpoint` (called only by the
+ * daemon's own periodic timer) and this function (called by the separate, operator-run
+ * `log-anchor.mjs` process) can run in different processes at any time, and an append is always
+ * safe against a concurrent append elsewhere — a read-modify-write rewrite of the checkpoints file
+ * from a second process would risk silently dropping a checkpoint the daemon appended in between.
+ */
+export function markAnchored(stateDir, checkpointHash, { txId, ref, anchoredAt = new Date().toISOString() }) {
+  if (!readCheckpoints(stateDir).some((cp) => cp.checkpointHash === checkpointHash)) {
+    throw new Error(`markAnchored: no checkpoint with checkpointHash ${checkpointHash}`);
+  }
+  const record = { checkpointHash, txId, ref, anchoredAt };
+  fs.appendFileSync(anchorsPath(stateDir), JSON.stringify(record) + '\n', { mode: 0o600 });
+  return record;
+}
+
+/** Every checkpoint, each with its anchor record merged in (if any) as `anchoredAt`/`txId`/`ref`. */
+export function listCheckpoints(stateDir) {
+  const anchors = readAnchors(stateDir);
+  return readCheckpoints(stateDir).map((cp) => {
+    const anchor = anchors.get(cp.checkpointHash);
+    return anchor ? { ...cp, anchoredAt: anchor.anchoredAt, txId: anchor.txId, ref: anchor.ref } : cp;
+  });
+}
+
+/** The checkpoints not yet anchored externally (see log-anchor.mjs) — no matching record in the
+ *  separate anchors file. */
+export function pendingAnchors(stateDir) {
+  return listCheckpoints(stateDir).filter((cp) => !cp.anchoredAt);
+}