@aura-labs-ai/scout 0.2.0

package/src/ap2/mandates.js

@@ -0,0 +1,366 @@
+/**
+ * AP2 Mandates for AURA Scout SDK
+ *
+ * Implements Google's Agent Payments Protocol (AP2) mandate system
+ * for secure, auditable AI agent payments.
+ *
+ * Mandate Types:
+ * - Intent Mandate: User authorizes agent to shop within constraints
+ * - Cart Mandate: User authorizes specific purchase
+ * - Payment Mandate: Authorization for payment network
+ *
+ * @see https://ap2-protocol.org/specification/
+ */
+
+import { createHash, createSign, createVerify, generateKeyPairSync } from 'crypto';
+
+/**
+ * AP2 Mandates - Create and validate payment mandates
+ */
+export class AP2Mandates {
+  /**
+   * Create an Intent Mandate
+   *
+   * Intent mandates authorize an agent to shop on behalf of a user
+   * within specified constraints (amount, categories, time, etc.)
+   *
+   * @param {Object} params
+   * @param {string} params.agentId - ID of the authorized agent
+   * @param {Object} params.constraints - Shopping constraints
+   * @param {number} params.constraints.maxAmount - Maximum purchase amount
+   * @param {string} params.constraints.currency - Currency code (USD, EUR, etc.)
+   * @param {string[]} params.constraints.categories - Allowed product categories
+   * @param {string} params.constraints.validUntil - ISO date string
+   * @param {string} params.constraints.merchantAllowlist - Optional merchant IDs
+   * @param {Object} params.userKey - User's signing key (private key)
+   * @returns {Object} Signed intent mandate
+   */
+  static async createIntent({
+    agentId,
+    constraints,
+    userKey,
+    userId,
+    metadata = {},
+  }) {
+    const mandate = {
+      type: 'intent',
+      version: '1.0',
+      id: generateMandateId(),
+      issuedAt: new Date().toISOString(),
+      issuer: {
+        type: 'user',
+        id: userId,
+      },
+      subject: {
+        type: 'agent',
+        id: agentId,
+      },
+      constraints: {
+        maxAmount: constraints.maxAmount,
+        currency: constraints.currency || 'USD',
+        categories: constraints.categories || [],
+        validUntil: constraints.validUntil,
+        validFrom: constraints.validFrom || new Date().toISOString(),
+        merchantAllowlist: constraints.merchantAllowlist || null,
+        merchantBlocklist: constraints.merchantBlocklist || null,
+        requireUserPresent: constraints.requireUserPresent ?? false,
+        maxTransactions: constraints.maxTransactions || null,
+      },
+      metadata,
+    };
+
+    // Create canonical form for signing
+    const canonical = canonicalize(mandate);
+    const signature = await sign(canonical, userKey);
+
+    return {
+      ...mandate,
+      proof: {
+        type: 'Ed25519Signature2020',
+        created: new Date().toISOString(),
+        verificationMethod: `did:key:${userId}#keys-1`,
+        proofPurpose: 'assertionMethod',
+        proofValue: signature,
+      },
+    };
+  }
+
+  /**
+   * Create a Cart Mandate
+   *
+   * Cart mandates authorize a specific purchase (exact items, price).
+   * Created when user explicitly approves a particular offer.
+   *
+   * @param {Object} params
+   * @param {string} params.sessionId - Commerce session ID
+   * @param {Object} params.offer - The specific offer being authorized
+   * @param {Object} params.userKey - User's signing key
+   * @returns {Object} Signed cart mandate
+   */
+  static async createCart({
+    sessionId,
+    offer,
+    userKey,
+    userId,
+    intentMandateId,
+    metadata = {},
+  }) {
+    const mandate = {
+      type: 'cart',
+      version: '1.0',
+      id: generateMandateId(),
+      issuedAt: new Date().toISOString(),
+      issuer: {
+        type: 'user',
+        id: userId,
+      },
+      intentMandateRef: intentMandateId,
+      cart: {
+        sessionId,
+        offerId: offer.id,
+        merchantId: offer.beaconId,
+        merchantName: offer.beaconName,
+        items: [{
+          product: offer.product,
+          quantity: offer.quantity,
+          unitPrice: offer.unitPrice,
+          currency: offer.currency || 'USD',
+        }],
+        totalAmount: offer.totalPrice || (offer.unitPrice * offer.quantity),
+        currency: offer.currency || 'USD',
+        deliveryDate: offer.deliveryDate,
+      },
+      userPresent: true, // User explicitly approved
+      expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), // 30 min
+      metadata,
+    };
+
+    const canonical = canonicalize(mandate);
+    const signature = await sign(canonical, userKey);
+
+    return {
+      ...mandate,
+      proof: {
+        type: 'Ed25519Signature2020',
+        created: new Date().toISOString(),
+        verificationMethod: `did:key:${userId}#keys-1`,
+        proofPurpose: 'assertionMethod',
+        proofValue: signature,
+      },
+    };
+  }
+
+  /**
+   * Create a Payment Mandate
+   *
+   * Payment mandates are shared with the payment network to provide
+   * context about the AI agent transaction.
+   *
+   * @param {Object} params
+   * @param {Object} params.cartMandate - The cart mandate being paid
+   * @param {Object} params.paymentMethod - Payment method details
+   * @param {Object} params.agentKey - Agent's signing key
+   * @returns {Object} Signed payment mandate
+   */
+  static async createPayment({
+    cartMandate,
+    paymentMethod,
+    agentId,
+    agentKey,
+    tapCredentials = null,
+  }) {
+    const mandate = {
+      type: 'payment',
+      version: '1.0',
+      id: generateMandateId(),
+      issuedAt: new Date().toISOString(),
+      cartMandateRef: cartMandate.id,
+      agent: {
+        id: agentId,
+        tapId: tapCredentials?.tapId || null, // Visa TAP registration
+      },
+      transaction: {
+        amount: cartMandate.cart.totalAmount,
+        currency: cartMandate.cart.currency,
+        merchantId: cartMandate.cart.merchantId,
+        merchantName: cartMandate.cart.merchantName,
+      },
+      userPresent: cartMandate.userPresent,
+      paymentMethod: {
+        type: paymentMethod.type, // 'card', 'bank', 'crypto'
+        network: paymentMethod.network, // 'visa', 'mastercard', etc.
+        tokenized: true, // Always use tokens, never raw card numbers
+      },
+      riskSignals: {
+        userAuthTime: cartMandate.issuedAt,
+        agentSessionDuration: calculateSessionDuration(cartMandate),
+        intentMandatePresent: !!cartMandate.intentMandateRef,
+      },
+    };
+
+    const canonical = canonicalize(mandate);
+    const signature = await sign(canonical, agentKey);
+
+    return {
+      ...mandate,
+      proof: {
+        type: 'Ed25519Signature2020',
+        created: new Date().toISOString(),
+        verificationMethod: `did:agent:${agentId}#keys-1`,
+        proofPurpose: 'assertionMethod',
+        proofValue: signature,
+      },
+    };
+  }
+
+  /**
+   * Verify a mandate's signature
+   */
+  static async verify(mandate, publicKey) {
+    if (!mandate.proof?.proofValue) {
+      return { valid: false, error: 'No proof present' };
+    }
+
+    const proof = mandate.proof;
+    const mandateWithoutProof = { ...mandate };
+    delete mandateWithoutProof.proof;
+
+    const canonical = canonicalize(mandateWithoutProof);
+
+    try {
+      const isValid = await verifySignature(canonical, proof.proofValue, publicKey);
+      return { valid: isValid };
+    } catch (error) {
+      return { valid: false, error: error.message };
+    }
+  }
+
+  /**
+   * Check if an intent mandate covers a proposed purchase
+   */
+  static validateIntentCoverage(intentMandate, proposedPurchase) {
+    const c = intentMandate.constraints;
+    const errors = [];
+
+    // Check amount
+    if (proposedPurchase.totalAmount > c.maxAmount) {
+      errors.push(`Amount ${proposedPurchase.totalAmount} exceeds max ${c.maxAmount}`);
+    }
+
+    // Check currency
+    if (c.currency && proposedPurchase.currency !== c.currency) {
+      errors.push(`Currency ${proposedPurchase.currency} not allowed (expected ${c.currency})`);
+    }
+
+    // Check validity period
+    const now = new Date();
+    if (c.validFrom && new Date(c.validFrom) > now) {
+      errors.push('Mandate not yet valid');
+    }
+    if (c.validUntil && new Date(c.validUntil) < now) {
+      errors.push('Mandate expired');
+    }
+
+    // Check categories
+    if (c.categories?.length > 0 && proposedPurchase.category) {
+      if (!c.categories.includes(proposedPurchase.category)) {
+        errors.push(`Category ${proposedPurchase.category} not in allowed list`);
+      }
+    }
+
+    // Check merchant allowlist
+    if (c.merchantAllowlist?.length > 0) {
+      if (!c.merchantAllowlist.includes(proposedPurchase.merchantId)) {
+        errors.push('Merchant not in allowlist');
+      }
+    }
+
+    // Check merchant blocklist
+    if (c.merchantBlocklist?.length > 0) {
+      if (c.merchantBlocklist.includes(proposedPurchase.merchantId)) {
+        errors.push('Merchant is blocklisted');
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Generate unique mandate ID
+ */
+function generateMandateId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `mandate_${timestamp}_${random}`;
+}
+
+/**
+ * Canonicalize object for signing (deterministic JSON)
+ */
+function canonicalize(obj) {
+  return JSON.stringify(obj, Object.keys(obj).sort());
+}
+
+/**
+ * Sign data with private key
+ */
+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');
+  }
+
+  // Mock signing for development
+  const hash = createHash('sha256').update(data).digest('base64');
+  return `mock_signature_${hash.substring(0, 20)}`;
+}
+
+/**
+ * Verify signature
+ */
+async function verifySignature(data, signature, publicKey) {
+  if (signature.startsWith('mock_signature_')) {
+    // Mock verification for development
+    const hash = createHash('sha256').update(data).digest('base64');
+    return signature === `mock_signature_${hash.substring(0, 20)}`;
+  }
+
+  // Real verification
+  const verifier = createVerify('sha256');
+  verifier.update(data);
+  return verifier.verify(publicKey, signature, 'base64');
+}
+
+/**
+ * Calculate session duration from mandate timestamps
+ */
+function calculateSessionDuration(cartMandate) {
+  const cartTime = new Date(cartMandate.issuedAt).getTime();
+  const now = Date.now();
+  return Math.floor((now - cartTime) / 1000); // seconds
+}
+
+/**
+ * Generate a key pair for signing (development utility)
+ */
+export function generateKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKey, privateKey };
+}
+
+export default AP2Mandates;

