@brainai/satp-client 2.0.0 → 2.0.2

package/src/pda.js

@@ -9,6 +9,7 @@ const {
   REVIEWS_AUTHORITY_SEED,
   ATTESTATION_SEED,
   REVIEW_SEED,
+  ESCROW_SEED,
 } = require('./constants');
 
 /**
@@ -136,6 +137,46 @@ function getReviewAttestationPDA(agentId, reviewsAuthority, reviewer, network =
   );
 }
 
+/**
+ * Derive the Escrow PDA for a client + description_hash pair.
+ * Seeds: ["escrow", client_pubkey, description_hash]
+ * @param {PublicKey|string} client - Client wallet
+ * @param {Buffer|number[]} descriptionHash - 32-byte SHA256 hash of job description
+ * @param {'mainnet'|'devnet'} network
+ */
+function getEscrowPDA(client, descriptionHash, network = 'devnet') {
+  const clientKey = new PublicKey(client);
+  const hashBuf = Buffer.isBuffer(descriptionHash)
+    ? descriptionHash
+    : Buffer.from(descriptionHash);
+  const programIds = getProgramIds(network);
+  if (!programIds.ESCROW) {
+    throw new Error('SATP v2 mainnet escrow program ID is not configured; pass devnet or wait for an approved mainnet escrow deployment');
+  }
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(ESCROW_SEED), clientKey.toBuffer(), hashBuf],
+    programIds.ESCROW
+  );
+}
+
+/**
+ * Derive the Review V3 PDA (job-scoped reviews).
+ * Seeds: ["review", job_pubkey, reviewer_pubkey]
+ * @param {PublicKey|string} jobPDA - Job/Escrow account pubkey
+ * @param {PublicKey|string} reviewer - Reviewer wallet
+ * @param {'mainnet'|'devnet'} network
+ */
+function getReviewV3PDA(jobPDA, reviewer, network = 'devnet') {
+  const jobKey = new PublicKey(jobPDA);
+  const reviewerKey = new PublicKey(reviewer);
+  const programIds = getProgramIds(network);
+  // Reviews V3 uses the same REVIEWS program ID
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(REVIEW_SEED), jobKey.toBuffer(), reviewerKey.toBuffer()],
+    programIds.REVIEWS
+  );
+}
+
 module.exports = {
   getIdentityPDA,
   getReputationAuthorityPDA,
@@ -145,4 +186,6 @@ module.exports = {
   getReviewsAuthorityPDA,
   getReviewPDA,
   getReviewAttestationPDA,
+  getEscrowPDA,
+  getReviewV3PDA,
 };

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,
+};

