@metamynd/agentsafe-signer 0.13.0

package/daemon-client.mjs

@@ -0,0 +1,97 @@
+// daemon-client.mjs — shared helpers for agentsafe-signer's OWN operator-facing scripts
+// (log-anchor.mjs, migrate.mjs) that need to connect to an already-running daemon's socket and
+// parse CLI-style arguments. Not for external packages — agentsafe-guard/agentsafe-mcp-guard
+// deliberately duplicate their own small copy of the connection logic instead of depending on
+// this package (see either's key-providers.mjs); this module is purely internal, avoiding a
+// THIRD hand-copy of the same ~40 lines within this package itself.
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { toPlatformSocketPath } from './daemon.mjs';
+
+const PROTOCOL_VERSION = 1;
+
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i++;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+/** Same connection + ENOENT-retry logic as agentsafe-guard/agentsafe-mcp-guard's own
+ *  key-providers.mjs (see either's comment for why): on Windows the signing socket is a pool of
+ *  independent named-pipe instances, each consumed by one connection and replaced asynchronously,
+ *  so a request can transiently race that replacement window even though the daemon is healthy.
+ *
+ *  `connectTimeoutMs` bounds the WHOLE call, not just the ENOENT-retry loop: a Windows named-pipe
+ *  connection attempt can in rare cases neither error nor connect (the relay process behind
+ *  windows-secure-pipe.mjs itself wedged mid-startup) — with only the retry-loop deadline, that
+ *  left a real caller hung indefinitely (found via a 5+ hour stuck process, not a timeout). The
+ *  overall timer below fires unconditionally regardless of the socket's state, so a wedged
+ *  connection now fails fast with a clear error instead of hanging forever. */
+export function daemonRequest(socketPath, op, params, { connectTimeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + connectTimeoutMs;
+    let settled = false;
+    const overallTimer = setTimeout(() => {
+      settled = true;
+      reject(Object.assign(new Error(`agentsafe-signer daemon unreachable at ${socketPath}: timed out after ${connectTimeoutMs}ms`), { code: 'DAEMON_UNREACHABLE' }));
+    }, connectTimeoutMs);
+    function attempt() {
+      if (settled) return;
+      const sock = net.connect(toPlatformSocketPath(socketPath));
+      const requestId = crypto.randomUUID();
+      let buf = '';
+      const cleanup = () => sock.destroy();
+      sock.once('error', (err) => {
+        cleanup();
+        if (settled) return;
+        if (err.code === 'ENOENT' && Date.now() < deadline) {
+          setTimeout(attempt, 20);
+          return;
+        }
+        settled = true;
+        clearTimeout(overallTimer);
+        reject(Object.assign(new Error(`agentsafe-signer daemon unreachable at ${socketPath}: ${err.message}`), { code: 'DAEMON_UNREACHABLE' }));
+      });
+      sock.once('connect', () => {
+        if (settled) return;
+        sock.write(JSON.stringify({ protocolVersion: PROTOCOL_VERSION, requestId, op, params }) + '\n');
+      });
+      sock.on('data', (chunk) => {
+        if (settled) return;
+        buf += chunk.toString('utf8');
+        const idx = buf.indexOf('\n');
+        if (idx === -1) return;
+        let res;
+        try {
+          res = JSON.parse(buf.slice(0, idx));
+        } catch (err) {
+          cleanup();
+          settled = true;
+          clearTimeout(overallTimer);
+          reject(err);
+          return;
+        }
+        cleanup();
+        settled = true;
+        clearTimeout(overallTimer);
+        if (res.ok) resolve(res.result);
+        else reject(Object.assign(new Error(res.error?.message || res.error?.code || 'daemon rejected request'), { code: res.error?.code }));
+      });
+    }
+    attempt();
+  });
+}

package/daemon.mjs

