@aura-labs-ai/scout 0.2.0 → 0.3.0

package/README.md

@@ -103,12 +103,21 @@ const scout = createScout({
   timeout: 30000, // optional, ms
   storage: customStorageAdapter, // optional, defaults to in-memory
   constraints: {}, // optional, default constraints
+  principalId: 'prn_01HXYZ...', // required — registered principal ID
+  capacity: 'agent_for_principal', // optional, defaults to 'agent_for_principal'
 });
 
 // Initialize and register with AURA Core (idempotent)
 await scout.ready();
 ```
 
+**Principal registration:** Before creating a Scout, register the principal (legal entity) via `POST /v1/principals`. The `principalId` links this agent to the accountable entity. See [Protocol Spec Section 3.1](../docs/protocol/PROTOCOL_SPECIFICATION.md) for details.
+
+**Capacity options:**
+- `agent_for_principal` — Agent acts on behalf of the declared principal (default)
+- `principal_direct` — The principal is operating directly (no separate agent entity)
+- `platform_delegated` — A platform operates the agent on behalf of multiple principals
+
 ### `scout.ping()`
 
 Read-only connectivity check. Verifies Core is reachable and its dependencies are healthy. Does not require `ready()` — works on a freshly created instance. No auth headers sent.
@@ -232,6 +241,27 @@ Scout uses **Ed25519 public key cryptography** for identity. When you call `scou
 
 No API keys or other credentials are required.
 
