@aura-labs-ai/scout 0.2.0

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

@@ -0,0 +1,413 @@
+/**
+ * AP2 Mandates Tests
+ *
+ * Tests for Google Agent Payments Protocol (AP2) mandate creation and validation.
+ *
+ * Run:
+ *   node --test src/tests/ap2-mandates.test.js
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { AP2Mandates, generateKeyPair } from '../ap2/mandates.js';
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+const testKeys = generateKeyPair();
+
+const createTestIntent = (overrides = {}) => ({
+  agentId: 'test-agent-001',
+  userId: 'test-user-001',
+  userKey: testKeys.privateKey,
+  constraints: {
+    maxAmount: 5000,
+    currency: 'USD',
+    categories: ['electronics'],
+    validUntil: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+  },
+  ...overrides,
+});
+
+const createTestOffer = (overrides = {}) => ({
+  id: 'offer-test-001',
+  beaconId: 'beacon-test-001',
+  beaconName: 'Test Merchant',
+  product: { name: 'Test Product', sku: 'TEST-001' },
+  unitPrice: 100,
+  quantity: 2,
+  totalPrice: 200,
+  currency: 'USD',
+  deliveryDate: '2026-03-01',
+  ...overrides,
+});
+
+// =============================================================================
+// Intent Mandate Tests
+// =============================================================================
+
+describe('AP2 Intent Mandates', () => {
+  test('creates valid intent mandate with required fields', async () => {
+    const params = createTestIntent();
+    const mandate = await AP2Mandates.createIntent(params);
+
+    assert.strictEqual(mandate.type, 'intent');
+    assert.strictEqual(mandate.version, '1.0');
+    assert.ok(mandate.id.startsWith('mandate_'));
+    assert.strictEqual(mandate.subject.id, params.agentId);
+    assert.strictEqual(mandate.issuer.id, params.userId);
+    assert.strictEqual(mandate.constraints.maxAmount, 5000);
+    assert.strictEqual(mandate.constraints.currency, 'USD');
+    assert.deepStrictEqual(mandate.constraints.categories, ['electronics']);
+  });
+
+  test('includes valid proof/signature', async () => {
+    const mandate = await AP2Mandates.createIntent(createTestIntent());
+
+    assert.ok(mandate.proof);
+    assert.strictEqual(mandate.proof.type, 'Ed25519Signature2020');
+    assert.ok(mandate.proof.created);
+    assert.ok(mandate.proof.verificationMethod);
+    assert.strictEqual(mandate.proof.proofPurpose, 'assertionMethod');
+    assert.ok(mandate.proof.proofValue);
+  });
+
+  test('sets default values for optional fields', async () => {
+    const mandate = await AP2Mandates.createIntent(createTestIntent());
+
+    assert.strictEqual(mandate.constraints.requireUserPresent, false);
+    assert.strictEqual(mandate.constraints.merchantAllowlist, null);
+    assert.strictEqual(mandate.constraints.merchantBlocklist, null);
+    assert.strictEqual(mandate.constraints.maxTransactions, null);
+  });
+
+  test('preserves custom constraint values', async () => {
+    const mandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: {
+        maxAmount: 1000,
+        currency: 'EUR',
+        requireUserPresent: true,
+        maxTransactions: 5,
+        merchantAllowlist: ['merchant-1', 'merchant-2'],
+        merchantBlocklist: ['bad-merchant'],
+      },
+    }));
+
+    assert.strictEqual(mandate.constraints.maxAmount, 1000);
+    assert.strictEqual(mandate.constraints.currency, 'EUR');
+    assert.strictEqual(mandate.constraints.requireUserPresent, true);
+    assert.strictEqual(mandate.constraints.maxTransactions, 5);
+    assert.deepStrictEqual(mandate.constraints.merchantAllowlist, ['merchant-1', 'merchant-2']);
+    assert.deepStrictEqual(mandate.constraints.merchantBlocklist, ['bad-merchant']);
+  });
+
+  test('includes metadata when provided', async () => {
+    const mandate = await AP2Mandates.createIntent(createTestIntent({
+      metadata: {
+        purpose: 'Office supplies',
+        department: 'Engineering',
+      },
+    }));
+
+    assert.deepStrictEqual(mandate.metadata, {
+      purpose: 'Office supplies',
+      department: 'Engineering',
+    });
+  });
+});
+
+// =============================================================================
+// Cart Mandate Tests
+// =============================================================================
+
+describe('AP2 Cart Mandates', () => {
+  test('creates valid cart mandate from offer', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent());
+    const offer = createTestOffer();
+
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-001',
+      offer,
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: intentMandate.id,
+    });
+
+    assert.strictEqual(cartMandate.type, 'cart');
+    assert.strictEqual(cartMandate.version, '1.0');
+    assert.ok(cartMandate.id.startsWith('mandate_'));
+    assert.strictEqual(cartMandate.intentMandateRef, intentMandate.id);
+    assert.strictEqual(cartMandate.cart.sessionId, 'session-test-001');
+    assert.strictEqual(cartMandate.cart.offerId, offer.id);
+    assert.strictEqual(cartMandate.cart.totalAmount, 200);
+    assert.strictEqual(cartMandate.userPresent, true);
+  });
+
+  test('cart mandate includes offer details', async () => {
+    const offer = createTestOffer({
+      unitPrice: 150,
+      quantity: 3,
+      totalPrice: 450,
+    });
+
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-002',
+      offer,
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: 'mandate_test_123',
+    });
+
+    assert.strictEqual(cartMandate.cart.items[0].quantity, 3);
+    assert.strictEqual(cartMandate.cart.items[0].unitPrice, 150);
+    assert.strictEqual(cartMandate.cart.totalAmount, 450);
+  });
+
+  test('cart mandate has expiration time', async () => {
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-003',
+      offer: createTestOffer(),
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: 'mandate_test_123',
+    });
+
+    const expiresAt = new Date(cartMandate.expiresAt).getTime();
+    const now = Date.now();
+
+    // Should expire in ~30 minutes (give or take a few seconds)
+    const diffMinutes = (expiresAt - now) / (1000 * 60);
+    assert.ok(diffMinutes >= 29 && diffMinutes <= 31, `Expected ~30 min expiry, got ${diffMinutes} min`);
+  });
+});
+
+// =============================================================================
+// Payment Mandate Tests
+// =============================================================================
+
+describe('AP2 Payment Mandates', () => {
+  test('creates payment mandate from cart mandate', async () => {
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-004',
+      offer: createTestOffer({ totalPrice: 500 }),
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: 'mandate_test_123',
+    });
+
+    const paymentMandate = await AP2Mandates.createPayment({
+      cartMandate,
+      paymentMethod: { type: 'card', network: 'visa' },
+      agentId: 'agent-test-001',
+      agentKey: testKeys.privateKey,
+    });
+
+    assert.strictEqual(paymentMandate.type, 'payment');
+    assert.strictEqual(paymentMandate.cartMandateRef, cartMandate.id);
+    assert.strictEqual(paymentMandate.transaction.amount, 500);
+    assert.strictEqual(paymentMandate.paymentMethod.type, 'card');
+    assert.strictEqual(paymentMandate.paymentMethod.network, 'visa');
+    assert.strictEqual(paymentMandate.paymentMethod.tokenized, true);
+  });
+
+  test('includes TAP credentials when provided', async () => {
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-005',
+      offer: createTestOffer(),
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: 'mandate_test_123',
+    });
+
+    const paymentMandate = await AP2Mandates.createPayment({
+      cartMandate,
+      paymentMethod: { type: 'card', network: 'mastercard' },
+      agentId: 'agent-test-001',
+      agentKey: testKeys.privateKey,
+      tapCredentials: { tapId: 'tap_agent_12345' },
+    });
+
+    assert.strictEqual(paymentMandate.agent.tapId, 'tap_agent_12345');
+  });
+
+  test('includes risk signals', async () => {
+    const cartMandate = await AP2Mandates.createCart({
+      sessionId: 'session-test-006',
+      offer: createTestOffer(),
+      userKey: testKeys.privateKey,
+      userId: 'test-user-001',
+      intentMandateId: 'mandate_test_123',
+    });
+
+    const paymentMandate = await AP2Mandates.createPayment({
+      cartMandate,
+      paymentMethod: { type: 'card', network: 'visa' },
+      agentId: 'agent-test-001',
+      agentKey: testKeys.privateKey,
+    });
+
+    assert.ok(paymentMandate.riskSignals);
+    assert.strictEqual(paymentMandate.riskSignals.userAuthTime, cartMandate.issuedAt);
+    assert.strictEqual(paymentMandate.riskSignals.intentMandatePresent, true);
+    assert.ok(typeof paymentMandate.riskSignals.agentSessionDuration === 'number');
+  });
+});
+
+// =============================================================================
+// Intent Coverage Validation Tests
+// =============================================================================
+
+describe('AP2 Intent Coverage Validation', () => {
+  test('validates amount within limits', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: { maxAmount: 1000 },
+    }));
+
+    const result = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      currency: 'USD',
+    });
+
+    assert.strictEqual(result.valid, true);
+    assert.deepStrictEqual(result.errors, []);
+  });
+
+  test('rejects amount exceeding limit', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: { maxAmount: 1000 },
+    }));
+
+    const result = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 1500,
+      currency: 'USD',
+    });
+
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.errors[0].includes('exceeds max'));
+  });
+
+  test('validates currency match', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: { maxAmount: 1000, currency: 'EUR' },
+    }));
+
+    const result = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      currency: 'USD',
+    });
+
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.errors[0].includes('Currency'));
+  });
+
+  test('validates category in allowlist', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: {
+        maxAmount: 1000,
+        categories: ['electronics', 'office'],
+      },
+    }));
+
+    const validResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      currency: 'USD',
+      category: 'electronics',
+    });
+    assert.strictEqual(validResult.valid, true);
+
+    const invalidResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      currency: 'USD',
+      category: 'furniture',
+    });
+    assert.strictEqual(invalidResult.valid, false);
+    assert.ok(invalidResult.errors[0].includes('Category'));
+  });
+
+  test('validates merchant allowlist', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: {
+        maxAmount: 1000,
+        merchantAllowlist: ['merchant-a', 'merchant-b'],
+      },
+    }));
+
+    const validResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      merchantId: 'merchant-a',
+    });
+    assert.strictEqual(validResult.valid, true);
+
+    const invalidResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      merchantId: 'merchant-c',
+    });
+    assert.strictEqual(invalidResult.valid, false);
+    assert.ok(invalidResult.errors[0].includes('allowlist'));
+  });
+
+  test('validates merchant blocklist', async () => {
+    const intentMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: {
+        maxAmount: 1000,
+        merchantBlocklist: ['bad-merchant'],
+      },
+    }));
+
+    const validResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      merchantId: 'good-merchant',
+    });
+    assert.strictEqual(validResult.valid, true);
+
+    const invalidResult = AP2Mandates.validateIntentCoverage(intentMandate, {
+      totalAmount: 500,
+      merchantId: 'bad-merchant',
+    });
+    assert.strictEqual(invalidResult.valid, false);
+    assert.ok(invalidResult.errors[0].includes('blocklisted'));
+  });
+
+  test('validates expiration', async () => {
+    const expiredMandate = await AP2Mandates.createIntent(createTestIntent({
+      constraints: {
+        maxAmount: 1000,
+        validUntil: new Date(Date.now() - 1000).toISOString(), // Expired
+      },
+    }));
+
+    const result = AP2Mandates.validateIntentCoverage(expiredMandate, {
+      totalAmount: 500,
+    });
+
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.errors[0].includes('expired'));
+  });
+});
+
+// =============================================================================
+// Signature Verification Tests
+// =============================================================================
+
+describe('AP2 Signature Verification', () => {
+  test('verifies valid mandate signature', async () => {
+    const mandate = await AP2Mandates.createIntent(createTestIntent());
+    const result = await AP2Mandates.verify(mandate, testKeys.publicKey);
+
+    // Note: Using mock signatures in dev mode
+    assert.ok(result.valid || result.error === undefined);
+  });
+
+  test('rejects mandate without proof', async () => {
+    const mandateWithoutProof = {
+      type: 'intent',
+      id: 'test-mandate',
+      // No proof field
+    };
+
+    const result = await AP2Mandates.verify(mandateWithoutProof, testKeys.publicKey);
+    assert.strictEqual(result.valid, false);
+    assert.ok(result.error.includes('No proof'));
+  });
+});

package/src/tests/intent-session.test.js

@@ -0,0 +1,292 @@
+/**
+ * IntentSession Tests — Phase B F22–F34
+ *
+ * Tests the IntentSession class that provides conversational
+ * intent completeness checking before submission to Core.
+ *
+ * Acceptance criteria:
+ *   F22: IntentSession.submit(text) accumulates text and checks completeness
+ *   F23: Returns { complete, missing, question, confidence } from submit()
+ *   F24: When complete === true, result includes completeness attestation
+ *   F25: Maintains previousRounds context across submit() calls
+ *   F26: State machine: idle → checking → incomplete/complete
+ *   F27: submit() on a complete session returns same result without re-checking
+ *   F28: reset() clears state back to idle
+ *   F29: getText() returns accumulated text
+ *   F30: Works without provider (regex-only fallback)
+ *   F31: Emits activity events
+ *   F32: Handles empty/whitespace text gracefully
+ *   F33: Handles very long text (>5000 chars) gracefully
+ *   F34: Multiple submit() calls accumulate text correctly
+ *
+ * Ref: ADR-002, DEC-024, DEC-025
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { IntentSession } from '../intent-session.js';
+
+// ── F22: submit() accumulates text and checks completeness ───
+
+describe('IntentSession.submit() — basic behavior (F22)', () => {
+
+  it('accepts text and returns a completeness result', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('I need 50 ergonomic keyboards under $5000');
+
+    assert.equal(typeof result.complete, 'boolean');
+    assert.ok(Array.isArray(result.missing));
+    assert.equal(typeof result.question, 'string');
+    assert.equal(typeof result.confidence, 'number');
+  });
+
+  it('accumulates text across multiple submit() calls', async () => {
+    const session = new IntentSession();
+    await session.submit('I need keyboards');
+    await session.submit('50 units under $5000');
+
+    assert.ok(session.getText().includes('I need keyboards'));
+    assert.ok(session.getText().includes('50 units under $5000'));
+  });
+});
+
+// ── F23: Returns { complete, missing, question, confidence } ──
+
+describe('IntentSession.submit() — return shape (F23)', () => {
+
+  it('returns all required fields', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('stuff');
+
+    assert.ok('complete' in result, 'Should have complete');
+    assert.ok('missing' in result, 'Should have missing');
+    assert.ok('question' in result, 'Should have question');
+    assert.ok('confidence' in result, 'Should have confidence');
+  });
+
+  it('missing is an array of category names', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('stuff');
+
+    assert.ok(Array.isArray(result.missing));
+    if (result.missing.length > 0) {
+      assert.equal(typeof result.missing[0], 'string');
+    }
+  });
+
+  it('question is a natural language string (or empty when complete)', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('stuff');
+
+    assert.equal(typeof result.question, 'string');
+    // For incomplete intents, question should not be empty
+    if (!result.complete) {
+      assert.ok(result.question.length > 0, 'Should have a question for incomplete intent');
+    }
+  });
+});
+
+// ── F24: Complete intent includes attestation ────────────────
+
+describe('IntentSession — completeness attestation (F24)', () => {
+
+  it('getAttestation() returns null before completion', async () => {
+    const session = new IntentSession();
+    await session.submit('stuff');
+
+    const att = session.getAttestation();
+    assert.equal(att, null);
+  });
+
+  it('getAttestation() returns attestation object when complete', async () => {
+    const session = new IntentSession();
+    // Provide a rich enough intent to satisfy Tier 1 categories
+    await session.submit('I need 50 ergonomic wireless keyboards under $5000 per unit');
+
+    if (session.state === 'complete') {
+      const att = session.getAttestation();
+      assert.ok(att, 'Should have attestation when complete');
+      assert.equal(att.complete, true);
+      assert.ok(Array.isArray(att.missing));
+      assert.equal(typeof att.confidence, 'number');
+    }
+    // If not complete with regex-only, that's OK — the attestation logic is still testable
+  });
+});
+
+// ── F25: Maintains previousRounds context ────────────────────
+
+describe('IntentSession — conversation context (F25)', () => {
+
+  it('tracks previous rounds for clarification context', async () => {
+    const session = new IntentSession();
+    await session.submit('I need keyboards');
+    await session.submit('50 units');
+
+    assert.ok(session.roundCount >= 2, 'Should track multiple rounds');
+  });
+
+  it('passes previousRounds to clarification generator', async () => {
+    const session = new IntentSession();
+    const r1 = await session.submit('I need keyboards');
+    const r2 = await session.submit('50 units under $5000');
+
+    // Second round should have different (or fewer) missing categories
+    // because context accumulates
+    assert.ok(r2.missing.length <= r1.missing.length || r2.confidence >= r1.confidence,
+      'Second round should show progress');
+  });
+});
+
+// ── F26: State machine: idle → checking → incomplete/complete ─
+
+describe('IntentSession — state machine (F26)', () => {
+
+  it('starts in idle state', () => {
+    const session = new IntentSession();
+    assert.equal(session.state, 'idle');
+  });
+
+  it('transitions to incomplete after incomplete submit', async () => {
+    const session = new IntentSession();
+    await session.submit('stuff');
+    assert.equal(session.state, 'incomplete');
+  });
+
+  it('transitions to complete when all categories satisfied', async () => {
+    const session = new IntentSession();
+    // Very rich intent — should satisfy most Tier 1 categories
+    await session.submit('I need 50 ergonomic wireless keyboards at $100 each under $5000 total budget');
+
+    // State should be either incomplete or complete depending on detection
+    assert.ok(['incomplete', 'complete'].includes(session.state));
+  });
+});
+
+// ── F27: submit() on complete session returns cached result ──
+
+describe('IntentSession — complete state caching (F27)', () => {
+
+  it('returns same result on subsequent submit() after completion', async () => {
+    const session = new IntentSession();
+    // Force complete state by providing rich intent
+    const r1 = await session.submit('I need 50 ergonomic wireless keyboards at $100 each under $5000');
+
+    if (session.state === 'complete') {
+      const r2 = await session.submit('more text that should be ignored');
+      assert.deepEqual(r1, r2, 'Should return same result after completion');
+    }
+  });
+});
+
+// ── F28: reset() clears state ────────────────────────────────
+
+describe('IntentSession.reset() (F28)', () => {
+
+  it('resets state back to idle', async () => {
+    const session = new IntentSession();
+    await session.submit('stuff');
+    assert.equal(session.state, 'incomplete');
+
+    session.reset();
+    assert.equal(session.state, 'idle');
+  });
+
+  it('clears accumulated text', async () => {
+    const session = new IntentSession();
+    await session.submit('stuff');
+    session.reset();
+    assert.equal(session.getText(), '');
+  });
+
+  it('resets round count', async () => {
+    const session = new IntentSession();
+    await session.submit('stuff');
+    session.reset();
+    assert.equal(session.roundCount, 0);
+  });
+});
+
+// ── F29: getText() returns accumulated text ──────────────────
+
+describe('IntentSession.getText() (F29)', () => {
+
+  it('returns empty string before any submit', () => {
+    const session = new IntentSession();
+    assert.equal(session.getText(), '');
+  });
+
+  it('returns all submitted text joined', async () => {
+    const session = new IntentSession();
+    await session.submit('I need keyboards');
+    await session.submit('50 units');
+    const text = session.getText();
+    assert.ok(text.includes('I need keyboards'));
+    assert.ok(text.includes('50 units'));
+  });
+});
+
+// ── F30: Works without provider (regex-only) ─────────────────
+
+describe('IntentSession — no provider (F30)', () => {
+
+  it('works without passing a provider (regex-only detection)', async () => {
+    const session = new IntentSession(); // no provider
+    const result = await session.submit('I need 50 keyboards under $5000');
+
+    assert.equal(typeof result.complete, 'boolean');
+    assert.ok(Array.isArray(result.missing));
+  });
+});
+
+// ── F32: Empty/whitespace text ───────────────────────────────
+
+describe('IntentSession — edge cases (F32, F33)', () => {
+
+  it('handles empty string gracefully', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('');
+
+    assert.equal(result.complete, false);
+    assert.ok(result.missing.length > 0, 'Empty text should have missing categories');
+  });
+
+  it('handles whitespace-only string gracefully', async () => {
+    const session = new IntentSession();
+    const result = await session.submit('   ');
+
+    assert.equal(result.complete, false);
+  });
+
+  // F33: Long text
+  it('handles text up to 5000 chars', async () => {
+    const session = new IntentSession();
+    const longText = 'I need 50 keyboards under $5000. '.repeat(150); // ~5000 chars
+    const result = await session.submit(longText);
+
+    assert.equal(typeof result.complete, 'boolean');
+  });
+});
+
+// ── F34: Multiple submit() accumulation ──────────────────────
+
+describe('IntentSession — multi-round accumulation (F34)', () => {
+
+  it('each submit adds to the accumulated context', async () => {
+    const session = new IntentSession();
+
+    const r1 = await session.submit('I need office supplies');
+    assert.ok(r1.missing.length > 0, 'First round should have missing');
+
+    const r2 = await session.submit('50 units of keyboards');
+    // Should have equal or fewer missing after adding quantity info
+
+    const r3 = await session.submit('budget is under $5000');
+    // Should have equal or fewer missing after adding price info
+
+    // Confidence should generally increase as we add more info
+    assert.ok(r3.confidence >= r1.confidence - 0.1,
+      'Confidence should not drastically decrease');
+  });
+});