@svsprotocol/solana 0.1.0

package/dist/action-production-proof-evidence.js

@@ -0,0 +1,553 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { summarizeApprovalDomain } from "./approval-signature.js";
+import { hashObject } from "./receipt.js";
+
+export const ACTION_PRODUCTION_PROOF_EVIDENCE_VERSION = "svs.action-production-proof-evidence.v1";
+export const ACTION_PRODUCTION_PROOF_EVIDENCE_VERIFICATION_VERSION = "svs.action-production-proof-evidence-verification.v1";
+export const DEFAULT_ACTION_PRODUCTION_PROOF_EVIDENCE_PATH = "./data/security/action-production-proof-evidence.json";
+
+export function createActionProductionProofEvidence({
+  record,
+  status,
+  productionProofWebhook = null,
+  recordPath = null,
+  generatedAt = new Date()
+} = {}) {
+  const productionStatus = status ?? createActionProductionProofStatus(record);
+  const approvalSignature = getActionApprovalSignature(record);
+  const approvalDomain = summarizeApprovalDomain(approvalSignature);
+  const requestSignature = record?.source?.requestSignature ?? null;
+  const webhookDelivery = summarizeProductionProofWebhookDelivery(productionProofWebhook);
+  const unsigned = {
+    version: ACTION_PRODUCTION_PROOF_EVIDENCE_VERSION,
+    generatedAt: generatedAt.toISOString(),
+    source: {
+      recordPath,
+      statusVersion: productionStatus?.version ?? null
+    },
+    productionProof: {
+      ready: productionStatus?.ready === true,
+      status: productionStatus?.status ?? null,
+      recordId: productionStatus?.recordId ?? record?.id ?? null,
+      botId: productionStatus?.botId ?? getActionRecordBotId(record),
+      receiptId: productionStatus?.receiptId ??
+        record?.independentVerification?.receiptId ??
+        record?.receipt?.id ??
+        null,
+      nextAction: productionStatus?.nextAction ?? null,
+      checks: Array.isArray(productionStatus?.checks)
+        ? productionStatus.checks.map(summarizeProductionProofCheck)
+        : []
+    },
+    request: {
+      authenticatedBotId: record?.source?.authenticatedBotId ?? null,
+      requestSignatureVerified: requestSignature?.verified === true,
+      requestSignatureSlot: requestSignature?.secretSlot ?? null,
+      requestSignatureVersion: requestSignature?.signatureVersion ?? requestSignature?.version ?? null,
+      requestNonce: record?.source?.requestNonce ?? null,
+      requestId: record?.source?.requestId ?? null,
+      idempotencyKey: record?.source?.idempotencyKey ?? null,
+      requestTimestamp: record?.source?.requestTimestamp ?? null
+    },
+    humanApproval: {
+      approved: record?.review?.outcome === "approved",
+      reviewer: record?.review?.reviewer ?? null,
+      signer: approvalSignature?.signer ?? null,
+      verified: approvalSignature?.verified === true,
+      messageHash: approvalSignature?.messageHash ?? null,
+      domain: approvalDomain.domain,
+      domainStatus: approvalDomain.status,
+      currentDomain: approvalDomain.current,
+      legacyDomainCompatible: approvalDomain.legacyCompatible
+    },
+    broadcast: {
+      confirmed: actionBroadcastConfirmed(record),
+      signature: record?.broadcast?.signature ?? null,
+      confirmationStatus: record?.broadcast?.confirmationStatus ?? null,
+      slot: record?.broadcast?.slot ?? null,
+      rpcUrl: record?.broadcast?.rpcUrl ?? record?.receipt?.network?.rpcUrl ?? null
+    },
+    receiptRegistry: {
+      confirmed: actionReceiptRegistryConfirmed(record),
+      signature: record?.receiptRegistry?.signature ?? null,
+      confirmationStatus: record?.receiptRegistry?.confirmationStatus ?? null,
+      slot: record?.receiptRegistry?.slot ?? null,
+      programId: record?.receiptRegistry?.programId ?? null,
+      receiptAccount: record?.receiptRegistry?.receiptAccount ??
+        record?.independentVerification?.receiptAccount ??
+        null,
+      planHash: record?.receiptRegistry?.planHash ?? null,
+      transactionPlanHash: record?.receiptRegistry?.transactionPlanHash ?? null
+    },
+    actionRecordVerification: {
+      ok: record?.independentVerification?.version === "svs.action-record-verification.v1" &&
+        record.independentVerification.ok === true,
+      version: record?.independentVerification?.version ?? null,
+      checkedAt: record?.independentVerification?.checkedAt ?? null,
+      receiptId: record?.independentVerification?.receiptId ?? null,
+      receiptAccount: record?.independentVerification?.receiptAccount ?? null,
+      registryTransactionSignature: record?.independentVerification?.registryTransactionSignature ?? null,
+      failedCheckCount: Number.isInteger(record?.independentVerification?.failedCheckCount)
+        ? record.independentVerification.failedCheckCount
+        : null
+    },
+    ...(webhookDelivery
+      ? {
+          productionProofWebhook: webhookDelivery
+        }
+      : {}),
+    policy: {
+      controllerWallet: record?.policySummary?.controllerWallet ??
+        record?.intent?.controllerWallet ??
+        record?.receipt?.controllerWallet ??
+        null,
+      policyHash: record?.receipt?.hashes?.policyHash ?? null,
+      intentHash: record?.receipt?.hashes?.intentHash ?? null,
+      simulationHash: record?.receipt?.hashes?.simulationHash ?? 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,
+    evidenceHash: hashActionProductionProofEvidence(unsigned)
+  };
+}
+
+export async function persistActionProductionProofEvidence({
+  outputPath = DEFAULT_ACTION_PRODUCTION_PROOF_EVIDENCE_PATH,
+  ...options
+} = {}) {
+  const evidence = createActionProductionProofEvidence(options);
+  const text = `${JSON.stringify(evidence, null, 2)}\n`;
+
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, text);
+
+  return {
+    path: outputPath,
+    bytes: Buffer.byteLength(text, "utf8"),
+    evidence
+  };
+}
+
+export function verifyActionProductionProofEvidence(evidence, {
+  requireReady = true,
+  expectedRecordId = null,
+  requireProductionProofWebhookDelivery = false,
+  staleAfterMs = null,
+  now = new Date()
+} = {}) {
+  const freshness = checkEvidenceFreshness({
+    generatedAt: evidence?.generatedAt,
+    staleAfterMs,
+    now
+  });
+  const recomputedHash = hashActionProductionProofEvidence(evidence);
+  const checks = [
+    check(
+      "Action production proof evidence version is supported",
+      evidence?.version === ACTION_PRODUCTION_PROOF_EVIDENCE_VERSION,
+      evidence?.version ?? "missing"
+    ),
+    check(
+      "Action production proof evidence hash is valid",
+      evidence?.evidenceHash === recomputedHash,
+      `declared=${evidence?.evidenceHash ?? "missing"} recomputed=${recomputedHash ?? "missing"}`
+    ),
+    check(
+      "Action production proof evidence excludes secrets",
+      evidence?.reportSafety?.secretsIncluded === false && !containsSecretMaterial(evidence),
+      `secretsIncluded=${evidence?.reportSafety?.secretsIncluded ?? "missing"}`
+    ),
+    check(
+      "Action production proof is ready",
+      !requireReady || evidence?.productionProof?.ready === true,
+      `status=${evidence?.productionProof?.status ?? "missing"}`
+    ),
+    check(
+      "Action production proof was requested by an authenticated signed bot",
+      !requireReady || Boolean(evidence?.request?.authenticatedBotId) &&
+        evidence.request.requestSignatureVerified === true,
+      `bot=${evidence?.request?.authenticatedBotId ?? "missing"} signed=${evidence?.request?.requestSignatureVerified ?? "missing"}`
+    ),
+    check(
+      "Action production proof has verified human approval",
+      !requireReady || evidence?.humanApproval?.approved === true &&
+        evidence.humanApproval.verified === true,
+      `approved=${evidence?.humanApproval?.approved ?? "missing"} verified=${evidence?.humanApproval?.verified ?? "missing"}`
+    ),
+    check(
+      "Action production proof approval domain is supported",
+      !requireReady || ["current", "legacy_compatible", "missing"].includes(evidence?.humanApproval?.domainStatus ?? "missing"),
+      `domain=${evidence?.humanApproval?.domain ?? "missing"} status=${evidence?.humanApproval?.domainStatus ?? "missing"}`
+    ),
+    check(
+      "Action production proof broadcast is confirmed",
+      !requireReady || evidence?.broadcast?.confirmed === true,
+      `signature=${evidence?.broadcast?.signature ?? "missing"} status=${evidence?.broadcast?.confirmationStatus ?? "missing"}`
+    ),
+    check(
+      "Action production proof custom registry is confirmed",
+      !requireReady || evidence?.receiptRegistry?.confirmed === true,
+      `account=${evidence?.receiptRegistry?.receiptAccount ?? "missing"} status=${evidence?.receiptRegistry?.confirmationStatus ?? "missing"}`
+    ),
+    check(
+      "Action production proof independent action-record verification passed",
+      !requireReady || evidence?.actionRecordVerification?.ok === true,
+      `version=${evidence?.actionRecordVerification?.version ?? "missing"} ok=${evidence?.actionRecordVerification?.ok ?? "missing"}`
+    )
+  ];
+
+  if (expectedRecordId) {
+    checks.push(check(
+      "Action production proof evidence record matches expected record",
+      evidence?.productionProof?.recordId === expectedRecordId,
+      `expected=${expectedRecordId} actual=${evidence?.productionProof?.recordId ?? "missing"}`
+    ));
+  }
+
+  if (staleAfterMs !== null && staleAfterMs !== undefined) {
+    checks.push(check(
+      "Action production proof evidence is fresh",
+      !freshness.stale,
+      freshness.ageMs === null
+        ? `generatedAt=${evidence?.generatedAt ?? "missing"}`
+        : `ageMs=${freshness.ageMs} staleAfterMs=${staleAfterMs}`
+    ));
+  }
+
+  const embeddedChecks = Array.isArray(evidence?.productionProof?.checks)
+    ? evidence.productionProof.checks
+    : [];
+  checks.push(...embeddedChecks.map((item) => check(
+    `Embedded production proof check: ${item.id ?? "unknown"}`,
+    !requireReady || item.ok === true,
+    item.detail ?? "missing"
+  )));
+  checks.push(...createProductionProofWebhookDeliveryChecks(evidence?.productionProofWebhook, {
+    required: requireProductionProofWebhookDelivery,
+    expectedRecordId: expectedRecordId ?? evidence?.productionProof?.recordId ?? null,
+    expectedBotId: evidence?.productionProof?.botId ?? evidence?.request?.authenticatedBotId ?? null
+  }));
+
+  const failedChecks = checks.filter((item) => !item.ok);
+
+  return {
+    version: ACTION_PRODUCTION_PROOF_EVIDENCE_VERIFICATION_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "verified" : freshness.stale ? "stale" : "failed",
+    checkedAt: now.toISOString(),
+    found: Boolean(evidence),
+    generatedAt: evidence?.generatedAt ?? null,
+    stale: freshness.stale,
+    ageMs: freshness.ageMs,
+    staleAfterMs,
+    evidenceHash: evidence?.evidenceHash ?? null,
+    computedEvidenceHash: recomputedHash,
+    recordId: evidence?.productionProof?.recordId ?? null,
+    botId: evidence?.productionProof?.botId ?? evidence?.request?.authenticatedBotId ?? null,
+    ready: evidence?.productionProof?.ready === true,
+    failedCheckCount: failedChecks.length,
+    failedChecks,
+    checks
+  };
+}
+
+export function summarizeProductionProofWebhookDelivery(webhook) {
+  const event = webhook?.event ?? webhook;
+
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+
+  const delivery = event.delivery ?? {};
+  const attempts = Array.isArray(event.deliveryAttempts) ? event.deliveryAttempts : [];
+  const signature = delivery.signature ?? attempts.at(-1)?.signature ?? null;
+
+  return {
+    version: "svs.action-production-proof-webhook-delivery.v1",
+    eventVersion: event.version ?? null,
+    eventType: event.eventType ?? null,
+    eventId: event.eventId ?? null,
+    createdAt: event.createdAt ?? null,
+    recordId: event.recordId ?? null,
+    botId: event.botId ?? null,
+    authenticatedBotId: event.authenticatedBotId ?? null,
+    payloadHashAlgorithm: event.payloadHashAlgorithm ?? "sha256",
+    payloadHash: event.payloadHash ?? null,
+    proofHash: event.data?.proofHash ?? null,
+    productionProofStatus: event.data?.status ?? null,
+    productionProofReady: event.data?.ready ?? null,
+    outboxPath: webhook?.path ?? null,
+    delivery: {
+      ok: delivery.ok === true,
+      mode: delivery.mode ?? null,
+      attemptedAt: delivery.attemptedAt ?? null,
+      deliveredAt: delivery.deliveredAt ?? null,
+      statusCode: delivery.statusCode ?? null,
+      error: delivery.error ?? null,
+      attemptCount: attempts.length,
+      signaturePresent: Boolean(signature),
+      signatureVersion: typeof signature === "string" && signature.includes("=")
+        ? signature.split("=")[0]
+        : null,
+      signatureTimestamp: delivery.signatureTimestamp ?? attempts.at(-1)?.signatureTimestamp ?? null
+    }
+  };
+}
+
+export function createProductionProofWebhookDeliveryChecks(webhook, {
+  required = false,
+  expectedRecordId = null,
+  expectedBotId = null
+} = {}) {
+  if (!webhook) {
+    return required
+      ? [check("Action production proof webhook delivery evidence is present", false, "missing")]
+      : [];
+  }
+
+  return [
+    check(
+      "Action production proof webhook delivery version is supported",
+      webhook.version === "svs.action-production-proof-webhook-delivery.v1",
+      webhook.version ?? "missing"
+    ),
+    check(
+      "Action production proof webhook event type is production proof ready",
+      webhook.eventType === "action.production_proof_ready",
+      webhook.eventType ?? "missing"
+    ),
+    check(
+      "Action production proof webhook record matches action",
+      !expectedRecordId || webhook.recordId === expectedRecordId,
+      `expected=${expectedRecordId ?? "none"} actual=${webhook.recordId ?? "missing"}`
+    ),
+    check(
+      "Action production proof webhook bot matches action",
+      !expectedBotId || [webhook.authenticatedBotId, webhook.botId].filter(Boolean).includes(expectedBotId),
+      `expected=${expectedBotId ?? "none"} bot=${webhook.botId ?? "missing"} authenticated=${webhook.authenticatedBotId ?? "missing"}`
+    ),
+    check(
+      "Action production proof webhook payload hash is pinned",
+      webhook.payloadHashAlgorithm === "sha256" && /^[0-9a-f]{64}$/.test(String(webhook.payloadHash ?? "")),
+      `${webhook.payloadHashAlgorithm ?? "missing"}:${webhook.payloadHash ?? "missing"}`
+    ),
+    check(
+      "Action production proof webhook delivery succeeded",
+      webhook.delivery?.ok === true,
+      `status=${webhook.delivery?.statusCode ?? "missing"} deliveredAt=${webhook.delivery?.deliveredAt ?? "missing"}`
+    ),
+    check(
+      "Action production proof webhook used signed delivery",
+      webhook.delivery?.signaturePresent === true && webhook.delivery?.signatureVersion === "v1",
+      `signaturePresent=${webhook.delivery?.signaturePresent ?? "missing"} version=${webhook.delivery?.signatureVersion ?? "missing"}`
+    )
+  ];
+}
+
+export function createActionProductionProofStatus(record) {
+  const recordId = record?.id ?? null;
+  const botId = getActionRecordBotId(record);
+  const requestedByAuthenticatedBot = Boolean(record?.source?.authenticatedBotId);
+  const approvalSignature = getActionApprovalSignature(record);
+  const humanApproved = approvalSignature?.verified === true;
+  const broadcastConfirmed = actionBroadcastConfirmed(record);
+  const receiptRegistryConfirmed = actionReceiptRegistryConfirmed(record);
+  const actionRecordVerified = record?.independentVerification?.version === "svs.action-record-verification.v1" &&
+    record.independentVerification.ok === true;
+  const checks = [
+    productionProofStatusCheck(
+      "requested_by_authenticated_bot",
+      requestedByAuthenticatedBot,
+      requestedByAuthenticatedBot
+        ? `requested by ${record.source.authenticatedBotId}`
+        : "record does not include authenticated bot source evidence"
+    ),
+    productionProofStatusCheck(
+      "human_wallet_approval_verified",
+      humanApproved,
+      humanApproved
+        ? `approved by ${approvalSignature.signer ?? record?.intent?.controllerWallet ?? "controller wallet"}`
+        : "operator must approve with the controller wallet"
+    ),
+    productionProofStatusCheck(
+      "broadcast_confirmed",
+      broadcastConfirmed,
+      broadcastConfirmed
+        ? `broadcast ${record.broadcast.signature}`
+        : "approved transaction must be broadcast and confirmed"
+    ),
+    productionProofStatusCheck(
+      "custom_receipt_registry_confirmed",
+      receiptRegistryConfirmed,
+      receiptRegistryConfirmed
+        ? `registry ${record.receiptRegistry.signature}`
+        : "confirmed action must be registered with the custom receipt registry"
+    ),
+    productionProofStatusCheck(
+      "action_record_verified",
+      actionRecordVerified,
+      actionRecordVerified
+        ? `receipt account ${record.independentVerification.receiptAccount ?? "verified"}`
+        : "operator must run Verify action after registry registration"
+    )
+  ];
+  const missingChecks = checks.filter((item) => !item.ok);
+  const ready = missingChecks.length === 0;
+
+  return {
+    version: "svs.action-production-proof-status.v1",
+    ready,
+    status: ready ? "ready" : "not_ready",
+    recordId,
+    botId,
+    queueStatus: record?.status ?? null,
+    txType: record?.intent?.txType ?? null,
+    receiptId: record?.independentVerification?.receiptId ?? record?.receipt?.id ?? null,
+    receiptRegistry: {
+      confirmationStatus: record?.receiptRegistry?.confirmationStatus ?? null,
+      signature: record?.receiptRegistry?.signature ?? null,
+      receiptAccount: record?.receiptRegistry?.receiptAccount ??
+        record?.independentVerification?.receiptAccount ??
+        null
+    },
+    actionRecordVerification: {
+      ok: actionRecordVerified,
+      version: record?.independentVerification?.version ?? null,
+      receiptAccount: record?.independentVerification?.receiptAccount ?? null,
+      registryTransactionSignature: record?.independentVerification?.registryTransactionSignature ?? null
+    },
+    checks,
+    missing: missingChecks.map((item) => item.id),
+    links: {
+      action: recordId ? `/api/actions/${encodeURIComponent(recordId)}` : null,
+      productionProof: ready && recordId ? `/api/actions/${encodeURIComponent(recordId)}/production-proof?checkReceiptRegistryChain=false` : null,
+      productionProofStatus: recordId ? `/api/actions/${encodeURIComponent(recordId)}/production-proof-status` : null
+    },
+    nextAction: createActionProductionProofNextAction(missingChecks[0])
+  };
+}
+
+export function hashActionProductionProofEvidence(evidence) {
+  if (!evidence || typeof evidence !== "object") {
+    return null;
+  }
+
+  const { evidenceHash: _evidenceHash, ...unsigned } = evidence;
+
+  return hashObject(unsigned);
+}
+
+function summarizeProductionProofCheck(check) {
+  return {
+    id: check?.id ?? null,
+    ok: check?.ok === true,
+    detail: check?.detail ?? null
+  };
+}
+
+function productionProofStatusCheck(id, ok, detail) {
+  return { id, ok: Boolean(ok), detail };
+}
+
+function getActionRecordBotId(record) {
+  return record?.source?.authenticatedBotId ?? record?.intent?.botId ?? record?.receipt?.botId ?? null;
+}
+
+function getActionApprovalSignature(record) {
+  return record?.review?.signature ?? record?.approvalSignature ?? null;
+}
+
+function actionBroadcastConfirmed(record) {
+  return Boolean(
+    record?.broadcast?.signature &&
+      !record.broadcast.error &&
+      ["confirmed", "finalized"].includes(record.broadcast.confirmationStatus)
+  );
+}
+
+function actionReceiptRegistryConfirmed(record) {
+  return Boolean(
+    record?.receiptRegistry?.signature &&
+      !record.receiptRegistry.error &&
+      ["confirmed", "finalized"].includes(record.receiptRegistry.confirmationStatus)
+  );
+}
+
+function createActionProductionProofNextAction(firstMissingCheck) {
+  if (!firstMissingCheck) {
+    return {
+      code: "fetch_production_proof",
+      message: "Action production proof is ready. Fetch /api/actions/{recordId}/production-proof."
+    };
+  }
+
+  const messages = {
+    requested_by_authenticated_bot: "Submit this action through authenticated bot credentials before treating it as a bot production proof.",
+    human_wallet_approval_verified: "Wait for the operator to approve this action with the controller wallet.",
+    broadcast_confirmed: "Wait for the approved transaction to be broadcast and confirmed on Solana.",
+    custom_receipt_registry_confirmed: "Wait for the operator to register the confirmed receipt with the custom receipt registry.",
+    action_record_verified: "Wait for the operator to run Verify action so the custom registry PDA proof is persisted."
+  };
+
+  return {
+    code: firstMissingCheck.id,
+    message: messages[firstMissingCheck.id] ?? firstMissingCheck.detail
+  };
+}
+
+function check(name, ok, detail) {
+  return {
+    name,
+    ok: Boolean(ok),
+    detail
+  };
+}
+
+function checkEvidenceFreshness({
+  generatedAt,
+  staleAfterMs,
+  now
+}) {
+  const generatedAtMs = Date.parse(generatedAt ?? "");
+
+  if (!Number.isFinite(generatedAtMs)) {
+    return {
+      stale: true,
+      ageMs: null
+    };
+  }
+
+  const ageMs = Math.max(0, now.getTime() - generatedAtMs);
+
+  return {
+    stale: staleAfterMs === null || staleAfterMs === undefined ? false : ageMs > staleAfterMs,
+    ageMs
+  };
+}
+
+function containsSecretMaterial(value) {
+  const text = JSON.stringify(value ?? {});
+
+  return [
+    "SVS_BOT_API_KEY=",
+    "SVS_BOT_REQUEST_SIGNING_SECRET=",
+    "SVS_BOT_PENDING_REQUEST_SIGNING_SECRET=",
+    "svs_",
+    "PRIVATE_SHARED_SECRET"
+  ].some((needle) => text.includes(needle));
+}

