@svsprotocol/solana 0.1.0

package/dist/verified-agent-registry-consumer.js

@@ -0,0 +1,421 @@
+import {
+  VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION,
+  hashVerifiedAgentRegistry,
+  hashVerifiedAgentRegistryTrustManifest
+} from "./verified-agent-registry.js";
+import { verifyVerifiedAgentProfile } from "./verified-agent-profile.js";
+import {
+  VERIFIED_AGENT_TRUST_SCORE_POLICY,
+  hashVerifiedAgentTrustScore
+} from "./verified-agent-trust-score.js";
+
+export const VERIFIED_AGENT_REGISTRY_CONSUMER_VERIFICATION_VERSION = "svs.verified-agent-registry-consumer-verification.v1";
+
+export async function verifyVerifiedAgentRegistryUrl({
+  registryUrl,
+  trustManifestUrl = null,
+  expectedRegistryHash,
+  requireVerified = true,
+  staleAfterMs = null,
+  now = new Date(),
+  fetchImpl = globalThis.fetch
+} = {}) {
+  if (!registryUrl) {
+    throw new Error("registryUrl is required.");
+  }
+
+  if (!expectedRegistryHash) {
+    throw new Error("expectedRegistryHash is required.");
+  }
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch implementation is required.");
+  }
+
+  const checkedAt = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
+  const registry = await fetchJson({ url: registryUrl, fetchImpl });
+  const computedRegistryHash = hashVerifiedAgentRegistry(registry);
+  const trustManifestStatus = await fetchAndVerifyTrustManifest({
+    registryUrl,
+    trustManifestUrl,
+    expectedRegistryHash,
+    registry,
+    fetchImpl
+  });
+  const checks = [
+    check(
+      "Registry hash matches pinned expected hash",
+      registry?.registryHash === expectedRegistryHash && computedRegistryHash === expectedRegistryHash,
+      `expected=${expectedRegistryHash} declared=${registry?.registryHash ?? "missing"} computed=${computedRegistryHash ?? "missing"}`
+    ),
+    check(
+      "Registry profile count matches entries",
+      registry?.profileCount === registry?.agents?.length,
+      `declared=${registry?.profileCount ?? "missing"} actual=${registry?.agents?.length ?? "missing"}`
+    ),
+    check(
+      "Registry has at least one agent",
+      Array.isArray(registry?.agents) && registry.agents.length > 0,
+      `count=${registry?.agents?.length ?? "missing"}`
+    ),
+    ...trustManifestStatus.checks
+  ];
+  const agents = [];
+
+  if (Array.isArray(registry?.agents)) {
+    for (const [index, agent] of registry.agents.entries()) {
+      const agentChecks = [];
+      let profile = null;
+      let profileUrl = null;
+      let verification = null;
+      const computedTrustScoreHash = hashVerifiedAgentTrustScore(agent.trustScore);
+      const manifestAgent = Array.isArray(trustManifestStatus.manifest?.agents)
+        ? trustManifestStatus.manifest.agents.find((item) => item.botId === agent.botId)
+        : null;
+
+      try {
+        profileUrl = resolveRegistryUrl(registryUrl, agent.profilePath);
+        profile = await fetchJson({ url: profileUrl, fetchImpl });
+        verification = verifyVerifiedAgentProfile(profile, {
+          requireVerified,
+          expectedBotId: agent.botId,
+          staleAfterMs,
+          now
+        });
+      } catch (error) {
+        agentChecks.push(check(
+          "Linked profile can be fetched",
+          false,
+          error.message
+        ));
+      }
+
+      if (profile) {
+        agentChecks.push(
+          check(
+            "Linked profile verifies",
+            verification?.ok === true,
+            `status=${verification?.status ?? "missing"} failed=${verification?.failedCheckCount ?? "missing"}`
+          ),
+          check(
+            "Registry bot id matches linked profile",
+            agent.botId === profile.agent?.botId,
+            `registry=${agent.botId ?? "missing"} profile=${profile.agent?.botId ?? "missing"}`
+          ),
+          check(
+            "Registry profile hash matches linked profile",
+            agent.profileHash === profile.profileHash,
+            `registry=${agent.profileHash ?? "missing"} profile=${profile.profileHash ?? "missing"}`
+          ),
+          check(
+            "Registry status matches linked profile",
+            agent.status === profile.status?.value,
+            `registry=${agent.status ?? "missing"} profile=${profile.status?.value ?? "missing"}`
+          ),
+          check(
+            "Registry certification hash matches linked profile",
+            agent.certificationHash === profile.certification?.certificationHash,
+            `registry=${agent.certificationHash ?? "missing"} profile=${profile.certification?.certificationHash ?? "missing"}`
+          ),
+          check(
+            "Registry agent trust score hash is valid",
+            !agent.trustScore ||
+              agent.trustScore.trustScoreHash === computedTrustScoreHash,
+            agent.trustScore
+              ? `declared=${agent.trustScore.trustScoreHash ?? "missing"} computed=${computedTrustScoreHash ?? "missing"}`
+              : "not present"
+          ),
+          check(
+            "Hosted registry trust manifest agent trust score matches registry",
+            !manifestAgent?.trustScore ||
+              agentTrustScoreSummaryMatchesRegistry(manifestAgent.trustScore, agent.trustScore),
+            manifestAgent?.trustScore
+              ? `manifest=${manifestAgent.trustScore.trustScoreHash ?? "missing"} registry=${agent.trustScore?.trustScoreHash ?? "missing"}`
+              : "not present"
+          )
+        );
+
+        if (verification?.failedChecks?.length) {
+          agentChecks.push(...verification.failedChecks.map((item) => ({
+            name: `Profile check: ${item.name}`,
+            ok: false,
+            detail: item.detail
+          })));
+        }
+      }
+
+      agents.push({
+        index,
+        botId: agent?.botId ?? null,
+        profilePath: agent?.profilePath ?? null,
+        profileUrl,
+        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,
+        trustScore: summarizeTrustScore(agent.trustScore, computedTrustScoreHash)
+      });
+    }
+  }
+
+  checks.push(check(
+    "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_CONSUMER_VERIFICATION_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "verified" : "failed",
+    checkedAt,
+    registryUrl,
+    trustManifestUrl: trustManifestStatus.url,
+    expectedRegistryHash,
+    registryHash: registry?.registryHash ?? null,
+    computedRegistryHash,
+    trustManifest: trustManifestStatus.summary,
+    profileCount: registry?.profileCount ?? null,
+    verifiedAgentCount: agents.filter((agent) => agent.ok).length,
+    failedCheckCount: failedChecks.length,
+    failedChecks,
+    checks,
+    agents
+  };
+}
+
+async function fetchAndVerifyTrustManifest({
+  registryUrl,
+  trustManifestUrl,
+  expectedRegistryHash,
+  registry,
+  fetchImpl
+}) {
+  const resolvedTrustManifestUrl = trustManifestUrl ?? resolveRegistryUrl(registryUrl, "trust-manifest.json");
+  const checks = [];
+  let manifest = null;
+
+  try {
+    manifest = await fetchJson({ url: resolvedTrustManifestUrl, fetchImpl });
+    checks.push(check(
+      "Hosted registry trust manifest can be fetched",
+      true,
+      resolvedTrustManifestUrl
+    ));
+  } catch (error) {
+    checks.push(check(
+      "Hosted registry trust manifest can be fetched",
+      false,
+      error.message
+    ));
+
+    return {
+      url: resolvedTrustManifestUrl,
+      summary: {
+        found: false,
+        url: resolvedTrustManifestUrl,
+        trustManifestHash: null,
+        computedTrustManifestHash: null,
+        registryHash: null
+      },
+      checks
+    };
+  }
+
+  const computedTrustManifestHash = hashVerifiedAgentRegistryTrustManifest(manifest);
+  const manifestAgentsMatchRegistry = trustManifestAgentsMatchRegistry({ manifest, registry });
+
+  checks.push(
+    check(
+      "Hosted registry trust manifest version is supported",
+      manifest.version === VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION,
+      manifest.version ?? "missing"
+    ),
+    check(
+      "Hosted registry trust manifest hash is valid",
+      manifest.trustManifestHash === computedTrustManifestHash,
+      `declared=${manifest.trustManifestHash ?? "missing"} computed=${computedTrustManifestHash ?? "missing"}`
+    ),
+    check(
+      "Hosted registry trust manifest pins expected registry hash",
+      manifest.registry?.registryHash === expectedRegistryHash &&
+        manifest.registry?.registryHash === registry?.registryHash,
+      `expected=${expectedRegistryHash ?? "missing"} manifest=${manifest.registry?.registryHash ?? "missing"} registry=${registry?.registryHash ?? "missing"}`
+    ),
+    check(
+      "Hosted 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(
+      "Hosted registry trust manifest agents match registry",
+      manifestAgentsMatchRegistry.ok,
+      manifestAgentsMatchRegistry.detail
+    ),
+    check(
+      "Hosted 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(
+      "Hosted registry trust manifest excludes secrets",
+      manifest.reportSafety?.secretsIncluded === false && !containsSecretMaterial(manifest),
+      `secretsIncluded=${manifest.reportSafety?.secretsIncluded ?? "missing"}`
+    )
+  );
+
+  return {
+    url: resolvedTrustManifestUrl,
+    summary: {
+      found: true,
+      url: resolvedTrustManifestUrl,
+      trustManifestHash: manifest.trustManifestHash ?? null,
+      computedTrustManifestHash,
+      registryHash: manifest.registry?.registryHash ?? null,
+      agentCount: Array.isArray(manifest.agents) ? manifest.agents.length : null,
+      trustScorePolicy: summarizeTrustScorePolicy(manifest.trustScorePolicy)
+    },
+    manifest,
+    checks
+  };
+}
+
+function trustManifestAgentsMatchRegistry({ manifest, registry }) {
+  if (!Array.isArray(manifest?.agents) || !Array.isArray(registry?.agents)) {
+    return {
+      ok: false,
+      detail: `manifest=${manifest?.agents?.length ?? "missing"} registry=${registry?.agents?.length ?? "missing"}`
+    };
+  }
+
+  const manifestByBotId = new Map(manifest.agents.map((agent) => [agent.botId, agent]));
+  const mismatches = [];
+
+  for (const registryAgent of registry.agents) {
+    const manifestAgent = manifestByBotId.get(registryAgent.botId);
+
+    if (!manifestAgent) {
+      mismatches.push(`${registryAgent.botId}: missing`);
+      continue;
+    }
+
+    for (const key of ["name", "status", "profileHash", "certificationHash", "recordId", "profilePath", "badgePath", "pagePath"]) {
+      if ((manifestAgent[key] ?? null) !== (registryAgent[key] ?? null)) {
+        mismatches.push(`${registryAgent.botId}: ${key}`);
+      }
+    }
+
+    if (!agentTrustScoreSummaryMatchesRegistry(manifestAgent.trustScore, registryAgent.trustScore)) {
+      mismatches.push(`${registryAgent.botId}: trustScore`);
+    }
+  }
+
+  return {
+    ok: mismatches.length === 0,
+    detail: mismatches.length === 0 ? "matched" : `mismatches=${mismatches.slice(0, 5).join(", ")}`
+  };
+}
+
+async function fetchJson({ url, fetchImpl }) {
+  const response = await fetchImpl(url);
+
+  if (!response?.ok) {
+    throw new Error(`HTTP ${response?.status ?? "unknown"} while fetching ${url}`);
+  }
+
+  return response.json();
+}
+
+function resolveRegistryUrl(registryUrl, relativePath) {
+  if (!relativePath || typeof relativePath !== "string") {
+    throw new Error("registry agent profilePath is required.");
+  }
+
+  if (/^[a-z][a-z0-9+.-]*:/i.test(relativePath)) {
+    throw new Error("registry agent profilePath must be relative.");
+  }
+
+  return new URL(relativePath, registryUrl).toString();
+}
+
+function check(name, ok, detail = "") {
+  return { name, ok: Boolean(ok), detail };
+}
+
+function summarizeTrustScore(trustScore, computedTrustScoreHash = hashVerifiedAgentTrustScore(trustScore)) {
+  if (!trustScore) {
+    return null;
+  }
+
+  return {
+    version: trustScore.version ?? null,
+    status: trustScore.status ?? null,
+    score: Number.isFinite(trustScore.score) ? trustScore.score : null,
+    maxScore: Number.isFinite(trustScore.maxScore) ? trustScore.maxScore : null,
+    evidenceComplete: trustScore.evidenceComplete === true,
+    blockingSignalCount: Number.isFinite(trustScore.blockingSignalCount) ? trustScore.blockingSignalCount : null,
+    passedSignalCount: Number.isFinite(trustScore.passedSignalCount) ? trustScore.passedSignalCount : null,
+    failedSignalCount: Number.isFinite(trustScore.failedSignalCount) ? trustScore.failedSignalCount : null,
+    trustScoreHash: trustScore.trustScoreHash ?? null,
+    computedTrustScoreHash,
+    hashValid: Boolean(trustScore.trustScoreHash) && trustScore.trustScoreHash === computedTrustScoreHash,
+    highTrustMinimumScore: VERIFIED_AGENT_TRUST_SCORE_POLICY.highTrustMinimumScore,
+    nextAction: trustScore.nextAction ?? null
+  };
+}
+
+function summarizeTrustScorePolicy(policy) {
+  if (!policy) {
+    return null;
+  }
+
+  return {
+    version: policy.version ?? null,
+    scoreVersion: policy.scoreVersion ?? null,
+    highTrustMinimumScore: policy.highTrustMinimumScore ?? null,
+    maxScore: policy.maxScore ?? null,
+    highTrustRequiresEvidenceComplete: policy.highTrustRequiresEvidenceComplete === true,
+    requiredSignalIds: Array.isArray(policy.requiredSignalIds) ? policy.requiredSignalIds : [],
+    optionalSignalIds: Array.isArray(policy.optionalSignalIds) ? policy.optionalSignalIds : []
+  };
+}
+
+function agentTrustScoreSummaryMatchesRegistry(manifestTrustScore, registryTrustScore) {
+  if (!manifestTrustScore && !registryTrustScore) {
+    return true;
+  }
+
+  if (!manifestTrustScore || !registryTrustScore) {
+    return false;
+  }
+
+  return [
+    "status",
+    "score",
+    "maxScore",
+    "evidenceComplete",
+    "blockingSignalCount",
+    "trustScoreHash"
+  ].every((key) => (manifestTrustScore[key] ?? null) === (registryTrustScore[key] ?? null));
+}
+
+function containsSecretMaterial(value) {
+  const text = JSON.stringify(value ?? {});
+
+  return /(svs_live|svs_req_live|BEGIN PRIVATE KEY|secret-value)/i.test(text);
+}

