@svsprotocol/solana 0.1.0

package/dist/receipt.js

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from "node:crypto";
+
+export function hashObject(value) {
+  return createHash("sha256")
+    .update(JSON.stringify(sortObject(value)))
+    .digest("hex");
+}
+
+export function createReceipt({ intent, policy, decision, risk, simulation }) {
+  const issuedAt = new Date().toISOString();
+  const policyHash = hashObject(policy);
+  const simulationHash = hashObject(simulation ?? {});
+
+  const receipt = {
+    receiptId: randomUUID(),
+    issuedAt,
+    botId: intent.botId,
+    controllerWallet: intent.controllerWallet,
+    policyId: policy.id,
+    policyHash,
+    authorizationType: decision.authorizationType,
+    allowed: decision.allowed,
+    riskScore: risk.score,
+    riskFindings: risk.findings,
+    simulationHash,
+    intentHash: hashObject(intent),
+    transactionSignature: intent.transactionSignature ?? null
+  };
+
+  return {
+    ...receipt,
+    receiptHash: hashObject(receipt)
+  };
+}
+
+function sortObject(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortObject);
+  }
+
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce((result, key) => {
+        result[key] = sortObject(value[key]);
+        return result;
+      }, {});
+  }
+
+  return value;
+}

package/dist/signed-proof-read-protection.js

