@brainai/satp-client 2.0.1 → 2.0.2

package/examples/runtime-policy-adapter.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+const { evaluateRuntimePolicy } = require('..');
+
+const trustedIdentity = {
+  agentId: 'brainchain-demo',
+  active: true,
+  satpVerified: true,
+  trustScore: 88,
+  capabilities: ['mcp:deploy-readiness', 'satp:trust-read'],
+  evidenceUpdatedAt: '2026-05-21T00:00:00Z',
+};
+
+const examples = [
+  {
+    name: 'MCP protected tool',
+    identity: trustedIdentity,
+    action: {
+      type: 'mcp_protected_tool',
+      resource: 'mcp://protected/deploy-readiness',
+      operation: 'read',
+      requiresCapability: 'mcp:deploy-readiness',
+      requiresFreshEvidence: true,
+    },
+  },
+  {
+    name: 'x402 paid endpoint',
+    identity: trustedIdentity,
+    action: {
+      type: 'x402_endpoint',
+      resource: 'https://api.example.test/reputation',
+      operation: 'lookup',
+      costUsd: 0.05,
+    },
+    options: {
+      actionPaymentPreapproved: true,
+      policy: { maxAutoSpendUsd: 0.01 },
+    },
+  },
+  {
+    name: 'Host trust-score degrade',
+    identity: { ...trustedIdentity, trustScore: 62 },
+    action: {
+      type: 'host_trust_gate',
+      resource: 'satp://trust-score',
+      operation: 'gate',
+      minimumTrustScore: 80,
+      allowDegraded: true,
+    },
+  },
+  {
+    name: 'Optional paid x402 evidence lookup',
+    identity: { ...trustedIdentity, evidenceUpdatedAt: '2026-04-01T00:00:00Z' },
+    action: {
+      type: 'mcp_protected_tool',
+      resource: 'mcp://protected/high-risk-action',
+      operation: 'prepare',
+      requiresFreshEvidence: true,
+      evidenceLookup: {
+        type: 'x402',
+        endpoint: 'https://api.example.test/evidence',
+        maxCostUsd: 0.05,
+      },
+    },
+    options: {
+      now: '2026-05-21T00:00:00Z',
+    },
+  },
+];
+
+for (const item of examples) {
+  const result = evaluateRuntimePolicy(item.identity, item.action, item.options);
+  console.log(JSON.stringify({ name: item.name, ...result }, null, 2));
+}

