2.0.0 — wallet-auth types + AgentScoreError.details + createSession args + drop verifyWebhookSignature

.claude/CLAUDE.md

@@ -4,16 +4,18 @@ TypeScript client for the AgentScore trust and reputation API.
 
 ## Identity Model
 
+Two identity paths: `X-Wallet-Address` (wallet-based) and `X-Operator-Token` (credential-based). Wallet addresses accept both EVM (`0x...` 40-hex) and Solana (base58, 32–44 chars) formats — network is auto-detected from the address shape. `assess()` responses include `resolved_operator` and `linked_wallets[]` (same-operator sibling wallets, normalized per network — EVM lowercased, Solana base58 verbatim; may mix chains for cross-chain operators). `createSession()` and `createCredential()` responses include an `agent_memory` cross-merchant pattern hint. `createSession()` also returns `next_steps.action: "deliver_verify_url_and_poll"` + polling instructions. `pollSession()` returns `next_steps.action` of `continue_polling`, `retry_merchant_request_with_operator_token`, `use_stored_operator_token`, `create_new_session`, `verification_failed`, or `contact_support` depending on state.
+
 ## Methods
 
 - `getReputation(address, options?)` — cached reputation lookup (free)
-- `assess(address, options?)` — identity gate with policy (paid). Accepts `operatorToken` for non-wallet agents.
-- `createSession(options?)` — create verification session for identity bootstrapping
-- `pollSession(sessionId, pollSecret)` — poll session status, returns credential when verified
-- `createCredential(options?)` — create operator credential (24h TTL default)
+- `assess(address, options?)` — identity gate with policy (paid). Accepts `operatorToken` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`.
+- `createSession(options?)` — create verification session for identity bootstrapping. Returns `agent_memory` + `next_steps`.
+- `pollSession(sessionId, pollSecret)` — poll session status, returns credential when verified, plus `next_steps.action`.
+- `createCredential(options?)` — create operator credential (24h TTL default). Response includes `agent_memory`.
 - `listCredentials()` — list active credentials
 - `revokeCredential(id)` — revoke a credential
-- `associateWallet({ operatorToken, walletAddress, network, idempotencyKey? })` — report a signer wallet seen paying under a credential (TEC-189). Fire-and-forget; use the payment intent id / tx hash as `idempotencyKey` so retries don't inflate transaction_count.
+- `associateWallet({ operatorToken, walletAddress, network, idempotencyKey? })` — report a signer wallet seen paying under a credential. Fire-and-forget; use the payment intent id / tx hash as `idempotencyKey` so retries don't inflate transaction_count.
 
 ## Architecture
 

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - uses: useblacksmith/checkout@v1
       - uses: oven-sh/setup-bun@v2
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         with:
           path: ~/.bun/install/cache
           key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}

.github/workflows/security.yml

@@ -23,9 +23,9 @@ jobs:
 
       - name: Install osv-scanner
         run: |
-          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.2/osv-scanner_linux_amd64 -o osv-scanner
+          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.5/osv-scanner_linux_arm64 -o osv-scanner
           chmod +x osv-scanner
 
       - name: Scan dependencies
-        run: ./osv-scanner --lockfile=bun.lock --format=table || true
+        run: ./osv-scanner scan source --lockfile=bun.lock --format=table
 

README.md

@@ -59,20 +59,30 @@ console.log(result.decision); // "allow" | "deny"
 
 ### Verification Sessions
 
-Bootstrap identity for first-time agents:
+Bootstrap identity for first-time agents. The success body carries structured `next_steps` (with `action: "deliver_verify_url_and_poll"`) and a cross-merchant `agent_memory` hint. Poll responses carry `next_steps.action` from the typed `NextStepsAction` union (`continue_polling`, `retry_merchant_request_with_operator_token`, `use_stored_operator_token`, `create_new_session`, `verification_failed`, `contact_support`).
 
 ```typescript
 // Create a session — returns a verify_url for the user and a poll_url for the agent
 const session = await client.createSession();
 console.log(session.verify_url, session.poll_url, session.poll_secret);
+console.log(session.next_steps.action); // "deliver_verify_url_and_poll"
 
 // Poll until the user completes verification
 const status = await client.pollSession(session.session_id, session.poll_secret);
 if (status.status === "verified") {
   console.log(status.operator_token); // "opc_..." — use for future requests
 }
+
+// Optional pre-association: attach the session to a known wallet or refresh KYC
+// for an existing operator credential.
+await client.createSession({ address: "0x..." });
+await client.createSession({ operator_token: "opc_..." }); // KYC refresh
 ```
 
+### Wallet resolution
+
+`assess()` responses include `resolved_operator` and `linked_wallets[]` — all same-operator sibling wallets (claimed via SIWE or captured via prior `associateWallet`). The list may mix EVM addresses (`0x...` lowercased) and Solana addresses (base58, case-preserved) for cross-chain operators; merchants doing wallet-signer-match checks should accept a payment signed by any address in the list, regardless of chain. The `address` parameter on `assess()` and `getReputation()` accepts either format — network is auto-detected from the address shape.
+
 ### Credential Management
 
 ```typescript
@@ -121,6 +131,23 @@ try {
 }
 ```
 
+`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing:
+
+```typescript
+try {
+  await client.assess("0xabc...", { policy: { require_kyc: true } });
+} catch (err) {
+  if (!(err instanceof AgentScoreError)) throw err;
+  if (err.code === "wallet_signer_mismatch") {
+    const linked = err.details.linked_wallets as string[] | undefined;
+    console.log("Re-sign from one of:", linked);
+  }
+  if (err.code === "token_expired") {
+    console.log("Verify at:", err.details.verify_url);
+  }
+}
+```
+
 ## Documentation
 
 - [API Reference](https://docs.agentscore.sh)