@metamynd/agentsafe-signer 0.13.0

package/merkle.mjs

@@ -0,0 +1,68 @@
+// merkle.mjs — a minimal, dependency-light Merkle tree, ported line-for-line from the platform's
+// own backend/src/features/magp/merkle.ts (same algorithm mmt-graph already ported for its own
+// package) rather than importing it: agentsafe-signer has no dependency on the backend or any
+// other package in this monorepo, by design, so the handful of pure functions get copied instead.
+// Used by log-checkpoint.mjs to batch the daemon's own request log into periodic, chained,
+// tamper-evident checkpoints (docs/design/agent-key-custody-local-signer-daemon-plan.md, T11).
+//
+// Pure and deterministic: sha256 only, no clock/IO. Leaves and nodes are lower-case hex; an odd
+// node is paired with itself (Bitcoin-style duplication).
+import { createHash } from 'node:crypto';
+
+/** sha256 → lower-case hex. */
+export function sha256Hex(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/** Hash two hex nodes by concatenating their raw bytes (not the hex text). */
+function hashNodes(a, b) {
+  return sha256Hex(Buffer.concat([Buffer.from(a, 'hex'), Buffer.from(b, 'hex')]));
+}
+
+/** One level of the tree: pair up nodes (duplicating a lone last node) and hash. */
+function nextLevel(level) {
+  const next = [];
+  for (let i = 0; i < level.length; i += 2) {
+    const left = level[i];
+    const right = i + 1 < level.length ? level[i + 1] : left;
+    next.push(hashNodes(left, right));
+  }
+  return next;
+}
+
+/** The Merkle root over the ordered leaves. Single leaf → itself; empty → sha256(""). */
+export function merkleRoot(leaves) {
+  if (leaves.length === 0) return sha256Hex('');
+  let level = leaves.slice();
+  while (level.length > 1) level = nextLevel(level);
+  return level[0];
+}
+
+/**
+ * The inclusion proof for `leaves[index]` — the sibling hashes from leaf to root.
+ * @returns {{sibling: string, position: 'left'|'right'}[]}
+ */
+export function merkleProof(leaves, index) {
+  if (index < 0 || index >= leaves.length) throw new Error('merkleProof: index out of range');
+  const proof = [];
+  let level = leaves.slice();
+  let idx = index;
+  while (level.length > 1) {
+    const isRightNode = idx % 2 === 1;
+    const pairIdx = isRightNode ? idx - 1 : idx + 1;
+    const sibling = pairIdx < level.length ? level[pairIdx] : level[idx]; // lone last node pairs with itself
+    proof.push({ sibling, position: isRightNode ? 'left' : 'right' });
+    level = nextLevel(level);
+    idx = Math.floor(idx / 2);
+  }
+  return proof;
+}
+
+/** Verify a leaf's inclusion proof reproduces the anchored root. */
+export function verifyMerkleProof(leaf, proof, root) {
+  let computed = leaf;
+  for (const step of proof) {
+    computed = step.position === 'left' ? hashNodes(step.sibling, computed) : hashNodes(computed, step.sibling);
+  }
+  return computed === root;
+}

package/migrate.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// migrate.mjs — key-loss recovery / migration CLI (docs/design/agent-key-custody-local-signer-
+// daemon-plan.md's own README used to list this as a real gap: "No migration or fresh-
+// provisioning CLI driving rotateNetworkIdentity ... end to end — the daemon exposes what those
+// flows need (generate-key, sign-key-control-challenge), but nothing wires them together yet.").
+//
+// Rotates an EXISTING agent's network identity onto a FRESH key the daemon generates and never
+// exposes, using the backend's real rotateNetworkIdentity (BYOK path — the server never sees a
+// private key) plus the verify-key/regenerate-challenge proof-of-possession trio
+// (backend/src/features/agent-identity/agent-network-identity.service.ts) rather than inventing
+// a parallel mechanism. Before that trio existed, a BYOK rotation had NO proof anyone held the
+// matching private key at all — this script exists specifically to drive the now-real flow.
+//
+// Requires TWO sockets from an already-running daemon: its ADMIN socket open (generate-key — the
+// admin socket is a brief, operator-initiated provisioning window, not always-on: `agentsafe-
+// signer start --admin`) and its normal SIGNING socket (sign-key-control-challenge, always on).
+// Requires a bearer token from the backend's own session auth — rotateNetworkIdentity is a
+// sensitive, human-authorized, ownership-checked action, deliberately NOT something an agent's
+// own self-signed request can authorize on its own (unlike, say, T11's log-checkpoint anchoring,
+// which genuinely is a low-stakes self-authenticating action).
+//
+// Does NOT hot-swap the identity of an already-running daemon process — this package's identity
+// binding is deliberately startup-only (`--identity`), not a mutable admin operation; after a
+// successful migration, restart the daemon bound to the new DID (this script prints the exact
+// command rather than running it).
+//
+//   node migrate.mjs --state-dir ./.signer --api-url https://api.example.com/v1 \
+//     --auth-token $TOKEN --ref <agentIdentityId-or-did> --network-identity-id <id>
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, daemonRequest } from './daemon-client.mjs';
+
+async function apiCall(apiUrl, method, urlPath, authToken, body) {
+  const res = await fetch(new URL(urlPath, apiUrl), {
+    method,
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${authToken}` },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json?.success) {
+    throw new Error(`${method} ${urlPath} failed (HTTP ${res.status}): ${json?.message ?? 'no response body'}`);
+  }
+  return json.data;
+}
+
+/**
+ * Rotates the network identity at `networkIdentityId` onto a fresh key the daemon itself
+ * generates: (1) generate-key on the admin socket (`allowRekey: true` — harmless even if the
+ * daemon has never held a key before, and required if it has); (2) POST .../rotate with the new
+ * publicKey (BYOK); (3) sign-key-control-challenge over the returned keyChallenge on the signing
+ * socket; (4) POST .../verify-key with that signature. Skips steps 3-4 if the rotation already
+ * came back verified (a managed, non-BYOK path — not the normal case here, but handled rather
+ * than assumed impossible). Returns the new DID and the exact restart command, rather than
+ * hot-swapping the running daemon's identity itself — see this file's own header on why.
+ */
+export async function runMigrate({ stateDir, socketPath, adminSocketPath, apiUrl, authToken, ref, networkIdentityId }) {
+  const { publicKeyHex } = await daemonRequest(adminSocketPath, 'generate-key', { allowRekey: true });
+
+  const rotated = await apiCall(
+    apiUrl,
+    'POST',
+    `/agent-identity/${encodeURIComponent(ref)}/network-identities/${encodeURIComponent(networkIdentityId)}/rotate`,
+    authToken,
+    { publicKey: publicKeyHex },
+  );
+
+  if (!rotated.keyVerifiedAt) {
+    if (!rotated.keyChallenge) throw new Error(`rotate response has no keyChallenge to prove possession with — got: ${JSON.stringify(rotated)}`);
+    const { signature } = await daemonRequest(socketPath, 'sign-key-control-challenge', { challenge: rotated.keyChallenge });
+    await apiCall(
+      apiUrl,
+      'POST',
+      `/agent-identity/${encodeURIComponent(ref)}/network-identities/${encodeURIComponent(rotated.networkIdentityId)}/verify-key`,
+      authToken,
+      { signature },
+    );
+  }
+
+  return {
+    did: rotated.did,
+    networkIdentityId: rotated.networkIdentityId,
+    restartCommand: `node cli.mjs start --state-dir ${stateDir} --role agent --identity ${rotated.did}`,
+  };
+}
+
+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 adminSocketPath = args['admin-socket-path'] ?? path.join(stateDir, 'signer-admin.sock');
+  const apiUrl = args['api-url'] ?? process.env.AGENTSAFE_SIGNER_API_URL;
+  const authToken = args['auth-token'] ?? process.env.AGENTSAFE_SIGNER_AUTH_TOKEN;
+  const ref = args.ref;
+  const networkIdentityId = args['network-identity-id'];
+
+  const missing = [];
+  if (!apiUrl) missing.push('--api-url (or AGENTSAFE_SIGNER_API_URL)');
+  if (!authToken) missing.push('--auth-token (or AGENTSAFE_SIGNER_AUTH_TOKEN)');
+  if (!ref) missing.push('--ref <agentIdentityId or DID>');
+  if (!networkIdentityId) missing.push('--network-identity-id <id>');
+  if (missing.length > 0) {
+    console.error(`agentsafe-signer migrate requires: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log('[migrate] asking the daemon to generate a fresh key (requires --admin to be open right now)...');
+  const result = await runMigrate({ stateDir, socketPath, adminSocketPath, apiUrl, authToken, ref, networkIdentityId });
+  console.log(`[migrate] rotated to ${result.did} and verified proof of possession.`);
+  console.log('[migrate] restart the daemon bound to the new identity:');
+  console.log(`  ${result.restartCommand}`);
+}
+
+// Only run as a CLI when invoked directly (`node migrate.mjs`), not when cli.mjs imports
+// runMigrate from this same file.
+if (process.argv[1] && path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1])) {
+  main().catch((err) => {
+    console.error('[migrate] fatal:', err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@metamynd/agentsafe-signer",
+  "version": "0.13.0",
+  "description": "Local signer daemon for AgentSafe agent/service keys \u2014 the key never enters the calling guard's own process. See docs/design/agent-key-custody-local-signer-daemon-plan.md.",
+  "type": "module",
+  "main": "./daemon.mjs",
+  "exports": {
+    ".": "./daemon.mjs",
+    "./keystore": "./keystore.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "daemon.mjs",
+    "windows-secure-pipe.mjs",
+    "merkle.mjs",
+    "log-checkpoint.mjs",
+    "log-anchor.mjs",
+    "migrate.mjs",
+    "daemon-client.mjs",
+    "keystore.mjs",
+    "secure-memory.mjs",
+    "kek-backends.mjs",
+    "service-installer.mjs",
+    "cli.mjs",
+    "policy-core.mjs",
+    "governance-envelope.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node daemon-protocol.smoke.mjs && node daemon-key-exfiltration.smoke.mjs && node kek-backends.smoke.mjs && node service-installer.smoke.mjs && node daemon-envelope-parity.smoke.mjs && node daemon-admin-socket.smoke.mjs && node daemon-log-integrity.smoke.mjs && node daemon-socket-permissions.smoke.mjs && node daemon-hardening.smoke.mjs && node daemon-hardening-tier2.smoke.mjs && node log-anchor.smoke.mjs && node migrate.smoke.mjs && node secure-memory.smoke.mjs",
+    "start": "node cli.mjs"
+  },
+  "dependencies": {
+    "sodium-native": "^4.3.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "author": "MetaMynd",
+  "license": "MIT",
+  "homepage": "https://metamynd.ai",
+  "bin": {
+    "agentsafe-signer": "./cli.mjs"
+  }
+}