package/dist/verified-agent-registry.d.ts

@@ -0,0 +1,36 @@
+import type {
+  JsonObject,
+  SvsVerifiedAgentRegistry,
+  SvsVerifiedAgentRegistryBuildOptions,
+  SvsVerifiedAgentRegistryTrustManifest,
+  SvsVerifiedAgentRegistryVerificationOptions,
+  SvsVerifiedAgentRegistryVerification
+} from "./common.js";
+
+export type {
+  SvsVerifiedAgentRegistry,
+  SvsVerifiedAgentRegistryBuildOptions,
+  SvsVerifiedAgentRegistryTrustManifest,
+  SvsVerifiedAgentRegistryVerificationOptions,
+  SvsVerifiedAgentRegistryVerification
+} from "./common.js";
+
+export const DEFAULT_VERIFIED_AGENT_REGISTRY_DIR: string;
+export const VERIFIED_AGENT_REGISTRY_BUILD_VERSION: "svs.verified-agent-registry-build.v1";
+export const VERIFIED_AGENT_REGISTRY_TRUST_MANIFEST_VERSION: "svs.verified-agent-registry-trust-manifest.v1";
+export const VERIFIED_AGENT_REGISTRY_VERIFICATION_VERSION: "svs.verified-agent-registry-verification.v1";
+export const VERIFIED_AGENT_REGISTRY_VERSION: "svs.verified-agent-registry.v1";
+
+export function buildVerifiedAgentRegistry(options: SvsVerifiedAgentRegistryBuildOptions): Promise<JsonObject>;
+
+export function createVerifiedAgentRegistryTrustManifest(options?: {
+  title?: string;
+  generatedAt?: Date | string;
+  registry: SvsVerifiedAgentRegistry;
+}): SvsVerifiedAgentRegistryTrustManifest;
+
+export function hashVerifiedAgentRegistry(registry: unknown): string | null;
+
+export function hashVerifiedAgentRegistryTrustManifest(manifest: unknown): string | null;
+
+export function verifyVerifiedAgentRegistry(options?: SvsVerifiedAgentRegistryVerificationOptions): Promise<SvsVerifiedAgentRegistryVerification>;