@@ -0,0 +1,495 @@
+import { hashObject } from "./receipt.js";
+import { createSignedBotRequest } from "./svs-client.js";
+
+export const SIGNED_PROOF_READ_PROTECTION_VERSION = "svs.signed-proof-read-protection-evidence.v1";
+export const SIGNED_PROOF_READ_PROTECTION_VERIFICATION_VERSION = "svs.signed-proof-read-protection-verification.v1";
+export const DEFAULT_SIGNED_PROOF_READ_PROTECTION_EVIDENCE_PATH = "./data/security/signed-proof-read-protection-evidence.json";
+
+export async function createSignedProofReadProtectionEvidence({
+  serverUrl = "http://127.0.0.1:4173",
+  recordId,
+  apiKey,
+  requestSigningSecret,
+  botId = null,
+  forbiddenBotId = null,
+  forbiddenApiKey = null,
+  forbiddenRequestSigningSecret = null,
+  checkReceiptRegistryChain = false,
+  fetchImpl = globalThis.fetch,
+  now = new Date()
+} = {}) {
+  if (!recordId) {
+    throw new Error("recordId is required.");
+  }
+
+  if (!apiKey) {
+    throw new Error("apiKey is required.");
+  }
+
+  if (!requestSigningSecret) {
+    throw new Error("requestSigningSecret is required.");
+  }
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("A fetch implementation is required.");
+  }
+
+  const checkedAt = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
+  const baseUrl = String(serverUrl).replace(/\/+$/, "");
+  const statusPath = `/api/actions/${encodeURIComponent(recordId)}/production-proof-status`;
+  const proofPath = `/api/actions/${encodeURIComponent(recordId)}/production-proof?checkReceiptRegistryChain=${checkReceiptRegistryChain ? "true" : "false"}`;
+  const unsignedStatus = await requestJson({
+    fetchImpl,
+    url: `${baseUrl}${statusPath}`,
+    headers: {
+      authorization: `Bearer ${apiKey}`
+    }
+  });
+  const signedStatus = await signedGetJson({
+    fetchImpl,
+    url: `${baseUrl}${statusPath}`,
+    apiKey,
+    requestSigningSecret,
+    timestamp: checkedAt
+  });
+  const signedProof = await signedGetJson({
+    fetchImpl,
+    url: `${baseUrl}${proofPath}`,
+    apiKey,
+    requestSigningSecret,
+    timestamp: checkedAt
+  });
+  const shouldCheckForeignBot = Boolean(forbiddenApiKey || forbiddenRequestSigningSecret || forbiddenBotId);
+  const missingForeignCredentials = shouldCheckForeignBot && (!forbiddenApiKey || !forbiddenRequestSigningSecret);
+  const foreignSignedStatus = !missingForeignCredentials && shouldCheckForeignBot
+    ? await signedGetJson({
+        fetchImpl,
+        url: `${baseUrl}${statusPath}`,
+        apiKey: forbiddenApiKey,
+        requestSigningSecret: forbiddenRequestSigningSecret,
+        timestamp: checkedAt
+      })
+    : null;
+  const foreignSignedProof = !missingForeignCredentials && shouldCheckForeignBot
+    ? await signedGetJson({
+        fetchImpl,
+        url: `${baseUrl}${proofPath}`,
+        apiKey: forbiddenApiKey,
+        requestSigningSecret: forbiddenRequestSigningSecret,
+        timestamp: checkedAt
+      })
+    : null;
+  const unsigned = {
+    version: SIGNED_PROOF_READ_PROTECTION_VERSION,
+    ok: null,
+    status: null,
+    checkedAt,
+    serverUrl: baseUrl,
+    botId,
+    recordId,
+    proofReadPolicy: {
+      unsignedReadMustFail: true,
+      signedStatusReadMustSucceed: true,
+      signedProofReadMustSucceed: true,
+      foreignSignedReadMustFail: shouldCheckForeignBot,
+      signedReadBody: "",
+      checkReceiptRegistryChain: Boolean(checkReceiptRegistryChain),
+      scope: {
+        type: "record_owner_bot",
+        ownerBotId: botId,
+        forbiddenBotId,
+        missingForeignCredentials
+      }
+    },
+    unsignedStatusRead: summarizeResponse(unsignedStatus),
+    signedStatusRead: summarizeResponse(signedStatus, {
+      expectedVersion: "svs.action-production-proof-status.v1",
+      recordId
+    }),
+    signedProofRead: summarizeResponse(signedProof, {
+      expectedVersion: "svs.action-production-proof-response.v1",
+      recordId
+    }),
+    foreignSignedStatusRead: shouldCheckForeignBot
+      ? summarizeResponse(foreignSignedStatus, {
+          expectedVersion: "svs.action-production-proof-status.v1",
+          recordId,
+          missingCredentials: missingForeignCredentials
+        })
+      : null,
+    foreignSignedProofRead: shouldCheckForeignBot
+      ? summarizeResponse(foreignSignedProof, {
+          expectedVersion: "svs.action-production-proof-response.v1",
+          recordId,
+          missingCredentials: missingForeignCredentials
+        })
+      : null,
+    secretMaterialRedacted: true
+  };
+  const failedChecks = createSignedProofReadProtectionChecks(unsigned)
+    .filter((check) => !check.ok)
+    .map((check) => ({
+      name: check.name,
+      category: signedProofReadProtectionFailureCategory(check),
+      detail: check.detail
+    }));
+  const evidence = {
+    ...unsigned,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "passed" : "failed",
+    failedCheckCount: failedChecks.length,
+    failedChecks
+  };
+
+  return {
+    ...evidence,
+    evidenceHash: hashSignedProofReadProtectionEvidence(evidence)
+  };
+}
+
+export function verifySignedProofReadProtectionEvidence(evidence, {
+  expectedRecordId = null,
+  staleAfterMs = null,
+  now = new Date()
+} = {}) {
+  const recomputedHash = hashSignedProofReadProtectionEvidence(evidence);
+  const freshness = checkEvidenceFreshness({
+    generatedAt: evidence?.checkedAt,
+    staleAfterMs,
+    now
+  });
+  const checks = [
+    check(
+      "Signed proof-read protection evidence version is supported",
+      evidence?.version === SIGNED_PROOF_READ_PROTECTION_VERSION,
+      evidence?.version ?? "missing"
+    ),
+    check(
+      "Signed proof-read protection evidence hash is valid",
+      evidence?.evidenceHash === recomputedHash,
+      `declared=${evidence?.evidenceHash ?? "missing"} recomputed=${recomputedHash ?? "missing"}`
+    ),
+    check(
+      "Signed proof-read protection evidence excludes secrets",
+      evidence?.secretMaterialRedacted === true && !containsSecretMaterial(evidence),
+      `secretMaterialRedacted=${evidence?.secretMaterialRedacted ?? "missing"}`
+    ),
+    ...createSignedProofReadProtectionChecks(evidence)
+  ];
+
+  if (expectedRecordId) {
+    checks.push(check(
+      "Signed proof-read protection record matches expected record",
+      evidence?.recordId === expectedRecordId,
+      `expected=${expectedRecordId} actual=${evidence?.recordId ?? "missing"}`
+    ));
+  }
+
+  if (staleAfterMs !== null && staleAfterMs !== undefined) {
+    checks.push(check(
+      "Signed proof-read protection evidence is fresh",
+      !freshness.stale,
+      freshness.ageMs === null
+        ? `checkedAt=${evidence?.checkedAt ?? "missing"}`
+        : `ageMs=${freshness.ageMs} staleAfterMs=${staleAfterMs}`
+    ));
+  }
+
+  const failedChecks = checks
+    .filter((item) => !item.ok)
+    .map((item) => ({
+      name: item.name,
+      category: signedProofReadProtectionFailureCategory(item),
+      detail: item.detail
+    }));
+
+  return {
+    version: SIGNED_PROOF_READ_PROTECTION_VERIFICATION_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "verified" : freshness.stale ? "stale" : "failed",
+    checkedAt: now instanceof Date ? now.toISOString() : new Date(now).toISOString(),
+    found: Boolean(evidence),
+    stale: freshness.stale,
+    ageMs: freshness.ageMs,
+    staleAfterMs,
+    evidenceHash: evidence?.evidenceHash ?? null,
+    computedEvidenceHash: recomputedHash,
+    botId: evidence?.botId ?? null,
+    recordId: evidence?.recordId ?? null,
+    unsignedRejected: evidence?.unsignedStatusRead?.accepted === false,
+    signedStatusAccepted: evidence?.signedStatusRead?.accepted === true,
+    signedProofAccepted: evidence?.signedProofRead?.accepted === true,
+    signedProofSetHash: evidence?.signedProofRead?.proofSetHash ?? null,
+    foreignBotId: evidence?.proofReadPolicy?.scope?.forbiddenBotId ?? null,
+    foreignStatusRejected: evidence?.foreignSignedStatusRead?.accepted === false,
+    foreignProofRejected: evidence?.foreignSignedProofRead?.accepted === false,
+    failedCheckCount: failedChecks.length,
+    failedChecks,
+    checks
+  };
+}
+
+export function hashSignedProofReadProtectionEvidence(evidence) {
+  if (!evidence || typeof evidence !== "object") {
+    return null;
+  }
+
+  const {
+    evidenceHash,
+    ok,
+    status,
+    failedCheckCount,
+    failedChecks,
+    ...hashable
+  } = evidence;
+
+  return hashObject(hashable);
+}
+
+async function signedGetJson({
+  fetchImpl,
+  url,
+  apiKey,
+  requestSigningSecret,
+  timestamp
+}) {
+  const signed = createSignedBotRequest({
+    body: "",
+    requestSigningSecret,
+    timestamp,
+    headers: {
+      authorization: `Bearer ${apiKey}`
+    }
+  });
+
+  return await requestJson({
+    fetchImpl,
+    url,
+    headers: signed.headers
+  });
+}
+
+async function requestJson({
+  fetchImpl,
+  url,
+  headers
+}) {
+  let response;
+
+  try {
+    response = await fetchImpl(url, {
+      method: "GET",
+      headers
+    });
+  } catch (error) {
+    return {
+      url,
+      statusCode: null,
+      ok: false,
+      body: {
+        error: error?.message ?? "fetch failed",
+        cause: error?.cause?.message ?? null,
+        code: error?.cause?.code ?? null
+      },
+      bodyHash: hashObject({
+        error: error?.message ?? "fetch failed",
+        cause: error?.cause?.message ?? null,
+        code: error?.cause?.code ?? null
+      }),
+      bodyBytes: 0
+    };
+  }
+
+  const text = await response.text();
+  let body = null;
+
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+
+  return {
+    url,
+    statusCode: response.status,
+    ok: response.ok === true,
+    body,
+    bodyHash: hashObject({ text }),
+    bodyBytes: Buffer.byteLength(text, "utf8")
+  };
+}
+
+function summarizeResponse(response, {
+  expectedVersion = null,
+  recordId = null,
+  missingCredentials = false
+} = {}) {
+  const body = response?.body;
+  const proof = body?.proof;
+
+  return {
+    statusCode: response?.statusCode ?? null,
+    accepted: response?.statusCode >= 200 && response?.statusCode < 300,
+    missingCredentials: Boolean(missingCredentials),
+    bodyHash: response?.bodyHash ?? null,
+    bodyBytes: response?.bodyBytes ?? null,
+    version: body?.version ?? null,
+    expectedVersion,
+    recordId: body?.recordId ?? proof?.recordId ?? body?.evidence?.productionProof?.recordId ?? null,
+    expectedRecordId: recordId,
+    ready: body?.ready ?? null,
+    error: body?.error ?? null,
+    errorCause: body?.cause ?? null,
+    errorCode: body?.code ?? null,
+    proofSetHash: proof?.verificationSetHash ?? proof?.manifest?.verificationSetHash ?? null
+  };
+}
+
+function createSignedProofReadProtectionChecks(evidence) {
+  const checks = [
+    check(
+      "Unsigned production proof status read is rejected",
+      evidence?.unsignedStatusRead?.accepted === false &&
+        evidence.unsignedStatusRead.statusCode === 401 &&
+        /signature/i.test(evidence.unsignedStatusRead.error ?? ""),
+      `status=${evidence?.unsignedStatusRead?.statusCode ?? "missing"} error=${evidence?.unsignedStatusRead?.error ?? "missing"}`
+    ),
+    check(
+      "Signed production proof status read succeeds",
+      evidence?.signedStatusRead?.accepted === true &&
+        evidence.signedStatusRead.statusCode === 200 &&
+        evidence.signedStatusRead.version === "svs.action-production-proof-status.v1",
+      `status=${evidence?.signedStatusRead?.statusCode ?? "missing"} version=${evidence?.signedStatusRead?.version ?? "missing"}`
+    ),
+    check(
+      "Signed production proof status read is ready",
+      evidence?.signedStatusRead?.ready === true,
+      `ready=${evidence?.signedStatusRead?.ready ?? "missing"}`
+    ),
+    check(
+      "Signed production proof response read succeeds",
+      evidence?.signedProofRead?.accepted === true &&
+        evidence.signedProofRead.statusCode === 200 &&
+        evidence.signedProofRead.version === "svs.action-production-proof-response.v1",
+      `status=${evidence?.signedProofRead?.statusCode ?? "missing"} version=${evidence?.signedProofRead?.version ?? "missing"}`
+    ),
+    check(
+      "Signed proof-read responses match the expected action record",
+      evidence?.recordId &&
+        evidence.signedStatusRead?.recordId === evidence.recordId &&
+        evidence.signedProofRead?.recordId === evidence.recordId,
+      `expected=${evidence?.recordId ?? "missing"} status=${evidence?.signedStatusRead?.recordId ?? "missing"} proof=${evidence?.signedProofRead?.recordId ?? "missing"}`
+    )
+  ];
+
+  if (evidence?.proofReadPolicy?.foreignSignedReadMustFail === true) {
+    checks.push(
+      check(
+        "Foreign signed production proof status read is rejected",
+        evidence?.foreignSignedStatusRead?.accepted === false &&
+          evidence.foreignSignedStatusRead.statusCode === 403 &&
+          /cannot inspect action|not allowed|forbidden|unauthorized/i.test(evidence.foreignSignedStatusRead.error ?? ""),
+        `status=${evidence?.foreignSignedStatusRead?.statusCode ?? "missing"} error=${evidence?.foreignSignedStatusRead?.error ?? "missing"} missingCredentials=${evidence?.foreignSignedStatusRead?.missingCredentials ?? "missing"}`
+      ),
+      check(
+        "Foreign signed production proof response read is rejected",
+        evidence?.foreignSignedProofRead?.accepted === false &&
+          evidence.foreignSignedProofRead.statusCode === 403 &&
+          /cannot inspect action|not allowed|forbidden|unauthorized/i.test(evidence.foreignSignedProofRead.error ?? ""),
+        `status=${evidence?.foreignSignedProofRead?.statusCode ?? "missing"} error=${evidence?.foreignSignedProofRead?.error ?? "missing"} missingCredentials=${evidence?.foreignSignedProofRead?.missingCredentials ?? "missing"}`
+      )
+    );
+  }
+
+  return checks;
+}
+
+function check(name, ok, detail = null) {
+  return {
+    name,
+    ok: Boolean(ok),
+    detail
+  };
+}
+
+function checkEvidenceFreshness({
+  generatedAt,
+  staleAfterMs,
+  now
+}) {
+  if (staleAfterMs === null || staleAfterMs === undefined) {
+    return {
+      stale: false,
+      ageMs: null
+    };
+  }
+
+  const generatedMs = Date.parse(generatedAt);
+  const nowMs = now instanceof Date ? now.getTime() : Date.parse(now);
+
+  if (!Number.isFinite(generatedMs) || !Number.isFinite(nowMs)) {
+    return {
+      stale: true,
+      ageMs: null
+    };
+  }
+
+  const ageMs = nowMs - generatedMs;
+
+  return {
+    stale: ageMs < 0 || ageMs > staleAfterMs,
+    ageMs
+  };
+}
+
+function containsSecretMaterial(value) {
+  const text = JSON.stringify(value ?? {});
+
+  return [
+    /SVS_BOT_API_KEY=/i,
+    /SVS_BOT_REQUEST_SIGNING_SECRET=/i,
+    /requestSigningSecret/i,
+    /apiKey/i,
+    /authorization:\s*bearer/i,
+    /svs-request-signature/i,
+    /v1=[0-9a-f]{64}/i
+  ].some((pattern) => pattern.test(text));
+}
+
+function signedProofReadProtectionFailureCategory(check) {
+  const name = String(check?.name ?? "").toLowerCase();
+
+  if (name.includes("unsigned")) {
+    return "unsigned_proof_read_not_rejected";
+  }
+
+  if (name.includes("status read succeeds") || name.includes("status read is ready")) {
+    return "signed_proof_status_read_failed";
+  }
+
+  if (name.includes("response read succeeds")) {
+    return "signed_proof_response_read_failed";
+  }
+
+  if (name.includes("foreign signed")) {
+    return "foreign_signed_proof_read_not_rejected";
+  }
+
+  if (name.includes("record matches")) {
+    return "signed_proof_read_record_mismatch";
+  }
+
+  if (name.includes("fresh")) {
+    return "signed_proof_read_evidence_stale";
+  }
+
+  if (name.includes("secret")) {
+    return "signed_proof_read_secret_leak";
+  }
+
+  if (name.includes("hash") || name.includes("version")) {
+    return "signed_proof_read_evidence_invalid";
+  }
+
+  return "signed_proof_read_failed";
+}

