@sars267/pi-delegation-broker 0.1.0-alpha.0

package/src/fake-provider.mjs

@@ -0,0 +1,81 @@
+const INPUT_DIGEST = /^[a-f0-9]{64}$/;
+const EVENT_TYPES = new Set(["succeeded", "rate_limited", "auth_fatal", "failed_before_effect"]);
+
+function nonNegativeInteger(value, name) {
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a non-negative integer`);
+  return value;
+}
+
+function normalizeEvent(event) {
+  if (!event || !EVENT_TYPES.has(event.type)) throw new Error("fake provider event type is not allowed");
+  const delayMs = event.delayMs === undefined ? 0 : nonNegativeInteger(event.delayMs, "delayMs");
+  if (delayMs > 10_000) throw new Error("fake provider delayMs must be at most 10000");
+  if (event.type === "succeeded") {
+    // resultRef crosses back into the child response; keep it opaque and
+    // identifier-shaped so a controller cannot accidentally put text/secrets
+    // into an assistant message or durable provider event.
+    if (typeof event.resultRef !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(event.resultRef)) throw new Error("succeeded event requires an identifier-shaped resultRef");
+    return {
+      type: "succeeded",
+      resultRef: event.resultRef,
+      usage: {
+        input: nonNegativeInteger(event.usage?.input ?? 0, "usage.input"),
+        output: nonNegativeInteger(event.usage?.output ?? 0, "usage.output"),
+        costMicros: nonNegativeInteger(event.usage?.costMicros ?? 0, "usage.costMicros"),
+      },
+      delayMs,
+    };
+  }
+  if (event.type === "rate_limited") {
+    if (!Number.isInteger(event.retryAfterMs) || event.retryAfterMs < 1 || event.retryAfterMs > 86_400_000) throw new Error("rate_limited event requires bounded retryAfterMs");
+    return { type: "rate_limited", retryAfterMs: event.retryAfterMs, delayMs };
+  }
+  if (event.type === "auth_fatal") return { type: "auth_fatal", delayMs };
+  return { type: "failed_before_effect", reasonCode: typeof event.reasonCode === "string" ? event.reasonCode.slice(0, 80) : "unknown", delayMs };
+}
+
+function waitForDelay(delayMs, signal) {
+  if (signal?.aborted) return Promise.reject(new Error("provider_attempt_aborted"));
+  if (delayMs === 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, delayMs);
+    function done() {
+      signal?.removeEventListener("abort", aborted);
+      resolve();
+    }
+    function aborted() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", aborted);
+      reject(new Error("provider_attempt_aborted"));
+    }
+    signal?.addEventListener("abort", aborted, { once: true });
+  });
+}
+
+/** Controller-configured deterministic provider substitute. It never receives raw input or credentials. */
+export class ScriptedFakeProvider {
+  #plans = new Map();
+
+  configure(taskId, events) {
+    if (typeof taskId !== "string" || !taskId || !Array.isArray(events) || events.length === 0) {
+      throw new Error("fake provider plan needs taskId and at least one event");
+    }
+    this.#plans.set(taskId, events.map(normalizeEvent));
+    return { status: "configured", taskId, eventCount: events.length };
+  }
+
+  async attempt(lease, inputDigest, signal) {
+    if (typeof inputDigest !== "string" || !INPUT_DIGEST.test(inputDigest)) throw new Error("provider attempt requires a SHA-256 input digest");
+    const plan = this.#plans.get(lease.taskId);
+    if (!plan || plan.length === 0) throw new Error("no fake provider event configured for task");
+    // Do not consume the scripted outcome until its cancellable pre-effect
+    // delay completes. A disconnected/aborted child therefore records no
+    // provider event and cannot turn cancellation into a hidden side effect.
+    const planned = plan[0];
+    await waitForDelay(planned.delayMs, signal);
+    if (signal?.aborted) throw new Error("provider_attempt_aborted");
+    plan.shift();
+    const { delayMs: _delayMs, ...event } = planned;
+    return structuredClone(event);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,11 @@
+/**
+ * Public API for the non-production, single-host Pi delegation broker reference.
+ * It intentionally contains no provider credential, HTTP client, or automatic
+ * provider failover implementation.
+ */
+export { SqliteLeaseBroker } from "./broker.mjs";
+export { BrokerIpcServer, requestBrokerIpc } from "./ipc.mjs";
+export { provisionBrokeredAgentDir } from "./isolated-child-config.mjs";
+export { signedRegistryMessage, verifySignedRegistry } from "./signed-registry.mjs";
+export { SingleHostBrokerSupervisor } from "./supervisor.mjs";
+export { BrokeredLaunchResolver } from "./trusted-launch-resolver.mjs";

package/src/ipc.mjs

@@ -0,0 +1,249 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { dirname } from "node:path";
+const MAX_REQUEST_BYTES = 64 * 1024;
+const CHILD_METHODS = new Set(["heartbeat", "release", "providerAttempt"]);
+const CONTROLLER_METHODS = new Set(["reserve", "issueLeaseCapability", "markRateLimited", "markUnknown", "markHealthy", "release", "configureFakeProvider"]);
+
+function sameSecret(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function privateSocketParent(socketPath) {
+  const parent = dirname(socketPath);
+  mkdirSync(parent, { recursive: true, mode: 0o700 });
+  const stat = statSync(parent);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) {
+    throw new Error(`Broker socket parent must be an owner-only directory: ${parent}`);
+  }
+}
+
+function validateTtl(value) {
+  if (value === undefined) return 30_000;
+  if (!Number.isInteger(value) || value < 1_000 || value > 60_000) throw new Error("heartbeat ttlMs must be an integer between 1000 and 60000");
+  return value;
+}
+
+/**
+ * Line-delimited JSON IPC for the local controller and a lease-scoped child.
+ * The controller token is never returned to a child. A child capability can
+ * only heartbeat/release the one currently active lease it represents.
+ */
+export class BrokerIpcServer {
+  #broker;
+  #socketPath;
+  #controllerToken;
+  #fakeProvider;
+  #server;
+  #connections = new Set();
+
+  constructor({ broker, socketPath, controllerToken = randomBytes(32).toString("base64url"), fakeProvider }) {
+    if (!broker || !socketPath) throw new Error("Broker IPC server needs broker and socketPath");
+    this.#broker = broker;
+    this.#socketPath = socketPath;
+    this.#controllerToken = controllerToken;
+    this.#fakeProvider = fakeProvider;
+    this.#server = createServer((socket) => {
+      this.#connections.add(socket);
+      socket.once("close", () => this.#connections.delete(socket));
+      this.#handle(socket);
+    });
+  }
+
+  get socketPath() { return this.#socketPath; }
+  /** Parent-only bootstrap secret. Do not pass to child environment or logs. */
+  get controllerToken() { return this.#controllerToken; }
+
+  async start() {
+    privateSocketParent(this.#socketPath);
+    if (existsSync(this.#socketPath)) {
+      if (!lstatSync(this.#socketPath).isSocket()) throw new Error(`Refusing to remove non-socket broker path: ${this.#socketPath}`);
+      rmSync(this.#socketPath);
+    }
+    await new Promise((resolve, reject) => {
+      const onError = (error) => { this.#server.off("listening", onListening); reject(error); };
+      const onListening = () => { this.#server.off("error", onError); resolve(); };
+      this.#server.once("error", onError);
+      this.#server.once("listening", onListening);
+      this.#server.listen(this.#socketPath);
+    });
+    chmodSync(this.#socketPath, 0o600);
+    return { socketPath: this.#socketPath };
+  }
+
+  /**
+   * Drain local requests briefly, then destroy remaining sockets. Destroying a
+   * delayed child attempt also aborts its fake pre-effect transport, avoiding
+   * a daemon shutdown that waits indefinitely for an untrusted child.
+   */
+  async stop({ drainMs = 2_000 } = {}) {
+    if (!Number.isInteger(drainMs) || drainMs < 0 || drainMs > 60_000) throw new Error("drainMs must be an integer between 0 and 60000");
+    if (this.#server.listening) {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          for (const socket of this.#connections) socket.destroy();
+        }, drainMs);
+        timer.unref?.();
+        this.#server.close((error) => {
+          clearTimeout(timer);
+          error ? reject(error) : resolve();
+        });
+      });
+    }
+    if (existsSync(this.#socketPath) && lstatSync(this.#socketPath).isSocket()) rmSync(this.#socketPath);
+  }
+
+  #handle(socket) {
+    socket.setEncoding("utf8");
+    let buffered = "";
+    let handling = false;
+    let responded = false;
+    const abortController = new AbortController();
+    // requestBrokerIpc keeps its write side open until the response. A client
+    // abort destroys the connection; race that against a delayed fake attempt
+    // so cancellation is observed before the scripted outcome is consumed.
+    socket.once("close", () => {
+      if (!responded) abortController.abort();
+    });
+    socket.on("data", (chunk) => {
+      if (handling) return;
+      buffered += chunk;
+      if (Buffer.byteLength(buffered) > MAX_REQUEST_BYTES) {
+        responded = true;
+        return this.#respond(socket, { id: null, ok: false, error: "request_too_large" });
+      }
+      const newline = buffered.indexOf("\n");
+      if (newline < 0) return;
+      handling = true;
+      const line = buffered.slice(0, newline);
+      buffered = "";
+      let request;
+      try { request = JSON.parse(line); } catch {
+        responded = true;
+        return this.#respond(socket, { id: null, ok: false, error: "invalid_json" });
+      }
+      void Promise.resolve(this.#dispatch(request, Date.now(), abortController.signal)).then(
+        (result) => {
+          if (abortController.signal.aborted) return;
+          responded = true;
+          this.#respond(socket, { id: request?.id ?? null, ok: true, result });
+        },
+        (error) => {
+          if (abortController.signal.aborted) return;
+          responded = true;
+          // Do not stringify raw request fields or authorization in an error.
+          this.#respond(socket, { id: request?.id ?? null, ok: false, error: error instanceof Error ? error.message : "internal_error" });
+        },
+      );
+    });
+    socket.on("error", () => socket.destroy());
+  }
+
+  #respond(socket, response) {
+    if (!socket.destroyed && !socket.writableEnded) socket.end(`${JSON.stringify(response)}\n`);
+  }
+
+  async #dispatch(request, now, signal) {
+    if (!request || typeof request.method !== "string") throw new Error("invalid_request");
+    const { method, params = {}, authorization } = request;
+    if (sameSecret(authorization, this.#controllerToken)) {
+      if (!CONTROLLER_METHODS.has(method)) throw new Error("controller_method_not_allowed");
+      if (method === "reserve") return this.#broker.reserve(params.contract, now);
+      if (method === "issueLeaseCapability") return this.#broker.issueLeaseCapability(params.leaseId, params.fencingToken, now);
+      if (method === "markRateLimited") return this.#broker.markRateLimited(params.resourceId, params.retryAfterMs, now);
+      if (method === "markUnknown") return this.#broker.markUnknown(params.resourceId, now, params.reason);
+      if (method === "markHealthy") return this.#broker.markHealthy(params.resourceId, now);
+      if (method === "release") return this.#broker.release(params.leaseId, params.fencingToken, "controller release", now);
+      if (method === "configureFakeProvider") {
+        if (!this.#fakeProvider) throw new Error("fake_provider_unavailable");
+        return this.#fakeProvider.configure(params.taskId, params.events);
+      }
+    }
+    if (!CHILD_METHODS.has(method)) throw new Error("unauthorized");
+    const capability = this.#broker.leaseForCapability(authorization, now);
+    if (capability.status !== "authorized") throw new Error("unauthorized");
+    if (method === "heartbeat") return this.#broker.heartbeat(capability.lease.leaseId, capability.lease.fencingToken, now, validateTtl(params.ttlMs));
+    if (method === "release") return this.#broker.release(capability.lease.leaseId, capability.lease.fencingToken, "child release", now);
+    return this.#providerAttempt(capability.lease, params.inputDigest, signal);
+  }
+
+  async #providerAttempt(lease, inputDigest, signal) {
+    // Publishing this core must not turn an absent real provider proxy into a
+    // successful fake model call. Tests opt into ScriptedFakeProvider explicitly.
+    if (!this.#fakeProvider) throw new Error("provider_transport_unavailable");
+    const event = await this.#fakeProvider.attempt(lease, inputDigest, signal);
+    if (signal?.aborted) throw new Error("provider_attempt_aborted");
+    // A delayed attempt must re-check the lease at observation time, not at
+    // socket admission time. Otherwise a result arriving after TTL could be
+    // recorded/returned under an already expired fencing boundary.
+    const observedAt = Date.now();
+    const telemetry = this.#broker.recordProviderEvent(lease.leaseId, lease.fencingToken, inputDigest, event, observedAt);
+    if (telemetry.status !== "recorded") throw new Error("lease no longer active");
+    if (event.type === "succeeded") {
+      if (lease.enforcement.output === "hard" && lease.maxOutputTokens !== undefined && event.usage.output > lease.maxOutputTokens) {
+        this.#broker.release(lease.leaseId, lease.fencingToken, "hard output budget exceeded", observedAt);
+        return { status: "budget_exceeded", maxOutputTokens: lease.maxOutputTokens };
+      }
+      return { status: "succeeded", resultRef: event.resultRef, usage: event.usage };
+    }
+    if (event.type === "rate_limited") {
+      const cooldown = this.#broker.markRateLimited(lease.resourceId, event.retryAfterMs, observedAt);
+      this.#broker.release(lease.leaseId, lease.fencingToken, "provider rate limited", observedAt);
+      return { status: "rate_limited", retryAfterMs: event.retryAfterMs, capacityGroup: cooldown.capacityGroup, retryAt: cooldown.until };
+    }
+    if (event.type === "auth_fatal") {
+      this.#broker.markUnknown(lease.resourceId, observedAt, "provider auth fatal");
+      this.#broker.release(lease.leaseId, lease.fencingToken, "provider auth fatal", observedAt);
+      return { status: "auth_fatal" };
+    }
+    this.#broker.release(lease.leaseId, lease.fencingToken, "provider failed before effect", observedAt);
+    return { status: "failed_before_effect", reasonCode: event.reasonCode };
+  }
+}
+
+/** One-request-per-connection client used by fake controller/provider tests. */
+export function requestBrokerIpc({ socketPath, authorization, method, params = {}, signal }) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error("aborted"));
+    const socket = createConnection(socketPath);
+    socket.setEncoding("utf8");
+    let buffered = "";
+    let settled = false;
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const succeed = (result) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+    const onAbort = () => {
+      socket.destroy();
+      fail(new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    socket.once("connect", () => {
+      // Keep the write side open until the broker replies. That lets an abort
+      // be distinguishable from a normal one-request/one-response exchange.
+      if (!settled) socket.write(`${JSON.stringify({ id: randomBytes(8).toString("hex"), authorization, method, params })}\n`);
+    });
+    socket.on("data", (chunk) => { buffered += chunk; });
+    socket.once("error", fail);
+    socket.once("end", () => {
+      try {
+        const response = JSON.parse(buffered.trim());
+        if (!response.ok) throw new Error(response.error);
+        succeed(response.result);
+      } catch (error) { fail(error); }
+    });
+  });
+}