+## Protocol Modules (Phase B)
+
+Scout SDK ships modules for the external commerce protocols AURA composes
+with. All sign with Ed25519 via Node's `crypto.sign(null, data, key)` API
+(NOT `createSign('sha256')` — Ed25519 does its own internal hashing and
+does not take a hash algorithm parameter).
+
+| Module | Path | Purpose |
+|--------|------|---------|
+| AP2 (Google Agent Payments Protocol) | `src/ap2/mandates.js` | Intent → Cart → Payment mandate creation, signature verification, intent-coverage validation. |
+| TAP (Visa Trusted Agent Protocol) | `src/tap/visa.js` | Agent registration, request signing per HTTP Message Signatures, key rotation. |
+| MCP (Model Context Protocol) | `src/mcp/client.js` | Beacon discovery and protocol query. |
+
+Test coverage:
+
+```bash
+node --test src/tests/ap2-mandates.test.js     # AP2 mandates: 20 tests
+node --test src/tests/visa-tap.test.js         # Visa TAP: 21 tests
+node --test src/tests/mcp-client.test.js       # MCP client: 18 tests
+```
+
 ## License
 
 Business Source License 1.1 — See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,18 +1,16 @@
 {
   "name": "@aura-labs-ai/scout",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scout SDK for AURA - Build buying agents that participate in agentic commerce",
   "type": "module",
   "main": "src/index.js",
-  "types": "src/index.d.ts",
   "bin": {
     "scout-cli": "./bin/scout-cli.js",
     "aura-scout": "./bin/scout-cli.js"
   },
   "exports": {
     ".": {
-      "import": "./src/index.js",
-      "types": "./src/index.d.ts"
+      "import": "./src/index.js"
     },
     "./mcp": {
       "import": "./src/mcp/client.js"
@@ -25,7 +23,7 @@
     }
   },
   "scripts": {
-    "test": "node --test src/**/*.test.js",
+    "test": "node --test src/*.test.js src/**/*.test.js src/**/**/*.test.js",
     "test:protocols": "node src/tests/run-protocol-tests.js",
     "test:scenarios": "node src/tests/scenarios/index.js",
     "test:ap2": "node --test src/tests/scenarios/ap2-scenarios.test.js",
@@ -37,8 +35,8 @@
     "example:protocols": "node examples/protocol-integration.js"
   },
   "dependencies": {
-    "@aura-labs-ai/nlp": "^0.1.0",
-    "@aura-labs-ai/sdk-common": "^0.1.0"
+    "@aura-labs-ai/nlp": "^0.2.0",
+    "@aura-labs-ai/sdk-common": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.0"

package/src/ap2/mandates.js

@@ -12,7 +12,12 @@
  * @see https://ap2-protocol.org/specification/
  */
 
-import { createHash, createSign, createVerify, generateKeyPairSync } from 'crypto';
+import {
+  createHash,
+  generateKeyPairSync,
+  sign as cryptoSign,
+  verify as cryptoVerify,
+} from 'crypto';
 
 /**
  * AP2 Mandates - Create and validate payment mandates
@@ -310,25 +315,28 @@ function canonicalize(obj) {
 }
 
 /**
- * Sign data with private key
+ * Sign data with private key.
+ *
+ * Ed25519 signs the message directly — no separate hash algorithm is
+ * involved. The Node 'crypto' API for Ed25519 is crypto.sign(null, data, key);
+ * the older createSign('sha256') API throws "Unsupported crypto operation"
+ * on Ed25519 keys because Ed25519 does not take a hash specifier.
  */
 async function sign(data, privateKey) {
-  // In production, use proper Ed25519 signing
-  // For now, use Node.js crypto
-  if (typeof privateKey === 'string') {
-    // Assume PEM format
-    const signer = createSign('sha256');
-    signer.update(data);
-    return signer.sign(privateKey, 'base64');
+  if (typeof privateKey === 'string' || (privateKey && privateKey.type === 'private')) {
+    // PEM-string or KeyObject. Ed25519 signs the buffer directly.
+    return cryptoSign(null, Buffer.from(data), privateKey).toString('base64');
   }
 
-  // Mock signing for development
+  // No private key provided — mock signature for development paths.
   const hash = createHash('sha256').update(data).digest('base64');
   return `mock_signature_${hash.substring(0, 20)}`;
 }
 
 /**
- * Verify signature
+ * Verify signature against public key.
+ *
+ * Mirrors sign(): crypto.verify(null, data, key, signature) for Ed25519.
  */
 async function verifySignature(data, signature, publicKey) {
   if (signature.startsWith('mock_signature_')) {
@@ -337,10 +345,7 @@ async function verifySignature(data, signature, publicKey) {
     return signature === `mock_signature_${hash.substring(0, 20)}`;
   }
 
-  // Real verification
-  const verifier = createVerify('sha256');
-  verifier.update(data);
-  return verifier.verify(publicKey, signature, 'base64');
+  return cryptoVerify(null, Buffer.from(data), publicKey, Buffer.from(signature, 'base64'));
 }
 
 /**

package/src/client.js

@@ -91,7 +91,11 @@ export class ScoutClient {
    * Falls back to Bearer token auth if apiKey is provided.
    */
   async #request(method, path, body = null, extraHeaders = {}) {
-    const url = `${this.#config.coreUrl}${API_VERSION}${path}`;
+    // Sign the exact path we send. Core mounts routes under API_VERSION and verifies
+    // request.url, so the SDK must sign the versioned path, not the bare one (SDK-01,
+    // DEC-148).
+    const versionedPath = `${API_VERSION}${path}`;
+    const url = `${this.#config.coreUrl}${versionedPath}`;
     const requestId = randomUUID();
     const bodyString = body ? JSON.stringify(body) : null;
 
@@ -104,14 +108,18 @@ export class ScoutClient {
 
     // Auth: prefer Ed25519 signing, fall back to Bearer token
     if (this.#keyManager && this.#agentId) {
-      const { signature, timestamp } = this.#keyManager.signRequest({
+      const host = new URL(this.#config.coreUrl).host;
+      const { signature, timestamp, nonce } = this.#keyManager.signRequest({
         method,
-        path,
+        path: versionedPath,
         body: bodyString,
+        host,
       });
       headers['X-Agent-Id'] = this.#agentId;
       headers['X-Agent-Signature'] = signature;
       headers['X-Agent-Timestamp'] = timestamp;
+      headers['X-Agent-Nonce'] = nonce;
+      headers['X-Agent-Host'] = host;
     } else if (this.#config.apiKey) {
       headers['Authorization'] = `Bearer ${this.#config.apiKey}`;
     }

package/src/index.js

@@ -90,6 +90,8 @@ export class Scout {
    * @param {object} [config.storage] - Storage adapter with get/set/remove methods
    * @param {object} [config.constraints] - Default constraints for all sessions
    * @param {object} [config.logger] - External logger instance (optional)
+   * @param {string} [config.principalId] - Principal ID (registered via POST /v1/principals). Required for v1.5+ protocol compliance.
+   * @param {string} [config.capacity] - Agent capacity: 'agent_for_principal' (default), 'principal_direct', or 'platform_delegated'
    */
   constructor(config = {}) {
     this.#config = {
@@ -247,9 +249,15 @@ export class Scout {
       const publicKey = this.#keyManager.publicKey;
 
       // Build registration body
+      // Protocol v1.5: principal_id and capacity are required by Core.
+      // If not provided in config, Core will reject with 400.
+      // Wire contract: the Ed25519 key is sent as `public_key`. The local
+      // variable stays camelCase; only the JSON key on the wire is snake_case.
       const body = {
-        publicKey,
+        public_key: publicKey,
         type: 'scout',
+        principal_id: this.#config.principalId || metadata.principalId || undefined,
+        capacity: this.#config.capacity || metadata.capacity || 'agent_for_principal',
         manifest: {
           name: metadata.name || 'AURA Scout',
           version: '0.1.0',
@@ -269,7 +277,7 @@ export class Scout {
         'X-Agent-Signature': signature,
       });
 
-      this.#agentId = result.agentId;
+      this.#agentId = result.agentId || result.agent_id;
       this.#registered = true;
 
       // Persist agentId for next launch
@@ -281,16 +289,24 @@ export class Scout {
       // Update activity context with assigned agentId
       this.#activity.setScoutContext({
         agentId: this.#agentId,
+        principalId: result.principal_id || null,
+        capacity: result.capacity || null,
       });
 
       finish({
         success: true,
         metadata: {
           agentId: this.#agentId,
+          principalId: result.principal_id,
+          capacity: result.capacity,
         },
       });
 
-      return { agentId: this.#agentId };
+      return {
+        agentId: this.#agentId,
+        principalId: result.principal_id,
+        capacity: result.capacity,
+      };
     } catch (error) {
       this.#activity.record(ScoutActivityEventTypes.SCOUT_REGISTRATION_FAILED, {
         success: false,

package/src/key-manager.js

@@ -107,25 +107,31 @@ export class KeyManager {
   /**
    * Build and sign the canonical request string for HTTP request authentication
    *
-   * Format: "${method}\n${path}\n${timestamp}\n${bodyDigest}"
+   * Format: "${method}\n${path}\n${timestamp}\n${nonce}\n${bodyDigest}"
+   * The nonce (GAP-02) makes each signed request single-use; it is returned so the
+   * caller can emit the matching X-Agent-Nonce header. This string MUST byte-match
+   * Core's buildSigningString (aura-core .../lib/agent-auth.js).
    *
    * @param {object} params
    * @param {string} params.method - HTTP method (uppercase)
    * @param {string} params.path - Request path (e.g., /sessions)
    * @param {string|null} params.body - JSON body string or null
-   * @returns {{ signature: string, timestamp: string }} Signature and timestamp to include in headers
+   * @param {string} [params.host] - Optional target host (@authority, GAP-05); when set it is folded into the signed bytes and must be sent as X-Agent-Host
+   * @returns {{ signature: string, timestamp: string, nonce: string }} Signature, timestamp, and nonce for the request headers
    */
-  signRequest({ method, path, body }) {
+  signRequest({ method, path, body, host }) {
     this.#ensureInitialized();
 
     const timestamp = Date.now().toString();
+    const nonce = crypto.randomBytes(16).toString('hex');
     const bodyDigest = body
       ? crypto.createHash('sha256').update(body).digest('base64')
       : '';
-    const signingString = `${method}\n${path}\n${timestamp}\n${bodyDigest}`;
+    const base = `${method}\n${path}\n${timestamp}\n${nonce}\n${bodyDigest}`;
+    const signingString = host ? `${base}\n${host}` : base;
     const signature = this.sign(signingString);
 
-    return { signature, timestamp };
+    return { signature, timestamp, nonce };
   }
 
   /**

package/src/key-manager.test.js

@@ -161,13 +161,17 @@ describe('KeyManager signRequest', () => {
     await km.init();
   });
 
-  it('should return signature and timestamp for GET request', () => {
+  it('should return signature, timestamp, and nonce for GET request', () => {
     const result = km.signRequest({ method: 'GET', path: '/health', body: null });
 
     assert.equal(typeof result.signature, 'string');
     assert.equal(typeof result.timestamp, 'string');
     assert.equal(Buffer.from(result.signature, 'base64').length, 64);
 
+    // Nonce (GAP-02) should be a non-empty string
+    assert.equal(typeof result.nonce, 'string');
+    assert.ok(result.nonce.length > 0);
+
     // Timestamp should be a recent unix ms
     const ts = parseInt(result.timestamp, 10);
     assert.ok(Math.abs(Date.now() - ts) < 1000);
@@ -175,7 +179,7 @@ describe('KeyManager signRequest', () => {
 
   it('should produce verifiable signature for POST request', () => {
     const body = JSON.stringify({ intent: 'buy widgets' });
-    const { signature, timestamp } = km.signRequest({
+    const { signature, timestamp, nonce } = km.signRequest({
       method: 'POST',
       path: '/sessions',
       body,
@@ -183,20 +187,20 @@ describe('KeyManager signRequest', () => {
 
     // Reconstruct the signing string server-side would build
     const bodyDigest = crypto.createHash('sha256').update(body).digest('base64');
-    const signingString = `POST\n/sessions\n${timestamp}\n${bodyDigest}`;
+    const signingString = `POST\n/sessions\n${timestamp}\n${nonce}\n${bodyDigest}`;
 
     const valid = verifySignature(km.publicKey, signingString, signature);
     assert.equal(valid, true);
   });
 
   it('should produce verifiable signature for GET (no body)', () => {
-    const { signature, timestamp } = km.signRequest({
+    const { signature, timestamp, nonce } = km.signRequest({
       method: 'GET',
       path: '/sessions/123',
       body: null,
     });
 
-    const signingString = `GET\n/sessions/123\n${timestamp}\n`;
+    const signingString = `GET\n/sessions/123\n${timestamp}\n${nonce}\n`;
     const valid = verifySignature(km.publicKey, signingString, signature);
     assert.equal(valid, true);
   });
@@ -277,15 +281,36 @@ describe('KeyManager cross-compat with agent-auth.js signing scheme', () => {
     await km.init();
 
     const body = JSON.stringify({ intent: 'test intent' });
-    const { signature, timestamp } = km.signRequest({
+    const { signature, timestamp, nonce } = km.signRequest({
+      method: 'POST',
+      path: '/sessions',
+      body,
+    });
+
+    // Server reconstructs: buildSigningString(method, path, timestamp, nonce, body)
+    const bodyDigest = crypto.createHash('sha256').update(body).digest('base64');
+    const signingString = `POST\n/sessions\n${timestamp}\n${nonce}\n${bodyDigest}`;
+
+    const valid = verifySignature(km.publicKey, signingString, signature);
+    assert.equal(valid, true);
+  });
+
+  it('should bind the host into the signature when host is provided (GAP-05)', async () => {
+    const km = new KeyManager();
+    await km.init();
+
+    const body = JSON.stringify({ intent: 'test intent' });
+    const { signature, timestamp, nonce } = km.signRequest({
       method: 'POST',
       path: '/sessions',
       body,
+      host: 'core.example',
     });
 
-    // Server reconstructs: buildSigningString(method, path, timestamp, body)
+    // Server reconstructs with the 6th host field appended:
+    // buildSigningString(method, path, timestamp, nonce, body, host)
     const bodyDigest = crypto.createHash('sha256').update(body).digest('base64');
-    const signingString = `POST\n/sessions\n${timestamp}\n${bodyDigest}`;
+    const signingString = `POST\n/sessions\n${timestamp}\n${nonce}\n${bodyDigest}\ncore.example`;
 
     const valid = verifySignature(km.publicKey, signingString, signature);
     assert.equal(valid, true);

package/src/session.js

@@ -55,7 +55,8 @@ export class Session {
    * Session ID
    */
   get id() {
-    return this.#data.sessionId;
+    // Wire contract: Core returns the session identifier as `session_id`.
+    return this.#data.session_id;
   }
 
   /**
@@ -228,8 +229,11 @@ export class Session {
     });
 
     try {
+      // Wire contract: the commit payload carries the selected offer as
+      // `offer_id`. The local variable stays camelCase; only the JSON key
+      // crossing the HTTP boundary is snake_case.
       const response = await this.#client.post(`/sessions/${this.id}/commit`, {
-        offerId,
+        offer_id: offerId,
       });
 
       this.#data.status = SessionStatus.COMMITTED;
@@ -340,17 +344,18 @@ export class Constraints {
   getViolations(offer) {
     const violations = [];
 
-    // Check budget
+    // Check budget. `offer` is the raw Core offer body, so the wire keys
+    // `total_price` and `delivery_date` are read directly.
     if (this.#constraints.maxBudget !== null) {
-      if (offer.totalPrice > this.#constraints.maxBudget) {
-        violations.push(`price_exceeds_budget:${offer.totalPrice}>${this.#constraints.maxBudget}`);
+      if (offer.total_price > this.#constraints.maxBudget) {
+        violations.push(`price_exceeds_budget:${offer.total_price}>${this.#constraints.maxBudget}`);
       }
     }
 
     // Check delivery date
     if (this.#constraints.deliveryBy !== null) {
-      if (offer.deliveryDate && new Date(offer.deliveryDate) > this.#constraints.deliveryBy) {
-        violations.push(`delivery_too_late:${offer.deliveryDate}`);
+      if (offer.delivery_date && new Date(offer.delivery_date) > this.#constraints.deliveryBy) {
+        violations.push(`delivery_too_late:${offer.delivery_date}`);
       }
     }
 
@@ -370,15 +375,16 @@ export class Constraints {
   score(offer) {
     let score = 50; // Base score
 
-    // Budget utilization (prefer lower prices)
-    if (this.#constraints.maxBudget && offer.totalPrice) {
-      const utilizationRatio = offer.totalPrice / this.#constraints.maxBudget;
+    // Budget utilization (prefer lower prices). `offer` is the raw Core
+    // offer body, so the wire key `total_price` is read directly.
+    if (this.#constraints.maxBudget && offer.total_price) {
+      const utilizationRatio = offer.total_price / this.#constraints.maxBudget;
       score += (1 - utilizationRatio) * 20; // Up to +20 for lower prices
     }
 
     // Delivery speed (prefer earlier delivery)
-    if (this.#constraints.deliveryBy && offer.deliveryDate) {
-      const deliveryDate = new Date(offer.deliveryDate);
+    if (this.#constraints.deliveryBy && offer.delivery_date) {
+      const deliveryDate = new Date(offer.delivery_date);
       const deadline = this.#constraints.deliveryBy;
       const now = new Date();
       const totalWindow = deadline - now;
@@ -440,15 +446,17 @@ export class Offer {
     this.#constraints = constraints;
   }
 
+  // Public getters keep idiomatic camelCase names; the values are read from
+  // the raw Core offer body, whose protocol fields are snake_case on the wire.
   get id() { return this.#data.id; }
-  get beaconId() { return this.#data.beaconId; }
-  get beaconName() { return this.#data.beaconName; }
+  get beaconId() { return this.#data.beacon_id; }
+  get beaconName() { return this.#data.beacon_name; }
   get product() { return this.#data.product; }
-  get unitPrice() { return this.#data.unitPrice; }
+  get unitPrice() { return this.#data.unit_price; }
   get quantity() { return this.#data.quantity; }
-  get totalPrice() { return this.#data.totalPrice || (this.unitPrice * this.quantity); }
+  get totalPrice() { return this.#data.total_price || (this.unitPrice * this.quantity); }
   get currency() { return this.#data.currency || 'USD'; }
-  get deliveryDate() { return this.#data.deliveryDate; }
+  get deliveryDate() { return this.#data.delivery_date; }
   get terms() { return this.#data.terms || {}; }
   get metadata() { return this.#data.metadata || {}; }
 
@@ -499,11 +507,13 @@ export class Transaction {
     }
   }
 
-  get id() { return this.#data.transactionId; }
+  // Public getters keep camelCase names; values are read from the raw Core
+  // transaction body, whose protocol fields are snake_case on the wire.
+  get id() { return this.#data.transaction_id; }
   get status() { return this.#data.status; }
-  get offerId() { return this.#data.offerId; }
-  get paymentStatus() { return this.#data.paymentStatus; }
-  get fulfillmentStatus() { return this.#data.fulfillmentStatus; }
+  get offerId() { return this.#data.offer_id; }
+  get paymentStatus() { return this.#data.payment_status; }
+  get fulfillmentStatus() { return this.#data.fulfillment_status; }
 
   /**
    * Refresh transaction state from Core
@@ -584,9 +594,10 @@ export class Transaction {
    * Get beacon information
    */
   get beacon() {
+    // `beacon_id` and `beacon_name` are the snake_case wire keys (v3.0).
     return {
-      id: this.#data.beaconId,
-      name: this.#data.beaconName,
+      id: this.#data.beacon_id,
+      name: this.#data.beacon_name,
     };
   }
 

package/src/session.test.js

@@ -0,0 +1,178 @@
+/**
+ * Session / Offer / Transaction wire-contract unit tests
+ *
+ * Locks in the snake_case HTTP/JSON wire contract (openapi.json) for the
+ * Session, Offer, Transaction, and Constraints classes:
+ *
+ *   - Response bodies received from Core use snake_case protocol keys
+ *     (session_id, beacon_id, unit_price, total_price, delivery_date,
+ *     transaction_id, offer_id, payment_status, fulfillment_status).
+ *   - The commit() request payload sends `offer_id` on the wire.
+ *
+ * Public JS getter names remain idiomatic camelCase; only the keys crossing
+ * the HTTP boundary are snake_case. These tests assert both: the camelCase
+ * public API reads correctly from snake_case wire data, and the commit
+ * payload is built with the snake_case key.
+ *
+ * Imports only ./session.js, which has no workspace-package dependencies,
+ * so it runs without the monorepo's linked node_modules.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { Session, Offer, Transaction, Constraints } from './session.js';
+
+// A stub HTTP client that records the last POST and returns a canned body.
+function makeClient({ getBody = {}, postBody = {} } = {}) {
+  const calls = { get: [], post: [] };
+  return {
+    calls,
+    async get(path) {
+      calls.get.push({ path });
+      return getBody;
+    },
+    async post(path, body) {
+      calls.post.push({ path, body });
+      return postBody;
+    },
+  };
+}
+
+describe('Session — reads snake_case wire fields', () => {
+  it('exposes session_id from the response body as id', () => {
+    const session = new Session({ session_id: 'sess_123', status: 'created' }, makeClient(), {});
+    assert.equal(session.id, 'sess_123');
+  });
+
+  it('does NOT read a legacy camelCase sessionId key', () => {
+    const session = new Session({ sessionId: 'sess_legacy', status: 'created' }, makeClient(), {});
+    assert.equal(session.id, undefined);
+  });
+
+  it('refresh() re-reads session_id from the refreshed body', async () => {
+    const client = makeClient({ getBody: { session_id: 'sess_refreshed', status: 'offers_available' } });
+    const session = new Session({ session_id: 'sess_123', status: 'created' }, client, {});
+    await session.refresh();
+    assert.equal(session.id, 'sess_refreshed');
+    assert.equal(session.status, 'offers_available');
+    assert.equal(client.calls.get[0].path, '/sessions/sess_123');
+  });
+});
+
+describe('Session.commit() — sends offer_id on the wire', () => {
+  it('builds the commit payload with the snake_case offer_id key', async () => {
+    const offer = new Offer(
+      { id: 'offer_1', total_price: 100, unit_price: 50, quantity: 2 },
+      new Constraints({}),
+    );
+    const client = makeClient({ postBody: { transaction_id: 'txn_1', status: 'committed' } });
+    const session = new Session({ session_id: 'sess_1', status: 'offers_available' }, client, {});
+    // Inject the offer into the session's private offer list via waitForOffers path:
+    // commit() looks up this.#offers, so we exercise it through the public surface.
+    session.offers.push(offer);
+
+    const txn = await session.commit('offer_1');
+
+    const post = client.calls.post[0];
+    assert.equal(post.path, '/sessions/sess_1/commit');
+    assert.deepEqual(post.body, { offer_id: 'offer_1' });
+    assert.ok(!('offerId' in post.body), 'payload must not carry camelCase offerId');
+    assert.equal(txn.id, 'txn_1');
+  });
+});
+
+describe('Offer — getters read snake_case wire fields', () => {
+  const raw = {
+    id: 'offer_42',
+    beacon_id: 'beacon_7',
+    beacon_name: 'Acme',
+    product: { name: 'Widget' },
+    unit_price: 25,
+    quantity: 4,
+    total_price: 100,
+    currency: 'USD',
+    delivery_date: '2026-07-01',
+  };
+
+  it('maps beacon_id -> beaconId', () => {
+    assert.equal(new Offer(raw, new Constraints({})).beaconId, 'beacon_7');
+  });
+
+  it('maps unit_price -> unitPrice and total_price -> totalPrice', () => {
+    const offer = new Offer(raw, new Constraints({}));
+    assert.equal(offer.unitPrice, 25);
+    assert.equal(offer.totalPrice, 100);
+  });
+
+  it('maps delivery_date -> deliveryDate', () => {
+    assert.equal(new Offer(raw, new Constraints({})).deliveryDate, '2026-07-01');
+  });
+
+  it('derives totalPrice from unit_price * quantity when total_price is absent', () => {
+    const offer = new Offer({ id: 'o', unit_price: 10, quantity: 3 }, new Constraints({}));
+    assert.equal(offer.totalPrice, 30);
+  });
+});
+
+describe('Constraints — evaluate raw snake_case offer bodies', () => {
+  it('flags a budget violation using total_price', () => {
+    const constraints = new Constraints({ maxBudget: 50 });
+    const violations = constraints.getViolations({ total_price: 120 });
+    assert.equal(violations.length, 1);
+    assert.match(violations[0], /price_exceeds_budget:120>50/);
+  });
+
+  it('flags a late delivery using delivery_date', () => {
+    const constraints = new Constraints({ deliveryBy: new Date('2026-07-01') });
+    const violations = constraints.getViolations({ delivery_date: '2026-08-01' });
+    assert.equal(violations.length, 1);
+    assert.match(violations[0], /delivery_too_late:2026-08-01/);
+  });
+
+  it('an Offer that meets constraints reports no violations', () => {
+    const constraints = new Constraints({ maxBudget: 200, deliveryBy: new Date('2026-09-01') });
+    const offer = new Offer(
+      { id: 'o', total_price: 100, delivery_date: '2026-07-01' },
+      constraints,
+    );
+    assert.equal(offer.meetsConstraints, true);
+    assert.deepEqual(offer.constraintViolations, []);
+  });
+});
+
+describe('Transaction — getters read snake_case wire fields', () => {
+  const raw = {
+    transaction_id: 'txn_99',
+    status: 'committed',
+    offer_id: 'offer_5',
+    payment_status: 'pending',
+    fulfillment_status: 'processing',
+    beacon_id: 'beacon_3',
+    beacon_name: 'Globex',
+  };
+
+  it('maps transaction_id -> id and offer_id -> offerId', () => {
+    const txn = new Transaction(raw, makeClient());
+    assert.equal(txn.id, 'txn_99');
+    assert.equal(txn.offerId, 'offer_5');
+  });
+
+  it('maps payment_status -> paymentStatus and fulfillment_status -> fulfillmentStatus', () => {
+    const txn = new Transaction(raw, makeClient());
+    assert.equal(txn.paymentStatus, 'pending');
+    assert.equal(txn.fulfillmentStatus, 'processing');
+  });
+
+  it('beacon getter reads beacon_id from the wire body', () => {
+    const txn = new Transaction(raw, makeClient());
+    assert.deepEqual(txn.beacon, { id: 'beacon_3', name: 'Globex' });
+  });
+
+  it('refresh() re-reads transaction_id from the refreshed body', async () => {
+    const client = makeClient({ getBody: { transaction_id: 'txn_after', status: 'completed' } });
+    const txn = new Transaction(raw, client);
+    await txn.refresh();
+    assert.equal(txn.id, 'txn_after');
+    assert.equal(client.calls.get[0].path, '/transactions/txn_99');
+  });
+});

package/src/tap/visa.js

@@ -12,7 +12,13 @@
  * @see https://usa.visa.com/about-visa/newsroom/press-releases.releaseId.21716.html
  */
 
-import { createHash, createSign, createVerify, generateKeyPairSync, randomBytes } from 'crypto';
+import {
+  createHash,
+  generateKeyPairSync,
+  randomBytes,
+  sign as cryptoSign,
+  verify as cryptoVerify,
+} from 'crypto';
 
 // TAP Registry URL (would be Visa's in production)
 const TAP_REGISTRY_URL = process.env.TAP_REGISTRY_URL || 'https://tap.visa.com/v1';
@@ -313,21 +319,21 @@ export class VisaTAP {
   }
 
   /**
-   * Sign data with private key
+   * Sign data with private key (Ed25519).
+   *
+   * Ed25519 signs the message directly — no separate hash algorithm. The
+   * older createSign('sha256') API throws "Unsupported crypto operation"
+   * on Ed25519 keys.
    */
   static #sign(data, privateKey) {
-    const signer = createSign('sha256');
-    signer.update(data);
-    return signer.sign(privateKey, 'base64');
+    return cryptoSign(null, Buffer.from(data), privateKey).toString('base64');
   }
 
   /**
-   * Verify signature with public key
+   * Verify signature with public key (Ed25519).
    */
   static #verify(data, signature, publicKey) {
-    const verifier = createVerify('sha256');
-    verifier.update(data);
-    return verifier.verify(publicKey, signature, 'base64');
+    return cryptoVerify(null, Buffer.from(data), publicKey, Buffer.from(signature, 'base64'));
   }
 }
 

package/src/tests/ap2-mandates.test.js

@@ -21,13 +21,19 @@ const createTestIntent = (overrides = {}) => ({
   agentId: 'test-agent-001',
   userId: 'test-user-001',
   userKey: testKeys.privateKey,
+  ...overrides,
+  // Deep-merge constraints so a test that overrides one field (e.g.
+  // merchantAllowlist) still inherits the defaults (currency, categories,
+  // validUntil). Shallow-spread above clobbered the whole constraints object,
+  // which made currency undefined and surfaced the wrong validation error
+  // first ('Currency undefined not allowed' instead of the asserted error).
   constraints: {
     maxAmount: 5000,
     currency: 'USD',
     categories: ['electronics'],
     validUntil: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+    ...(overrides.constraints || {}),
   },
-  ...overrides,
 });
 
 const createTestOffer = (overrides = {}) => ({
@@ -333,18 +339,25 @@ describe('AP2 Intent Coverage Validation', () => {
       },
     }));
 
+    // proposedPurchase must conform on every other dimension that the
+    // mandate constrains (currency, category) so the assertion isolates
+    // the merchant-allowlist behaviour.
     const validResult = AP2Mandates.validateIntentCoverage(intentMandate, {
       totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
       merchantId: 'merchant-a',
     });
     assert.strictEqual(validResult.valid, true);
 
     const invalidResult = AP2Mandates.validateIntentCoverage(intentMandate, {
       totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
       merchantId: 'merchant-c',
     });
     assert.strictEqual(invalidResult.valid, false);
-    assert.ok(invalidResult.errors[0].includes('allowlist'));
+    assert.ok(invalidResult.errors.some(e => e.includes('allowlist')), `Expected an 'allowlist' error, got: ${JSON.stringify(invalidResult.errors)}`);
   });
 
   test('validates merchant blocklist', async () => {
@@ -357,16 +370,20 @@ describe('AP2 Intent Coverage Validation', () => {
 
     const validResult = AP2Mandates.validateIntentCoverage(intentMandate, {
       totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
       merchantId: 'good-merchant',
     });
     assert.strictEqual(validResult.valid, true);
 
     const invalidResult = AP2Mandates.validateIntentCoverage(intentMandate, {
       totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
       merchantId: 'bad-merchant',
     });
     assert.strictEqual(invalidResult.valid, false);
-    assert.ok(invalidResult.errors[0].includes('blocklisted'));
+    assert.ok(invalidResult.errors.some(e => e.includes('blocklisted')), `Expected a 'blocklisted' error, got: ${JSON.stringify(invalidResult.errors)}`);
   });
 
   test('validates expiration', async () => {
@@ -379,10 +396,12 @@ describe('AP2 Intent Coverage Validation', () => {
 
     const result = AP2Mandates.validateIntentCoverage(expiredMandate, {
       totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
     });
 
     assert.strictEqual(result.valid, false);
-    assert.ok(result.errors[0].includes('expired'));
+    assert.ok(result.errors.some(e => e.includes('expired')), `Expected an 'expired' error, got: ${JSON.stringify(result.errors)}`);
   });
 });
 

package/src/tests/client.test.js

@@ -0,0 +1,82 @@
+/**
+ * ScoutClient signed-request path tests (SDK-01, DEC-148)
+ *
+ * Regression guard for the path-versioning bug: the client builds the URL as
+ * `${coreUrl}/v1${path}` but must SIGN the same versioned path, because Core mounts
+ * routes under /v1 and verifies request.url. These tests drive the REAL client with a
+ * mocked fetch and verify the emitted X-Agent-Signature against a reconstruction that
+ * uses the URL's pathname — so a client that signs the bare (unversioned) path fails.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import { ScoutClient } from '../client.js';
+import { KeyManager, MemoryStorage } from '../key-manager.js';
+
+// Rebuild a Node KeyObject from a raw base64 Ed25519 public key (mirrors Core).
+function rawPublicKeyToKeyObject(base64Key) {
+  const raw = Buffer.from(base64Key, 'base64');
+  const der = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), raw]);
+  return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+}
+
+// Core's canonical authenticated_request signing string (buildSigningString).
+function coreSigningString(method, path, timestamp, bodyString, nonce, host) {
+  const bodyDigest = bodyString ? crypto.createHash('sha256').update(bodyString).digest('base64') : '';
+  const base = `${method}\n${path}\n${timestamp}\n${nonce}\n${bodyDigest}`;
+  return host ? `${base}\n${host}` : base;
+}
+
+async function signedClient(coreUrl) {
+  const km = new KeyManager({ storage: new MemoryStorage() });
+  await km.init();
+  const client = new ScoutClient({ coreUrl, timeout: 5000 });
+  client.setKeyManager(km, '11111111-2222-4333-8444-555555555555');
+  return { client, publicKey: km.publicKey };
+}
+
+function captureFetch() {
+  const state = {};
+  globalThis.fetch = async (url, opts) => {
+    state.url = url;
+    state.opts = opts;
+    return { ok: true, status: 200, json: async () => ({}) };
+  };
+  return state;
+}
+
+describe('ScoutClient signs the versioned path it sends (SDK-01, DEC-148)', () => {
+  let originalFetch;
+  beforeEach(() => { originalFetch = globalThis.fetch; });
+  afterEach(() => { globalThis.fetch = originalFetch; });
+
+  it('a signed GET verifies against the VERSIONED path the client actually sent', async () => {
+    const captured = captureFetch();
+    const { client, publicKey } = await signedClient('https://core-a.example');
+
+    await client.get('/sessions/abc');
+
+    const sentPath = new URL(captured.url).pathname;
+    assert.equal(sentPath, '/v1/sessions/abc', 'the client sends the versioned path');
+    const h = captured.opts.headers;
+    const signingString = coreSigningString('GET', sentPath, h['X-Agent-Timestamp'], null, h['X-Agent-Nonce'], h['X-Agent-Host']);
+    const ok = crypto.verify(null, Buffer.from(signingString), rawPublicKeyToKeyObject(publicKey), Buffer.from(h['X-Agent-Signature'], 'base64'));
+    assert.equal(ok, true, 'X-Agent-Signature must verify against the versioned path (fails if the client signed the bare path)');
+  });
+
+  it('a signed POST with body verifies against the versioned path and the sent bytes', async () => {
+    const captured = captureFetch();
+    const { client, publicKey } = await signedClient('https://core-a.example');
+
+    await client.post('/sessions', { intent: 'buy widgets' });
+
+    const sentPath = new URL(captured.url).pathname;
+    assert.equal(sentPath, '/v1/sessions');
+    const h = captured.opts.headers;
+    const signingString = coreSigningString('POST', sentPath, h['X-Agent-Timestamp'], captured.opts.body, h['X-Agent-Nonce'], h['X-Agent-Host']);
+    const ok = crypto.verify(null, Buffer.from(signingString), rawPublicKeyToKeyObject(publicKey), Buffer.from(h['X-Agent-Signature'], 'base64'));
+    assert.equal(ok, true);
+    assert.equal(h['X-Agent-Host'], 'core-a.example', 'the bound host is the target Core host');
+  });
+});