@brainai/satp-client 2.0.5 → 2.0.7

package/README.md

@@ -3,7 +3,7 @@
 **Solana Agent Trust Protocol** - JavaScript/TypeScript SDK for reading and
 building reviewed SATP V3 program interactions.
 
-Current stable npm package: **@brainai/satp-client@2.0.3** | rc dist-tag: **@brainai/satp-client@2.0.2** | Programs: **6**
+Current stable npm package: **@brainai/satp-client@2.0.6** | unpublished source candidate: **@brainai/satp-client@2.0.7** | rc dist-tag: **@brainai/satp-client@2.0.2** | Programs: **6**
 
 ## Installation
 
@@ -11,20 +11,29 @@ Choose stable, rc, or Git based on what the consumer needs to prove:
 
 | Channel | Use when | Command |
 | --- | --- | --- |
-| Stable npm | Default production-style consumption of the stable public package. | `npm install @brainai/satp-client@2.0.3` |
+| Stable npm | Default production-style consumption of the stable public package. | `npm install @brainai/satp-client@2.0.6` |
 | Historical rc exact version | Explicit HQ-assigned reproduction or lockfile evidence for the historical pre-stable artifact. | `npm install @brainai/satp-client@2.0.2` |
 | Release candidate tag | Explicit HQ-assigned rc validation where a moving dist-tag is acceptable and the task names the tag as the target. | `npm install @brainai/satp-client@rc` |
 | Reviewed Git commit | PR coordination or source-review installs tied to an exact SATP commit. | `npm install git+https://github.com/brainAI-bot/satp.git#<SATP_COMMIT>` |
 
-Registry readback on 2026-07-26 shows npm `latest` resolves to
-`@brainai/satp-client@2.0.3` and the `rc` dist-tag resolves to `2.0.2`.
-Stable consumers should use `latest`/`2.0.3` unless HQ assigns an explicit
+Registry readback on 2026-08-20 shows npm `latest` resolves to
+`@brainai/satp-client@2.0.6` and the `rc` dist-tag resolves to `2.0.2`.
+Stable consumers should use `latest`/`2.0.6` unless HQ assigns an explicit
 release-candidate validation task.
 
+Registry publish/readback on 2026-08-02 confirms `2.0.6` is the stable npm
+package. This documentation update does not publish the package or move any npm
+dist-tag.
+
+Source release-prep on 2026-08-20 advances package metadata to `2.0.7` as the
+next unpublished patch candidate containing the packed-consumer UUID advisory
+remediation merged in PR #145. This source candidate is not published and does
+not change the stable or `rc` registry tags.
+
 For stable consumer installs, pin the current published npm package:
 
 ```bash
-npm install @brainai/satp-client@2.0.3
+npm install @brainai/satp-client@2.0.6
 ```
 
 For rc validation:
@@ -48,13 +57,23 @@ npm install git+https://github.com/brainAI-bot/satp.git#<SATP_COMMIT>
 
 The old `0.0.0-extraction` label was extraction-branch metadata and is not the
 current consumer package. Do not treat branch-only Git installs as npm latest.