package/src/client.js

@@ -0,0 +1,217 @@
+/**
+ * Scout HTTP Client
+ *
+ * Handles all HTTP communication with AURA Core.
+ *
+ * Supports two authentication modes:
+ *   1. Ed25519 signed requests (new — via KeyManager)
+ *   2. Bearer token (legacy — via apiKey)
+ *
+ * When a KeyManager is set, all requests are signed with the agent's
+ * private key and include X-Agent-Id, X-Agent-Signature, and
+ * X-Agent-Timestamp headers.
+ *
+ * Adds correlation IDs (X-Request-ID) to every request for end-to-end tracing.
+ * Reports request timing and outcomes to the activity logger when provided.
+ */
+
+import { randomUUID } from 'crypto';
+import { ConnectionError, AuthenticationError, ScoutError } from './errors.js';
+import { ScoutActivityEventTypes } from './activity.js';
+
+// API version prefix — all requests target this version of the Core API.
+// Bump this constant when upgrading to a new API version.
+const API_VERSION = '/v1';
+
+export class ScoutClient {
+  #config;
+  #keyManager = null;
+  #agentId = null;
+  #activityLogger;
+
+  constructor(config, activityLogger = null) {
+    this.#config = config;
+    this.#activityLogger = activityLogger;
+  }
+
+  /**
+   * Configure the client to sign requests with Ed25519
+   *
+   * @param {KeyManager} keyManager - Initialized KeyManager instance
+   * @param {string} agentId - Registered agent UUID
+   */
+  setKeyManager(keyManager, agentId) {
+    this.#keyManager = keyManager;
+    this.#agentId = agentId;
+  }
+
+  /**
+   * Make HTTP GET request to Core
+   */
+  async get(path) {
+    return this.#request('GET', path);
+  }
+
+  /**
+   * Make HTTP POST request to Core
+   */
+  async post(path, body) {
+    return this.#request('POST', path, body);
+  }
+
+  /**
+   * Make HTTP POST request with explicit extra headers (used for registration)
+   *
+   * @param {string} path - API path
+   * @param {object} body - Request body
+   * @param {object} extraHeaders - Additional headers (e.g., X-Agent-Signature for registration)
+   */
+  async postSigned(path, body, extraHeaders = {}) {
+    return this.#request('POST', path, body, extraHeaders);
+  }
+
+  /**
+   * Make HTTP PUT request to Core
+   */
+  async put(path, body) {
+    return this.#request('PUT', path, body);
+  }
+
+  /**
+   * Make HTTP DELETE request to Core
+   */
+  async delete(path) {
+    return this.#request('DELETE', path);
+  }
+
+  /**
+   * Core HTTP request method
+   *
+   * If a KeyManager is configured, requests are signed with Ed25519.
+   * 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}`;
+    const requestId = randomUUID();
+    const bodyString = body ? JSON.stringify(body) : null;
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-Scout-SDK': '@aura-labs-ai/scout/0.1.0',
+      'X-Request-ID': requestId,
+      ...extraHeaders,
+    };
+
+    // Auth: prefer Ed25519 signing, fall back to Bearer token
+    if (this.#keyManager && this.#agentId) {
+      const { signature, timestamp } = this.#keyManager.signRequest({
+        method,
+        path,
+        body: bodyString,
+      });
+      headers['X-Agent-Id'] = this.#agentId;
+      headers['X-Agent-Signature'] = signature;
+      headers['X-Agent-Timestamp'] = timestamp;
+    } else if (this.#config.apiKey) {
+      headers['Authorization'] = `Bearer ${this.#config.apiKey}`;
+    }
+
+    const options = {
+      method,
+      headers,
+      signal: AbortSignal.timeout(this.#config.timeout),
+    };
+
+    if (bodyString) {
+      options.body = bodyString;
+    }
+
+    // Record request start
+    let completeTimer;
+    if (this.#activityLogger) {
+      completeTimer = this.#activityLogger.startTimer(ScoutActivityEventTypes.REQUEST_COMPLETE, {
+        correlationId: requestId,
+        metadata: { method, path, url },
+      });
+      this.#activityLogger.record(ScoutActivityEventTypes.REQUEST_START, {
+        correlationId: requestId,
+        metadata: { method, path, url },
+      });
+    }
+
+    try {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        const errorMsg = error.message || `Request failed with status ${response.status}`;
+
+        // Record failure
+        if (this.#activityLogger) {
+          this.#activityLogger.record(ScoutActivityEventTypes.REQUEST_FAILED, {
+            correlationId: requestId,
+            success: false,
+            error: errorMsg,
+            metadata: { method, path, statusCode: response.status },
+          });
+        }
+
+        if (response.status === 401) {
+          throw new AuthenticationError(errorMsg);
+        }
+
+        if (response.status === 403) {
+          throw new AuthenticationError(errorMsg);
+        }
+
+        if (response.status === 404) {
+          throw new ScoutError(errorMsg, 'NOT_FOUND');
+        }
+
+        throw new ScoutError(errorMsg, error.code || 'REQUEST_FAILED');
+      }
+
+      const result = await response.json();
+
+      // Record success
+      if (completeTimer) {
+        completeTimer({
+          success: true,
+          metadata: { method, path, statusCode: response.status },
+        });
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof ScoutError) throw error;
+
+      const isTimeout = error.name === 'AbortError' || error.name === 'TimeoutError';
+      const errorMsg = isTimeout
+        ? `Request timed out after ${this.#config.timeout}ms`
+        : `Failed to connect to AURA Core: ${error.message}`;
+
+      // Record failure
+      if (this.#activityLogger) {
+        this.#activityLogger.record(ScoutActivityEventTypes.REQUEST_FAILED, {
+          correlationId: requestId,
+          success: false,
+          error: errorMsg,
+          metadata: { method, path, timeout: isTimeout },
+        });
+      }
+
+      if (isTimeout) {
+        throw new ConnectionError(errorMsg);
+      }
+
+      throw new ConnectionError(errorMsg);
+    }
+  }
+
+  /**
+   * Get the configured Core URL
+   */
+  get coreUrl() {
+    return this.#config.coreUrl;
+  }
+}

