@ijfw/memory-server 1.4.1 → 1.4.4

package/src/dispatch/registry-cli.js

@@ -0,0 +1,339 @@
+/**
+ * dispatch/registry-cli.js — IJFW v1.4.3/B14 + B17 registry CLI handlers.
+ *
+ * Frozen export contract (Wave A invariants):
+ *   export const handlers = {
+ *     '<subcommand>': async (args, ctx) => ({ ok, output?, error? }),
+ *     ...
+ *   };
+ *   export const subcommandHelp = {
+ *     '<subcommand>': 'one-line description',
+ *     ...
+ *   };
+ *
+ * Subcommands owned by this module:
+ *   - registry-list
+ *   - registry-add <name> <url> [<meta-key-path>]
+ *   - registry-remove <name>
+ *   - registry-prioritize <name> <position>
+ *   - registry-status
+ *   - trust-registry --emergency [<url>]
+ *
+ * Phase D will wire these into dispatch/extension.js via
+ * `Object.entries(handlers)`. Each handler accepts a token array (already
+ * tokenized + dequoted) and the dispatch ctx (cwd, homedir, etc.).
+ */
+
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir as osHomedir } from 'node:os';
+import { createPublicKey } from 'node:crypto';
+
+import {
+  loadRegistrySources,
+  refreshTrustFromAllRegistries,
+  readSourceCache,
+  RegistrySourcesError,
+  META_KEY_SENTINEL,
+  IJFW_REGISTRY_META_KEY_PEM,
+  SOURCE_NAME_PATTERN,
+} from '../extension-registry.js';
+
+function homedir(ctx) {
+  return (ctx && ctx.homedir) || osHomedir();
+}
+
+function registriesConfigPath(ctx) {
+  return join(homedir(ctx), '.ijfw', 'registries.json');
+}
+
+async function readRegistriesFile(ctx) {
+  const path = registriesConfigPath(ctx);
+  try {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.registries)) {
+      throw new Error('registries.json: invalid shape');
+    }
+    return { path, doc: parsed };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        path,
+        doc: { schema_version: '1.0', registries: [] },
+      };
+    }
+    throw err;
+  }
+}
+
+async function writeRegistriesFile(ctx, doc) {
+  const path = registriesConfigPath(ctx);
+  await mkdir(join(homedir(ctx), '.ijfw'), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+  const { rename } = await import('node:fs/promises');
+  await rename(tmp, path);
+}
+
+function tokenize(args) {
+  if (Array.isArray(args)) return args.filter((x) => x !== undefined && x !== null);
+  const s = String(args || '').trim();
+  if (!s) return [];
+  // Simple whitespace split for CLI surface.
+  return s.split(/\s+/);
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * registry-list — print all configured registries in priority order.
+ */
+async function registryList(_args, _ctx) {
+  let sources;
+  try {
+    sources = await loadRegistrySources();
+  } catch (err) {
+    if (err instanceof RegistrySourcesError) {
+      return { ok: false, error: `registries.json invalid (${err.reason}): ${err.message}` };
+    }
+    throw err;
+  }
+  const lines = ['IJFW Registry Sources (priority order):', ''];
+  for (const src of sources) {
+    const usingEmbedded =
+      src.meta_key_pem === IJFW_REGISTRY_META_KEY_PEM ? ' [meta_key=<embedded>]' : '';
+    lines.push(`  [${src.priority}] ${src.name}`);
+    lines.push(`        url: ${src.url}`);
+    lines.push(
+      `        ttl: publishers=${Math.round(src.publisher_ttl_ms / 1000)}s revocation=${Math.round(src.revocation_ttl_ms / 1000)}s${usingEmbedded}`,
+    );
+  }
+  return { ok: true, output: lines.join('\n') };
+}
+
+/**
+ * registry-add <name> <url> [<meta-key-path>]
+ *
+ * Appends to ~/.ijfw/registries.json. Validates name/url/PEM. Refuses
+ * duplicate names. Persists in priority-append order.
+ */
+async function registryAdd(args, ctx) {
+  const tokens = tokenize(args);
+  if (tokens.length < 2) {
+    return { ok: false, error: 'usage: registry-add <name> <url> [<meta-key-path>]' };
+  }
+  const [name, url, metaKeyPath] = tokens;
+
+  if (!SOURCE_NAME_PATTERN.test(name)) {
+    return { ok: false, error: `name must match /^[a-z0-9_-]+$/, got '${name}'` };
+  }
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    return { ok: false, error: `invalid URL: ${url}` };
+  }
+  if (parsedUrl.protocol !== 'https:') {
+    return { ok: false, error: `url must use HTTPS, got ${parsedUrl.protocol}` };
+  }
+
+  let metaKeyPem = META_KEY_SENTINEL;
+  if (metaKeyPath) {
+    let raw;
+    try {
+      raw = await readFile(metaKeyPath, 'utf8');
+    } catch (err) {
+      return { ok: false, error: `cannot read meta-key at ${metaKeyPath}: ${err.message}` };
+    }
+    try {
+      createPublicKey(raw);
+    } catch (err) {
+      return { ok: false, error: `meta-key PEM parse failed: ${err.message}` };
+    }
+    metaKeyPem = raw;
+  }
+
+  const { doc } = await readRegistriesFile(ctx);
+  if (doc.registries.some((r) => r.name === name)) {
+    return { ok: false, error: `registry '${name}' already exists` };
+  }
+  const nextPriority =
+    doc.registries.reduce((max, r) => (typeof r.priority === 'number' ? Math.max(max, r.priority) : max), -1) + 1;
+  doc.registries.push({
+    name,
+    url,
+    meta_key_pem: metaKeyPem,
+    priority: nextPriority,
+    publisher_ttl_ms: 24 * 60 * 60 * 1000,
+    revocation_ttl_ms: 5 * 60 * 1000,
+  });
+  await writeRegistriesFile(ctx, doc);
+  return { ok: true, output: `added registry '${name}' at priority ${nextPriority}` };
+}
+
+/**
+ * registry-remove <name>
+ */
+async function registryRemove(args, ctx) {
+  const tokens = tokenize(args);
+  if (tokens.length < 1) {
+    return { ok: false, error: 'usage: registry-remove <name>' };
+  }
+  const name = tokens[0];
+  const { doc } = await readRegistriesFile(ctx);
+  const idx = doc.registries.findIndex((r) => r.name === name);
+  if (idx === -1) {
+    return { ok: false, error: `registry '${name}' not found` };
+  }
+  doc.registries.splice(idx, 1);
+  await writeRegistriesFile(ctx, doc);
+  return { ok: true, output: `removed registry '${name}'` };
+}
+
+/**
+ * registry-prioritize <name> <position>
+ */
+async function registryPrioritize(args, ctx) {
+  const tokens = tokenize(args);
+  if (tokens.length < 2) {
+    return { ok: false, error: 'usage: registry-prioritize <name> <position>' };
+  }
+  const [name, posRaw] = tokens;
+  const position = Number.parseInt(posRaw, 10);
+  if (!Number.isFinite(position)) {
+    return { ok: false, error: `position must be a non-negative integer, got '${posRaw}'` };
+  }
+  const { doc } = await readRegistriesFile(ctx);
+  const target = doc.registries.find((r) => r.name === name);
+  if (!target) {
+    return { ok: false, error: `registry '${name}' not found` };
+  }
+  target.priority = position;
+  doc.registries.sort((a, b) => (a.priority || 0) - (b.priority || 0));
+  // Renumber to ensure unique priorities.
+  doc.registries.forEach((r, i) => {
+    r.priority = i;
+  });
+  await writeRegistriesFile(ctx, doc);
+  return { ok: true, output: `set '${name}' to priority ${position} (renumbered)` };
+}
+
+/**
+ * registry-status — per-source cache age + fetch state.
+ */
+async function registryStatus(_args, _ctx) {
+  let sources;
+  try {
+    sources = await loadRegistrySources();
+  } catch (err) {
+    if (err instanceof RegistrySourcesError) {
+      return { ok: false, error: `registries.json invalid (${err.reason}): ${err.message}` };
+    }
+    throw err;
+  }
+  const lines = ['IJFW Registry Status:', ''];
+  for (const src of sources) {
+    const { cache, corrupt, reason } = await readSourceCache(src);
+    lines.push(`  [${src.priority}] ${src.name} (${src.url})`);
+    if (corrupt) {
+      lines.push(`        CORRUPT (${reason}) — next refresh will rebuild`);
+      continue;
+    }
+    const pubAt = cache.publishers_fetched_at || '(never)';
+    const revAt = cache.revocation_fetched_at || '(never)';
+    const pubCount = cache.publishers ? Object.keys(cache.publishers).length : 0;
+    const revCount = Array.isArray(cache.revoked) ? cache.revoked.length : 0;
+    lines.push(`        publishers_fetched_at: ${pubAt} (${pubCount} entries)`);
+    lines.push(`        revocation_fetched_at: ${revAt} (${revCount} revoked)`);
+  }
+  return { ok: true, output: lines.join('\n') };
+}
+
+/**
+ * trust-registry --emergency [<url>] — bypass caches; force fresh fetch.
+ *
+ * Without --emergency, fall through to the regular split-TTL path.
+ */
+async function trustRegistry(args, _ctx) {
+  const tokens = tokenize(args);
+  const emergency = tokens.includes('--emergency');
+  const remaining = tokens.filter((t) => t !== '--emergency');
+
+  // Optional URL arg post-emergency. With a URL we target only that single
+  // source via loadRegistrySources()'s back-compat fall-back. Without, full
+  // federation refresh.
+  const url = remaining[0];
+
+  const opts = { emergency };
+  if (url) {
+    // Synthesize a one-shot source descriptor.
+    opts.sources = [
+      {
+        name: 'cli',
+        url,
+        meta_key_pem: IJFW_REGISTRY_META_KEY_PEM,
+        priority: 0,
+        publisher_ttl_ms: 24 * 60 * 60 * 1000,
+        revocation_ttl_ms: 5 * 60 * 1000,
+      },
+    ];
+  }
+
+  let result;
+  try {
+    result = await refreshTrustFromAllRegistries(opts);
+  } catch (err) {
+    if (err instanceof RegistrySourcesError) {
+      return { ok: false, error: `registries.json invalid (${err.reason}): ${err.message}` };
+    }
+    return { ok: false, error: err.message };
+  }
+  if (!result.ok) {
+    return { ok: false, error: result.error || 'refresh failed' };
+  }
+  const summary = result.multi
+    ? `sources=${result.multi.sources.length} global_revocations=${result.multi.global_revocations.length} conflicts=${result.multi.conflicts.length}`
+    : 'no diff';
+  const warnings = result.warnings && result.warnings.length > 0
+    ? `\nwarnings:\n${result.warnings.map((w) => `  - ${w}`).join('\n')}`
+    : '';
+  return {
+    ok: true,
+    output: `trust-registry${emergency ? ' --emergency' : ''}: ${summary}${warnings}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Frozen exports (Wave-A invariant)
+// ---------------------------------------------------------------------------
+
+export const handlers = Object.freeze({
+  'registry-list': registryList,
+  'registry-add': registryAdd,
+  'registry-remove': registryRemove,
+  'registry-prioritize': registryPrioritize,
+  'registry-status': registryStatus,
+  'trust-registry': trustRegistry,
+});
+
+export const subcommandHelp = Object.freeze({
+  'registry-list': 'list configured registries in priority order',
+  'registry-add': 'add <name> <url> [<meta-key-path>] — append a registry source',
+  'registry-remove': 'remove <name> — remove a registry source by name',
+  'registry-prioritize': 'prioritize <name> <position> — change a source\'s priority',
+  'registry-status': 'show per-source cache state (publishers + revocation TTLs)',
+  'trust-registry': 'refresh trust from all sources; --emergency bypasses cache',
+});
+
+// Helper for tests
+export const _testInternals = Object.freeze({
+  registriesConfigPath,
+  readRegistriesFile,
+  writeRegistriesFile,
+});
+
+// Avoid an "unused" lint hit on `stat` (kept for future use).
+void stat;

package/src/dispatch/signer-cli.js

@@ -0,0 +1,311 @@
+/**
+ * dispatch/signer-cli.js — IJFW v1.4.3 W9-A2 / B15
+ *
+ * CLI handlers for signing-key management. Exported as the frozen
+ * `{ handlers, subcommandHelp }` shape so the Phase D orchestrator can wire
+ * them into the top-level dispatch table without per-area editing.
+ *
+ * Subcommands:
+ *
+ *   keygen <author> [--backend software|ssh-agent] [--ssh-key-comment <c>]
+ *     - Default backend: software (existing v1.4.0 behavior — generates a
+ *       fresh Ed25519 keypair on disk).
+ *     - --backend ssh-agent: NO private-key generation in IJFW. Connects
+ *       to the running SSH agent, enumerates Ed25519 identities, selects
+ *       one to enroll. Writes only the public material:
+ *         ~/.ijfw/keys/<keyId>/public.pem
+ *         ~/.ijfw/keys/<keyId>/backend.json
+ *           { backend, pubkey_blob_hex, keyId, ssh_key_comment }
+ *       The comment is recorded for display only; sign-time identity
+ *       selection matches on pubkey_blob_hex (SEC-H-03).
+ *
+ *   keygen-fido2 <author>
+ *     - Deferred stub. Prints a message routing users to ssh-agent or the
+ *       default software backend. Exits 0 (deferred, not failed).
+ *
+ * Spec: .planning/1.4.3/HANDOFF-1.4.3.md §B15
+ */
+
+import { mkdir, writeFile, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  generatePublisherKeypair,
+} from '../extension-signer.js';
+import {
+  listAgentIdentities,
+  pubkeyBlobFromPem,
+  ed25519PemFromRaw,
+  publicKeyFingerprint,
+  _testInternals,
+} from '../hardware-signer.js';
+
+/**
+ * Parse argv-style array (or whitespace-split string) into `{ positional, flags }`.
+ * Supports `--flag` (boolean) and `--flag value` (string value).
+ *
+ * @param {string|string[]} input
+ * @returns {{ positional: string[], flags: Record<string, string|boolean> }}
+ */
+function parseArgs(input) {
+  const tokens = Array.isArray(input)
+    ? input.slice()
+    : String(input || '').trim().split(/\s+/).filter(Boolean);
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok.startsWith('--')) {
+      const name = tok.slice(2);
+      const next = tokens[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[name] = next;
+        i += 1;
+      } else {
+        flags[name] = true;
+      }
+    } else {
+      positional.push(tok);
+    }
+  }
+  return { positional, flags };
+}
+
+/**
+ * Extract the SSH wire ssh-ed25519 alg prefix used for filtering Ed25519
+ * identities returned by the agent.
+ */
+const ED25519_ALG_PREFIX = _testInternals.sshWireString(_testInternals.SSH_ED25519_ALG);
+
+/**
+ * Build the per-key directory path under the (possibly overridden) home.
+ */
+function keysDir(home, keyId) {
+  return join(home, '.ijfw', 'keys', keyId);
+}
+
+/**
+ * Convert an SSH-wire Ed25519 pubkey blob back into PEM. Useful when
+ * enrolling — the agent gives us the wire blob, but downstream verify
+ * paths want PEM.
+ *
+ * @param {Buffer} blob
+ * @returns {string} PEM
+ */
+function ed25519PemFromBlob(blob) {
+  // Blob shape: ssh-string("ssh-ed25519") || ssh-string(raw32).
+  // Skip the alg prefix; the trailing string is the raw key.
+  const algLen = ED25519_ALG_PREFIX.length;
+  // The raw key follows; the leading 4 bytes are the length (always 32).
+  const raw = blob.slice(algLen + 4);
+  if (raw.length !== 32) {
+    throw new Error(`Expected 32-byte Ed25519 raw key, got ${raw.length}`);
+  }
+  return ed25519PemFromRaw(raw);
+}
+
+/**
+ * Filter agent identities to Ed25519 only.
+ *
+ * @param {Array<{blob: Buffer, comment: string}>} identities
+ * @returns {Array<{blob: Buffer, comment: string}>}
+ */
+function ed25519Only(identities) {
+  return identities.filter(
+    i => i.blob.length >= ED25519_ALG_PREFIX.length
+      && i.blob.slice(0, ED25519_ALG_PREFIX.length).equals(ED25519_ALG_PREFIX),
+  );
+}
+
+/**
+ * Enrol an existing SSH-agent identity as an IJFW publisher key.
+ *
+ * Workflow:
+ *   1. Connect to SSH_AUTH_SOCK (errors clearly if unavailable).
+ *   2. List identities; filter to Ed25519.
+ *   3. Resolve a single candidate. Selection precedence:
+ *      a. If --ssh-key-comment is provided, prefer that comment.
+ *      b. Otherwise: exactly 1 Ed25519 identity → auto-pick. Multiple
+ *         identities → fail with usage hint (interactive picker not yet
+ *         wired into MCP transport).
+ *   4. Compute keyId = sha256(SPKI-DER of the agent-key's PEM).
+ *   5. Write public.pem + backend.json to ~/.ijfw/keys/<keyId>/.
+ *
+ * @param {object} args
+ * @param {string} args.author informational author label
+ * @param {string} [args.sshKeyComment] disambiguator
+ * @param {string} [args.home] override ~/.ijfw root (test isolation)
+ * @param {string} [args.socketPath] override SSH_AUTH_SOCK (test isolation)
+ * @returns {Promise<{ ok: true, keyId: string, dir: string, ssh_key_comment: string, backend: 'ssh-agent' } | { ok: false, error: string }>}
+ */
+async function enrolSshAgentKey(args) {
+  const home = args.home || homedir();
+  let identities;
+  try {
+    identities = await listAgentIdentities(args.socketPath);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const candidates = ed25519Only(identities);
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      error: 'SSH agent has no Ed25519 identities; add one with `ssh-keygen -t ed25519` and `ssh-add`',
+    };
+  }
+  let chosen;
+  if (args.sshKeyComment) {
+    const matches = candidates.filter(c => c.comment === args.sshKeyComment);
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        error: `SSH agent has no Ed25519 identity with comment ${JSON.stringify(args.sshKeyComment)}`,
+      };
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        error: `Multiple SSH agent identities share comment ${JSON.stringify(args.sshKeyComment)}; comments are not unique — disambiguate by re-running ssh-add or removing duplicates`,
+      };
+    }
+    chosen = matches[0];
+  } else if (candidates.length === 1) {
+    chosen = candidates[0];
+  } else {
+    return {
+      ok: false,
+      error: `Multiple Ed25519 identities in SSH agent (${candidates.length}); pass --ssh-key-comment <c> to disambiguate. Comments seen: ${candidates.map(c => JSON.stringify(c.comment)).join(', ')}`,
+    };
+  }
+
+  let pem;
+  try {
+    pem = ed25519PemFromBlob(chosen.blob);
+  } catch (err) {
+    return { ok: false, error: `failed to convert agent blob to PEM: ${err.message}` };
+  }
+  const keyId = publicKeyFingerprint(pem);
+  // Belt-and-braces self-consistency check: the blob we just stored should
+  // round-trip back through PEM and yield the same blob.
+  const roundTripBlob = pubkeyBlobFromPem(pem);
+  if (!roundTripBlob.equals(chosen.blob)) {
+    return {
+      ok: false,
+      error: 'internal: pubkey blob round-trip via PEM differed; refusing to enrol',
+    };
+  }
+
+  const dir = keysDir(home, keyId);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  try { await chmod(dir, 0o700); } catch { /* best-effort */ }
+  await writeFile(join(dir, 'public.pem'), pem, 'utf8');
+  try { await chmod(join(dir, 'public.pem'), 0o644); } catch { /* best-effort */ }
+  const backendJson = {
+    backend: 'ssh-agent',
+    pubkey_blob_hex: chosen.blob.toString('hex'),
+    keyId,
+    ssh_key_comment: chosen.comment, // display only — never used for matching
+  };
+  await writeFile(
+    join(dir, 'backend.json'),
+    JSON.stringify(backendJson, null, 2) + '\n',
+    'utf8',
+  );
+  if (typeof args.author === 'string' && args.author.length > 0) {
+    try {
+      await writeFile(
+        join(dir, 'author.txt'),
+        `${args.author}\n${new Date().toISOString()}\n`,
+        'utf8',
+      );
+    } catch { /* non-fatal */ }
+  }
+
+  return {
+    ok: true,
+    keyId,
+    dir,
+    ssh_key_comment: chosen.comment,
+    backend: 'ssh-agent',
+  };
+}
+
+/**
+ * keygen handler. Dispatches to software (default) or ssh-agent backend
+ * per --backend.
+ *
+ * @param {string|string[]} args
+ * @param {object} [ctx]
+ * @returns {Promise<object>}
+ */
+async function keygenHandler(args, ctx = {}) {
+  const { positional, flags } = parseArgs(args);
+  const author = positional[0] || '';
+  const backend = flags.backend === true ? undefined : flags.backend;
+
+  if (backend === undefined || backend === 'software') {
+    const kp = await generatePublisherKeypair(author);
+    return {
+      ok: true,
+      backend: 'software',
+      keyId: kp.keyId,
+      dir: kp.dir,
+      publicKey: kp.publicKey,
+    };
+  }
+
+  if (backend === 'ssh-agent') {
+    const sshKeyComment = flags['ssh-key-comment'] === true
+      ? undefined
+      : flags['ssh-key-comment'];
+    return enrolSshAgentKey({
+      author,
+      sshKeyComment,
+      home: ctx.home,
+      socketPath: ctx.socketPath,
+    });
+  }
+
+  // Fail-closed per SEC-L-02. Unknown backend names must not silently fall
+  // through to software.
+  return {
+    ok: false,
+    error: `Unsupported --backend value ${JSON.stringify(backend)}; valid: software, ssh-agent`,
+  };
+}
+
+/**
+ * keygen-fido2 handler — deferred stub.
+ *
+ * Native libfido2 bindings would be IJFW's first native prod dep; that's
+ * a v1.5.0+ architecture decision. For v1.4.3, FIDO2-backed signing is
+ * available transitively via ssh-agent (modern YubiKey/Solokey speak
+ * SSH agent natively).
+ *
+ * @returns {Promise<{ ok: true, deferred: true, message: string }>}
+ */
+async function keygenFido2Handler(_args, ctx = {}) {
+  const msg = 'FIDO2/libfido2 path deferred to v1.5.0; use --backend ssh-agent or default software backend';
+  // Write to stderr for CLI visibility without disturbing JSON-stdout
+  // consumers. Optionally inject a writer via ctx for tests.
+  const stderr = ctx.stderr || process.stderr;
+  try { stderr.write(`${msg}\n`); } catch { /* ignore */ }
+  return { ok: true, deferred: true, message: msg };
+}
+
+export const handlers = Object.freeze({
+  keygen: keygenHandler,
+  'keygen-fido2': keygenFido2Handler,
+});
+
+export const subcommandHelp = Object.freeze({
+  keygen: 'keygen <author> [--backend software|ssh-agent] [--ssh-key-comment <c>] — generate or enrol a publisher signing key',
+  'keygen-fido2': 'keygen-fido2 <author> — deferred to v1.5.0; use --backend ssh-agent instead',
+});
+
+// Test-only exports.
+export const _testOnly = Object.freeze({
+  parseArgs,
+  enrolSshAgentKey,
+});