+Continue to [Quick Start](#quick-start) for an installed-package flow that uses
+only files shipped in the package.
+
+The consumer-root `node` commands below use the stable npm package layout. For
+the reviewed Git-commit channel, insert `packages/satp-client/` after
+`node_modules/@brainai/satp-client/` because that channel installs the repository
+root package rather than the standalone npm artifact.
 
 Mainnet program IDs are present for the reviewed V3 registry, but availability
 is not action approval. Mainnet writes, deploys, keypair use, authority changes,
 value-bearing escrow actions, npm promotion, and production claims still require
-a separate HQ approval and the relevant owner-gated runbook. See
-`docs/mainnet-authority-decision-packet-6c8a5545.md` for the public authority
-decision packet.
+a separate HQ approval and the relevant owner-gated runbook. See the
+[public authority decision packet](https://github.com/brainAI-bot/satp/blob/main/docs/mainnet-authority-decision-packet-6c8a5545.md).
+
+Legacy `SATPSDK` is V2-only compatibility. It defaults to devnet and rejects
+`network: 'mainnet'` unless `allowLegacyV2Mainnet: true` is passed explicitly.
+New integrations should prefer `SATPV3SDK` or `createSATPClient`.
 
 RC-S6 semantic uncertainty outcomes are covered by the offline conformance gate
 merged in `93db1b3` (PR #53, `[#43394290]`) and runnable with
@@ -69,9 +88,15 @@ escrow readiness, mainnet readiness, npm latest adoption, or product approval.
 
 ## Quick Start
 
-For the root consumer quickstart covering stable npm, rc validation, Git-review
-pins, read-only trust packets, conformance checks, and network boundaries, see
-[`docs/quickstart.md`](../../docs/quickstart.md).
+This installed-package quickstart covers an offline read-only SDK flow.
+
+For copy-paste MCP, A2A/agent-runtime, and x402 paid-endpoint examples, see the
+packed [`examples/adoption-quickstarts.js`](examples/adoption-quickstarts.js)
+or run this command from the consumer project root after installation:
+
+```bash
+node node_modules/@brainai/satp-client/examples/adoption-quickstarts.js
+```
 
 ```javascript
 const { SATPV3SDK } = require('@brainai/satp-client');
@@ -116,14 +141,14 @@ const tx = await sdk.buildCreateIdentity(creatorPubkey, 'myAgent', {
 
 ## Programs & Program IDs
 
-| Program | Devnet | Description |
+| Program | Mainnet | Description |
 |---------|--------|-------------|
 | `identity_v3` | `GTppU4E44BqXTQgbqMZ68ozFzhP1TLty3EGnzzjtNZfG` | Agent identity, names, wallets, face/birth |
 | `reviews_v3` | `r9XX4frcqxxAZ6Au9V5PA3EAxs1zoNckqLLmoSRcNr4` | Peer reviews with 1-5 star ratings |
 | `attestations_v3` | `6Xd1dAQJPvQRJ4Ntr6LtPTjDjPUZ8nfnmYLZaZ2DtrdD` | Third-party attestations & proofs |
 | `reputation_v3` | `2Lz7KzMvKdrGeAuS8WPHu7jK2yScrnKVgacpYVEuDjkJ` | Weighted reputation scoring (CPI → identity) |
 | `validation_v3` | `6rYRiCYidJYV7QvKrzKGgNu4oMh6BAvynked69R7xMbV` | Validation level computation (CPI → identity) |
-| `escrow_v3` | `B1Se8SPx7GLUisa4LYeXY1tDZy5TviJrsV2yMLgqUXmg` | SOL escrow for agent jobs |
+| `escrow_v3` | `HXCUWKR2NvRcZ7rNAJHwPcH6QAAWaLR4bRFbfyuDND6C` | SOL escrow for agent jobs |
 
 ## API Reference
 
@@ -162,6 +187,39 @@ if (!validation.ok) throw new Error(validation.errors.join('; '));
 re-derives the expected packet so tampered PDA, program, request, or hash fields
 surface as explicit errors.
 
+`verifyIdentityAttestationRequest(request, expectations)` validates a standalone
+unsigned request before a consumer stores or displays it. It recomputes the
+canonical request hash, program IDs, agent ID hash, Genesis PDA, and attestation
+PDA, and enforces the no-sign/no-transaction request shape. Optional expectations
+bind the request to host-owned inputs without requiring RPC or a signer:
+
+```javascript
+const {
+  prepareIdentityAttestationRequest,
+  verifyIdentityAttestationRequest,
+} = require('@brainai/satp-client');
+
+const request = prepareIdentityAttestationRequest({
+  subjectWallet: '11111111111111111111111111111111',
+  agentId: 'brainChain',
+  claimType: 'identity',
+  metadataHash: '93d122f8879fe87c186c10a00db8fbc80a73cecd2ede44b9ffa6410be3c2b805',
+  network: 'devnet',
+});
+
+const verification = verifyIdentityAttestationRequest(request, {
+  expectedSubjectWallet: '11111111111111111111111111111111',
+  expectedAgentId: 'brainChain',
+  expectedClaimType: 'identity',
+  expectedNetwork: 'devnet',
+});
+
+if (!verification.ok) throw new Error(verification.errors.join('; '));
+```
+
+The result shape is `{ ok, errors, warnings }`. Verification is local and
+read-only; it does not prove that an attester signed or submitted anything.
+
 ### x402 Discovery Evidence Lookup Helpers
 
 `parseX402DiscoveryMetadata(input)`, `buildX402EvidenceLookup(input, opts)`,
@@ -171,10 +229,12 @@ read-only: x402 payment metadata can identify where evidence may be fetched, but
 it is discovery/evidence lookup only and never authorizes SATP action execution,
 spending, live payment, signing, transactions, or host policy bypass.
 
-Run the offline example:
+Run the packed
+[`examples/x402-discovery-evidence-lookup.js`](./examples/x402-discovery-evidence-lookup.js)
+from the consumer project root:
 
 ```bash
-node packages/satp-client/examples/x402-discovery-evidence-lookup.js
+node node_modules/@brainai/satp-client/examples/x402-discovery-evidence-lookup.js
 ```
 
 The example parses discovery metadata, builds an evidence lookup descriptor, and
@@ -183,6 +243,17 @@ builds a runtime policy action descriptor. It asserts
 `paymentAuthorization: false`, `actionAuthorization: false`,
 `spendAuthorized: false`, and `livePaymentRequired: false`.
 
+The proposed issue #14 Track C endpoint spec for third-party SATP reputation
+and evidence consumers lives in the
+[source repository](https://github.com/brainAI-bot/satp/blob/main/docs/x402-reputation-evidence-lookup-api.md).
+Its packed
+[`examples/x402-reputation-evidence-lookup-client.js`](./examples/x402-reputation-evidence-lookup-client.js)
+is runnable from the consumer project root with:
+
+```bash
+node node_modules/@brainai/satp-client/examples/x402-reputation-evidence-lookup-client.js
+```
+
 ### Runtime Policy Adapter Helper
 
 `createRuntimePolicyAdapter(opts)` provides a host-oriented wrapper around the
@@ -480,19 +551,11 @@ and must not be treated as SATP protocol authority.
 
 ## Testing
 
-```bash
-# Unit tests (101)
-node test-v3.js
-
-# Devnet integration tests (16)
-node test-v3-devnet.js
-
-# CPI integration tests (35)
-cd .. && node tests/devnet-cpi-integration.js
-
-# Release-safety defaults and network-boundary checks
-node test-release-safety.js
-```
+The npm artifact does not ship the repository's maintainer test suites. Run
+those suites only from a source checkout using the repository-root scripts in
+the [source package manifest](https://github.com/brainAI-bot/satp/blob/main/package.json).
+Installed-package consumers can exercise every offline example linked in this
+README using the consumer-root commands in the relevant sections above.
 
 ## Network Configuration
 
@@ -541,6 +604,10 @@ const genesis = deserializeGenesisRecord(acct.data);
 console.log(genesis.agentName, genesis.reputationScore, genesis.isBorn);
 ```
 
+Genesis parsing is layout-aware for RC-S6 review. Parsed records include
+`layout` and `hasIsActiveField`; `isActive` is `null` when the account bytes do
+not carry the historical `is_active` field.
+
 ### Usage: Auto-detect Account Type
 
 ```js

package/examples/adoption-quickstarts.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  buildRuntimePolicyActionDescriptorFromX402Discovery,
+  buildSatpTrustPacket,
+  createRuntimePolicyAdapter,
+  getV3ProgramIds,
+  validateSatpTrustPacket,
+} = require('../src');
+
+const METADATA_HASH = '93d122f8879fe87c186c10a00db8fbc80a73cecd2ede44b9ffa6410be3c2b805';
+
+async function mcpToolServerQuickstart() {
+  function createSatpMcpTools() {
+    return {
+      'satp.getPrograms': async ({ network = 'devnet' } = {}) => ({
+        network,
+        programs: getV3ProgramIds(network),
+        guardrails: {
+          readOnly: true,
+          writesSolanaState: false,
+          usesKeypairs: false,
+        },
+      }),
+
+      'satp.prepareAttestationRequest': async ({
+        subjectWallet,
+        agentId,
+        claimType = 'identity',
+        metadataHash,
+        network = 'devnet',
+      }) => {
+        const packet = buildSatpTrustPacket({
+          subjectWallet,
+          agentId,
+          claimType,
+          metadataHash,
+          network,
+        });
+        const validation = validateSatpTrustPacket(packet);
+        if (!validation.ok) throw new Error(validation.errors.join('; '));
+
+        return {
+          packet,
+          guardrails: {
+            readOnly: true,
+            livePaymentRequired: false,
+            transaction: null,
+          },
+        };
+      },
+    };
+  }
+
+  const tools = createSatpMcpTools();
+  const prepared = await tools['satp.prepareAttestationRequest']({
+    subjectWallet: '11111111111111111111111111111111',
+    agentId: 'example-mcp-agent',
+    metadataHash: METADATA_HASH,
+  });
+  return {
+    audience: 'mcp-tool-server-builders',
+    mode: prepared.packet.mode,
+    guardrails: prepared.guardrails,
+  };
+}
+
+function agentRuntimeQuickstart() {
+  const now = new Date().toISOString();
+  const adapter = createRuntimePolicyAdapter({
+    policy: {
+      minimumTrustScore: 70,
+      denyTrustScoreBelow: 25,
+      requireVerifiedIdentity: true,
+      maxAutoSpendUsd: 0,
+    },
+  });
+  const identity = {
+    agentId: 'partner-runtime-agent',
+    active: true,
+    satpVerified: true,
+    trustScore: 82,
+    capabilities: ['a2a:task.delegate'],
+    evidenceUpdatedAt: now,
+  };
+  const action = adapter.action({
+    type: 'a2a_agent_runtime',
+    resource: 'a2a://task/delegate',
+    operation: 'delegate',
+    capability: 'a2a:task.delegate',
+    requiresFreshEvidence: true,
+    operatorApprovalRequired: false,
+  });
+  const result = adapter.evaluate(identity, action, { now });
+  const auditTrace = adapter.auditTrace(identity, action, { result, now });
+
+  return {
+    audience: 'a2a-agent-runtime-builders',
+    decision: result.decision,
+    reasonCodes: result.reasonCodes,
+    localDecisionOnly: auditTrace.guardrails.localDecisionOnly,
+  };
+}
+
+function x402PaidEndpointQuickstart() {
+  const discovery = {
+    endpoint: 'https://api.example.test/satp/reputation',
+    action: 'lookup',
+    accepts: [{
+      scheme: 'exact',
+      network: 'solana-mainnet',
+      asset: 'USDC',
+      maxAmountRequired: '10000',
+      resource: 'https://api.example.test/satp/reputation',
+      description: 'SATP-backed reputation evidence lookup',
+    }],
+  };
+  const lookupAction = buildRuntimePolicyActionDescriptorFromX402Discovery(
+    discovery,
+    { maxCostUsd: 0.01 }
+  );
+  const adapter = createRuntimePolicyAdapter({
+    policy: { maxAutoSpendUsd: 0, minimumTrustScore: 70 },
+  });
+  const identity = {
+    agentId: 'x402-consumer-agent',
+    active: true,
+    satpVerified: true,
+    trustScore: 90,
+    capabilities: ['satp:evidence.lookup'],
+    evidenceUpdatedAt: '2026-05-21T00:00:00Z',
+  };
+  const result = adapter.evaluate(identity, lookupAction, {
+    evidenceLookupPaymentPreapproved: false,
+    now: '2026-07-31T00:00:00Z',
+  });
+
+  return {
+    audience: 'x402-paid-endpoint-builders',
+    decision: result.decision,
+    reasonCodes: result.reasonCodes,
+    guardrail: lookupAction.evidenceLookup.guardrail,
+    paymentBoundary: {
+      satpPackageUseIsFreeOpen: true,
+      x402OnlyForHostedReputationEvidenceLookup: true,
+      paymentIsNotActionAuthorization: true,
+      livePaymentRequired: false,
+    },
+  };
+}
+
+async function run() {
+  const examples = [
+    await mcpToolServerQuickstart(),
+    agentRuntimeQuickstart(),
+    x402PaidEndpointQuickstart(),
+  ];
+  console.log(JSON.stringify({ examples }, null, 2));
+}
+
+if (require.main === module) {
+  run().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  agentRuntimeQuickstart,
+  mcpToolServerQuickstart,
+  x402PaidEndpointQuickstart,
+};

package/examples/runtime-policy-adapter.js

@@ -44,7 +44,7 @@ const examples = [
     },
   },
   {
-    name: 'Host trust-score degrade',
+    name: 'AgentFolio trust-score degrade',
     identity: { ...trustedIdentity, trustScore: 62 },
     action: buildRuntimePolicyActionDescriptor({
       type: 'agentfolio_trust_gate',
@@ -55,6 +55,18 @@ const examples = [
       now: '2026-05-21T00:00:00Z',
     },
   },
+  {
+    name: 'Host trust-score gate alias',
+    identity: { ...trustedIdentity, trustScore: 74 },
+    action: buildRuntimePolicyActionDescriptor({
+      type: 'host_trust_gate',
+      profileId: 'brainchain-demo',
+      minimumTrustScore: 80,
+    }),
+    options: {
+      now: '2026-05-21T00:00:00Z',
+    },
+  },
   {
     name: 'Optional paid x402 evidence lookup',
     identity: { ...trustedIdentity, evidenceUpdatedAt: '2026-04-01T00:00:00Z' },

package/examples/x402-reputation-evidence-lookup-client.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('node:assert/strict');
+const {
+  X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+  buildRuntimePolicyActionDescriptorFromX402Discovery,
+} = require('../src');
+
+const LOOKUP_SCHEMA_VERSION = 'satp.x402ReputationEvidenceLookup.v1';
+
+const discoveryMetadata = {
+  schemaVersion: 'satp.x402DiscoveryMetadata.v1',
+  protocol: 'x402',
+  action: 'satp.reputationEvidence.lookup',
+  endpoint: 'https://satp-provider.example/v1/satp/evidence/reputation',
+  resource: 'satp://evidence/reputation',
+  paymentRequired: true,
+  accepts: [
+    {
+      scheme: 'exact',
+      network: '<provider-selected-payment-network>',
+      asset: '<provider-selected-asset>',
+      payTo: '<provider-controlled-recipient>',
+      maxAmountRequired: '<provider-disclosed-maximum>',
+      resource: 'https://satp-provider.example/v1/satp/evidence/reputation',
+      description: 'Read-only SATP reputation evidence lookup',
+      mimeType: 'application/json',
+      maxTimeoutSeconds: 60,
+    },
+  ],
+  guardrail: X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+};
+
+function buildLookupUrl(endpoint, request) {
+  const url = new URL(endpoint);
+  if (request.agentId) url.searchParams.set('agentId', request.agentId);
+  if (request.wallet) url.searchParams.set('wallet', request.wallet);
+  if (request.network) url.searchParams.set('network', request.network);
+  if (request.include) url.searchParams.set('include', request.include.join(','));
+  if (request.minEvidenceUpdatedAt) url.searchParams.set('minEvidenceUpdatedAt', request.minEvidenceUpdatedAt);
+  if (request.trace) url.searchParams.set('trace', request.trace);
+  return url;
+}
+
+function assertLookupBoundary(body) {
+  assert.equal(body.schemaVersion, LOOKUP_SCHEMA_VERSION);
+  assert.equal(body.policyBoundary.guardrail, X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION);
+  assert.equal(body.policyBoundary.paymentAuthorization, false);
+  assert.equal(body.policyBoundary.actionAuthorization, false);
+  assert.equal(body.policyBoundary.spendAuthorized, false);
+}
+
+async function fetchSatpReputationEvidence({
+  fetchImpl,
+  endpoint = discoveryMetadata.endpoint,
+  request,
+  x402PaymentHeader,
+}) {
+  if (typeof fetchImpl !== 'function') throw new Error('fetchImpl is required for this offline example');
+  const url = buildLookupUrl(endpoint, request);
+  const response = await fetchImpl(url, {
+    method: 'GET',
+    headers: {
+      Accept: 'application/json',
+      'X-PAYMENT': x402PaymentHeader,
+    },
+  });
+  const body = await response.json();
+  assertLookupBoundary(body);
+  if (!response.ok) {
+    throw new Error(body.error && body.error.code ? body.error.code : 'satp_lookup_failed');
+  }
+  return body;
+}
+
+function createMockFetch() {
+  return async function mockFetch(url, options = {}) {
+    assert.equal(url.pathname, '/v1/satp/evidence/reputation');
+    assert.equal(url.searchParams.get('agentId'), 'brainChain');
+    assert.equal(options.headers.Accept, 'application/json');
+    assert.equal(options.headers['X-PAYMENT'], 'fixture-x402-payment-proof');
+
+    return {
+      ok: true,
+      async json() {
+        return {
+          schemaVersion: LOOKUP_SCHEMA_VERSION,
+          lookup: {
+            lookupId: 'lkp_fixture_brainchain_devnet_01',
+            agentId: 'brainChain',
+            wallet: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgBNG',
+            network: 'devnet',
+            queriedAt: '2026-07-28T03:18:00Z',
+          },
+          reputation: {
+            score: 88,
+            tier: 'trusted',
+            sourceProgram: 'reputation_v3',
+            computedAt: '2026-07-28T03:10:00Z',
+          },
+          evidence: {
+            attestations: [
+              {
+                claimType: 'github_verified',
+                issuer: 'satp-attestation-authority',
+                status: 'valid',
+              },
+            ],
+          },
+          proof: {
+            source: 'satp',
+            programSet: 'v3',
+            trace: 'redacted',
+            evidenceUpdatedAt: '2026-07-28T03:10:00Z',
+          },
+          policyBoundary: {
+            paymentAuthorization: false,
+            actionAuthorization: false,
+            spendAuthorized: false,
+            livePaymentRequiredByClient: false,
+            guardrail: X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION,
+            message: 'x402 payment grants lookup access only and does not authorize SATP agent actions.',
+          },
+        };
+      },
+    };
+  };
+}
+
+async function runExample() {
+  const descriptor = buildRuntimePolicyActionDescriptorFromX402Discovery(discoveryMetadata, {
+    sourceKind: 'well-known-x402',
+    maxCostUsd: 0,
+  });
+  assert.equal(descriptor.operation, 'satp.reputationEvidence.lookup');
+  assert.equal(descriptor.paymentAuthorization, false);
+  assert.equal(descriptor.actionAuthorization, false);
+  assert.equal(descriptor.spendAuthorized, false);
+  assert.equal(descriptor.livePaymentRequired, false);
+
+  const body = await fetchSatpReputationEvidence({
+    fetchImpl: createMockFetch(),
+    request: {
+      agentId: 'brainChain',
+      network: 'devnet',
+      include: ['identity', 'reputation', 'attestations', 'policy'],
+      trace: 'redacted',
+    },
+    x402PaymentHeader: 'fixture-x402-payment-proof',
+  });
+
+  return {
+    endpoint: discoveryMetadata.endpoint,
+    lookupId: body.lookup.lookupId,
+    score: body.reputation.score,
+    guardrail: body.policyBoundary.guardrail,
+    paymentAuthorization: body.policyBoundary.paymentAuthorization,
+    actionAuthorization: body.policyBoundary.actionAuthorization,
+    spendAuthorized: body.policyBoundary.spendAuthorized,
+    livePaymentRequired: descriptor.livePaymentRequired,
+  };
+}
+
+if (require.main === module) {
+  runExample()
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((err) => {
+      console.error(err.message);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = {
+  LOOKUP_SCHEMA_VERSION,
+  discoveryMetadata,
+  buildLookupUrl,
+  assertLookupBoundary,
+  fetchSatpReputationEvidence,
+  createMockFetch,
+  runExample,
+};