package/src/trust-packet.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const { prepareIdentityAttestationRequest } = require('./attestation-request');
+
+const TRUST_PACKET_SCHEMA_VERSION = 'satp.trustPacket.v1';
+
+function canonicalStringify(value) {
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalStringify).join(',') + ']';
+  }
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + canonicalStringify(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+function sameJsonValue(left, right) {
+  return canonicalStringify(left) === canonicalStringify(right);
+}
+
+/**
+ * Build a deterministic, read-only SATP trust packet for consumer preflight.
+ *
+ * The packet wraps the unsigned identity-attestation request with the derived
+ * program IDs, Genesis PDA, attestation PDA, request hash, and explicit flags
+ * proving that no signer, transaction, instruction, RPC write, or payment is
+ * required to consume it.
+ */
+function buildSatpTrustPacket(opts = {}) {
+  const request = prepareIdentityAttestationRequest(opts);
+  return {
+    schemaVersion: TRUST_PACKET_SCHEMA_VERSION,
+    packetType: 'satp-trust-packet',
+    mode: 'offline-readonly-trust-packet',
+    network: request.network,
+    subjectWallet: request.subjectWallet,
+    agentId: request.agentId,
+    claimType: request.claimType,
+    attestationType: request.attestationType,
+    metadataHash: request.metadataHash,
+    attester: request.attester,
+    expiresAt: request.expiresAt,
+    programs: { ...request.programs },
+    pda: {
+      genesis: request.genesisPda,
+      genesisBump: request.genesisBump,
+      attestation: request.attestationPda,
+      attestationBump: request.attestationBump,
+    },
+    requestHash: request.requestHash,
+    flags: {
+      signingRequired: false,
+      transactionRequired: false,
+      writesRequired: false,
+      livePaymentRequired: false,
+      unsigned: true,
+      noSign: true,
+      noTransaction: true,
+    },
+    instructions: [],
+    signers: [],
+    transaction: null,
+    request,
+  };
+}
+
+function validateSatpTrustPacket(packet) {
+  const errors = [];
+  if (!packet || typeof packet !== 'object') {
+    return { ok: false, errors: ['packet must be an object'] };
+  }
+
+  if (packet.schemaVersion !== TRUST_PACKET_SCHEMA_VERSION) {
+    errors.push('schemaVersion must be ' + TRUST_PACKET_SCHEMA_VERSION);
+  }
+  if (packet.packetType !== 'satp-trust-packet') {
+    errors.push('packetType must be satp-trust-packet');
+  }
+  if (packet.mode !== 'offline-readonly-trust-packet') {
+    errors.push('mode must be offline-readonly-trust-packet');
+  }
+
+  const expectedFlags = {
+    signingRequired: false,
+    transactionRequired: false,
+    writesRequired: false,
+    livePaymentRequired: false,
+    unsigned: true,
+    noSign: true,
+    noTransaction: true,
+  };
+  if (!sameJsonValue(packet.flags, expectedFlags)) {
+    errors.push('flags must be read-only, unsigned, and no-transaction');
+  }
+  if (!Array.isArray(packet.instructions) || packet.instructions.length !== 0) {
+    errors.push('instructions must be an empty array');
+  }
+  if (!Array.isArray(packet.signers) || packet.signers.length !== 0) {
+    errors.push('signers must be an empty array');
+  }
+  if (packet.transaction !== null) {
+    errors.push('transaction must be null');
+  }
+
+  let expected;
+  try {
+    expected = buildSatpTrustPacket({
+      subjectWallet: packet.subjectWallet,
+      agentId: packet.agentId,
+      claimType: packet.claimType || packet.attestationType,
+      metadataHash: packet.metadataHash,
+      attester: packet.attester,
+      network: packet.network,
+      expiresAt: packet.expiresAt,
+    });
+  } catch (err) {
+    errors.push('packet cannot be re-derived: ' + err.message);
+    return { ok: false, errors };
+  }
+
+  const fields = [
+    'network',
+    'subjectWallet',
+    'agentId',
+    'claimType',
+    'attestationType',
+    'metadataHash',
+    'attester',
+    'expiresAt',
+    'programs',
+    'pda',
+    'requestHash',
+    'request',
+  ];
+  for (const field of fields) {
+    if (!sameJsonValue(packet[field], expected[field])) {
+      errors.push(field + ' does not match derived trust packet');
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  TRUST_PACKET_SCHEMA_VERSION,
+  buildSatpTrustPacket,
+  validateSatpTrustPacket,
+};

package/src/v3-pda.d.ts

@@ -0,0 +1,72 @@
+import { PublicKey } from '@solana/web3.js';
+
+export type Network = 'mainnet' | 'devnet';
+
+export interface V3ProgramIds {
+  IDENTITY: PublicKey;
+  REVIEWS: PublicKey;
+  REPUTATION: PublicKey;
+  ATTESTATIONS: PublicKey;
+  VALIDATION: PublicKey;
+  ESCROW: PublicKey;
+}
+
+/** Get all V3 program IDs for a network. */
+export function getV3ProgramIds(network?: Network): V3ProgramIds;
+
+/** SHA-256 hash of agent ID string. Returns 32-byte Buffer. */
+export function hashAgentId(agentId: string): Buffer;
+
+/** SHA-256 hash of lowercased name string. Returns 32-byte Buffer. */
+export function hashName(name: string): Buffer;
+
+/** Derive Genesis PDA from agent ID hash. */
+export function getGenesisPDA(agentIdHash: string | Buffer, network?: Network): [PublicKey, number];
+
+/** Derive Reputation V3 Authority PDA. */
+export function getV3ReputationAuthorityPDA(network?: Network): [PublicKey, number];
+
+/** Derive Validation V3 Authority PDA. */
+export function getV3ValidationAuthorityPDA(network?: Network): [PublicKey, number];
+
+/** Derive MintTracker PDA from Genesis PDA. */
+export function getV3MintTrackerPDA(genesisPDA: PublicKey | string, network?: Network): [PublicKey, number];
+
+/** Derive NameRegistry PDA from name hash. */
+export function getNameRegistryPDA(nameHash: string | Buffer, network?: Network): [PublicKey, number];
+
+/** Derive LinkedWallet PDA from Genesis PDA and wallet. */
+export function getLinkedWalletPDA(
+  genesisPDA: PublicKey | string,
+  wallet: PublicKey | string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Review V3 PDA from job account and reviewer. */
+export function getV3ReviewPDA(
+  jobPDA: PublicKey | string,
+  reviewer: PublicKey | string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Attestation PDA from agent ID hash, attester, and type. */
+export function getV3AttestationPDA(
+  agentIdHash: string | Buffer,
+  attester: PublicKey | string,
+  attestationType: string,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Review Counter PDA from agent ID. */
+export function getV3ReviewCounterPDA(
+  agentIdOrHash: string | Buffer,
+  network?: Network
+): [PublicKey, number];
+
+/** Derive Escrow V3 PDA from client, description hash, and nonce. */
+export function getV3EscrowPDA(
+  client: PublicKey | string,
+  descriptionHash: Buffer,
+  nonce: number | bigint,
+  network?: Network
+): [PublicKey, number];