package/src/errors.js

@@ -0,0 +1,66 @@
+/**
+ * Scout SDK Error Classes
+ */
+
+/**
+ * Base error for all Scout SDK errors
+ */
+export class ScoutError extends Error {
+  constructor(message, code = 'SCOUT_ERROR') {
+    super(message);
+    this.name = 'ScoutError';
+    this.code = code;
+  }
+}
+
+/**
+ * Connection/network errors
+ */
+export class ConnectionError extends ScoutError {
+  constructor(message) {
+    super(message, 'CONNECTION_ERROR');
+    this.name = 'ConnectionError';
+  }
+}
+
+/**
+ * Authentication errors (invalid API key, etc.)
+ */
+export class AuthenticationError extends ScoutError {
+  constructor(message) {
+    super(message, 'AUTHENTICATION_ERROR');
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Session-related errors
+ */
+export class SessionError extends ScoutError {
+  constructor(message, code = 'SESSION_ERROR') {
+    super(message, code);
+    this.name = 'SessionError';
+  }
+}
+
+/**
+ * Constraint validation errors
+ */
+export class ConstraintError extends ScoutError {
+  constructor(message, constraint) {
+    super(message, 'CONSTRAINT_ERROR');
+    this.name = 'ConstraintError';
+    this.constraint = constraint;
+  }
+}
+
+/**
+ * Offer-related errors
+ */
+export class OfferError extends ScoutError {
+  constructor(message, offerId) {
+    super(message, 'OFFER_ERROR');
+    this.name = 'OfferError';
+    this.offerId = offerId;
+  }
+}