@svsprotocol/solana 0.1.0

package/dist/verified-agent-adoption-kit.js

@@ -0,0 +1,471 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashObject } from "./receipt.js";
+import {
+  VERIFIED_AGENT_PROFILE_VERSION,
+  hashVerifiedAgentProfile
+} from "./verified-agent-profile.js";
+import {
+  VERIFIED_AGENT_REGISTRY_VERSION,
+  hashVerifiedAgentRegistry
+} from "./verified-agent-registry.js";
+
+export const VERIFIED_AGENT_ADOPTION_KIT_VERSION = "svs.verified-agent-adoption-kit.v1";
+export const DEFAULT_VERIFIED_AGENT_ADOPTION_KIT_DIR = "./data/security/verified-agent-adoption-kit";
+
+export function createVerifiedAgentAdoptionKit({
+  profile,
+  registry,
+  registryUrl = null,
+  expectedRegistryHash = null,
+  trustManifestUrl = null,
+  registryIndexUrl = null,
+  profileUrl = null,
+  badgeUrl = null,
+  previewReadiness = null,
+  consumerEvidence = null,
+  protocolId = "svs-protocol",
+  generatedAt = new Date()
+} = {}) {
+  const generatedAtIso = generatedAt instanceof Date ? generatedAt.toISOString() : new Date(generatedAt).toISOString();
+  const botId = profile?.agent?.botId ?? null;
+  const effectiveRegistryHash = expectedRegistryHash ?? registry?.registryHash ?? null;
+  const registryBase = registryUrl ? getUrlBase(registryUrl) : null;
+  const registryAgent = Array.isArray(registry?.agents)
+    ? registry.agents.find((agent) => agent.botId === botId) ?? null
+    : null;
+  const effectiveProfileUrl = profileUrl ??
+    deriveUrl(registryBase, registryAgent?.profilePath) ??
+    profile?.agent?.profileUrl;
+  const effectiveBadgeUrl = badgeUrl ??
+    deriveUrl(registryBase, registryAgent?.badgePath) ??
+    profile?.agent?.badgeUrl;
+  const effectiveTrustManifestUrl = trustManifestUrl ??
+    previewReadiness?.routes?.trustManifestUrl ??
+    deriveUrl(registryBase, "trust-manifest.json");
+  const effectiveRegistryIndexUrl = registryIndexUrl ??
+    previewReadiness?.routes?.indexUrl ??
+    deriveUrl(registryBase, "index.html");
+  const protocolEnv = createProtocolEnv({
+    registryUrl,
+    registryHash: effectiveRegistryHash,
+    botId,
+    profileUrl: effectiveProfileUrl,
+    badgeUrl: effectiveBadgeUrl,
+    protocolId
+  });
+  const sdkSnippet = createSdkSnippet({
+    registryUrl,
+    registryHash: effectiveRegistryHash,
+    botId
+  });
+  const verificationCommands = {
+    hosted: registryUrl && effectiveRegistryHash
+      ? `npm run verify:verified-agent-registry-url -- --url ${registryUrl} --expected-hash ${effectiveRegistryHash}`
+      : null,
+    local: "npm run verify:verified-agent-registry -- --file ./data/verified-agent-registry/registry.json",
+    preview: previewReadiness?.snippets?.checkCommand ?? null
+  };
+  const adoptionChecklist = [
+    "Publish or share the registry directory containing registry.json, trust-manifest.json, index.html, profile JSON, and badge SVG.",
+    "Give protocol teams SVS_VERIFIED_AGENT_REGISTRY_URL and SVS_VERIFIED_AGENT_REGISTRY_HASH from this kit.",
+    "Require protocols to run the hosted registry verifier or SDK middleware before accepting the bot.",
+    "Display the verified-agent badge and profile link in the bot UI or docs.",
+    "Regenerate this kit after certification, registry, profile, or preview-readiness evidence changes."
+  ];
+  const refreshReason = createVerifiedAgentAdoptionKitRefreshReason({
+    profile,
+    registry,
+    expectedRegistryHash: effectiveRegistryHash,
+    badgeUrl: effectiveBadgeUrl,
+    trustManifestUrl: effectiveTrustManifestUrl,
+    previewReadiness,
+    consumerEvidence
+  });
+  const checks = [
+    kitCheck("Verified-agent profile version is supported", profile?.version === VERIFIED_AGENT_PROFILE_VERSION, profile?.version ?? "missing"),
+    kitCheck("Verified-agent profile hash is valid", profile?.profileHash === hashVerifiedAgentProfile(profile), `declared=${profile?.profileHash ?? "missing"} computed=${hashVerifiedAgentProfile(profile) ?? "missing"}`),
+    kitCheck("Verified-agent profile is verified", profile?.status?.ok === true && profile?.status?.value === "verified", profile?.status?.value ?? "missing"),
+    kitCheck("Verified-agent registry version is supported", registry?.version === VERIFIED_AGENT_REGISTRY_VERSION, registry?.version ?? "missing"),
+    kitCheck("Verified-agent registry hash is valid", registry?.registryHash === hashVerifiedAgentRegistry(registry), `declared=${registry?.registryHash ?? "missing"} computed=${hashVerifiedAgentRegistry(registry) ?? "missing"}`),
+    kitCheck("Verified-agent registry hash matches expected hash", !expectedRegistryHash || registry?.registryHash === expectedRegistryHash, `expected=${expectedRegistryHash ?? "none"} actual=${registry?.registryHash ?? "missing"}`),
+    kitCheck("Verified-agent registry includes profile bot", Boolean(registryAgent), botId ?? "missing"),
+    kitCheck("Verified-agent registry profile hash matches profile", registryAgent?.profileHash === profile?.profileHash, `registry=${registryAgent?.profileHash ?? "missing"} profile=${profile?.profileHash ?? "missing"}`),
+    kitCheck("Registry URL is copyable", Boolean(registryUrl), registryUrl ?? "missing"),
+    kitCheck("Pinned registry hash is copyable", isSha256(effectiveRegistryHash), effectiveRegistryHash ?? "missing"),
+    kitCheck("Profile URL is copyable", Boolean(effectiveProfileUrl), effectiveProfileUrl ?? "missing"),
+    kitCheck("Badge URL is copyable", Boolean(effectiveBadgeUrl), effectiveBadgeUrl ?? "missing"),
+    kitCheck("Protocol env excludes secret material", !containsSecretMaterial(protocolEnv), "redacted"),
+    kitCheck("SDK snippet pins registry URL and hash", Boolean(registryUrl && effectiveRegistryHash && sdkSnippet.includes(registryUrl) && sdkSnippet.includes(effectiveRegistryHash)), "snippet"),
+    kitCheck("Preview readiness is ready when provided", !previewReadiness || previewReadiness.ok === true && previewReadiness.status === "ready", previewReadiness?.status ?? "not_provided"),
+    kitCheck("Consumer evidence is verified when provided", !consumerEvidence || consumerEvidence.ok === true, consumerEvidence?.status ?? "not_provided")
+  ];
+  const failedChecks = checks.filter((check) => !check.ok);
+  const unsigned = {
+    version: VERIFIED_AGENT_ADOPTION_KIT_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "ready" : "failed",
+    generatedAt: generatedAtIso,
+    bot: {
+      botId,
+      name: profile?.agent?.name ?? botId,
+      status: profile?.status?.value ?? null,
+      badgeText: profile?.display?.badgeText ?? null,
+      certificationHash: profile?.certification?.certificationHash ?? registryAgent?.certificationHash ?? null,
+      recordId: profile?.certification?.recordId ?? registryAgent?.recordId ?? null,
+      qualityTarget: profile?.qualityTarget ?? registryAgent?.qualityTarget ?? null
+    },
+    registry: {
+      title: registry?.title ?? null,
+      registryHash: registry?.registryHash ?? null,
+      expectedRegistryHash: effectiveRegistryHash,
+      profileCount: registry?.profileCount ?? null,
+      verifiedAgentCount: Array.isArray(registry?.agents)
+        ? registry.agents.filter((agent) => agent.status === "verified" && agent.verification?.ok === true).length
+        : null,
+      profileHash: profile?.profileHash ?? null,
+      trustManifestHash: previewReadiness?.registry?.trustManifestHash ?? null
+    },
+    urls: {
+      registryUrl,
+      trustManifestUrl: effectiveTrustManifestUrl,
+      registryIndexUrl: effectiveRegistryIndexUrl,
+      profileUrl: effectiveProfileUrl,
+      badgeUrl: effectiveBadgeUrl
+    },
+    copy: {
+      protocolEnv,
+      sdkSnippet,
+      verificationCommands,
+      adoptionChecklist
+    },
+    proofs: {
+      previewReadinessHash: previewReadiness?.evidenceHash ?? null,
+      previewReadinessStatus: previewReadiness?.status ?? null,
+      consumerEvidenceHash: consumerEvidence?.evidenceHash ?? null,
+      consumerEvidenceStatus: consumerEvidence?.status ?? null
+    },
+    refreshReason,
+    reportSafety: {
+      secretsIncluded: false,
+      redactedFields: [
+        "SVS_BOT_API_KEY",
+        "SVS_BOT_REQUEST_SIGNING_SECRET",
+        "SVS_BOT_PENDING_REQUEST_SIGNING_SECRET",
+        "apiKey",
+        "requestSigningSecret",
+        "pendingRequestSigningSecret",
+        "webhookSecret",
+        "svs-request-signature"
+      ]
+    },
+    checkCount: checks.length,
+    passedCheckCount: checks.length - failedChecks.length,
+    failedCheckCount: failedChecks.length,
+    checks,
+    failedChecks,
+    nextAction: failedChecks.length === 0
+      ? {
+          code: "share_verified_agent_adoption_kit",
+          message: "Share this non-secret kit with bot teams, protocols, or auditors so they can verify the registry, profile, and badge without dashboard access."
+        }
+      : {
+          code: "repair_verified_agent_adoption_kit",
+          message: "Regenerate the verified profile and registry, provide hosted URLs, and rerun the adoption kit before sharing it."
+        }
+  };
+
+  return {
+    ...unsigned,
+    adoptionKitHash: hashVerifiedAgentAdoptionKit(unsigned)
+  };
+}
+
+export function hashVerifiedAgentAdoptionKit(kit) {
+  if (!kit || typeof kit !== "object") {
+    return null;
+  }
+
+  const { adoptionKitHash: _adoptionKitHash, ...unsigned } = kit;
+
+  return hashObject(unsigned);
+}
+
+export async function persistVerifiedAgentAdoptionKit({
+  outputDir = DEFAULT_VERIFIED_AGENT_ADOPTION_KIT_DIR,
+  ...options
+} = {}) {
+  const kit = createVerifiedAgentAdoptionKit(options);
+  const jsonPath = join(outputDir, "adoption-kit.json");
+  const readmePath = join(outputDir, "README.md");
+
+  await mkdir(outputDir, { recursive: true });
+  await Promise.all([
+    writeFile(jsonPath, `${JSON.stringify(kit, null, 2)}\n`),
+    writeFile(readmePath, renderVerifiedAgentAdoptionKitReadme(kit))
+  ]);
+
+  return {
+    version: "svs.verified-agent-adoption-kit-persist-result.v1",
+    ok: kit.ok,
+    status: kit.status,
+    outputDir,
+    kitPath: jsonPath,
+    readmePath,
+    adoptionKitHash: kit.adoptionKitHash,
+    botId: kit.bot.botId,
+    registryHash: kit.registry.registryHash,
+    refreshReason: kit.refreshReason,
+    nextAction: kit.nextAction,
+    kit
+  };
+}
+
+export function createVerifiedAgentAdoptionKitRefreshReason({
+  profile = null,
+  registry = null,
+  expectedRegistryHash = null,
+  badgeUrl = null,
+  trustManifestUrl = null,
+  previewReadiness = null,
+  consumerEvidence = null
+} = {}) {
+  const sourcePins = {
+    profileHash: profile?.profileHash ?? null,
+    registryHash: registry?.registryHash ?? null,
+    expectedRegistryHash: expectedRegistryHash ?? registry?.registryHash ?? null,
+    trustManifestHash: registry?.trustManifestHash ?? previewReadiness?.registry?.trustManifestHash ?? null,
+    badgeUrl: badgeUrl ?? profile?.agent?.badgeUrl ?? null,
+    trustManifestUrl,
+    previewReadinessHash: previewReadiness?.evidenceHash ?? null,
+    consumerEvidenceHash: consumerEvidence?.evidenceHash ?? null,
+    certificationHash: profile?.certification?.certificationHash ?? null,
+    recordId: profile?.certification?.recordId ?? null
+  };
+  const refreshTriggers = [
+    sourcePins.profileHash ? "profile hash" : null,
+    sourcePins.registryHash ? "registry hash" : null,
+    sourcePins.trustManifestHash || sourcePins.trustManifestUrl ? "trust manifest" : null,
+    sourcePins.badgeUrl ? "badge URL" : null,
+    sourcePins.previewReadinessHash ? "preview-readiness proof" : null,
+    sourcePins.consumerEvidenceHash ? "consumer verification proof" : null,
+    sourcePins.certificationHash || sourcePins.recordId ? "bot certification" : null
+  ].filter(Boolean);
+
+  return {
+    version: "svs.verified-agent-adoption-kit-refresh-reason.v1",
+    reason: "source_pins_current_at_generation",
+    summary: refreshTriggers.length
+      ? `Generated from current ${refreshTriggers.join(", ")}. Regenerate when any source pin changes or the export freshness window expires.`
+      : "Generated without complete source pins. Regenerate after profile, registry, badge, trust-manifest, preview, or consumer proof changes.",
+    refreshTriggers,
+    sourcePins,
+    operatorAction: "Regenerate the adoption kit after registry, profile, badge, trust-manifest, preview-readiness, consumer-proof, or certification changes before cutting a release."
+  };
+}
+
+export function compareVerifiedAgentAdoptionKitSourcePins({
+  kit = null,
+  profile = null,
+  registry = null,
+  previewReadiness = null,
+  consumerEvidence = null,
+  expectedRegistryHash = null
+} = {}) {
+  const sourcePins = kit?.refreshReason?.sourcePins ?? {};
+  const currentPins = {
+    profileHash: profile?.profileHash ?? null,
+    registryHash: registry?.registryHash ??
+      previewReadiness?.registry?.registryHash ??
+      previewReadiness?.registryHash ??
+      consumerEvidence?.summary?.registryHash ??
+      consumerEvidence?.registryHash ??
+      null,
+    expectedRegistryHash: expectedRegistryHash ??
+      registry?.registryHash ??
+      previewReadiness?.registry?.registryHash ??
+      previewReadiness?.registryHash ??
+      consumerEvidence?.summary?.registryHash ??
+      consumerEvidence?.registryHash ??
+      null,
+    trustManifestHash: registry?.trustManifestHash ?? previewReadiness?.registry?.trustManifestHash ?? null,
+    previewReadinessHash: previewReadiness?.evidenceHash ?? null,
+    consumerEvidenceHash: consumerEvidence?.evidenceHash ?? null,
+    certificationHash: profile?.certification?.certificationHash ?? null,
+    recordId: profile?.certification?.recordId ?? null
+  };
+  const comparableFields = [
+    "profileHash",
+    "registryHash",
+    "expectedRegistryHash",
+    "trustManifestHash",
+    "previewReadinessHash",
+    "consumerEvidenceHash",
+    "certificationHash",
+    "recordId"
+  ];
+  const checks = comparableFields.map((field) => {
+    const pinned = sourcePins[field] ?? null;
+    const current = currentPins[field] ?? null;
+    const comparable = Boolean(pinned && current);
+
+    return {
+      field,
+      ok: comparable ? pinned === current : true,
+      comparable,
+      pinned,
+      current,
+      status: comparable ? pinned === current ? "matched" : "drifted" : "not_checked"
+    };
+  });
+  const driftedFields = checks.filter((check) => check.status === "drifted").map((check) => check.field);
+  const comparableFieldsChecked = checks.filter((check) => check.comparable).map((check) => check.field);
+  const notCheckedFields = checks.filter((check) => !check.comparable).map((check) => check.field);
+
+  return {
+    version: "svs.verified-agent-adoption-kit-source-pin-comparison.v1",
+    ok: driftedFields.length === 0,
+    status: driftedFields.length === 0 ? "matched" : "drifted",
+    sourcePins,
+    currentPins,
+    comparableFields: comparableFieldsChecked,
+    notCheckedFields,
+    driftedFields,
+    checks,
+    summary: driftedFields.length === 0
+      ? comparableFieldsChecked.length
+        ? `Source pins match current evidence for ${comparableFieldsChecked.join(", ")}.`
+        : "No current source evidence was available for source-pin comparison."
+      : `Source pin drift detected for ${driftedFields.join(", ")}. Regenerate the adoption kit before release.`
+  };
+}
+
+export function renderVerifiedAgentAdoptionKitReadme(kit) {
+  const commands = kit?.copy?.verificationCommands ?? {};
+  const refresh = kit?.refreshReason ?? null;
+
+  return `# SVS Verified Agent Adoption Kit
+
+Bot: ${kit?.bot?.botId ?? "unknown"}
+Status: ${kit?.status ?? "unknown"}
+Registry hash: ${kit?.registry?.registryHash ?? "missing"}
+Adoption kit hash: ${kit?.adoptionKitHash ?? "missing"}
+Refresh reason: ${refresh?.summary ?? "not recorded"}
+
+## Protocol Env
+
+\`\`\`sh
+${kit?.copy?.protocolEnv ?? ""}
+\`\`\`
+
+## SDK Check
+
+\`\`\`js
+${kit?.copy?.sdkSnippet ?? ""}
+\`\`\`
+
+## Verify
+
+\`\`\`sh
+${commands.hosted ?? commands.local ?? ""}
+\`\`\`
+
+## Freshness and Fail-Closed Export
+
+This kit is a portable handoff for protocols, bot teams, and auditors. It must stay current with the registry, trust manifest, agent profile, badge, and preview-readiness proof that it points to. Deployment-ready verification sets can enforce \`verifiedAgentAdoptionKitStaleAfterMs\`; when that policy is required, export and verifier checks fail closed if the embedded kit is too old or no longer matches the pinned registry/profile proof. Regenerate the kit after registry, profile, badge, trust-manifest, or preview-proof changes before cutting a release.
+
+Refresh trigger summary: ${refresh?.summary ?? "not recorded"}
+
+Pinned refresh inputs:
+
+- Profile hash: ${refresh?.sourcePins?.profileHash ?? "missing"}
+- Registry hash: ${refresh?.sourcePins?.registryHash ?? "missing"}
+- Trust manifest hash: ${refresh?.sourcePins?.trustManifestHash ?? "missing"}
+- Badge URL: ${refresh?.sourcePins?.badgeUrl ?? "missing"}
+- Preview-readiness proof: ${refresh?.sourcePins?.previewReadinessHash ?? "missing"}
+- Consumer verification proof: ${refresh?.sourcePins?.consumerEvidenceHash ?? "missing"}
+- Bot certification: ${refresh?.sourcePins?.certificationHash ?? "missing"}
+
+## Links
+
+- Registry: ${kit?.urls?.registryUrl ?? "missing"}
+- Trust manifest: ${kit?.urls?.trustManifestUrl ?? "missing"}
+- Profile: ${kit?.urls?.profileUrl ?? "missing"}
+- Badge: ${kit?.urls?.badgeUrl ?? "missing"}
+
+## Checklist
+
+${(kit?.copy?.adoptionChecklist ?? []).map((item) => `- ${item}`).join("\n")}
+
+## Safety
+
+This handoff is designed to be non-secret. It should contain public registry URLs, hashes, profile links, badge links, verifier commands, and protocol snippets only.
+`;
+}
+
+function createProtocolEnv({
+  registryUrl,
+  registryHash,
+  botId,
+  profileUrl,
+  badgeUrl,
+  protocolId
+}) {
+  return [
+    `SVS_PROTOCOL_ID=${protocolId}`,
+    `SVS_AGENT_BOT_ID=${botId ?? "REPLACE_WITH_BOT_ID"}`,
+    `SVS_VERIFIED_AGENT_REGISTRY_URL=${registryUrl ?? "REPLACE_WITH_REGISTRY_JSON_URL"}`,
+    `SVS_VERIFIED_AGENT_REGISTRY_HASH=${registryHash ?? "REPLACE_WITH_REGISTRY_HASH"}`,
+    `SVS_VERIFIED_AGENT_PROFILE_URL=${profileUrl ?? "REPLACE_WITH_PROFILE_JSON_URL"}`,
+    `SVS_VERIFIED_AGENT_BADGE_URL=${badgeUrl ?? "REPLACE_WITH_BADGE_SVG_URL"}`
+  ].join("\n");
+}
+
+function createSdkSnippet({ registryUrl, registryHash, botId }) {
+  return `import { createHostedVerifiedAgentRegistryMiddleware } from "@svsprotocol/solana/protocol";
+
+const requireSvsAgent = createHostedVerifiedAgentRegistryMiddleware({
+  registryUrl: "${registryUrl ?? "REPLACE_WITH_REGISTRY_JSON_URL"}",
+  expectedRegistryHash: "${registryHash ?? "REPLACE_WITH_REGISTRY_HASH"}"
+});
+
+await requireSvsAgent({ botId: "${botId ?? "REPLACE_WITH_BOT_ID"}" });`;
+}
+
+function deriveUrl(baseUrl, relativePath) {
+  if (!baseUrl || !relativePath) {
+    return null;
+  }
+
+  try {
+    return new URL(relativePath, baseUrl).toString();
+  } catch {
+    return null;
+  }
+}
+
+function getUrlBase(url) {
+  try {
+    return new URL(".", url.endsWith("/") ? url : url).toString();
+  } catch {
+    return null;
+  }
+}
+
+function kitCheck(name, ok, detail = null) {
+  return {
+    name,
+    ok: ok === true,
+    detail
+  };
+}
+
+function isSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/i.test(value);
+}
+
+function containsSecretMaterial(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value ?? "");
+
+  return /(SVS_BOT_API_KEY|SVS_BOT_REQUEST_SIGNING_SECRET|requestSigningSecret|pendingRequestSigningSecret|webhookSecret|svs-request-signature)\s*=/i.test(text);
+}