package/src/isolated-child-config.mjs

@@ -0,0 +1,27 @@
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/**
+ * Controller-side provisioning for a brokered child. The directory holds no
+ * provider credential: its only persistent setting disables Pi-local retries.
+ * Lease routing/capability stays ephemeral in the child's environment.
+ */
+export function provisionBrokeredAgentDir(path) {
+  const agentDir = resolve(path);
+  mkdirSync(agentDir, { recursive: true, mode: 0o700 });
+  const stat = statSync(agentDir);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) {
+    throw new Error(`Brokered agent dir must be owner-only: ${agentDir}`);
+  }
+  const settings = {
+    retry: {
+      // The broker, rather than Pi's same-child retry loop, owns recovery and
+      // any compatible replacement decision.
+      enabled: false,
+      provider: { maxRetries: 0 },
+    },
+  };
+  const settingsPath = join(agentDir, "settings.json");
+  writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+  return { agentDir, settingsPath };
+}

package/src/signed-registry.mjs

@@ -0,0 +1,154 @@
+import { createHash, createPublicKey, verify } from "node:crypto";
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/;
+const ENFORCEMENT = new Set(["hard", "metered_best_effort", "unavailable"]);
+const PROFILE_STATUS = new Set(["approved", "disabled"]);
+
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function canonicalize(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isSafeInteger(value)) throw new Error("Signed registry contains a non-finite or unsafe number");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  if (!isPlainObject(value)) throw new Error("Signed registry must contain JSON objects only");
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+}
+
+function ownKeysExactly(value, keys, label) {
+  if (!isPlainObject(value)) throw new Error(`${label} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new Error(`${label} has unsupported or missing fields`);
+  }
+}
+
+function requireIdentifier(value, label) {
+  if (typeof value !== "string" || !IDENTIFIER.test(value)) throw new Error(`${label} is not a bounded identifier`);
+  return value;
+}
+
+function requireTimestamp(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${label} must be a positive safe-integer timestamp`);
+  return value;
+}
+
+function freeze(value) {
+  if (Array.isArray(value)) value.forEach(freeze);
+  else if (isPlainObject(value)) Object.values(value).forEach(freeze);
+  return Object.freeze(value);
+}
+
+function normalizedBrokerRegistry(registry) {
+  ownKeysExactly(registry, ["registryVersion", "issuedAt", "expiresAt", "profiles", "capacityGroups", "resources"], "Signed registry");
+  requireIdentifier(registry.registryVersion, "registryVersion");
+  const issuedAt = requireTimestamp(registry.issuedAt, "issuedAt");
+  const expiresAt = requireTimestamp(registry.expiresAt, "expiresAt");
+  if (expiresAt <= issuedAt) throw new Error("Signed registry expiresAt must be after issuedAt");
+  if (!isPlainObject(registry.profiles) || !isPlainObject(registry.capacityGroups) || !isPlainObject(registry.resources)) {
+    throw new Error("Signed registry profiles, capacityGroups and resources must be objects");
+  }
+
+  const profiles = {};
+  for (const [id, profile] of Object.entries(registry.profiles)) {
+    requireIdentifier(id, `profile ${id}`);
+    ownKeysExactly(profile, ["status", "supports"], `profile ${id}`);
+    if (typeof profile.status !== "string" || !PROFILE_STATUS.has(profile.status)) throw new Error(`profile ${id} has invalid status`);
+    if (!Array.isArray(profile.supports) || profile.supports.length === 0) throw new Error(`profile ${id} supports must be a non-empty array`);
+    const supports = profile.supports.map((capability) => requireIdentifier(capability, `profile ${id} support`));
+    if (new Set(supports).size !== supports.length) throw new Error(`profile ${id} has duplicate supports`);
+    profiles[id] = { status: profile.status, supports };
+  }
+  if (Object.keys(profiles).length === 0) throw new Error("Signed registry must contain a profile");
+
+  const capacityGroups = {};
+  for (const [id, group] of Object.entries(registry.capacityGroups)) {
+    requireIdentifier(id, `capacity group ${id}`);
+    ownKeysExactly(group, ["maxConcurrent"], `capacity group ${id}`);
+    if (!Number.isSafeInteger(group.maxConcurrent) || group.maxConcurrent < 1 || group.maxConcurrent > 10_000) {
+      throw new Error(`capacity group ${id} has invalid maxConcurrent`);
+    }
+    capacityGroups[id] = { maxConcurrent: group.maxConcurrent };
+  }
+  if (Object.keys(capacityGroups).length === 0) throw new Error("Signed registry must contain a capacity group");
+
+  const resources = {};
+  for (const [id, resource] of Object.entries(registry.resources)) {
+    requireIdentifier(id, `resource ${id}`);
+    ownKeysExactly(resource, ["capacityGroup", "profile", "enforcement"], `resource ${id}`);
+    requireIdentifier(resource.capacityGroup, `resource ${id} capacityGroup`);
+    requireIdentifier(resource.profile, `resource ${id} profile`);
+    if (!capacityGroups[resource.capacityGroup]) throw new Error(`resource ${id} references unknown capacity group`);
+    if (!profiles[resource.profile]) throw new Error(`resource ${id} references unknown profile`);
+    ownKeysExactly(resource.enforcement, ["input", "output", "cost"], `resource ${id} enforcement`);
+    const enforcement = {};
+    for (const dimension of ["input", "output", "cost"]) {
+      const value = resource.enforcement[dimension];
+      if (typeof value !== "string" || !ENFORCEMENT.has(value)) throw new Error(`resource ${id} has invalid ${dimension} enforcement`);
+      enforcement[dimension] = value;
+    }
+    resources[id] = { capacityGroup: resource.capacityGroup, profile: resource.profile, enforcement };
+  }
+  if (Object.keys(resources).length === 0) throw new Error("Signed registry must contain a resource");
+
+  return {
+    registryVersion: registry.registryVersion,
+    issuedAt,
+    expiresAt,
+    brokerRegistry: { profiles, capacityGroups, resources },
+  };
+}
+
+function decodeSignature(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]{86}$/.test(value)) throw new Error("Signed registry signature must be an Ed25519 base64url signature");
+  const signature = Buffer.from(value, "base64url");
+  if (signature.length !== 64) throw new Error("Signed registry signature has an invalid length");
+  return signature;
+}
+
+/** Canonical bytes that an offline release signer must sign with Ed25519. */
+export function signedRegistryMessage({ schemaVersion, keyId, registry }) {
+  if (schemaVersion !== 1) throw new Error("Signed registry schemaVersion must equal 1");
+  requireIdentifier(keyId, "keyId");
+  // Validate semantics before signing too, so a release tool cannot produce a
+  // valid-looking envelope whose payload a supervisor later refuses.
+  normalizedBrokerRegistry(registry);
+  return Buffer.from(canonicalize({ schemaVersion, keyId, registry }), "utf8");
+}
+
+/**
+ * Verify a controller-owned signed registry before it reaches SQLite admission.
+ * `trustedKeys` is a controller/release-pipeline keyring (keyId -> public key),
+ * never child configuration and never an account/provider credential.
+ */
+export function verifySignedRegistry(envelope, { trustedKeys, now = Date.now() } = {}) {
+  ownKeysExactly(envelope, ["schemaVersion", "keyId", "registry", "signature"], "Signed registry envelope");
+  if (!isPlainObject(trustedKeys)) throw new Error("Signed registry requires a trusted keyring");
+  const message = signedRegistryMessage(envelope);
+  const key = trustedKeys[envelope.keyId];
+  if (!key) throw new Error(`Signed registry keyId is not trusted: ${envelope.keyId}`);
+  let publicKey;
+  try { publicKey = createPublicKey(key); } catch { throw new Error("Signed registry trusted public key is invalid"); }
+  if (publicKey.asymmetricKeyType !== "ed25519") throw new Error("Signed registry trusted key must be Ed25519");
+  if (!verify(null, message, publicKey, decodeSignature(envelope.signature))) throw new Error("Signed registry signature verification failed");
+  const normalized = normalizedBrokerRegistry(envelope.registry);
+  if (!Number.isSafeInteger(now) || now < normalized.issuedAt || now >= normalized.expiresAt) {
+    throw new Error("Signed registry is not currently valid");
+  }
+  const fingerprint = createHash("sha256").update(message).digest("hex");
+  return freeze({
+    keyId: envelope.keyId,
+    registryVersion: normalized.registryVersion,
+    issuedAt: normalized.issuedAt,
+    expiresAt: normalized.expiresAt,
+    fingerprint,
+    brokerRegistry: normalized.brokerRegistry,
+  });
+}