package/dist/solana-agent-kit.d.ts

@@ -0,0 +1,35 @@
+import type {
+  SvsAdapterActionInput,
+  SvsAdapterActionResult,
+  SvsAdapterOptions,
+  SvsAdapterReadinessResult,
+  JsonObject
+} from "./common.js";
+import { SvsAdapterCoreError } from "./adapter-core.js";
+
+export const SOLANA_AGENT_KIT_ADAPTER_VERSION: "svs.solana-agent-kit-adapter.v1";
+export const SOLANA_AGENT_KIT_TOOL_NAME: "svs_verify_and_submit_solana_action";
+
+export class SvsSolanaAgentKitAdapterError extends SvsAdapterCoreError {}
+
+export interface SvsSolanaAgentKitAdapter {
+  version: typeof SOLANA_AGENT_KIT_ADAPTER_VERSION;
+  name: typeof SOLANA_AGENT_KIT_TOOL_NAME;
+  description: string;
+  botId: string;
+  policyId: string | null;
+  rpcUrl: string | null;
+  client: unknown;
+  requireSvsProductionReady(options?: Partial<SvsAdapterOptions>): Promise<SvsAdapterReadinessResult>;
+  verifyAndSubmitSolanaAction(input: SvsAdapterActionInput, options?: Partial<SvsAdapterOptions>): Promise<SvsAdapterActionResult>;
+  tool: {
+    name: typeof SOLANA_AGENT_KIT_TOOL_NAME;
+    description: string;
+    parameters: JsonObject;
+    execute(input: SvsAdapterActionInput): Promise<SvsAdapterActionResult>;
+  };
+}
+
+export function createSvsSolanaAgentKitAdapter(options: SvsAdapterOptions): SvsSolanaAgentKitAdapter;
+export function requireSvsProductionReady(options: SvsAdapterOptions): Promise<SvsAdapterReadinessResult>;
+export function verifyAndSubmitSolanaAction(options: SvsAdapterOptions & SvsAdapterActionInput): Promise<SvsAdapterActionResult>;