package/examples/x402-discovery-evidence-lookup.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('node:assert/strict');
+const {
+  X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+  parseX402DiscoveryMetadata,
+  buildX402EvidenceLookup,
+  buildRuntimePolicyActionDescriptorFromX402Discovery,
+} = require('../src');
+
+const discoveryMetadata = {
+  action: 'satp.resolveIdentity',
+  endpoint: 'https://example.invalid/.well-known/x402/satp',
+  accepts: [
+    {
+      scheme: 'exact',
+      network: 'base',
+      asset: 'USDC',
+      amountRequired: '1',
+      resource: 'satp://identity/brainChain',
+      description: 'Read-only SATP evidence lookup',
+      mimeType: 'application/json',
+    },
+  ],
+};
+
+const discovery = parseX402DiscoveryMetadata(discoveryMetadata);
+const evidenceLookup = buildX402EvidenceLookup(discoveryMetadata, {
+  sourceKind: 'well-known-x402',
+  maxCostUsd: 0.01,
+});
+const descriptor = buildRuntimePolicyActionDescriptorFromX402Discovery(discoveryMetadata, {
+  sourceKind: 'well-known-x402',
+  maxCostUsd: 0.01,
+});
+
+assert.equal(discovery.guardrail, X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+assert.equal(evidenceLookup.guardrail, X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+assert.equal(evidenceLookup.paymentAuthorization, false);
+assert.equal(evidenceLookup.actionAuthorization, false);
+assert.equal(evidenceLookup.spendAuthorized, false);
+assert.equal(evidenceLookup.livePaymentRequired, false);
+assert.equal(descriptor.guardrail, X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+assert.equal(descriptor.paymentAuthorization, false);
+assert.equal(descriptor.actionAuthorization, false);
+assert.equal(descriptor.spendAuthorized, false);
+assert.equal(descriptor.livePaymentRequired, false);
+assert.deepEqual(descriptor.evidenceLookup, evidenceLookup);
+
+console.log(JSON.stringify(
+  {
+    resource: discovery.resource,
+    endpoint: discovery.endpoint,
+    evidenceLookupType: evidenceLookup.type,
+    operation: descriptor.operation,
+    guardrail: descriptor.guardrail,
+    paymentAuthorization: descriptor.paymentAuthorization,
+    actionAuthorization: descriptor.actionAuthorization,
+    spendAuthorized: descriptor.spendAuthorized,
+    livePaymentRequired: descriptor.livePaymentRequired,
+    warning: 'x402 payment metadata is discovery/evidence lookup only; it is not action authorization.',
+  },
+  null,
+  2
+));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainai/satp-client",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "SATP client SDK surface prepared for release-candidate review; publish only after the release packet passes.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -9,15 +9,29 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./wallet-control-challenge": {
+      "types": "./src/index.d.ts",
+      "default": "./src/wallet-control-challenge.js"
+    },
+    "./x402-discovery": {
+      "types": "./src/index.d.ts",
+      "default": "./src/x402-discovery.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "src/",
+    "examples/",
     "README.md"
   ],
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js",
+    "test:runtime-policy": "node --test test-runtime-policy-adapter.js",
+    "runtime-policy:example": "node examples/runtime-policy-adapter.js",
+    "test:wallet-control": "node test-wallet-control-challenge.js",
+    "test:x402-discovery": "node test-x402-discovery.js",
+    "check:exports": "node test-release-safety.js"
   },
   "keywords": [
     "solana",
@@ -45,7 +59,10 @@
   },
   "private": false,
   "overrides": {
-    "ws": "^8.20.1"
+    "ws": "^8.21.0",
+    "jayson": {
+      "uuid": "^11.1.1"
+    }
   },
   "publishConfig": {
     "tag": "rc",

package/src/index.d.ts

@@ -89,6 +89,180 @@ export interface SatpTrustPacketValidation {
   errors: string[];
 }
 
+export interface X402PaymentRequirement {
+  scheme?: string;
+  network?: string;
+  asset?: string;
+  payTo?: string;
+  maxAmountRequired?: string | number;
+  amountRequired?: string | number;
+  resource?: string;
+  description?: string;
+  mimeType?: string;
+  maxTimeoutSeconds?: number;
+  extra?: unknown;
+}
+
+export interface X402DiscoveryMetadata {
+  schemaVersion: 'satp.x402DiscoveryMetadata.v1';
+  protocol: 'x402';
+  resource: string | null;
+  endpoint: string | null;
+  action: string | null;
+  paymentRequired: boolean;
+  paymentRequirements: X402PaymentRequirement[];
+  guardrail: 'X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION';
+}
+
+export interface X402EvidenceLookup {
+  type: 'x402';
+  endpoint: string | null;
+  maxCostUsd: number | null;
+  protocol: 'x402';
+  source: {
+    kind: string;
+    url: string | null;
+  };
+  resource: string | null;
+  paymentRequired: boolean;
+  paymentRequirements: X402PaymentRequirement[];
+  discovery: X402DiscoveryMetadata;
+  guardrail: 'X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION';
+  paymentAuthorization: false;
+  actionAuthorization: false;
+  spendAuthorized: false;
+  livePaymentRequired: false;
+}
+
+export type RuntimePolicyDecision =
+  | 'allow'
+  | 'deny'
+  | 'degrade'
+  | 'needs_approval';
+
+export interface RuntimePolicyIdentityPayload {
+  active?: boolean;
+  satpVerified?: boolean;
+  verified?: boolean;
+  agentFolioTrustScore?: number;
+  trustScore?: number;
+  capabilities?: string[];
+  evidenceUpdatedAt?: string | number | Date | null;
+}
+
+export interface RuntimePolicyActionDescriptor {
+  type?: string;
+  resource?: string;
+  operation?: string;
+  requiresCapability?: string;
+  minimumTrustScore?: number;
+  allowDegraded?: boolean;
+  requiresFreshEvidence?: boolean;
+  costUsd?: number;
+  protectedTool?: boolean;
+  operatorApprovalRequired?: boolean;
+  evidenceLookup?: {
+    type?: string;
+    endpoint?: string;
+    maxCostUsd?: number;
+  } | X402EvidenceLookup;
+}
+
+export interface RuntimePolicyConfig {
+  minimumTrustScore?: number;
+  denyTrustScoreBelow?: number;
+  maxAutoSpendUsd?: number;
+  requireVerifiedIdentity?: boolean;
+  staleEvidenceAfterMs?: number;
+}
+
+export interface RuntimePolicyOptions {
+  now?: string | number | Date;
+  actionPaymentPreapproved?: boolean;
+  evidenceLookupPaymentPreapproved?: boolean;
+  operatorApproved?: boolean;
+  policy?: RuntimePolicyConfig;
+}
+
+export interface RuntimePolicyResult {
+  decision: RuntimePolicyDecision;
+  reasonCodes: string[];
+  message: string;
+  checks: Record<string, unknown>;
+}
+
+export const DECISIONS: Readonly<{
+  ALLOW: 'allow';
+  DENY: 'deny';
+  DEGRADE: 'degrade';
+  NEEDS_APPROVAL: 'needs_approval';
+}>;
+
+export const REASON_CODES: Readonly<Record<string, string>>;
+export const DEFAULT_POLICY: Readonly<Required<RuntimePolicyConfig>>;
+
+export function evaluateRuntimePolicy(
+  identityPayload: RuntimePolicyIdentityPayload,
+  actionDescriptor: RuntimePolicyActionDescriptor,
+  options?: RuntimePolicyOptions
+): RuntimePolicyResult;
+
+export interface WalletControlChallengeOptions {
+  agentId: string;
+  wallet: PublicKey | string;
+  network?: Network;
+  domain?: string;
+  audience?: string;
+  nonce?: string;
+  issuedAt?: number;
+  expiresAt?: number;
+}
+
+export interface WalletControlChallenge {
+  schemaVersion: 'satp.walletControlChallenge.v1';
+  challengeType: 'wallet-control';
+  domain: string;
+  audience: string;
+  network: Network;
+  agentId: string;
+  wallet: string;
+  nonce: string;
+  issuedAt: number;
+  expiresAt: number;
+  agentIdHash: string;
+  genesisPda: string;
+  genesisBump: number;
+  linkedWalletPda: string;
+  linkedWalletBump: number;
+}
+
+export interface WalletControlChallengePdas {
+  agentIdHash: string;
+  genesisPda: string;
+  genesisBump: number;
+  linkedWalletPda: string;
+  linkedWalletBump: number;
+}
+
+export interface VerifyWalletControlChallengeSignatureOptions {
+  challenge: WalletControlChallenge | Record<string, unknown>;
+  signature: string | Buffer | Uint8Array | number[];
+  expectedWallet?: PublicKey | string;
+  expectedAgentId?: string;
+  expectedDomain?: string;
+  expectedAudience?: string;
+  now?: number;
+  usedNonces?: Set<string> | string[] | Record<string, boolean>;
+  replayCache?: { has(nonce: string): boolean } | string[] | Record<string, boolean>;
+  isNonceUsed?: (nonce: string, challenge: WalletControlChallenge) => boolean;
+}
+
+export interface WalletControlChallengeVerification {
+  ok: boolean;
+  errors: string[];
+  challengeHash: string;
+}
+
 // ─── V2 SDK ──────────────────────────────────────────────
 
 export interface V2ProgramIds {
@@ -235,6 +409,73 @@ export function validateSatpTrustPacket(
   packet: SatpTrustPacket | Record<string, unknown> | null | undefined
 ): SatpTrustPacketValidation;
 
+export const X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION: 'X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION';
+export const X402_DISCOVERY_SCHEMA_VERSION: 'satp.x402DiscoveryMetadata.v1';
+export const RUNTIME_POLICY_ACTION_DESCRIPTOR_SCHEMA_VERSION: 'satp.runtimePolicyActionDescriptor.v1';
+
+export function parseX402DiscoveryMetadata(
+  input: Record<string, unknown> | string
+): X402DiscoveryMetadata;
+
+export function buildX402EvidenceLookup(
+  input: Record<string, unknown> | string,
+  opts?: {
+    endpoint?: string;
+    maxCostUsd?: number;
+    sourceKind?: string;
+    sourceUrl?: string;
+  }
+): X402EvidenceLookup;
+
+export function buildRuntimePolicyActionDescriptorFromX402Discovery(
+  input: Record<string, unknown> | string,
+  opts?: {
+    type?: string;
+    resource?: string;
+    operation?: string;
+    requiresFreshEvidence?: boolean;
+    endpoint?: string;
+    maxCostUsd?: number;
+    sourceKind?: string;
+    sourceUrl?: string;
+  }
+): RuntimePolicyActionDescriptor & {
+  schemaVersion: 'satp.runtimePolicyActionDescriptor.v1';
+  evidenceLookup: X402EvidenceLookup;
+  paymentAuthorization: false;
+  actionAuthorization: false;
+  spendAuthorized: false;
+  livePaymentRequired: false;
+  guardrail: 'X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION';
+};
+
+export const buildRuntimePolicyActionDescriptorFromX402: typeof buildRuntimePolicyActionDescriptorFromX402Discovery;
+
+export const WALLET_CONTROL_CHALLENGE_SCHEMA_VERSION: 'satp.walletControlChallenge.v1';
+export const WALLET_CONTROL_CHALLENGE_TYPE: 'wallet-control';
+export const DEFAULT_WALLET_CONTROL_DOMAIN: string;
+export const DEFAULT_WALLET_CONTROL_AUDIENCE: string;
+
+export function buildWalletControlChallenge(
+  opts: WalletControlChallengeOptions
+): WalletControlChallenge;
+
+export function canonicalWalletControlChallenge(
+  challenge: WalletControlChallenge | Record<string, unknown>
+): string;
+
+export function hashWalletControlChallenge(
+  challenge: WalletControlChallenge | Record<string, unknown>
+): string;
+
+export function deriveWalletControlChallengePdas(
+  opts: Pick<WalletControlChallengeOptions, 'agentId' | 'wallet' | 'network'>
+): WalletControlChallengePdas;
+
+export function verifyWalletControlChallengeSignature(
+  opts: VerifyWalletControlChallengeSignatureOptions
+): WalletControlChallengeVerification;
+
 // ─── Borsh Deserialization Helpers ──────────────────────
 
 export {

package/src/index.js

@@ -783,6 +783,14 @@ const {
   buildSatpTrustPacket,
   validateSatpTrustPacket,
 } = require('./trust-packet');
+const {
+  DECISIONS,
+  DEFAULT_POLICY,
+  REASON_CODES,
+  evaluateRuntimePolicy,
+} = require('./runtime-policy-adapter');
+const walletControlChallenge = require('./wallet-control-challenge');
+const x402Discovery = require('./x402-discovery');
 
 // Legacy V3 SDK wrapper — keeps string constructor compatibility while using
 // the local extracted SATPV3SDK implementation so offline tests and consumers
@@ -926,6 +934,28 @@ module.exports = {
   TRUST_PACKET_SCHEMA_VERSION,
   buildSatpTrustPacket,
   validateSatpTrustPacket,
+  WALLET_CONTROL_CHALLENGE_SCHEMA_VERSION: walletControlChallenge.WALLET_CONTROL_CHALLENGE_SCHEMA_VERSION,
+  WALLET_CONTROL_CHALLENGE_TYPE: walletControlChallenge.WALLET_CONTROL_CHALLENGE_TYPE,
+  DEFAULT_WALLET_CONTROL_DOMAIN: walletControlChallenge.DEFAULT_WALLET_CONTROL_DOMAIN,
+  DEFAULT_WALLET_CONTROL_AUDIENCE: walletControlChallenge.DEFAULT_WALLET_CONTROL_AUDIENCE,
+  buildWalletControlChallenge: walletControlChallenge.buildWalletControlChallenge,
+  canonicalWalletControlChallenge: walletControlChallenge.canonicalWalletControlChallenge,
+  hashWalletControlChallenge: walletControlChallenge.hashWalletControlChallenge,
+  deriveWalletControlChallengePdas: walletControlChallenge.deriveWalletControlChallengePdas,
+  verifyWalletControlChallengeSignature: walletControlChallenge.verifyWalletControlChallengeSignature,
+  X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION: x402Discovery.X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+  X402_DISCOVERY_SCHEMA_VERSION: x402Discovery.X402_DISCOVERY_SCHEMA_VERSION,
+  RUNTIME_POLICY_ACTION_DESCRIPTOR_SCHEMA_VERSION: x402Discovery.RUNTIME_POLICY_ACTION_DESCRIPTOR_SCHEMA_VERSION,
+  parseX402DiscoveryMetadata: x402Discovery.parseX402DiscoveryMetadata,
+  buildX402EvidenceLookup: x402Discovery.buildX402EvidenceLookup,
+  buildRuntimePolicyActionDescriptorFromX402Discovery: x402Discovery.buildRuntimePolicyActionDescriptorFromX402Discovery,
+  buildRuntimePolicyActionDescriptorFromX402: x402Discovery.buildRuntimePolicyActionDescriptorFromX402,
+
+  // Runtime policy adapter (offline/local guardrail helper)
+  DECISIONS,
+  DEFAULT_POLICY,
+  REASON_CODES,
+  evaluateRuntimePolicy,
 
   // V3 Deserialization (local extracted scaffold)
   // NOTE: v3sdk.deserializeGenesis has isActive field mismatch with deployed program

package/src/runtime-policy-adapter.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const DECISIONS = Object.freeze({
+  ALLOW: 'allow',
+  DENY: 'deny',
+  DEGRADE: 'degrade',
+  NEEDS_APPROVAL: 'needs_approval',
+});
+
+const REASON_CODES = Object.freeze({
+  ACTION_PAYMENT_NEEDS_APPROVAL: 'ACTION_PAYMENT_NEEDS_APPROVAL',
+  ACTION_PAYMENT_PREAPPROVED: 'ACTION_PAYMENT_PREAPPROVED',
+  EVIDENCE_FRESH: 'EVIDENCE_FRESH',
+  EVIDENCE_STALE_OR_MISSING: 'EVIDENCE_STALE_OR_MISSING',
+  IDENTITY_INACTIVE: 'IDENTITY_INACTIVE',
+  IDENTITY_UNVERIFIED: 'IDENTITY_UNVERIFIED',
+  INVALID_ACTION_COST_USD: 'INVALID_ACTION_COST_USD',
+  LOCAL_POLICY_ALLOW: 'LOCAL_POLICY_ALLOW',
+  MISSING_CAPABILITY: 'MISSING_CAPABILITY',
+  PROTECTED_TOOL_REQUIRES_APPROVAL: 'PROTECTED_TOOL_REQUIRES_APPROVAL',
+  TRUST_SCORE_BELOW_DENY_FLOOR: 'TRUST_SCORE_BELOW_DENY_FLOOR',
+  TRUST_SCORE_BELOW_MINIMUM: 'TRUST_SCORE_BELOW_MINIMUM',
+  TRUST_SCORE_OK: 'TRUST_SCORE_OK',
+  X402_LOOKUP_PAYMENT_PREAPPROVED: 'X402_LOOKUP_PAYMENT_PREAPPROVED',
+  X402_LOOKUP_REQUIRES_APPROVAL: 'X402_LOOKUP_REQUIRES_APPROVAL',
+  X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION: 'X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION',
+});
+
+const DEFAULT_POLICY = Object.freeze({
+  minimumTrustScore: 70,
+  denyTrustScoreBelow: 25,
+  maxAutoSpendUsd: 0,
+  requireVerifiedIdentity: true,
+  staleEvidenceAfterMs: 7 * 24 * 60 * 60 * 1000,
+});
+
+function evaluateRuntimePolicy(identityPayload, actionDescriptor, options = {}) {
+  const policy = { ...DEFAULT_POLICY, ...(options.policy || {}) };
+  const now = options.now ? new Date(options.now) : new Date();
+  const identity = normalizeIdentity(identityPayload);
+  const action = normalizeAction(actionDescriptor);
+  const reasonCodes = [];
+  const checks = {};
+
+  checks.identityActive = identity.active === true;
+  if (!checks.identityActive) {
+    reasonCodes.push(REASON_CODES.IDENTITY_INACTIVE);
+    return decision(DECISIONS.DENY, reasonCodes, checks, 'Identity is not active.');
+  }
+
+  checks.identityVerified = !policy.requireVerifiedIdentity || identity.verified === true;
+  if (!checks.identityVerified) {
+    reasonCodes.push(REASON_CODES.IDENTITY_UNVERIFIED);
+    return decision(DECISIONS.DENY, reasonCodes, checks, 'Identity is not verified by local policy.');
+  }
+
+  checks.hasCapability = !action.requiresCapability || identity.capabilities.includes(action.requiresCapability);
+  if (!checks.hasCapability) {
+    reasonCodes.push(REASON_CODES.MISSING_CAPABILITY);
+    return decision(DECISIONS.DENY, reasonCodes, checks, 'Required capability is absent.');
+  }
+
+  checks.trustScore = identity.trustScore;
+  checks.minimumTrustScore = action.minimumTrustScore ?? policy.minimumTrustScore;
+  if (identity.trustScore < policy.denyTrustScoreBelow) {
+    reasonCodes.push(REASON_CODES.TRUST_SCORE_BELOW_DENY_FLOOR);
+    return decision(DECISIONS.DENY, reasonCodes, checks, 'Trust score is below the deny floor.');
+  }
+
+  if (identity.trustScore < checks.minimumTrustScore) {
+    reasonCodes.push(REASON_CODES.TRUST_SCORE_BELOW_MINIMUM);
+    if (action.allowDegraded === true) {
+      return decision(DECISIONS.DEGRADE, reasonCodes, checks, 'Trust score permits degraded access only.');
+    }
+    return decision(DECISIONS.NEEDS_APPROVAL, reasonCodes, checks, 'Trust score needs an operator decision.');
+  }
+  reasonCodes.push(REASON_CODES.TRUST_SCORE_OK);
+
+  checks.evidenceFresh = isEvidenceFresh(identity, policy, now);
+  if (action.requiresFreshEvidence && !checks.evidenceFresh) {
+    reasonCodes.push(REASON_CODES.EVIDENCE_STALE_OR_MISSING);
+    return staleEvidenceDecision(action, options, reasonCodes, checks);
+  }
+  if (action.requiresFreshEvidence) reasonCodes.push(REASON_CODES.EVIDENCE_FRESH);
+
+  checks.actionCostUsd = action.costUsd;
+  checks.actionCostUsdValid = action.costUsdValid;
+  if (!action.costUsdValid) {
+    reasonCodes.push(REASON_CODES.INVALID_ACTION_COST_USD);
+    return decision(DECISIONS.DENY, reasonCodes, checks, 'Action costUsd must be a finite non-negative number.');
+  }
+
+  checks.maxAutoSpendUsd = policy.maxAutoSpendUsd;
+  if (checks.actionCostUsd > checks.maxAutoSpendUsd && options.actionPaymentPreapproved !== true) {
+    reasonCodes.push(REASON_CODES.ACTION_PAYMENT_NEEDS_APPROVAL);
+    return decision(DECISIONS.NEEDS_APPROVAL, reasonCodes, checks, 'Paid action exceeds local auto-spend policy.');
+  }
+  if (checks.actionCostUsd > 0) {
+    reasonCodes.push(REASON_CODES.ACTION_PAYMENT_PREAPPROVED);
+    reasonCodes.push(REASON_CODES.X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+  }
+
+  if (action.protectedTool && action.operatorApprovalRequired && options.operatorApproved !== true) {
+    reasonCodes.push(REASON_CODES.PROTECTED_TOOL_REQUIRES_APPROVAL);
+    return decision(DECISIONS.NEEDS_APPROVAL, reasonCodes, checks, 'Protected tool requires operator approval.');
+  }
+
+  reasonCodes.push(REASON_CODES.LOCAL_POLICY_ALLOW);
+  return decision(DECISIONS.ALLOW, reasonCodes, checks, 'Local runtime policy allows the action.');
+}
+
+function staleEvidenceDecision(action, options, reasonCodes, checks) {
+  const lookup = action.evidenceLookup || null;
+  if (!lookup || lookup.type !== 'x402') {
+    return decision(DECISIONS.DEGRADE, reasonCodes, checks, 'Evidence is stale or missing; no paid lookup path is configured.');
+  }
+
+  checks.evidenceLookup = {
+    type: lookup.type,
+    endpoint: lookup.endpoint || null,
+    maxCostUsd: lookup.maxCostUsd ?? null,
+  };
+
+  if (options.evidenceLookupPaymentPreapproved !== true) {
+    reasonCodes.push(REASON_CODES.X402_LOOKUP_REQUIRES_APPROVAL);
+    reasonCodes.push(REASON_CODES.X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+    return decision(DECISIONS.NEEDS_APPROVAL, reasonCodes, checks, 'Paid x402 evidence lookup requires approval before use.');
+  }
+
+  reasonCodes.push(REASON_CODES.X402_LOOKUP_PAYMENT_PREAPPROVED);
+  reasonCodes.push(REASON_CODES.X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+  return decision(DECISIONS.DEGRADE, reasonCodes, checks, 'Paid lookup may refresh evidence, but does not authorize the agent action.');
+}
+
+function decision(value, reasonCodes, checks, message) {
+  return {
+    decision: value,
+    reasonCodes: Array.from(new Set(reasonCodes)),
+    message,
+    checks,
+  };
+}
+
+function normalizeIdentity(identity = {}) {
+  return {
+    agentId: identity.agentId || identity.profileId || null,
+    active: identity.active !== false,
+    verified: identity.verified === true || identity.satpVerified === true,
+    trustScore: clampScore(identity.trustScore ?? identity.agentFolioTrustScore ?? 0),
+    capabilities: Array.isArray(identity.capabilities) ? identity.capabilities.slice() : [],
+    evidenceUpdatedAt: identity.evidenceUpdatedAt || identity.lastEvidenceAt || null,
+  };
+}
+
+function normalizeAction(action = {}) {
+  const parsedCost = parseActionCostUsd(action);
+
+  return {
+    type: action.type || 'generic',
+    resource: action.resource || null,
+    operation: action.operation || null,
+    requiresCapability: action.requiresCapability || null,
+    minimumTrustScore: Number.isFinite(action.minimumTrustScore) ? action.minimumTrustScore : null,
+    allowDegraded: action.allowDegraded === true,
+    requiresFreshEvidence: action.requiresFreshEvidence === true,
+    evidenceLookup: action.evidenceLookup || null,
+    protectedTool: action.protectedTool === true || action.type === 'mcp_protected_tool',
+    operatorApprovalRequired: action.operatorApprovalRequired === true,
+    costUsd: parsedCost.value,
+    costUsdValid: parsedCost.valid,
+  };
+}
+
+function parseActionCostUsd(action) {
+  if (!Object.prototype.hasOwnProperty.call(action, 'costUsd') || action.costUsd == null) {
+    return { value: 0, valid: true };
+  }
+
+  if (typeof action.costUsd !== 'number' || !Number.isFinite(action.costUsd) || action.costUsd < 0) {
+    return { value: null, valid: false };
+  }
+
+  return { value: action.costUsd, valid: true };
+}
+
+function clampScore(value) {
+  const score = Number(value);
+  if (!Number.isFinite(score)) return 0;
+  return Math.max(0, Math.min(100, score));
+}
+
+function isEvidenceFresh(identity, policy, now) {
+  if (!identity.evidenceUpdatedAt) return false;
+  const updatedAt = new Date(identity.evidenceUpdatedAt);
+  if (Number.isNaN(updatedAt.getTime())) return false;
+  const ageMs = now.getTime() - updatedAt.getTime();
+  if (ageMs < 0) return false;
+  return ageMs <= policy.staleEvidenceAfterMs;
+}
+
+module.exports = {
+  DECISIONS,
+  DEFAULT_POLICY,
+  REASON_CODES,
+  evaluateRuntimePolicy,
+};