@brainai/satp-client 2.0.6 → 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.5** | unpublished source candidate: **@brainai/satp-client@2.0.6** | 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,25 +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.5` |
+| 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-31 shows npm `latest` resolves to
-`@brainai/satp-client@2.0.5` and the `rc` dist-tag resolves to `2.0.2`.
-Stable consumers should use `latest`/`2.0.5` 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.
 
-Source release-prep on 2026-08-02 advances package metadata to `2.0.6` as the
-next unpublished stable semver candidate because npm `latest` is already
-`2.0.5` and npm package versions are immutable. This does not publish the
-package or move any npm dist-tag.
+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.5
+npm install @brainai/satp-client@2.0.6
 ```
 
 For rc validation:
@@ -53,13 +57,19 @@ 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.
@@ -78,15 +88,14 @@ 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
-[`docs/adoption-quickstarts.md`](../../docs/adoption-quickstarts.md) or run:
+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 packages/satp-client/examples/adoption-quickstarts.js
+node node_modules/@brainai/satp-client/examples/adoption-quickstarts.js
 ```
 
 ```javascript
@@ -178,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)`,
@@ -187,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
@@ -200,12 +244,14 @@ builds a runtime policy action descriptor. It asserts
 `spendAuthorized: false`, and `livePaymentRequired: false`.
 
 The proposed issue #14 Track C endpoint spec for third-party SATP reputation
-and evidence consumers lives in
-[`docs/x402-reputation-evidence-lookup-api.md`](../../docs/x402-reputation-evidence-lookup-api.md).
-Its companion offline caller example is runnable with:
+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 packages/satp-client/examples/x402-reputation-evidence-lookup-client.js
+node node_modules/@brainai/satp-client/examples/x402-reputation-evidence-lookup-client.js
 ```
 
 ### Runtime Policy Adapter Helper
@@ -505,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
 

package/idls/v3/attestations_v3.json

