@brainai/satp-client 2.0.6 → 2.0.8

package/src/attestation-request.js

@@ -144,6 +144,182 @@ function prepareIdentityAttestationRequest(opts = {}) {
   };
 }
 
+function appendMismatch(errors, field, actual, expected) {
+  try {
+    if (canonicalStringify(actual) !== canonicalStringify(expected)) {
+      errors.push(`${field} does not match the value derived from public inputs`);
+    }
+  } catch (err) {
+    errors.push(`${field} must be canonical JSON-compatible data`);
+  }
+}
+
+function appendExpectation(errors, field, actual, expected, normalize) {
+  if (expected === undefined) return;
+
+  try {
+    const normalizedExpected = normalize ? normalize(expected) : expected;
+    if (actual !== normalizedExpected) {
+      errors.push(`${field} does not match the expected value`);
+    }
+  } catch (err) {
+    errors.push(`expected ${field}: ${err.message}`);
+  }
+}
+
+/**
+ * Verify an offline identity-attestation request from public inputs only.
+ *
+ * The verifier recomputes the canonical request hash, program IDs, agent hash,
+ * and PDAs. It never connects to RPC, reads credentials, builds a transaction,
+ * signs, sends, or mutates chain state.
+ *
+ * @param {object} request
+ * @param {object} [expectations]
+ * @returns {{ok: boolean, errors: string[], warnings: string[]}}
+ */
+function verifyIdentityAttestationRequest(request, expectations = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    return { ok: false, errors: ['request must be an object'], warnings };
+  }
+  if (!expectations || typeof expectations !== 'object' || Array.isArray(expectations)) {
+    return { ok: false, errors: ['expectations must be an object'], warnings };
+  }
+
+  if (request.schemaVersion !== REQUEST_SCHEMA_VERSION) {
+    errors.push(`schemaVersion must be ${REQUEST_SCHEMA_VERSION}`);
+  }
+  if (request.requestType !== 'identity-attestation') {
+    errors.push('requestType must be identity-attestation');
+  }
+  if (request.mode !== 'unsigned-readonly-request') {
+    errors.push('mode must be unsigned-readonly-request');
+  }
+  if (request.signingRequired !== false) {
+    errors.push('signingRequired must be false');
+  }
+  if (request.unsigned !== true) {
+    errors.push('unsigned must be true');
+  }
+  if (!Array.isArray(request.instructions) || request.instructions.length !== 0) {
+    errors.push('instructions must be an empty array');
+  }
+  if (!Array.isArray(request.signers) || request.signers.length !== 0) {
+    errors.push('signers must be an empty array');
+  }
+  if (request.transaction !== null) {
+    errors.push('transaction must be null');
+  }
+
+  const hashPayload = { ...request };
+  delete hashPayload.requestHash;
+  let recomputedRequestHash;
+  try {
+    recomputedRequestHash = hashObject(hashPayload);
+  } catch (err) {
+    errors.push('request payload must be canonical JSON-compatible data');
+  }
+  if (typeof request.requestHash !== 'string' || !/^[a-f0-9]{64}$/.test(request.requestHash)) {
+    errors.push('requestHash must be a lowercase 32-byte hex string');
+  } else if (recomputedRequestHash && request.requestHash !== recomputedRequestHash) {
+    errors.push('requestHash does not match the canonical request payload');
+  }
+
+  let expectedRequest;
+  try {
+    expectedRequest = prepareIdentityAttestationRequest({
+      subjectWallet: request.subjectWallet,
+      agentId: request.agentId,
+      claimType: request.claimType,
+      metadataHash: request.metadataHash,
+      attester: request.attester,
+      network: request.network,
+      expiresAt: request.expiresAt,
+    });
+  } catch (err) {
+    errors.push(`public inputs are invalid: ${err.message}`);
+  }
+
+  if (expectedRequest) {
+    for (const field of [
+      'network',
+      'subjectWallet',
+      'agentId',
+      'attester',
+      'claimType',
+      'attestationType',
+      'metadataHash',
+      'proofData',
+      'expiresAt',
+      'agentIdHash',
+      'genesisPda',
+      'genesisBump',
+      'attestationPda',
+      'attestationBump',
+      'programs',
+      'requestHash',
+    ]) {
+      appendMismatch(errors, field, request[field], expectedRequest[field]);
+    }
+  }
+
+  appendExpectation(
+    errors,
+    'subjectWallet',
+    request.subjectWallet,
+    expectations.expectedSubjectWallet,
+    (value) => normalizePublicKey(value, 'expectedSubjectWallet'),
+  );
+  appendExpectation(
+    errors,
+    'agentId',
+    request.agentId,
+    expectations.expectedAgentId,
+    (value) => normalizeString(value, 'expectedAgentId'),
+  );
+  appendExpectation(
+    errors,
+    'claimType',
+    request.claimType,
+    expectations.expectedClaimType,
+    (value) => normalizeString(value, 'expectedClaimType', { maxBytes: 32 }),
+  );
+  appendExpectation(
+    errors,
+    'metadataHash',
+    request.metadataHash,
+    expectations.expectedMetadataHash,
+    normalizeMetadataHash,
+  );
+  appendExpectation(
+    errors,
+    'attester',
+    request.attester,
+    expectations.expectedAttester,
+    (value) => normalizePublicKey(value, 'expectedAttester'),
+  );
+  appendExpectation(
+    errors,
+    'network',
+    request.network,
+    expectations.expectedNetwork,
+    normalizeNetwork,
+  );
+  appendExpectation(
+    errors,
+    'expiresAt',
+    request.expiresAt,
+    expectations.expectedExpiresAt,
+    normalizeExpiresAt,
+  );
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
 module.exports = {
   prepareIdentityAttestationRequest,
+  verifyIdentityAttestationRequest,
 };

