@ijfw/memory-server 1.4.0 → 1.4.3

package/src/dispatch/extension.js

@@ -29,7 +29,19 @@ import {
   addTrustedPublisher,
   removeTrustedPublisher,
   readTrustedPublishers,
+  loadPublisherKeypair,
+  signRotationToken,
+  verifyRotationToken,
 } from '../extension-signer.js';
+import {
+  refreshTrustFromRegistry,
+  readCachedRegistry,
+  verifyRegistry,
+  keygenMeta,
+  signRegistry,
+  verifyRegistryFile,
+  DEFAULT_REGISTRY_URL,
+} from '../extension-registry.js';
 import {
   deployExtensionSkillsToPlatforms,
   deployExtensionToAgentsMd,
@@ -355,6 +367,220 @@ async function deployOneExtension({ scope, name, extDir, projectRoot, result })
   }
 }
 
+// === B6: Registry commands ================================================
+
+async function cmdTrustRegistry({ args }) {
+  const url = args.trim() || DEFAULT_REGISTRY_URL;
+  try {
+    const r = await refreshTrustFromRegistry(url);
+    if (!r.ok) return { ok: false, command: 'trust-registry', error: r.error };
+    const lines = [];
+    if (r.fromCache) {
+      lines.push('(loaded from cache — network unavailable)');
+    } else if (r.diff) {
+      for (const kid of r.diff.added) lines.push(`+ added: ${kid}`);
+      for (const kid of r.diff.removed) lines.push(`- removed (revoked): ${kid}`);
+      for (const kid of r.diff.unchanged) lines.push(`  unchanged: ${kid}`);
+      for (const kid of r.diff.rejected) lines.push(`! rejected: ${kid}`);
+      if (lines.length === 0) lines.push('registry applied — no changes');
+    }
+    for (const w of (r.warnings || [])) lines.push(`[warn] ${w}`);
+    return { ok: true, command: 'trust-registry', result: { url, diff: r.diff, fromCache: r.fromCache, lines } };
+  } catch (err) {
+    return { ok: false, command: 'trust-registry', error: err.message };
+  }
+}
+
+async function cmdRegistryStatus() {
+  try {
+    const cached = await readCachedRegistry();
+    if (!cached.registry) {
+      return { ok: true, command: 'registry-status', result: { cached: false, message: 'no cached registry' } };
+    }
+    const ageMs = cached.cachedAt ? Date.now() - cached.cachedAt : null;
+    const ageHours = ageMs !== null ? (ageMs / 3600000).toFixed(1) : null;
+    const body = JSON.stringify(cached.registry);
+    const sizeBytes = Buffer.byteLength(body, 'utf8');
+    const sigStatus = verifyRegistry(body);
+    return {
+      ok: true,
+      command: 'registry-status',
+      result: {
+        cached: true,
+        stale: cached.stale,
+        cached_at: cached.cachedAt ? new Date(cached.cachedAt).toISOString() : null,
+        age_hours: ageHours,
+        size_bytes: sizeBytes,
+        signature_valid: sigStatus.valid,
+        signature_reason: sigStatus.reason,
+        publisher_count: Object.keys(cached.registry.publishers || {}).length,
+        revoked_count: (cached.registry.revoked || []).length,
+      },
+    };
+  } catch (err) {
+    return { ok: false, command: 'registry-status', error: err.message };
+  }
+}
+
+async function cmdKeygenMeta({ args }) {
+  const author = args.trim();
+  if (!author) return { ok: false, command: 'keygen-meta', error: 'missing author name; usage: keygen-meta <author>' };
+  try {
+    const r = await keygenMeta(author);
+    return {
+      ok: true,
+      command: 'keygen-meta',
+      result: { keyId: r.keyId, publicKey: r.publicKey, dir: r.dir },
+    };
+  } catch (err) {
+    return { ok: false, command: 'keygen-meta', error: err.message };
+  }
+}
+
+async function cmdSignRegistry({ args }) {
+  const registryPath = args.trim();
+  if (!registryPath) return { ok: false, command: 'sign-registry', error: 'missing path; usage: sign-registry <path>' };
+  try {
+    const r = await signRegistry(registryPath);
+    return r.ok
+      ? { ok: true, command: 'sign-registry', result: { path: registryPath } }
+      : { ok: false, command: 'sign-registry', error: r.error };
+  } catch (err) {
+    return { ok: false, command: 'sign-registry', error: err.message };
+  }
+}
+
+async function cmdVerifyRegistry({ args }) {
+  const registryPath = args.trim();
+  if (!registryPath) return { ok: false, command: 'verify-registry', error: 'missing path; usage: verify-registry <path>' };
+  try {
+    const r = await verifyRegistryFile(registryPath);
+    return {
+      ok: r.ok,
+      command: 'verify-registry',
+      result: { path: registryPath, valid: r.valid, reason: r.reason },
+    };
+  } catch (err) {
+    return { ok: false, command: 'verify-registry', error: err.message };
+  }
+}
+
+// === B8: Key rotation + revocation =========================================
+
+/**
+ * rotate-keys <oldKeyId> <newKeyId> [--out <file>]
+ *
+ * Loads both keypairs from ~/.ijfw/keys/<keyId>/, produces a rotation token
+ * signed by the old private key, writes JSON to --out or stdout.
+ */
+async function cmdRotateKeys({ args }) {
+  const tokens = String(args || '').split(/\s+/).filter(Boolean);
+
+  // Extract --out flag
+  let outFile = null;
+  const keep = [];
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i] === '--out' && tokens[i + 1]) {
+      outFile = tokens[i + 1];
+      i++;
+    } else {
+      keep.push(tokens[i]);
+    }
+  }
+
+  const [oldKeyId, newKeyId] = keep;
+  if (!oldKeyId || !newKeyId) {
+    return { ok: false, command: 'rotate-keys', error: 'usage: rotate-keys <oldKeyId> <newKeyId> [--out <file>]' };
+  }
+
+  const oldKp = await loadPublisherKeypair(oldKeyId);
+  if (!oldKp) return { ok: false, command: 'rotate-keys', error: `old keypair not found: ${oldKeyId}` };
+
+  const newKp = await loadPublisherKeypair(newKeyId);
+  if (!newKp) return { ok: false, command: 'rotate-keys', error: `new keypair not found: ${newKeyId}` };
+
+  let token;
+  try {
+    token = signRotationToken(oldKp.privateKey, newKp.publicKey);
+  } catch (err) {
+    return { ok: false, command: 'rotate-keys', error: `sign failed: ${err.message}` };
+  }
+
+  const json = JSON.stringify(token, null, 2) + '\n';
+
+  if (outFile) {
+    try {
+      await fs.writeFile(path.resolve(outFile), json, 'utf8');
+    } catch (err) {
+      return { ok: false, command: 'rotate-keys', error: `write failed: ${err.message}` };
+    }
+    return { ok: true, command: 'rotate-keys', result: { token, out: path.resolve(outFile) } };
+  }
+
+  return { ok: true, command: 'rotate-keys', result: { token } };
+}
+
+/**
+ * verify-rotation-token <file>
+ *
+ * Reads a rotation token JSON, looks up the old public key from the local
+ * trusted-publishers store (or ~/.ijfw/keys/<oldKeyId>/public.pem as fallback),
+ * calls verifyRotationToken, prints verdict.
+ */
+async function cmdVerifyRotationToken({ args }) {
+  const filePath = String(args || '').trim();
+  if (!filePath) {
+    return { ok: false, command: 'verify-rotation-token', error: 'usage: verify-rotation-token <file>' };
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(path.resolve(filePath), 'utf8');
+  } catch (err) {
+    return { ok: false, command: 'verify-rotation-token', error: `read failed: ${err.message}` };
+  }
+
+  let token;
+  try {
+    token = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, command: 'verify-rotation-token', error: `JSON parse failed: ${err.message}` };
+  }
+
+  const oldKeyId = token && token.old_key_id;
+  if (!oldKeyId) {
+    return { ok: false, command: 'verify-rotation-token', error: 'token missing old_key_id' };
+  }
+
+  // Look up old public key: trusted-publishers store first, then key-dir fallback.
+  let oldPublicKey = null;
+  const store = await readTrustedPublishers();
+  const entry = store.publishers && store.publishers[oldKeyId];
+  if (entry && entry.publicKey) {
+    oldPublicKey = entry.publicKey;
+  } else {
+    // Fallback: key may be on disk even if not in trust store (already revoked).
+    const kp = await loadPublisherKeypair(oldKeyId);
+    if (kp) oldPublicKey = kp.publicKey;
+  }
+
+  if (!oldPublicKey) {
+    return { ok: false, command: 'verify-rotation-token', error: `old public key not found for keyId: ${oldKeyId}` };
+  }
+
+  const verdict = verifyRotationToken(token, oldPublicKey);
+  return {
+    ok: verdict.valid,
+    command: 'verify-rotation-token',
+    result: {
+      valid: verdict.valid,
+      reason: verdict.reason,
+      old_key_id: token.old_key_id,
+      new_key_id: token.new_key_id,
+    },
+  };
+}
+
 async function cmdActivate({ args, projectRoot }) {
   const name = args && args.trim();
   if (!name) return { ok: false, command: 'activate', error: 'missing extension name; usage: activate <name>' };
@@ -380,8 +606,46 @@ async function cmdDeactivate() {
   }
 }
 