@@ -0,0 +1,439 @@
+{
+  "address": "",
+  "metadata": {
+    "name": "attestations_v3",
+    "version": "0.1.0",
+    "spec": "0.1.0",
+    "description": "SATP Attestations V3 — agent_id-based attestations with CPI from Reviews"
+  },
+  "instructions": [
+    {
+      "name": "create_attestation",
+      "docs": [
+        "Create an attestation for an agent (identified by agent_id).",
+        "PDA: `[b\"attestation_v3\", SHA256(agent_id), issuer, attestation_type]`"
+      ],
+      "discriminator": [
+        49,
+        24,
+        67,
+        80,
+        12,
+        249,
+        96,
+        239
+      ],
+      "accounts": [
+        {
+          "name": "attestation",
+          "writable": true
+        },
+        {
+          "name": "issuer",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program"
+        }
+      ],
+      "args": [
+        {
+          "name": "agent_id",
+          "type": "string"
+        },
+        {
+          "name": "attestation_type",
+          "type": "string"
+        },
+        {
+          "name": "proof_data",
+          "type": "string"
+        },
+        {
+          "name": "expires_at",
+          "type": {
+            "option": "i64"
+          }
+        }
+      ]
+    },
+    {
+      "name": "create_verified_attestation",
+      "docs": [
+        "Create an attestation that is pre-verified (issuer self-verifies at creation).",
+        "Same as create_attestation but sets verified = true.",
+        "Use when the issuer IS the verification authority (e.g., platform backend)."
+      ],
+      "discriminator": [
+        86,
+        95,
+        88,
+        56,
+        42,
+        225,
+        35,
+        29
+      ],
+      "accounts": [
+        {
+          "name": "attestation",
+          "writable": true
+        },
+        {
+          "name": "issuer",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program"
+        }
+      ],
+      "args": [
+        {
+          "name": "agent_id",
+          "type": "string"
+        },
+        {
+          "name": "attestation_type",
+          "type": "string"
+        },
+        {
+          "name": "proof_data",
+          "type": "string"
+        },
+        {
+          "name": "expires_at",
+          "type": {
+            "option": "i64"
+          }
+        }
+      ]
+    },
+    {
+      "name": "verify_attestation",
+      "docs": [
+        "Verify an attestation (issuer only)."
+      ],
+      "discriminator": [
+        144,
+        30,
+        116,
+        186,
+        33,
+        176,
+        35,
+        60
+      ],
+      "accounts": [
+        {
+          "name": "attestation",
+          "writable": true
+        },
+        {
+          "name": "issuer",
+          "signer": true
+        }
+      ],
+      "args": []
+    },
+    {
+      "name": "revoke_attestation",
+      "docs": [
+        "Revoke an attestation (issuer only)."
+      ],
+      "discriminator": [
+        12,
+        156,
+        103,
+        161,
+        194,
+        246,
+        211,
+        179
+      ],
+      "accounts": [
+        {
+          "name": "attestation",
+          "writable": true
+        },
+        {
+          "name": "issuer",
+          "signer": true
+        }
+      ],
+      "args": []
+    },
+    {
+      "name": "create_review_attestation",
+      "docs": [
+        "CPI-only: Called by Reviews V3 to auto-create a review attestation.",
+        "Auto-verified (programmatic attestation)."
+      ],
+      "discriminator": [
+        10,
+        168,
+        98,
+        89,
+        138,
+        54,
+        148,
+        202
+      ],
+      "accounts": [
+        {
+          "name": "attestation",
+          "writable": true
+        },
+        {
+          "name": "reviews_authority",
+          "docs": [
+            "Reviews program PDA authority — must sign via CPI"
+          ],
+          "signer": true
+        },
+        {
+          "name": "payer",
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program"
+        }
+      ],
+      "args": [
+        {
+          "name": "agent_id",
+          "type": "string"
+        },
+        {
+          "name": "reviewer",
+          "type": "pubkey"
+        },
+        {
+          "name": "rating",
+          "type": "u8"
+        }
+      ]
+    },
+    {
+      "name": "recompute_score",
+      "docs": [
+        "Recompute attestation-based score and verification level for an agent.",
+        "Reads all attestations for the agent (via remaining_accounts), computes:",
+        "- Score = sum of platform weights for verified, non-revoked, non-expired attestations",
+        "- Level = threshold-based on score (L1≥identity, L2≥50, L3≥100, L4≥150, L5≥200)",
+        "Then CPIs to identity_v3::update_score_and_level to persist on the genesis PDA.",
+        "Permissionless — anyone can trigger a recompute (read-only on attestations)."
+      ],
+      "discriminator": [
+        205,
+        1,
+        251,
+        248,
+        240,
+        27,
+        66,
+        214
+      ],
+      "accounts": [
+        {
+          "name": "genesis",
+          "docs": [
+            "The agent's genesis record — will be updated via CPI"
+          ],
+          "writable": true
+        },
+        {
+          "name": "attestations_authority",
+          "docs": [
+            "Attestations program PDA authority for CPI signing"
+          ]
+        },
+        {
+          "name": "identity_program",
+          "docs": [
+            "Identity program for CPI"
+          ]
+        },
+        {
+          "name": "caller",
+          "docs": [
+            "Permissionless caller — anyone can trigger recompute"
+          ],
+          "signer": true
+        }
+      ],
+      "args": []
+    }
+  ],
+  "accounts": [
+    {
+      "name": "attestations_v3::Attestation",
+      "discriminator": [
+        152,
+        125,
+        183,
+        86,
+        36,
+        146,
+        121,
+        73
+      ]
+    }
+  ],
+  "types": [
+    {
+      "name": "attestations_v3::Attestation",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent_id",
+            "type": "string"
+          },
+          {
+            "name": "agent_id_hash",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "attestation_type",
+            "type": "string"
+          },
+          {
+            "name": "issuer",
+            "type": "pubkey"
+          },
+          {
+            "name": "proof_data",
+            "type": "string"
+          },
+          {
+            "name": "verified",
+            "type": "bool"
+          },
+          {
+            "name": "created_at",
+            "type": "i64"
+          },
+          {
+            "name": "expires_at",
+            "type": {
+              "option": "i64"
+            }
+          },
+          {
+            "name": "is_revoked",
+            "type": "bool"
+          },
+          {
+            "name": "bump",
+            "type": "u8"
+          }
+        ]
+      }
+    },
+    {
+      "name": "attestations_v3::identity_v3::accounts::GenesisRecord",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent_id_hash",
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "agent_name",
+            "type": "string"
+          },
+          {
+            "name": "description",
+            "type": "string"
+          },
+          {
+            "name": "category",
+            "type": "string"
+          },
+          {
+            "name": "capabilities",
+            "type": {
+              "vec": "string"
+            }
+          },
+          {
+            "name": "metadata_uri",
+            "type": "string"
+          },
+          {
+            "name": "face_image",
+            "type": "string"
+          },
+          {
+            "name": "face_mint",
+            "type": "pubkey"
+          },
+          {
+            "name": "face_burn_tx",
+            "type": "string"
+          },
+          {
+            "name": "genesis_record",
+            "type": "i64"
+          },
+          {
+            "name": "is_active",
+            "type": "bool"
+          },
+          {
+            "name": "authority",
+            "type": "pubkey"
+          },
+          {
+            "name": "pending_authority",
+            "type": {
+              "option": "pubkey"
+            }
+          },
+          {
+            "name": "reputation_score",
+            "type": "u64"
+          },
+          {
+            "name": "verification_level",
+            "type": "u8"
+          },
+          {
+            "name": "reputation_updated_at",
+            "type": "i64"
+          },
+          {
+            "name": "verification_updated_at",
+            "type": "i64"
+          },
+          {
+            "name": "created_at",
+            "type": "i64"
+          },
+          {
+            "name": "updated_at",
+            "type": "i64"
+          },
+          {
+            "name": "bump",
+            "type": "u8"
+          }
+        ]
+      }
+    }
+  ]
+}