package/src/index.d.ts

@@ -46,6 +46,22 @@ export interface IdentityAttestationRequest {
   requestHash: string;
 }
 
+export interface IdentityAttestationRequestVerificationOptions {
+  expectedSubjectWallet?: PublicKey | string;
+  expectedAgentId?: string;
+  expectedClaimType?: string;
+  expectedMetadataHash?: string;
+  expectedAttester?: PublicKey | string;
+  expectedNetwork?: Network;
+  expectedExpiresAt?: number | null;
+}
+
+export interface IdentityAttestationRequestVerification {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
 export interface SatpTrustPacket {
   schemaVersion: 'satp.trustPacket.v1';
   packetType: 'satp-trust-packet';
@@ -89,6 +105,138 @@ export interface SatpTrustPacketValidation {
   errors: string[];
 }
 
+export const RUNTIME_AUTHORIZATION_EVIDENCE_SCHEMA_VERSION: 'satp.runtimeAuthorizationEvidence.v0';
+export const RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_ID: 'satp.runtimeAuthorizationEvidence';
+export const RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_VERSION: '0';
+export const RUNTIME_AUTHORIZATION_EVIDENCE_REASON_CODES: Readonly<{
+  UNSUPPORTED_PROFILE: 'unsupported_profile';
+  INVALID_EVIDENCE: 'invalid_evidence';
+  AUTHORIZATION_EXPIRED: 'authorization_expired';
+  SCOPE_MISMATCH: 'scope_mismatch';
+  VERIFIER_UNAVAILABLE: 'verifier_unavailable';
+}>;
+
+export interface RuntimeAuthorizationEvidenceDigest {
+  algorithm: 'sha256';
+  value: string;
+}
+
+export interface RuntimeAuthorizationEvidence {
+  schemaVersion: 'satp.runtimeAuthorizationEvidence.v0';
+  profile: {
+    id: 'satp.runtimeAuthorizationEvidence';
+    version: '0';
+  };
+  issuer: string;
+  verifier: string;
+  subject: string;
+  audience: string;
+  resource: string;
+  evidenceDigest: RuntimeAuthorizationEvidenceDigest;
+  observedAt: string;
+  expiresAt: string;
+  authorizationScope: string[];
+  policyDigest: RuntimeAuthorizationEvidenceDigest;
+}
+
+export interface RuntimeAuthorizationEvidenceInput {
+  schemaVersion?: string;
+  schema_version?: string;
+  profile?: { id?: string; version?: string | number };
+  profileId?: string;
+  profile_id?: string;
+  profileVersion?: string | number;
+  profile_version?: string | number;
+  issuer?: string | { id: string };
+  issuerId?: string;
+  issuer_id?: string;
+  verifier?: string | { id: string };
+  verifierId?: string;
+  verifier_id?: string;
+  subject?: string | { id: string };
+  subjectId?: string;
+  subject_id?: string;
+  audience?: string | { id: string };
+  audienceId?: string;
+  audience_id?: string;
+  resource?: string;
+  evidenceDigest?: RuntimeAuthorizationEvidenceDigest | string;
+  evidence_digest?: RuntimeAuthorizationEvidenceDigest | string;
+  observedAt?: string | number | Date;
+  observed_at?: string | number | Date;
+  expiresAt?: string | number | Date;
+  expires_at?: string | number | Date;
+  authorizationScope?: string | string[];
+  authorization_scope?: string | string[];
+  policyDigest?: RuntimeAuthorizationEvidenceDigest | string;
+  policy_digest?: RuntimeAuthorizationEvidenceDigest | string;
+  evidence?: {
+    digest?: RuntimeAuthorizationEvidenceDigest | string;
+    observedAt?: string | number | Date;
+    observed_at?: string | number | Date;
+  };
+  authorization?: {
+    scope?: string | string[];
+    expiresAt?: string | number | Date;
+    expires_at?: string | number | Date;
+  };
+  policy?: { digest?: RuntimeAuthorizationEvidenceDigest | string };
+}
+
+export interface RuntimeAuthorizationEvidenceVerificationOptions {
+  now?: string | number | Date;
+  expectedProfileId?: string;
+  expectedProfileVersion?: string | number;
+  expectedIssuer?: string | { id: string };
+  expectedVerifier?: string | { id: string };
+  expectedSubject?: string | { id: string };
+  expectedAudience?: string | { id: string };
+  expectedResource?: string;
+  expectedEvidenceDigest?: RuntimeAuthorizationEvidenceDigest | string;
+  expectedPolicyDigest?: RuntimeAuthorizationEvidenceDigest | string;
+  requiredScope?: string | string[];
+  requiredScopes?: string | string[];
+  availableVerifiers?: string | string[] | Set<string> | Record<string, boolean>;
+}
+
+export type RuntimeAuthorizationEvidenceReasonCode =
+  | 'unsupported_profile'
+  | 'invalid_evidence'
+  | 'authorization_expired'
+  | 'scope_mismatch'
+  | 'verifier_unavailable';
+
+export interface RuntimeAuthorizationEvidenceVerification {
+  ok: boolean;
+  reasonCode: RuntimeAuthorizationEvidenceReasonCode | null;
+  reasonCodes: RuntimeAuthorizationEvidenceReasonCode[];
+  message: string;
+  evidence: RuntimeAuthorizationEvidence | null;
+  checks: {
+    profileSupported: boolean;
+    structurallyValid: boolean;
+    authorizationCurrent?: boolean;
+    scopeMatches?: boolean;
+    verifierAvailable?: boolean;
+  };
+  guardrails: {
+    offlineOnly: true;
+    networkRequests: false;
+    writesSolanaState: false;
+    usesKeypairs: false;
+    authorizesPayment: false;
+  };
+}
+
+export function normalizeRuntimeAuthorizationEvidence(
+  input: RuntimeAuthorizationEvidenceInput
+): RuntimeAuthorizationEvidence;
+
+export function verifyRuntimeAuthorizationEvidence(
+  input: RuntimeAuthorizationEvidenceInput,
+  options?: RuntimeAuthorizationEvidenceVerificationOptions
+): RuntimeAuthorizationEvidenceVerification;
+
 export interface X402PaymentRequirement {
   scheme?: string;
   network?: string;
@@ -140,7 +288,64 @@ export type RuntimePolicyDecision =
   | 'degrade'
   | 'needs_approval';
 
+export interface RuntimePolicyActorEvidence {
+  verifier_id?: string;
+  verifierId?: string;
+  verified: boolean;
+  revoked?: boolean;
+  actor_id?: string;
+  actorId?: string;
+  subject_id?: string;
+  subjectId?: string;
+  issued_at?: string | number | Date;
+  issuedAt?: string | number | Date;
+  expires_at?: string | number | Date;
+  expiresAt?: string | number | Date;
+  delegation_depth?: number;
+  delegationDepth?: number;
+  delegation?: { depth?: number };
+  action_binding?: RuntimePolicyActionBinding;
+  actionBinding?: RuntimePolicyActionBinding;
+}
+
+export interface RuntimePolicyActionBinding {
+  action_id?: string;
+  actionId?: string;
+  type?: string;
+  resource?: string;
+  operation?: string;
+}
+
+export interface RuntimePolicyX402SettlementContext {
+  settlement_id?: string;
+  settlementId?: string;
+  verifier_id?: string;
+  verifierId?: string;
+  verified: boolean;
+  status: 'settled' | string;
+  purpose: 'action_payment' | 'evidence_lookup' | string;
+  actor_id?: string;
+  actorId?: string;
+  subject_id?: string;
+  subjectId?: string;
+  action_id?: string;
+  actionId?: string;
+  resource: string | null;
+  amount_usd?: number;
+  amountUsd?: number;
+  settled_at?: string | number | Date;
+  settledAt?: string | number | Date;
+}
+
 export interface RuntimePolicyIdentityPayload {
+  subject_id?: string;
+  subjectId?: string;
+  actor_id?: string;
+  actorId?: string;
+  actor_evidence?: RuntimePolicyActorEvidence;
+  actorEvidence?: RuntimePolicyActorEvidence;
+  agentId?: string;
+  profileId?: string;
   active?: boolean;
   satpVerified?: boolean;
   verified?: boolean;
@@ -152,6 +357,8 @@ export interface RuntimePolicyIdentityPayload {
 
 export interface RuntimePolicyActionDescriptor {
   schemaVersion?: string;
+  action_id?: string;
+  actionId?: string;
   surface?: string;
   type?: string;
   resource?: string;
@@ -178,6 +385,7 @@ export interface RuntimePolicyActionDescriptorBuildInput extends RuntimePolicyAc
 
 export interface RuntimePolicyHostActionDescriptor extends RuntimePolicyActionDescriptor {
   schemaVersion: 'satp.runtimePolicyHostActionDescriptor.v1';
+  actionId: string | null;
   type: string;
   resource: string | null;
   operation: string | null;
@@ -204,6 +412,9 @@ export interface RuntimePolicyConfig {
   maxAutoSpendUsd?: number;
   requireVerifiedIdentity?: boolean;
   staleEvidenceAfterMs?: number;
+  maxActorEvidenceAgeMs?: number;
+  maxDelegationDepth?: number;
+  maxSettlementAgeMs?: number;
 }
 
 export interface RuntimePolicyOptions {
@@ -211,6 +422,8 @@ export interface RuntimePolicyOptions {
   actionPaymentPreapproved?: boolean;
   evidenceLookupPaymentPreapproved?: boolean;
   operatorApproved?: boolean;
+  x402_settlement?: RuntimePolicyX402SettlementContext;
+  x402Settlement?: RuntimePolicyX402SettlementContext;
   policy?: RuntimePolicyConfig;
 }
 
@@ -237,6 +450,9 @@ export interface RuntimePolicyAuditTrace {
   message: string;
   subject: {
     agentId: string | null;
+    subjectId: string | null;
+    actorId: string | null;
+    actorEvidencePresent: boolean;
     active: boolean;
     verified: boolean;
     trustScoreBand: '90-100' | '80-89' | '70-79' | '50-69' | '25-49' | '0-24';
@@ -609,6 +825,11 @@ export function prepareIdentityAttestationRequest(
   opts: IdentityAttestationRequestOptions
 ): IdentityAttestationRequest;
 
+export function verifyIdentityAttestationRequest(
+  request: IdentityAttestationRequest | Record<string, unknown> | null | undefined,
+  expectations?: IdentityAttestationRequestVerificationOptions
+): IdentityAttestationRequestVerification;
+
 export const TRUST_PACKET_SCHEMA_VERSION: 'satp.trustPacket.v1';
 
 export function buildSatpTrustPacket(

package/src/index.js

@@ -782,7 +782,10 @@ class SATPSDK {
 const v3sdk = require('./v3-sdk');
 const v3pda = require('./v3-pda');
 const v3Borsh = require('./borsh-reader');
-const { prepareIdentityAttestationRequest } = require('./attestation-request');
+const {
+  prepareIdentityAttestationRequest,
+  verifyIdentityAttestationRequest,
+} = require('./attestation-request');
 const {
   TRUST_PACKET_SCHEMA_VERSION,
   buildSatpTrustPacket,
@@ -800,6 +803,7 @@ const {
   evaluateRuntimePolicy,
 } = require('./runtime-policy-adapter');
 const walletControlChallenge = require('./wallet-control-challenge');
+const runtimeAuthorizationEvidence = require('./runtime-authorization-evidence');
 const x402Discovery = require('./x402-discovery');
 const signerPolicy = require('./signer-policy');
 
@@ -884,6 +888,7 @@ module.exports = {
   getV3EscrowVaultATA: v3pda.getV3EscrowVaultATA,
   deriveReviewAttestationPda: getReviewAttestationPDA,
   prepareIdentityAttestationRequest,
+  verifyIdentityAttestationRequest,
   TRUST_PACKET_SCHEMA_VERSION,
   buildSatpTrustPacket,
   validateSatpTrustPacket,
@@ -896,6 +901,12 @@ module.exports = {
   hashWalletControlChallenge: walletControlChallenge.hashWalletControlChallenge,
   deriveWalletControlChallengePdas: walletControlChallenge.deriveWalletControlChallengePdas,
   verifyWalletControlChallengeSignature: walletControlChallenge.verifyWalletControlChallengeSignature,
+  RUNTIME_AUTHORIZATION_EVIDENCE_SCHEMA_VERSION: runtimeAuthorizationEvidence.RUNTIME_AUTHORIZATION_EVIDENCE_SCHEMA_VERSION,
+  RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_ID: runtimeAuthorizationEvidence.RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_ID,
+  RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_VERSION: runtimeAuthorizationEvidence.RUNTIME_AUTHORIZATION_EVIDENCE_PROFILE_VERSION,
+  RUNTIME_AUTHORIZATION_EVIDENCE_REASON_CODES: runtimeAuthorizationEvidence.RUNTIME_AUTHORIZATION_EVIDENCE_REASON_CODES,
+  normalizeRuntimeAuthorizationEvidence: runtimeAuthorizationEvidence.normalizeRuntimeAuthorizationEvidence,
+  verifyRuntimeAuthorizationEvidence: runtimeAuthorizationEvidence.verifyRuntimeAuthorizationEvidence,
   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,