package/dist/adapter-catalog.d.ts

@@ -0,0 +1,29 @@
+export const SVS_ADAPTER_CATALOG_VERSION: "svs.agent-framework-adapter-catalog.v1";
+
+export interface SvsAgentFrameworkAdapterCatalogEntry {
+  id: "custom-adapter-core" | "solana-agent-kit" | "elizaos" | "goat" | "vercel-ai-sdk" | string;
+  runtime: string;
+  category: "adapter-core" | "framework-adapter" | string;
+  packageExport: string;
+  exportPath: string;
+  adapterVersion: string;
+  readinessHelper: string;
+  submitHelper: string;
+  toolName: string | null;
+  pluginName: string | null;
+  actionName: string | null;
+  demoCommand: string;
+  docsPath: string;
+  hostValidationTarget: string;
+  bestFit: string;
+  primary: boolean;
+}
+
+export const SVS_AGENT_FRAMEWORK_ADAPTERS: readonly Readonly<SvsAgentFrameworkAdapterCatalogEntry>[];
+
+export function getSvsAgentFrameworkAdapters(options?: {
+  includeCustom?: boolean;
+  primaryOnly?: boolean;
+}): SvsAgentFrameworkAdapterCatalogEntry[];
+
+export function findSvsAgentFrameworkAdapter(identifier: string | null | undefined): SvsAgentFrameworkAdapterCatalogEntry | null;