@svsprotocol/solana 0.1.0

package/dist/verified-agent-registry.js

@@ -0,0 +1,826 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { hashObject } from "./receipt.js";
+import {
+  createVerifiedAgentBadgeSvg,
+  verifyVerifiedAgentProfile
+} from "./verified-agent-profile.js";
+import {
+  createVerifiedAgentTrustScore,
+  VERIFIED_AGENT_TRUST_SCORE_HIGH_TRUST_MIN,
+  VERIFIED_AGENT_TRUST_SCORE_POLICY
+} from "./verified-agent-trust-score.js";
+
+export const VERIFIED_AGENT_REGISTRY_VERSION = "svs.verified-agent-registry.v1";
+export const VERIFIED_AGENT_REGISTRY_BUILD_VERSION = "svs.verified-agent-registry-build.v1";
+export const VERIFIED_AGENT_REGISTRY_VERIFICATION_VERSION = "svs.verified-agent-registry-verification.v1";
+export const VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION = "svs.verified-agent-registry-trust-manifest.v1";
+export const DEFAULT_VERIFIED_AGENT_REGISTRY_DIR = "./data/verified-agent-registry";
+
+export async function buildVerifiedAgentRegistry({
+  profiles = [],
+  outputDir = DEFAULT_VERIFIED_AGENT_REGISTRY_DIR,
+  title = "SVS Verified Agent Registry",
+  generatedAt = new Date(),
+  staleAfterMs = null,
+  requireVerified = true,
+  now = generatedAt
+} = {}) {
+  if (!Array.isArray(profiles) || profiles.length === 0) {
+    throw new Error("At least one verified agent profile is required.");
+  }
+
+  await mkdir(outputDir, { recursive: true });
+
+  const generatedAtIso = generatedAt instanceof Date
+    ? generatedAt.toISOString()
+    : new Date(generatedAt).toISOString();
+  const agents = [];
+  const profileByBotId = new Map();
+
+  for (const entry of profiles) {
+    const profile = await loadProfileEntry(entry);
+    const verification = verifyVerifiedAgentProfile(profile, {
+      requireVerified,
+      staleAfterMs,
+      now
+    });
+
+    if (requireVerified && verification.ok !== true) {
+      throw new Error(
+        `Verified agent profile ${profile?.agent?.botId ?? entry?.profilePath ?? "unknown"} failed verification.`
+      );
+    }
+
+    const botId = profile.agent.botId;
+    const safeBotId = toSafePathSegment(botId);
+    const profileText = `${JSON.stringify(profile, null, 2)}\n`;
+    const badgeText = entry?.badgeText ?? await loadOptionalText(entry?.badgePath) ?? createVerifiedAgentBadgeSvg(profile);
+    const profileRelativePath = `agents/${safeBotId}/profile.json`;
+    const badgeRelativePath = `agents/${safeBotId}/badge.svg`;
+    const pageRelativePath = `agents/${safeBotId}/index.html`;
+    const agentDir = join(outputDir, "agents", safeBotId);
+    const trustScore = createRegistryAgentTrustScore({
+      profile,
+      profileVerification: verification,
+      generatedAt: generatedAtIso
+    });
+
+    await mkdir(agentDir, { recursive: true });
+    await Promise.all([
+      writeFile(join(outputDir, profileRelativePath), profileText),
+      writeFile(join(outputDir, badgeRelativePath), badgeText)
+    ]);
+
+    const agent = {
+      botId,
+      name: profile.agent.name ?? botId,
+      status: profile.status.value,
+      badgeText: profile.display.badgeText,
+      profileHash: profile.profileHash,
+      certificationHash: profile.certification.certificationHash,
+      recordId: profile.certification.recordId,
+      qualityTarget: profile.qualityTarget,
+      proofs: profile.proofs,
+      trustScore,
+      generatedAt: profile.generatedAt,
+      profilePath: profileRelativePath,
+      badgePath: badgeRelativePath,
+      pagePath: pageRelativePath,
+      verification: {
+        ok: verification.ok,
+        status: verification.status,
+        failedCheckCount: verification.failedCheckCount,
+        checkedAt: verification.checkedAt
+      }
+    };
+
+    agents.push(agent);
+    profileByBotId.set(botId, profile);
+  }
+
+  const unsignedRegistry = {
+    version: VERIFIED_AGENT_REGISTRY_VERSION,
+    generatedAt: generatedAtIso,
+    title,
+    profileCount: agents.length,
+    agents
+  };
+  const registry = {
+    ...unsignedRegistry,
+    registryHash: hashVerifiedAgentRegistry(unsignedRegistry)
+  };
+  const trustManifest = createVerifiedAgentRegistryTrustManifest({
+    title,
+    generatedAt: generatedAtIso,
+    registry
+  });
+
+  await Promise.all([
+    writeFile(join(outputDir, "registry.json"), `${JSON.stringify(registry, null, 2)}\n`),
+    writeFile(join(outputDir, "trust-manifest.json"), `${JSON.stringify(trustManifest, null, 2)}\n`),
+    writeFile(join(outputDir, "index.html"), renderRegistryIndex({ title, generatedAt: generatedAtIso, registry, trustManifest })),
+    ...registry.agents.map((agent) => writeFile(
+      join(outputDir, agent.pagePath),
+      renderAgentPage({
+        title,
+        generatedAt: generatedAtIso,
+        agent,
+        profile: profileByBotId.get(agent.botId),
+        registryHash: registry.registryHash
+      })
+    ))
+  ]);
+
+  return {
+    version: VERIFIED_AGENT_REGISTRY_BUILD_VERSION,
+    ok: true,
+    status: "built",
+    outputDir,
+    registryPath: join(outputDir, "registry.json"),
+    trustManifestPath: join(outputDir, "trust-manifest.json"),
+    indexPath: join(outputDir, "index.html"),
+    registryHash: registry.registryHash,
+    trustManifestHash: trustManifest.trustManifestHash,
+    profileCount: agents.length,
+    agents,
+    files: [
+      "registry.json",
+      "trust-manifest.json",
+      "index.html",
+      ...agents.flatMap((agent) => [
+        agent.profilePath,
+        agent.badgePath,
+        agent.pagePath
+      ])
+    ]
+  };
+}
+
+export function hashVerifiedAgentRegistry(registry) {
+  if (!registry || typeof registry !== "object") {
+    return null;
+  }
+
+  const { registryHash: _registryHash, ...unsigned } = registry;
+
+  return hashObject(unsigned);
+}
+
+export function hashVerifiedAgentRegistryTrustManifest(manifest) {
+  if (!manifest || typeof manifest !== "object") {
+    return null;
+  }
+
+  const { trustManifestHash: _trustManifestHash, ...unsigned } = manifest;
+
+  return hashObject(unsigned);
+}
+
+export function createVerifiedAgentRegistryTrustManifest({
+  title = "SVS Verified Agent Registry",
+  generatedAt = new Date(),
+  registry
+} = {}) {
+  if (!registry || typeof registry !== "object") {
+    throw new Error("registry is required.");
+  }
+
+  const generatedAtIso = generatedAt instanceof Date
+    ? generatedAt.toISOString()
+    : new Date(generatedAt).toISOString();
+  const unsigned = {
+    version: VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION,
+    title,
+    generatedAt: generatedAtIso,
+    registry: {
+      version: registry.version ?? null,
+      title: registry.title ?? title,
+      profileCount: registry.profileCount ?? null,
+      registryHash: registry.registryHash ?? null,
+      registryPath: "registry.json",
+      indexPath: "index.html"
+    },
+    hostedPaths: {
+      registryJson: "registry.json",
+      trustManifestJson: "trust-manifest.json",
+      registryIndex: "index.html"
+    },
+    verifierInstructions: {
+      cli: "npm run verify:verified-agent-registry-url -- --url REGISTRY_JSON_URL --expected-hash REGISTRY_HASH",
+      localCli: "npm run verify:verified-agent-registry -- --file ./data/verified-agent-registry/registry.json",
+      sdkImport: "import { verifyVerifiedAgentRegistryUrl } from '@svsprotocol/solana/verified-agent-registry';",
+      sdkCall: "await verifyVerifiedAgentRegistryUrl({ registryUrl, expectedRegistryHash });",
+      requiredChecks: [
+        "registry hash matches pinned expected hash",
+        "linked profile hashes match registry entries",
+        "linked profiles verify as current SVS verified profiles",
+        "agent trust-score summaries are registry-visible and hash-pinned",
+        "profile, registry, and trust manifest exclude secret material"
+      ]
+    },
+    trustScorePolicy: {
+      version: VERIFIED_AGENT_TRUST_SCORE_POLICY.version,
+      scoreVersion: VERIFIED_AGENT_TRUST_SCORE_POLICY.scoreVersion,
+      highTrustMinimumScore: VERIFIED_AGENT_TRUST_SCORE_POLICY.highTrustMinimumScore,
+      maxScore: VERIFIED_AGENT_TRUST_SCORE_POLICY.maxScore,
+      highTrustRequiresEvidenceComplete: VERIFIED_AGENT_TRUST_SCORE_POLICY.highTrustRequiresEvidenceComplete,
+      requiredSignalIds: VERIFIED_AGENT_TRUST_SCORE_POLICY.requiredSignalIds,
+      optionalSignalIds: VERIFIED_AGENT_TRUST_SCORE_POLICY.optionalSignalIds
+    },
+    trustStates: {
+      verified: "Registry hash, profile hashes, certification hashes, and linked profiles all verify.",
+      stale: "Profile or proof freshness is outside the relying party window.",
+      failed: "At least one hash, profile, certification, or linked proof check failed."
+    },
+    agents: Array.isArray(registry.agents)
+      ? registry.agents.map((agent) => ({
+          botId: agent.botId,
+          name: agent.name,
+          status: agent.status,
+          profileHash: agent.profileHash,
+          certificationHash: agent.certificationHash,
+          recordId: agent.recordId,
+          profilePath: agent.profilePath,
+          badgePath: agent.badgePath,
+          pagePath: agent.pagePath,
+          trustScore: agent.trustScore
+            ? {
+                status: agent.trustScore.status,
+                score: agent.trustScore.score,
+                maxScore: agent.trustScore.maxScore,
+                evidenceComplete: agent.trustScore.evidenceComplete,
+                blockingSignalCount: agent.trustScore.blockingSignalCount,
+                trustScoreHash: agent.trustScore.trustScoreHash
+              }
+            : null,
+          proofFreshness: {
+            generatedAt: agent.generatedAt ?? null,
+            verificationCheckedAt: agent.verification?.checkedAt ?? null
+          }
+        }))
+      : [],
+    reportSafety: {
+      secretsIncluded: false,
+      redactedFields: [
+        "SVS_BOT_API_KEY",
+        "SVS_BOT_REQUEST_SIGNING_SECRET",
+        "SVS_BOT_PENDING_REQUEST_SIGNING_SECRET",
+        "apiKey",
+        "requestSigningSecret",
+        "pendingRequestSigningSecret",
+        "webhookSecret"
+      ]
+    }
+  };
+
+  return {
+    ...unsigned,
+    trustManifestHash: hashVerifiedAgentRegistryTrustManifest(unsigned)
+  };
+}
+
+export async function verifyVerifiedAgentRegistry({
+  registry = null,
+  registryPath = null,
+  baseDir = null,
+  requireVerified = true,
+  staleAfterMs = null,
+  now = new Date()
+} = {}) {
+  const loadedRegistry = registry ?? await loadRegistryFromPath(registryPath);
+  const effectiveBaseDir = baseDir ?? (registryPath ? dirname(registryPath) : process.cwd());
+  const checks = [
+    check(
+      "Verified agent registry version is supported",
+      loadedRegistry?.version === VERIFIED_AGENT_REGISTRY_VERSION,
+      loadedRegistry?.version ?? "missing"
+    ),
+    check(
+      "Verified agent registry hash is valid",
+      loadedRegistry?.registryHash === hashVerifiedAgentRegistry(loadedRegistry),
+      `declared=${loadedRegistry?.registryHash ?? "missing"} computed=${hashVerifiedAgentRegistry(loadedRegistry) ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry profile count matches entries",
+      loadedRegistry?.profileCount === loadedRegistry?.agents?.length,
+      `declared=${loadedRegistry?.profileCount ?? "missing"} actual=${loadedRegistry?.agents?.length ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry has at least one agent",
+      Array.isArray(loadedRegistry?.agents) && loadedRegistry.agents.length > 0,
+      `count=${loadedRegistry?.agents?.length ?? "missing"}`
+    )
+  ];
+  const trustManifestStatus = await readAndVerifyRegistryTrustManifest({
+    baseDir: effectiveBaseDir,
+    registry: loadedRegistry
+  });
+  checks.push(...trustManifestStatus.checks);
+  const agents = [];
+
+  if (Array.isArray(loadedRegistry?.agents)) {
+    for (const [index, agent] of loadedRegistry.agents.entries()) {
+      const agentChecks = [];
+      let profile = null;
+      let profileVerification = null;
+
+      try {
+        const profilePath = resolveRegistryRelativePath(effectiveBaseDir, agent.profilePath);
+
+        profile = JSON.parse(await readFile(profilePath, "utf8"));
+        profileVerification = verifyVerifiedAgentProfile(profile, {
+          requireVerified,
+          expectedBotId: agent.botId,
+          staleAfterMs,
+          now
+        });
+      } catch (error) {
+        agentChecks.push(check(
+          "Verified agent registry linked profile can be loaded",
+          false,
+          error.message
+        ));
+      }
+
+      if (profile) {
+        agentChecks.push(
+          check(
+            "Verified agent registry linked profile verifies",
+            profileVerification?.ok === true,
+            `status=${profileVerification?.status ?? "missing"} failed=${profileVerification?.failedCheckCount ?? "missing"}`
+          ),
+          check(
+            "Verified agent registry bot id matches linked profile",
+            agent.botId === profile.agent?.botId,
+            `registry=${agent.botId ?? "missing"} profile=${profile.agent?.botId ?? "missing"}`
+          ),
+          check(
+            "Verified agent registry profile hash matches linked profile",
+            agent.profileHash === profile.profileHash,
+            `registry=${agent.profileHash ?? "missing"} profile=${profile.profileHash ?? "missing"}`
+          ),
+          check(
+            "Verified agent registry status matches linked profile",
+            agent.status === profile.status?.value,
+            `registry=${agent.status ?? "missing"} profile=${profile.status?.value ?? "missing"}`
+          ),
+          check(
+            "Verified agent registry certification hash matches linked profile",
+            agent.certificationHash === profile.certification?.certificationHash,
+            `registry=${agent.certificationHash ?? "missing"} profile=${profile.certification?.certificationHash ?? "missing"}`
+          ),
+          check(
+            "Verified agent registry verification summary matches linked profile",
+            agent.verification?.ok === profileVerification?.ok &&
+              agent.verification?.status === profileVerification?.status,
+            `registry=${agent.verification?.status ?? "missing"} profile=${profileVerification?.status ?? "missing"}`
+          )
+        );
+
+        if (profileVerification?.failedChecks?.length) {
+          agentChecks.push(...profileVerification.failedChecks.map((item) => ({
+            name: `Profile check: ${item.name}`,
+            ok: false,
+            detail: item.detail
+          })));
+        }
+      }
+
+      agents.push({
+        index,
+        botId: agent?.botId ?? null,
+        profilePath: agent?.profilePath ?? null,
+        ok: agentChecks.every((item) => item.ok),
+        failedCheckCount: agentChecks.filter((item) => !item.ok).length,
+        failedChecks: agentChecks.filter((item) => !item.ok),
+        checks: agentChecks,
+        profileHash: profile?.profileHash ?? null
+      });
+    }
+  }
+
+  checks.push(check(
+    "Verified agent registry linked profiles verify",
+    agents.every((agent) => agent.ok),
+    `failed=${agents.filter((agent) => !agent.ok).length}`
+  ));
+
+  const failedChecks = [
+    ...checks.filter((item) => !item.ok),
+    ...agents.flatMap((agent) => agent.failedChecks.map((item) => ({
+      ...item,
+      agentIndex: agent.index,
+      botId: agent.botId
+    })))
+  ];
+
+  return {
+    version: VERIFIED_AGENT_REGISTRY_VERIFICATION_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "verified" : "failed",
+    checkedAt: now instanceof Date ? now.toISOString() : new Date(now).toISOString(),
+    registryPath: registryPath ?? null,
+    registryHash: loadedRegistry?.registryHash ?? null,
+    computedRegistryHash: hashVerifiedAgentRegistry(loadedRegistry),
+    trustManifest: trustManifestStatus.summary,
+    profileCount: loadedRegistry?.profileCount ?? null,
+    verifiedAgentCount: agents.filter((agent) => agent.ok).length,
+    failedCheckCount: failedChecks.length,
+    failedChecks,
+    checks,
+    agents
+  };
+}
+
+async function loadRegistryFromPath(registryPath) {
+  if (!registryPath) {
+    throw new Error("registryPath is required.");
+  }
+
+  return JSON.parse(await readFile(registryPath, "utf8"));
+}
+
+async function readAndVerifyRegistryTrustManifest({
+  baseDir,
+  registry
+}) {
+  const manifestPath = resolveRegistryRelativePath(baseDir, "trust-manifest.json");
+  const checks = [];
+  let manifest = null;
+
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    checks.push(check(
+      "Verified agent registry trust manifest can be loaded",
+      false,
+      error.message
+    ));
+
+    return {
+      summary: {
+        found: false,
+        path: manifestPath,
+        trustManifestHash: null,
+        computedTrustManifestHash: null,
+        registryHash: null
+      },
+      checks
+    };
+  }
+
+  const computedTrustManifestHash = hashVerifiedAgentRegistryTrustManifest(manifest);
+
+  checks.push(
+    check(
+      "Verified agent registry trust manifest version is supported",
+      manifest.version === VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION,
+      manifest.version ?? "missing"
+    ),
+    check(
+      "Verified agent registry trust manifest hash is valid",
+      manifest.trustManifestHash === computedTrustManifestHash,
+      `declared=${manifest.trustManifestHash ?? "missing"} computed=${computedTrustManifestHash ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry trust manifest pins registry hash",
+      manifest.registry?.registryHash === registry?.registryHash,
+      `manifest=${manifest.registry?.registryHash ?? "missing"} registry=${registry?.registryHash ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry trust manifest agent count matches registry",
+      manifest.registry?.profileCount === registry?.profileCount &&
+        Array.isArray(manifest.agents) &&
+        manifest.agents.length === registry?.agents?.length,
+      `manifest=${manifest.registry?.profileCount ?? "missing"}/${manifest.agents?.length ?? "missing"} registry=${registry?.profileCount ?? "missing"}/${registry?.agents?.length ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry trust manifest has verifier instructions",
+      typeof manifest.verifierInstructions?.cli === "string" &&
+        manifest.verifierInstructions.cli.includes("verify:verified-agent-registry-url") &&
+        typeof manifest.verifierInstructions?.sdkCall === "string" &&
+        manifest.verifierInstructions.sdkCall.includes("verifyVerifiedAgentRegistryUrl"),
+      `cli=${manifest.verifierInstructions?.cli ?? "missing"}`
+    ),
+    check(
+      "Verified agent registry trust manifest excludes secrets",
+      manifest.reportSafety?.secretsIncluded === false && !containsSecretMaterial(manifest),
+      `secretsIncluded=${manifest.reportSafety?.secretsIncluded ?? "missing"}`
+    )
+  );
+
+  return {
+    summary: {
+      found: true,
+      path: manifestPath,
+      trustManifestHash: manifest.trustManifestHash ?? null,
+      computedTrustManifestHash,
+      registryHash: manifest.registry?.registryHash ?? null
+    },
+    checks
+  };
+}
+
+function resolveRegistryRelativePath(baseDir, relativePath) {
+  if (!relativePath || typeof relativePath !== "string") {
+    throw new Error("registry agent profilePath is required.");
+  }
+
+  if (isAbsolute(relativePath)) {
+    throw new Error("registry agent profilePath must be relative.");
+  }
+
+  const resolvedBase = resolve(baseDir);
+  const resolvedPath = resolve(resolvedBase, normalize(relativePath));
+
+  if (resolvedPath !== resolvedBase && !resolvedPath.startsWith(`${resolvedBase}/`)) {
+    throw new Error(`registry agent profilePath escapes registry directory: ${relativePath}`);
+  }
+
+  return resolvedPath;
+}
+
+async function loadProfileEntry(entry) {
+  if (entry?.profile) {
+    return entry.profile;
+  }
+
+  if (!entry?.profilePath) {
+    throw new Error("profilePath is required.");
+  }
+
+  return JSON.parse(await readFile(entry.profilePath, "utf8"));
+}
+
+async function loadOptionalText(path) {
+  if (!path) {
+    return null;
+  }
+
+  return readFile(path, "utf8");
+}
+
+function createRegistryAgentTrustScore({
+  profile,
+  profileVerification,
+  generatedAt
+} = {}) {
+  const profileProofs = profile?.proofs ?? {};
+  const actionProofOk = profileProofs.actionRecordVerificationOk === true &&
+    profileProofs.portableSetVerified === true;
+
+  return createVerifiedAgentTrustScore({
+    profile,
+    profileVerification,
+    registryVerification: {
+      ok: profileVerification?.ok === true,
+      status: profileVerification?.ok === true ? "verified" : "failed",
+      botId: profile?.agent?.botId ?? profileVerification?.botId ?? null
+    },
+    actionProductionProofVerification: actionProofOk
+      ? {
+          ok: true,
+          recordId: profile?.certification?.recordId ?? null,
+          evidenceHash: profileProofs.verificationSetHash ?? profile?.certification?.evidenceHash ?? null
+        }
+      : null,
+    generatedAt
+  });
+}
+
+function renderRegistryIndex({ title, generatedAt, registry, trustManifest }) {
+  const cards = registry.agents.map((agent) => `<article class="agent-card">
+  <img src="${escapeHtml(agent.badgePath)}" alt="${escapeHtml(agent.badgeText)} badge" />
+  <div>
+    <h2>${escapeHtml(agent.name)}</h2>
+    <p class="bot-id">${escapeHtml(agent.botId)}</p>
+    <dl>
+      <div><dt>Status</dt><dd>${escapeHtml(agent.status)}</dd></div>
+      <div><dt>Quality</dt><dd>${escapeHtml(formatQuality(agent.qualityTarget))}</dd></div>
+      <div><dt>Trust score</dt><dd>${renderTrustScoreInline(agent.trustScore)}</dd></div>
+      <div><dt>Profile hash</dt><dd><code>${escapeHtml(shortHash(agent.profileHash))}</code></dd></div>
+      <div><dt>Certification</dt><dd><code>${escapeHtml(shortHash(agent.certificationHash))}</code></dd></div>
+    </dl>
+    <nav>
+      <a href="${escapeHtml(agent.pagePath)}">Open agent page</a>
+      <a href="${escapeHtml(agent.profilePath)}">Profile JSON</a>
+    </nav>
+  </div>
+</article>`).join("\n");
+
+  return renderHtmlDocument({
+    title,
+    body: `<main class="shell">
+  <header class="hero">
+    <p class="eyebrow">SVS Agent Verification</p>
+    <h1>${escapeHtml(title)}</h1>
+    <p>Static registry of verified Solana agents. Each entry links to profile JSON, badge, certification hashes, and proof summary data for protocols and auditors.</p>
+    <dl class="summary">
+      <div><dt>Agents</dt><dd>${registry.profileCount}</dd></div>
+      <div><dt>Generated</dt><dd>${escapeHtml(generatedAt)}</dd></div>
+      <div><dt>Registry hash</dt><dd><code>${escapeHtml(registry.registryHash)}</code></dd></div>
+      <div><dt>Trust manifest</dt><dd><code>${escapeHtml(shortHash(trustManifest.trustManifestHash))}</code></dd></div>
+    </dl>
+  </header>
+  <section class="trust-panel">
+    <h2>Verifier Instructions</h2>
+    <p>Pin the registry hash before trusting badges or profile pages. A badge image alone is not proof.</p>
+    <pre>${escapeHtml(trustManifest.verifierInstructions.cli)}</pre>
+    <nav>
+      <a href="registry.json">Registry JSON</a>
+      <a href="trust-manifest.json">Trust manifest JSON</a>
+    </nav>
+  </section>
+  <section class="trust-panel">
+    <h2>Trust Checklist</h2>
+    <ul>
+${trustManifest.verifierInstructions.requiredChecks.map((item) => `      <li>${escapeHtml(item)}</li>`).join("\n")}
+    </ul>
+    <p class="score-note">High trust requires ${VERIFIED_AGENT_TRUST_SCORE_HIGH_TRUST_MIN}/${VERIFIED_AGENT_TRUST_SCORE_POLICY.maxScore}, complete required evidence, and zero blocking signals. Registry pages show the mechanical score so protocols can compare agents by evidence instead of badge text alone.</p>
+  </section>
+  <section class="agent-grid">
+${cards}
+  </section>
+</main>`
+  });
+}
+
+function renderAgentPage({ title, generatedAt, agent, profile, registryHash }) {
+  const proofRows = Object.entries(agent.proofs ?? {}).map(([key, value]) => `<tr>
+  <th>${escapeHtml(key)}</th>
+  <td>${escapeHtml(String(value))}</td>
+</tr>`).join("\n");
+  const profileJson = JSON.stringify(profile, null, 2);
+  const trustScoreRows = (agent.trustScore?.signals ?? []).map((signal) => `<tr>
+  <th>${escapeHtml(signal.label)}</th>
+  <td>
+    <strong>${signal.ok ? "passed" : signal.required ? "blocking" : "missing optional"}</strong>
+    <span>${escapeHtml(signal.earned)}/${escapeHtml(signal.weight)} pts</span>
+    <p>${escapeHtml(signal.detail)}</p>
+  </td>
+</tr>`).join("\n");
+
+  return renderHtmlDocument({
+    title: `${agent.name} - ${title}`,
+    body: `<main class="shell">
+  <header class="hero">
+    <p class="eyebrow">SVS Verified Agent</p>
+    <h1>${escapeHtml(agent.name)}</h1>
+    <p class="bot-id">${escapeHtml(agent.botId)}</p>
+    <img src="badge.svg" alt="${escapeHtml(agent.badgeText)} badge" />
+    <dl class="summary">
+      <div><dt>Status</dt><dd>${escapeHtml(agent.status)}</dd></div>
+      <div><dt>Quality</dt><dd>${escapeHtml(formatQuality(agent.qualityTarget))}</dd></div>
+      <div><dt>Trust score</dt><dd>${renderTrustScoreInline(agent.trustScore)}</dd></div>
+      <div><dt>Record</dt><dd><code>${escapeHtml(agent.recordId ?? "missing")}</code></dd></div>
+      <div><dt>Generated</dt><dd>${escapeHtml(generatedAt)}</dd></div>
+    </dl>
+  </header>
+  <section>
+    <h2>Verifier Instructions</h2>
+    <p>Verify the registry hash and linked profile before trusting this agent page or badge.</p>
+    <pre>npm run verify:verified-agent-registry-url -- --url REGISTRY_JSON_URL --expected-hash ${escapeHtml(registryHash ?? "REGISTRY_HASH")}</pre>
+    <p><a href="../../trust-manifest.json">Open trust-manifest.json</a></p>
+  </section>
+  <section>
+    <h2>Trust Score Explanation</h2>
+    <p>High trust requires ${VERIFIED_AGENT_TRUST_SCORE_HIGH_TRUST_MIN}/${VERIFIED_AGENT_TRUST_SCORE_POLICY.maxScore}, complete required evidence, and zero blocking signals. This score is deterministic and hash-pinned; it explains evidence quality but does not replace verifier checks.</p>
+    <dl class="summary">
+      <div><dt>Status</dt><dd>${escapeHtml(agent.trustScore?.status ?? "missing")}</dd></div>
+      <div><dt>Score</dt><dd>${escapeHtml(agent.trustScore?.score ?? "missing")}/${escapeHtml(agent.trustScore?.maxScore ?? VERIFIED_AGENT_TRUST_SCORE_POLICY.maxScore)}</dd></div>
+      <div><dt>Required evidence</dt><dd>${agent.trustScore?.evidenceComplete === true ? "complete" : "incomplete"}</dd></div>
+      <div><dt>Score hash</dt><dd><code>${escapeHtml(shortHash(agent.trustScore?.trustScoreHash))}</code></dd></div>
+    </dl>
+    <table class="trust-score-table">
+      <tbody>
+${trustScoreRows}
+      </tbody>
+    </table>
+    <p class="score-note">${escapeHtml(agent.trustScore?.nextAction?.message ?? "No trust score next action available.")}</p>
+  </section>
+  <section>
+    <h2>Proof Summary</h2>
+    <table>
+      <tbody>
+${proofRows}
+      </tbody>
+    </table>
+  </section>
+  <section>
+    <h2>Hashes</h2>
+    <dl class="summary">
+      <div><dt>Profile hash</dt><dd><code>${escapeHtml(agent.profileHash)}</code></dd></div>
+      <div><dt>Certification hash</dt><dd><code>${escapeHtml(agent.certificationHash ?? "missing")}</code></dd></div>
+    </dl>
+  </section>
+  <section>
+    <h2>Profile JSON</h2>
+    <p><a href="profile.json">Open profile.json</a></p>
+    <pre>${escapeHtml(profileJson)}</pre>
+  </section>
+  <p><a href="../../index.html">Back to registry</a></p>
+</main>`
+  });
+}
+
+function renderHtmlDocument({ title, body }) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #08111f; color: #edf7ff; }
+    body { margin: 0; background: #08111f; }
+    .shell { width: min(1120px, calc(100vw - 32px)); margin: 0 auto; padding: 40px 0; }
+    .hero { border-bottom: 1px solid rgba(255,255,255,0.14); padding-bottom: 24px; margin-bottom: 24px; }
+    .eyebrow { color: #14f195; font-weight: 800; text-transform: uppercase; font-size: 12px; }
+    h1 { font-size: 34px; line-height: 1.1; margin: 0 0 12px; letter-spacing: 0; }
+    h2 { font-size: 18px; margin-top: 28px; }
+    a { color: #14f195; font-weight: 700; }
+    code, pre { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.1); border-radius: 6px; }
+    code { padding: 2px 5px; }
+    pre { overflow: auto; padding: 16px; line-height: 1.45; }
+    .summary { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin: 20px 0 0; }
+    .summary div, .agent-card { background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.12); border-radius: 8px; padding: 14px; }
+    dt { color: #9fb2c7; font-size: 12px; font-weight: 800; text-transform: uppercase; }
+    dd { margin: 4px 0 0; overflow-wrap: anywhere; }
+    .agent-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; }
+    .agent-card img { margin-bottom: 14px; }
+    .agent-card h2 { margin: 0; }
+    .bot-id { color: #9fb2c7; overflow-wrap: anywhere; }
+    .agent-card nav { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 12px; }
+    .score-note { color: #b9c7d8; line-height: 1.55; }
+    table { width: 100%; border-collapse: collapse; background: rgba(255,255,255,0.04); border-radius: 8px; overflow: hidden; }
+    th, td { text-align: left; border-bottom: 1px solid rgba(255,255,255,0.1); padding: 10px; overflow-wrap: anywhere; }
+    th { color: #9fb2c7; width: 280px; }
+    .trust-score-table td strong { display: inline-block; margin-right: 10px; color: #14f195; }
+    .trust-score-table td span { color: #9fb2c7; font-size: 13px; font-weight: 800; }
+    .trust-score-table td p { margin: 6px 0 0; color: #b9c7d8; line-height: 1.45; }
+  </style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}
+
+function renderTrustScoreInline(trustScore) {
+  if (!trustScore) {
+    return "missing";
+  }
+
+  return `${escapeHtml(trustScore.score)}/${escapeHtml(trustScore.maxScore)} ${escapeHtml(trustScore.status)} <code>${escapeHtml(shortHash(trustScore.trustScoreHash))}</code>`;
+}
+
+function formatQuality(qualityTarget) {
+  if (!qualityTarget) {
+    return "missing";
+  }
+
+  return `${qualityTarget.score ?? "?"}/${qualityTarget.targetScore ?? "?"} ${qualityTarget.status ?? "unknown"}`;
+}
+
+function shortHash(hash) {
+  if (!hash) {
+    return "missing";
+  }
+
+  return hash.length > 18 ? `${hash.slice(0, 10)}...${hash.slice(-8)}` : hash;
+}
+
+function containsSecretMaterial(value) {
+  const text = JSON.stringify(value ?? {});
+
+  return /(svs_live|svs_req_live|BEGIN PRIVATE KEY|secret-value)/i.test(text);
+}
+
+function toSafePathSegment(value) {
+  const safe = String(value ?? "agent")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return safe || `agent-${Date.now()}`;
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function check(name, ok, detail) {
+  return {
+    name,
+    ok: Boolean(ok),
+    detail
+  };
+}