@@ -0,0 +1,558 @@
+// daemon.mjs — the local signer daemon (docs/design/agent-key-custody-local-signer-daemon-plan.md).
+// A separate process from the calling guard: holds the key, exposes a small closed set of signing
+// operations over a local socket, and never returns the key itself over either socket, under any
+// code path. See README.md for what's implemented in this pass vs. deliberately deferred.
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { buildAuthMessage, buildCheckpointAnchorMessage, buildLocalDecisionMessage } from './policy-core.mjs';
+import { envelopeHashFor } from './governance-envelope.mjs';
+import { KeyStore, KeyStoreError } from './keystore.mjs';
+import { createSecurePipePool, createSecurePipeOnce } from './windows-secure-pipe.mjs';
+import { takeCheckpoint } from './log-checkpoint.mjs';
+
+export const PROTOCOL_VERSION = 1;
+export const MAX_LINE_BYTES = 64 * 1024;
+export const FRESHNESS_MS = 5 * 60 * 1000;
+export const CLOCK_SKEW_MS = 30 * 1000;
+
+const ALL_SIGNING_OPS = new Set(['sign-authorize', 'sign-envelope', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']);
+
+// sign-log-checkpoint is in BOTH role sets, unlike every other sign-* op: it authenticates the
+// daemon's own log-tamper-evidence checkpoint (T11), which every daemon keeps regardless of
+// role — an agent-role daemon's log needs the same anchoring as a service-role daemon's.
+// sign-local-decision, like sign-authorize/sign-envelope, is agent-role-only — it signs an
+// AGENT's own local-first block/escalate/non-value-allow verdict for audit reporting
+// (agentsafe-guard.mjs's reportLocalDecision()); a service-role daemon never evaluates a
+// mandate locally, so it has nothing to report.
+const SIGNING_OPS_BY_ROLE = {
+  agent: new Set(['sign-authorize', 'sign-envelope', 'sign-handshake-nonce', 'sign-key-control-challenge', 'sign-log-checkpoint', 'sign-local-decision', 'get-identity', 'ping']),
+  service: new Set(['sign-handshake-nonce', 'sign-log-checkpoint', 'get-identity', 'ping']),
+};
+
+const DEFAULT_RATE_LIMITS = {
+  'sign-authorize': { max: 20, windowMs: 10_000 },
+  'sign-envelope': { max: 20, windowMs: 10_000 },
+  'sign-handshake-nonce': { max: 10, windowMs: 60_000 },
+  'sign-key-control-challenge': { max: 3, windowMs: 60 * 60 * 1000 },
+  // Local decisions are reported for every locally-decided block/escalate/non-value-allow, not
+  // just value-moving actions — under local-first mode that's the overwhelming majority of an
+  // agent's tool calls, so this ceiling is deliberately higher than sign-authorize's.
+  'sign-local-decision': { max: 60, windowMs: 10_000 },
+  // Checkpoints are taken on a coarse timer (DEFAULT_CHECKPOINT_INTERVAL_MS), so anchoring one is
+  // an infrequent, operator-driven action, not agent-runtime traffic — a low ceiling is plenty and
+  // catches a misbehaving or compromised anchor script hammering this op instead of running on
+  // its own schedule.
+  'sign-log-checkpoint': { max: 5, windowMs: 60 * 60 * 1000 },
+};
+
+export const DEFAULT_CHECKPOINT_INTERVAL_MS = 15 * 60 * 1000;
+
+// Matches agentsafe-guard.mjs's own REPORTABLE_LOCAL_DECISIONS exactly (LOCAL_DECISIONS the
+// backend's /policy/decisions/local actually accepts) — this daemon must never sign a
+// 'quarantine'/'suspend' or other value here just because a caller asked; only a genuine
+// local-first verdict shape is a valid thing to have signed under this op.
+const REPORTABLE_LOCAL_DECISIONS = new Set(['allow', 'observe', 'block', 'escalate']);
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_RE = /^[0-9a-f]+$/i;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/i;
+
+export class DaemonError extends Error {
+  constructor(code, message = code) {
+    super(message);
+    this.code = code;
+  }
+}
+
+class RateLimiter {
+  constructor() {
+    this.windows = new Map();
+  }
+  /** Returns true if this hit is within the limit. `max: 0` or `undefined` disables the limit for this op. */
+  hit(op, max, windowMs) {
+    if (!max) return true;
+    const now = Date.now();
+    let w = this.windows.get(op);
+    if (!w || now - w.start >= windowMs) {
+      w = { start: now, count: 0 };
+      this.windows.set(op, w);
+    }
+    w.count++;
+    return w.count <= max;
+  }
+}
+
+function isFiniteNonNegative(n) {
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0;
+}
+
+function freshnessOk(issuedAt, now = Date.now()) {
+  const ts = Date.parse(issuedAt);
+  if (Number.isNaN(ts)) return false;
+  const age = now - ts;
+  return age <= FRESHNESS_MS && age >= -CLOCK_SKEW_MS;
+}
+
+/** One JSON-Lines connection: buffers bytes, splits on '\n', parses+dispatches one request per line. */
+function attachJsonLines(socket, onLine, { maxLineBytes = MAX_LINE_BYTES } = {}) {
+  let buf = Buffer.alloc(0);
+  socket.on('data', (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    if (buf.length > maxLineBytes && !buf.includes(0x0a)) {
+      socket.destroy();
+      return;
+    }
+    let idx;
+    while ((idx = buf.indexOf(0x0a)) !== -1) {
+      const line = buf.subarray(0, idx).toString('utf8');
+      buf = buf.subarray(idx + 1);
+      if (line.trim().length === 0) continue;
+      if (Buffer.byteLength(line, 'utf8') > maxLineBytes) {
+        socket.destroy();
+        return;
+      }
+      onLine(line);
+    }
+  });
+}
+
+function writeResponse(socket, requestId, payload) {
+  const body = { protocolVersion: PROTOCOL_VERSION, requestId, ...payload };
+  socket.write(JSON.stringify(body) + '\n');
+}
+
+export class SignerDaemon {
+  #unlocked = false;
+  #unlockPromise;
+  #limiter = new RateLimiter();
+  #rateLimits;
+  #shadowMode;
+  #adminOpen = false;
+  #agentDid;
+  #log;
+  #checkpointTimer = null;
+
+  constructor({ stateDir, role, agentDid = null, kek, rateLimits = {}, shadowMode = true, log, checkpointIntervalMs = DEFAULT_CHECKPOINT_INTERVAL_MS }) {
+    if (role !== 'agent' && role !== 'service') throw new Error(`role must be 'agent' or 'service', got '${role}'`);
+    this.role = role;
+    this.stateDir = stateDir;
+    this.#agentDid = agentDid;
+    this.#rateLimits = { ...DEFAULT_RATE_LIMITS, ...rateLimits };
+    this.#shadowMode = shadowMode;
+    this.#log = log ?? defaultLogger(stateDir);
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    this.#unlockPromise = Promise.resolve().then(() => {
+      this.keystore = new KeyStore({ dir: stateDir, kek });
+      this.#unlocked = true;
+    });
+    // Fully local/offline (T11) — see log-checkpoint.mjs. `.unref()` so this timer alone never
+    // keeps the process alive; the signing socket already does that for a real daemon, and tests
+    // that construct a SignerDaemon without ever starting a socket already call process.exit()
+    // explicitly rather than waiting for handles to drain.
+    if (checkpointIntervalMs > 0) {
+      this.#checkpointTimer = setInterval(() => this.checkpointLog(), checkpointIntervalMs);
+      this.#checkpointTimer.unref?.();
+    }
+  }
+
+  /**
+   * Takes a checkpoint of the log right now, regardless of the timer — real callers get this for
+   * free on the interval above; tests and an operator-triggered `log-anchor.mjs` run call it
+   * directly for a deterministic, on-demand checkpoint rather than waiting out the timer. A log
+   * entry recording the checkpoint is written AFTER computing it, so it naturally lands in the
+   * NEXT checkpoint's batch rather than needing to somehow retroactively include itself.
+   */
+  checkpointLog() {
+    const checkpoint = takeCheckpoint(this.stateDir);
+    if (checkpoint) {
+      this.#log({ type: 'log-checkpoint', checkpointHash: checkpoint.checkpointHash, entryCount: checkpoint.entryCount, at: checkpoint.createdAt });
+    }
+    return checkpoint;
+  }
+
+  /** Stops the periodic checkpoint timer — not required for normal process-exit cleanup (the
+   *  timer is already unref'd), but available for anything that wants a SignerDaemon's lifecycle
+   *  fully quiesced without exiting the process (e.g. a test harness running many in one process). */
+  stopCheckpointing() {
+    if (this.#checkpointTimer) clearInterval(this.#checkpointTimer);
+    this.#checkpointTimer = null;
+  }
+
+  get unlocked() {
+    return this.#unlocked;
+  }
+
+  get identity() {
+    return this.#agentDid;
+  }
+
+  setIdentity(did) {
+    this.#agentDid = did;
+  }
+
+  async waitUntilUnlocked() {
+    await this.#unlockPromise;
+  }
+
+  #assertAllowedOp(op) {
+    if (!ALL_SIGNING_OPS.has(op)) throw new DaemonError('DAEMON_UNKNOWN_OPERATION', `unknown operation ${op}`);
+    if (!SIGNING_OPS_BY_ROLE[this.role].has(op)) throw new DaemonError('DAEMON_OPERATION_NOT_PERMITTED', `${op} not permitted for role ${this.role}`);
+  }
+
+  #assertRateLimit(op) {
+    const cfg = this.#rateLimits[op];
+    if (!cfg) return;
+    const ok = this.#limiter.hit(op, cfg.max, cfg.windowMs);
+    if (!ok) {
+      this.#log({ type: 'rate-limit', op, shadow: this.#shadowMode, at: new Date().toISOString() });
+      if (!this.#shadowMode) throw new DaemonError('DAEMON_RATE_LIMITED');
+    }
+  }
+
+  #sign(messageBuffer) {
+    if (!this.#unlocked) throw new DaemonError('DAEMON_LOCKED');
+    try {
+      return this.keystore.sign(messageBuffer);
+    } catch (err) {
+      if (err instanceof KeyStoreError && err.code === 'NOT_PROVISIONED') throw new DaemonError('DAEMON_NOT_PROVISIONED');
+      throw new DaemonError('DAEMON_INTERNAL_ERROR');
+    }
+  }
+
+  #assertIdentity(agentDid) {
+    if (!this.#agentDid) throw new DaemonError('DAEMON_NOT_PROVISIONED');
+    if (agentDid !== this.#agentDid) throw new DaemonError('DAEMON_IDENTITY_MISMATCH');
+  }
+
+  /** Dispatch one signing-socket request. Returns the `result` payload; throws DaemonError on any rejection. */
+  handleSigningRequest({ op, params }) {
+    this.#assertAllowedOp(op);
+    switch (op) {
+      case 'ping':
+        return { status: 'ok', unlocked: this.#unlocked };
+      case 'get-identity':
+        return { identity: this.#agentDid, publicKeyHex: this.#unlocked ? this.keystore.publicKeyHex() : null, role: this.role };
+      case 'sign-authorize':
+        return this.#handleSignAuthorize(params);
+      case 'sign-envelope':
+        return this.#handleSignEnvelope(params);
+      case 'sign-handshake-nonce':
+        return this.#handleSignHandshakeNonce(params);
+      case 'sign-key-control-challenge':
+        return this.#handleSignKeyControlChallenge(params);
+      case 'sign-log-checkpoint':
+        return this.#handleSignLogCheckpoint(params);
+      case 'sign-local-decision':
+        return this.#handleSignLocalDecision(params);
+      default:
+        throw new DaemonError('DAEMON_UNKNOWN_OPERATION');
+    }
+  }
+
+  #validateCoreFields({ agentDid, action, amount, currency, merchant, resource, nonce, issuedAt }) {
+    if (typeof agentDid !== 'string' || typeof action !== 'string' || typeof nonce !== 'string' || typeof issuedAt !== 'string') {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'missing required field');
+    }
+    if (action.length === 0 || action.includes('|')) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid action');
+    if (!isFiniteNonNegative(amount)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'amount must be finite and non-negative');
+    if (merchant !== undefined && typeof merchant !== 'string') throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid merchant');
+    if (currency !== undefined && typeof currency !== 'string') throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid currency');
+    if (resource !== undefined && typeof resource !== 'string') throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid resource');
+    this.#assertIdentity(agentDid);
+    if (!freshnessOk(issuedAt)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'issuedAt outside freshness window');
+  }
+
+  #handleSignAuthorize(params = {}) {
+    this.#assertRateLimit('sign-authorize');
+    this.#validateCoreFields(params);
+    const { agentDid, action, amount, currency = 'USD', merchant, resource, nonce, issuedAt } = params;
+    // `resource` is the 8th canonical field (canonical.ts) — dropping it here (found live: it
+    // was) means every request signed via this daemon silently omits it from the signature,
+    // so the real gate's 8-field reconstruction never matches for any resource-bearing call.
+    const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, resource, nonce, issuedAt });
+    return { signature: this.#sign(Buffer.from(message, 'utf8')) };
+  }
+
+  /**
+   * `LocalDecisionMessageFields` has a completely different shape from `AuthMessageFields`
+   * (agentDid/action/decision/reasonCode/nonce/issuedAt vs. .../amount/currency/merchant/...) —
+   * cannot reuse #validateCoreFields, which requires amount and treats merchant/currency as
+   * optional strings that don't exist on this shape at all.
+   */
+  #validateLocalDecisionFields({ agentDid, action, decision, reasonCode, nonce, issuedAt }) {
+    if (typeof agentDid !== 'string' || typeof action !== 'string' || typeof nonce !== 'string' || typeof issuedAt !== 'string') {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'missing required field');
+    }
+    if (action.length === 0 || action.includes('|')) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'invalid action');
+    if (typeof decision !== 'string' || !REPORTABLE_LOCAL_DECISIONS.has(decision)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'decision must be one of allow|observe|block|escalate');
+    }
+    if (typeof reasonCode !== 'string' || reasonCode.length === 0) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'reasonCode must be a non-empty string');
+    }
+    this.#assertIdentity(agentDid);
+    if (!freshnessOk(issuedAt)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'issuedAt outside freshness window');
+  }
+
+  /**
+   * Signs an agent's own local-first verdict for best-effort audit reporting (see
+   * agentsafe-guard.mjs's reportLocalDecision()) — a daemon-custody agent gets the same
+   * audit-visibility enhancement the static-key provider already has.
+   */
+  #handleSignLocalDecision(params = {}) {
+    this.#assertRateLimit('sign-local-decision');
+    this.#validateLocalDecisionFields(params);
+    const { agentDid, action, decision, reasonCode, nonce, issuedAt } = params;
+    const message = buildLocalDecisionMessage({ agentDid, action, decision, reasonCode, nonce, issuedAt });
+    return { signature: this.#sign(Buffer.from(message, 'utf8')) };
+  }
+
+  #handleSignEnvelope(params = {}) {
+    this.#assertRateLimit('sign-envelope');
+    this.#validateCoreFields(params);
+    const { agentDid, action, amount, currency = 'USD', merchant, itinerary, trace, materiality, nonce, issuedAt } = params;
+    const hash = envelopeHashFor({ agentDid, action, amount, currency, merchant, itinerary, trace, materiality, nonce, issuedAt, signature: '' });
+    return { envelopeSignature: this.#sign(Buffer.from(hash, 'utf8')) };
+  }
+
+  #handleSignHandshakeNonce(params = {}) {
+    this.#assertRateLimit('sign-handshake-nonce');
+    const { nonce } = params;
+    if (typeof nonce !== 'string' || !UUID_RE.test(nonce)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'nonce must be a UUID');
+    return { signature: this.#sign(Buffer.from(nonce, 'utf8')) };
+  }
+
+  #handleSignKeyControlChallenge(params = {}) {
+    this.#assertRateLimit('sign-key-control-challenge');
+    const { challenge } = params;
+    if (typeof challenge !== 'string' || challenge.length === 0 || challenge.length > 4096 || !HEX_RE.test(challenge)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'challenge must be non-empty hex');
+    }
+    // Signs the UTF-8 bytes of the hex STRING itself, not the hex-decoded bytes — matches the
+    // real convention both agentsafe-guard.mjs's original sign(challenge) and
+    // create-metamynd-agent's signChallengeHex already use (crypto.sign(..., Buffer.from(challenge,
+    // 'utf8'), ...)). Signing the decoded bytes instead would produce a signature the real
+    // verify-key backend endpoint does not accept — caught by daemon-keyprovider.smoke.mjs in
+    // agentsafe-guard, which is the first place this daemon was actually wired to a real caller.
+    return { signature: this.#sign(Buffer.from(challenge, 'utf8')) };
+  }
+
+  /**
+   * Signs a log-checkpoint anchor request (T11) — proves to the backend that THIS agent/service's
+   * daemon produced this checkpointHash, so the anchored HCS message can be trusted to actually
+   * come from the claimed identity. Unlike sign-authorize/sign-envelope, `agentDid` is never taken
+   * from `params` — it's always this daemon's own bound identity, the same way
+   * sign-key-control-challenge always signs under its own identity rather than trusting a
+   * caller-supplied one, so there is no identity-mismatch case to check here at all.
+   */
+  #handleSignLogCheckpoint(params = {}) {
+    this.#assertRateLimit('sign-log-checkpoint');
+    if (!this.#agentDid) throw new DaemonError('DAEMON_NOT_PROVISIONED');
+    const { checkpointHash, previousCheckpointHash, entryCount, nonce, issuedAt } = params;
+    if (typeof checkpointHash !== 'string' || !SHA256_HEX_RE.test(checkpointHash)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'checkpointHash must be a sha256 hex digest');
+    }
+    if (typeof previousCheckpointHash !== 'string' || !SHA256_HEX_RE.test(previousCheckpointHash)) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'previousCheckpointHash must be a sha256 hex digest');
+    }
+    if (!Number.isInteger(entryCount) || entryCount < 0) {
+      throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'entryCount must be a non-negative integer');
+    }
+    if (typeof nonce !== 'string' || !UUID_RE.test(nonce)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'nonce must be a UUID');
+    if (typeof issuedAt !== 'string' || !freshnessOk(issuedAt)) throw new DaemonError('DAEMON_MALFORMED_REQUEST', 'issuedAt outside freshness window');
+
+    const message = buildCheckpointAnchorMessage({ agentDid: this.#agentDid, checkpointHash, previousCheckpointHash, entryCount, nonce, issuedAt });
+    return { signature: this.#sign(Buffer.from(message, 'utf8')) };
+  }
+
+  /** Dispatch one admin-socket request. Only reachable while the admin socket is open (see startAdminServer). */
+  handleAdminRequest({ op, params = {} }) {
+    switch (op) {
+      case 'status':
+        return { hasKey: this.#unlocked ? this.keystore.hasKey() : false };
+      case 'generate-key': {
+        if (!this.#unlocked) throw new DaemonError('DAEMON_LOCKED');
+        try {
+          const publicKeyHex = this.keystore.generate({ allowRekey: !!params.allowRekey });
+          this.#log({ type: 'admin-generate-key', at: new Date().toISOString() });
+          return { publicKeyHex };
+        } catch (err) {
+          if (err instanceof KeyStoreError && err.code === 'KEY_ALREADY_EXISTS') throw new DaemonError('DAEMON_KEY_ALREADY_EXISTS');
+          throw new DaemonError('DAEMON_INTERNAL_ERROR');
+        }
+      }
+      default:
+        throw new DaemonError('DAEMON_UNKNOWN_OPERATION');
+    }
+  }
+
+  /** Starts the always-on signing socket. Resolves once listening. */
+  startSigningServer(socketPath) {
+    return startServer(socketPath, (socket) => {
+      attachJsonLines(socket, (line) => {
+        let req;
+        try {
+          req = JSON.parse(line);
+        } catch {
+          writeResponse(socket, null, { ok: false, error: { code: 'DAEMON_MALFORMED_REQUEST', message: 'invalid JSON' } });
+          return;
+        }
+        const requestId = typeof req.requestId === 'string' ? req.requestId : null;
+        if (req.protocolVersion !== PROTOCOL_VERSION) {
+          writeResponse(socket, requestId, { ok: false, error: { code: 'DAEMON_UNSUPPORTED_PROTOCOL_VERSION' } });
+          return;
+        }
+        try {
+          const result = this.handleSigningRequest(req);
+          this.#log({ type: 'sign', op: req.op, requestId, outcome: 'ok', at: new Date().toISOString() });
+          writeResponse(socket, requestId, { ok: true, result });
+        } catch (err) {
+          const code = err instanceof DaemonError ? err.code : 'DAEMON_INTERNAL_ERROR';
+          this.#log({ type: 'sign', op: req.op, requestId, outcome: code, at: new Date().toISOString() });
+          writeResponse(socket, requestId, { ok: false, error: { code, message: err.message } });
+        }
+      });
+    });
+  }
+
+  /**
+   * Starts the admin socket for exactly one successful operation or `timeoutMs`, whichever comes
+   * first, then closes it — deliberately not always-on the way the signing socket is (see
+   * docs/design/agent-key-custody-local-signer-daemon-plan.md, "The admin interface").
+   */
+  startAdminServer(socketPath, { timeoutMs = 60_000 } = {}) {
+    if (this.#adminOpen) throw new Error('admin socket already open');
+    this.#adminOpen = true;
+    return new Promise((resolve, reject) => {
+      let server;
+      const timer = setTimeout(() => server?.close(), timeoutMs);
+      // On Windows, {once, timeoutMs} lets the underlying secure-pipe relay own its own timeout
+      // too (windows-secure-pipe.mjs) — redundant with the `timer` above by design, not a bug:
+      // .close() is idempotent, and this layer's timer is still what Linux/macOS relies on since
+      // their branch of startServer has no timeout concept of its own.
+      startServer(socketPath, (socket) => {
+        attachJsonLines(socket, (line) => {
+          let req;
+          try {
+            req = JSON.parse(line);
+          } catch {
+            writeResponse(socket, null, { ok: false, error: { code: 'DAEMON_MALFORMED_REQUEST' } });
+            return;
+          }
+          const requestId = typeof req.requestId === 'string' ? req.requestId : null;
+          try {
+            const result = this.handleAdminRequest(req);
+            writeResponse(socket, requestId, { ok: true, result });
+            if (req.op === 'generate-key') {
+              clearTimeout(timer);
+              server.close();
+            }
+          } catch (err) {
+            const code = err instanceof DaemonError ? err.code : 'DAEMON_INTERNAL_ERROR';
+            writeResponse(socket, requestId, { ok: false, error: { code, message: err.message } });
+          }
+        });
+      }, { once: true, timeoutMs }).then((s) => {
+        server = s;
+        // If the pipe already closed before this .then() ever ran (its own overall timeoutMs
+        // elapsed with no connection — see startServer's own 'close' handling on Windows), a
+        // 'close' listener attached now would wait forever for an event that already happened.
+        // `.closed` is the synchronous escape hatch for exactly that race.
+        if (server.closed) {
+          this.#adminOpen = false;
+          resolve();
+          return;
+        }
+        server.on('close', () => {
+          this.#adminOpen = false;
+          resolve();
+        });
+      }, reject);
+    });
+  }
+}
+
+/** The short pipe name .NET's NamedPipeServerStream wants — the client-facing `\\.\pipe\...` path
+ *  and the server-side relay (windows-secure-pipe.mjs) both derive from this SAME function, so
+ *  they always agree on the name without either one hard-coding the other's format. */
+function windowsPipeName(logicalPath) {
+  const name = crypto.createHash('sha256').update(path.resolve(logicalPath)).digest('hex').slice(0, 32);
+  return `agentsafe-signer-${name}`;
+}
+
+/**
+ * Windows has no filesystem-path Unix domain sockets — Node requires the `\\.\pipe\` namespace
+ * there instead (the design doc's own "named pipe on Windows" distinction). A logical path is
+ * still passed in everywhere else in this module so callers don't need platform branches of
+ * their own; only this function and `startServer` below know the difference.
+ */
+export function toPlatformSocketPath(logicalPath) {
+  if (process.platform !== 'win32') return logicalPath;
+  return `\\\\.\\pipe\\${windowsPipeName(logicalPath)}`;
+}
+
+/**
+ * `{ once, timeoutMs }` route to the admin socket's one-shot lifecycle (real on every platform —
+ * see createSecurePipeOnce and the Linux/macOS branch below); omitted, it's the always-on signing
+ * socket. Resolves once the pipe/socket is genuinely ready to accept, not just "spawn requested" —
+ * on Windows that means waiting for the first relay instance's own ACL confirmation.
+ */
+function startServer(logicalPath, onConnection, { once = false, timeoutMs } = {}) {
+  if (process.platform === 'win32') {
+    const pipeName = windowsPipeName(logicalPath);
+    return new Promise((resolve, reject) => {
+      const server = once ? createSecurePipeOnce(pipeName, onConnection, { timeoutMs }) : createSecurePipePool(pipeName, onConnection, {});
+      server.once('aclVerified', (ruleCount) => {
+        // Real ACL restriction, not a filesystem mode bit — see windows-secure-pipe.mjs. A rule
+        // count other than 1 (current user only) means the pipe was NOT restricted as intended;
+        // fail loudly rather than silently serve on an unexpectedly-open pipe.
+        if (ruleCount !== 1) {
+          server.close();
+          reject(new Error(`named pipe ACL has ${ruleCount} rules, expected exactly 1 (current user only)`));
+          return;
+        }
+        resolve(server);
+      });
+      // Handles 'close' firing BEFORE 'aclVerified' ever did — two different reasons, two
+      // different outcomes. (1) createSecurePipeOnce exhausted its retries without the pipe ever
+      // becoming ready at all: emitted WITH an Error, and this promise REJECTS — before this
+      // existed, that case had no failure path at all and just hung forever. (2) The pipe's own
+      // overall timeoutMs elapsed with no client ever connecting — the normal, expected one-shot
+      // admin-socket lifecycle (see startAdminServer's own {once,timeoutMs}): emitted with NO
+      // error, and this promise still RESOLVES with the (already-closed) server — a caller like
+      // startAdminServer needs the server object either way to know its own #adminOpen bookkeeping
+      // is done, and checks `server.closed` synchronously for exactly this case (a 'close'
+      // listener attached only after this .then() fires would never see an event that already
+      // happened). A normal close AFTER a successful 'aclVerified'-driven resolve() is a harmless
+      // no-op here — whichever of resolve/reject settles a promise first wins.
+      server.once('close', (err) => {
+        if (err) reject(err);
+        else resolve(server);
+      });
+    });
+  }
+  const socketPath = logicalPath;
+  return new Promise((resolve, reject) => {
+    const server = net.createServer(onConnection);
+    server.on('error', reject);
+    if (fs.existsSync(socketPath)) fs.unlinkSync(socketPath);
+    fs.mkdirSync(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+    server.listen(socketPath, () => {
+      fs.chmodSync(socketPath, 0o600);
+      resolve(server);
+    });
+  });
+}
+
+function defaultLogger(stateDir) {
+  const logPath = path.join(stateDir, 'signer.log');
+  return (entry) => {
+    try {
+      fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', { mode: 0o600 });
+    } catch {
+      /* logging must never crash the daemon */
+    }
+  };
+}