+// v1.4.3 Phase D — CLI module registry. Each module exports the frozen
+// { handlers, subcommandHelp } shape; we union their handlers into a single
+// lookup and consult it BEFORE the legacy switch, so new --ide / --backend /
+// quota / federation subcommands take precedence.
+let _v143Handlers = null;
+async function loadV143Handlers() {
+  if (_v143Handlers !== null) return _v143Handlers;
+  const [registry, signer, quota, active] = await Promise.all([
+    import('./registry-cli.js'),
+    import('./signer-cli.js'),
+    import('./quota-cli.js'),
+    import('./active-cli.js'),
+  ]);
+  _v143Handlers = Object.assign(
+    Object.create(null),
+    registry.handlers || {},
+    signer.handlers || {},
+    quota.handlers || {},
+    active.handlers || {},
+  );
+  return _v143Handlers;
+}
+
 export async function extensionDispatch({ command, args = '', projectRoot }) {
   const ctx = { command, args: String(args || ''), projectRoot: String(projectRoot || process.cwd()) };
+
+  // v1.4.3 Phase D — CLI modules take precedence over legacy switch.
+  const handlers = await loadV143Handlers();
+  if (typeof handlers[command] === 'function') {
+    try {
+      const r = await handlers[command](ctx.args, ctx);
+      if (r && r.ok === false) {
+        return { ok: false, command, error: r.error || 'unknown error' };
+      }
+      return { ok: true, command, result: r };
+    } catch (err) {
+      return { ok: false, command, error: err && err.message ? err.message : String(err) };
+    }
+  }
+
   switch (command) {
     case 'add': return cmdAdd(ctx);
     case 'list': return cmdList(ctx);
@@ -394,11 +658,18 @@ export async function extensionDispatch({ command, args = '', projectRoot }) {
     case 'trusted': return cmdTrusted(ctx);
     case 'activate': return cmdActivate(ctx);
     case 'deactivate': return cmdDeactivate(ctx);
+    case 'trust-registry': return cmdTrustRegistry(ctx);
+    case 'registry-status': return cmdRegistryStatus(ctx);
+    case 'keygen-meta': return cmdKeygenMeta(ctx);
+    case 'sign-registry': return cmdSignRegistry(ctx);
+    case 'verify-registry': return cmdVerifyRegistry(ctx);
+    case 'rotate-keys': return cmdRotateKeys(ctx);
+    case 'verify-rotation-token': return cmdVerifyRotationToken(ctx);
     default:
       return {
         ok: false,
         command,
-        error: `unknown extension command: ${command}. Supported: add | list | remove | audit | deploy-lazy | keygen | trust | untrust | trusted | activate | deactivate`,
+        error: `unknown extension command: ${command}. Supported: add | list | remove | audit | deploy-lazy | keygen | trust | untrust | trusted | activate | deactivate | trust-registry | registry-status | keygen-meta | sign-registry | verify-registry | rotate-keys | verify-rotation-token`,
       };
   }
 }

package/src/dispatch/quota-cli.js

@@ -0,0 +1,42 @@
+/**
+ * dispatch/quota-cli.js — IJFW v1.4.3 W9-A3 (B16)
+ *
+ * Frozen CLI module contract:
+ *   export const handlers       — { '<subcommand>': async (args, ctx) => { ok, output?, error? } }
+ *   export const subcommandHelp — { '<subcommand>': 'one-line description' }
+ *
+ * Phase D wires these into `dispatch/extension.js`'s main switch by iterating
+ * Object.entries(handlers). Until then, this module is callable in isolation.
+ */
+
+import { getQuotaUsage, resetExtensionQuotas } from '../extension-quota-tracker.js';
+
+function homeFromCtx(ctx) {
+  if (ctx && typeof ctx.homedir === 'string') return ctx.homedir;
+  if (ctx && typeof ctx.homeDir === 'string') return ctx.homeDir;
+  return undefined; // tracker will fall back to env HOME / homedir()
+}
+
+export const handlers = Object.freeze({
+  'quota-status': async (args, ctx) => {
+    const name = Array.isArray(args) ? args[0] : undefined;
+    if (!name || typeof name !== 'string') {
+      return { ok: false, error: 'quota-status: extension name required' };
+    }
+    const usage = await getQuotaUsage(name, { homeDir: homeFromCtx(ctx) });
+    return { ok: true, output: JSON.stringify(usage, null, 2) };
+  },
+  'quota-reset': async (args, ctx) => {
+    const name = Array.isArray(args) ? args[0] : undefined;
+    if (!name || typeof name !== 'string') {
+      return { ok: false, error: 'quota-reset: extension name required' };
+    }
+    await resetExtensionQuotas(name, { homeDir: homeFromCtx(ctx) });
+    return { ok: true, output: 'reset' };
+  },
+});
+
+export const subcommandHelp = Object.freeze({
+  'quota-status': 'quota-status [<ext-name>] — print current usage vs limits',
+  'quota-reset': 'quota-reset <ext-name> — admin: manually reset counters',
+});

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;