@mcp-i/core 0.1.0

package/src/delegation/__tests__/did-web-resolver.test.ts

@@ -0,0 +1,467 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  DidWebResolver,
+  createDidWebResolver,
+  isDidWeb,
+  parseDidWeb,
+  didWebToUrl,
+} from '../did-web-resolver.js';
+import type { FetchProvider } from '../../providers/base.js';
+import type { DIDDocument } from '../vc-verifier.js';
+
+/**
+ * Tests for did:web resolver
+ *
+ * These tests verify the did:web resolution functionality:
+ * - URL construction for root domain DIDs
+ * - URL construction for path-based DIDs
+ * - Successful resolution with mocked fetch
+ * - Null return on 404
+ * - Null return on invalid JSON
+ * - Null return on missing `id` field in response
+ */
+
+describe('did:web URL Construction', () => {
+  describe('isDidWeb', () => {
+    it('should return true for did:web DIDs', () => {
+      expect(isDidWeb('did:web:example.com')).toBe(true);
+      expect(isDidWeb('did:web:example.com:path')).toBe(true);
+      expect(isDidWeb('did:web:sub.example.com')).toBe(true);
+    });
+
+    it('should return false for non-did:web DIDs', () => {
+      expect(isDidWeb('did:key:z6Mk...')).toBe(false);
+      expect(isDidWeb('did:example:123')).toBe(false);
+      expect(isDidWeb('not-a-did')).toBe(false);
+      expect(isDidWeb('')).toBe(false);
+    });
+  });
+
+  describe('parseDidWeb', () => {
+    it('should parse root domain DID', () => {
+      const result = parseDidWeb('did:web:example.com');
+      expect(result).not.toBeNull();
+      expect(result?.domain).toBe('example.com');
+      expect(result?.path).toEqual([]);
+    });
+
+    it('should parse path-based DID', () => {
+      const result = parseDidWeb('did:web:example.com:path:to:doc');
+      expect(result).not.toBeNull();
+      expect(result?.domain).toBe('example.com');
+      expect(result?.path).toEqual(['path', 'to', 'doc']);
+    });
+
+    it('should handle URL-encoded components', () => {
+      // %3A is URL-encoded colon, which would be used for port numbers
+      const result = parseDidWeb('did:web:example.com%3A8080');
+      expect(result).not.toBeNull();
+      expect(result?.domain).toBe('example.com:8080');
+      expect(result?.path).toEqual([]);
+    });
+
+    it('should return null for invalid DIDs', () => {
+      expect(parseDidWeb('did:key:z6Mk...')).toBeNull();
+      expect(parseDidWeb('did:web:')).toBeNull();
+      expect(parseDidWeb('')).toBeNull();
+    });
+  });
+
+  describe('didWebToUrl', () => {
+    it('should convert root domain DID to .well-known URL', () => {
+      const url = didWebToUrl('did:web:example.com');
+      expect(url).toBe('https://example.com/.well-known/did.json');
+    });
+
+    it('should convert subdomain DID to .well-known URL', () => {
+      const url = didWebToUrl('did:web:agents.example.com');
+      expect(url).toBe('https://agents.example.com/.well-known/did.json');
+    });
+
+    it('should convert single path component DID to path URL', () => {
+      const url = didWebToUrl('did:web:example.com:user');
+      expect(url).toBe('https://example.com/user/did.json');
+    });
+
+    it('should convert multi-path DID to path URL', () => {
+      const url = didWebToUrl('did:web:example.com:path:to:doc');
+      expect(url).toBe('https://example.com/path/to/doc/did.json');
+    });
+
+    it('should handle agents path pattern', () => {
+      const url = didWebToUrl('did:web:example.com:agents:bot1');
+      expect(url).toBe('https://example.com/agents/bot1/did.json');
+    });
+
+    it('should handle URL-encoded port number', () => {
+      const url = didWebToUrl('did:web:example.com%3A8080');
+      expect(url).toBe('https://example.com:8080/.well-known/did.json');
+    });
+
+    it('should handle URL-encoded port number with path', () => {
+      const url = didWebToUrl('did:web:example.com%3A3000:users:alice');
+      expect(url).toBe('https://example.com:3000/users/alice/did.json');
+    });
+
+    it('should return null for invalid DIDs', () => {
+      expect(didWebToUrl('did:key:z6Mk...')).toBeNull();
+      expect(didWebToUrl('did:web:')).toBeNull();
+      expect(didWebToUrl('')).toBeNull();
+    });
+  });
+});
+
+describe('DidWebResolver', () => {
+  let mockFetchProvider: FetchProvider;
+  let resolver: DidWebResolver;
+
+  const validDIDDocument: DIDDocument = {
+    id: 'did:web:example.com',
+    verificationMethod: [
+      {
+        id: 'did:web:example.com#key-1',
+        type: 'Ed25519VerificationKey2020',
+        controller: 'did:web:example.com',
+        publicKeyJwk: {
+          kty: 'OKP',
+          crv: 'Ed25519',
+          x: 'test-public-key-base64url',
+        },
+      },
+    ],
+    authentication: ['did:web:example.com#key-1'],
+    assertionMethod: ['did:web:example.com#key-1'],
+  };
+
+  const createMockFetchProvider = (
+    responseBody: unknown,
+    status = 200
+  ): FetchProvider => {
+    return {
+      resolveDID: vi.fn(),
+      fetchStatusList: vi.fn(),
+      fetchDelegationChain: vi.fn(),
+      fetch: vi.fn().mockResolvedValue({
+        ok: status >= 200 && status < 300,
+        status,
+        json: vi.fn().mockResolvedValue(responseBody),
+      }),
+    };
+  };
+
+  const createMockFetchProviderWithJsonError = (): FetchProvider => {
+    return {
+      resolveDID: vi.fn(),
+      fetchStatusList: vi.fn(),
+      fetchDelegationChain: vi.fn(),
+      fetch: vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: vi.fn().mockRejectedValue(new Error('Invalid JSON')),
+      }),
+    };
+  };
+
+  const createMockFetchProviderWithNetworkError = (): FetchProvider => {
+    return {
+      resolveDID: vi.fn(),
+      fetchStatusList: vi.fn(),
+      fetchDelegationChain: vi.fn(),
+      fetch: vi.fn().mockRejectedValue(new Error('Network error')),
+    };
+  };
+
+  beforeEach(() => {
+    mockFetchProvider = createMockFetchProvider(validDIDDocument);
+    resolver = new DidWebResolver(mockFetchProvider, { cacheTtl: 1000 });
+  });
+
+  describe('successful resolution', () => {
+    it('should resolve did:web:example.com', async () => {
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).not.toBeNull();
+      expect(result?.id).toBe('did:web:example.com');
+      expect(result?.verificationMethod).toHaveLength(1);
+      expect(result?.verificationMethod?.[0]?.type).toBe('Ed25519VerificationKey2020');
+      expect(mockFetchProvider.fetch).toHaveBeenCalledWith(
+        'https://example.com/.well-known/did.json'
+      );
+    });
+
+    it('should resolve path-based DID', async () => {
+      const pathDIDDocument: DIDDocument = {
+        ...validDIDDocument,
+        id: 'did:web:example.com:agents:bot1',
+        verificationMethod: [
+          {
+            ...validDIDDocument.verificationMethod![0]!,
+            id: 'did:web:example.com:agents:bot1#key-1',
+            controller: 'did:web:example.com:agents:bot1',
+          },
+        ],
+      };
+
+      mockFetchProvider = createMockFetchProvider(pathDIDDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com:agents:bot1');
+
+      expect(result).not.toBeNull();
+      expect(result?.id).toBe('did:web:example.com:agents:bot1');
+      expect(mockFetchProvider.fetch).toHaveBeenCalledWith(
+        'https://example.com/agents/bot1/did.json'
+      );
+    });
+
+    it('should cache successful resolutions', async () => {
+      await resolver.resolve('did:web:example.com');
+      await resolver.resolve('did:web:example.com');
+
+      // Should only fetch once due to caching
+      expect(mockFetchProvider.fetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return cached result', async () => {
+      const result1 = await resolver.resolve('did:web:example.com');
+      const result2 = await resolver.resolve('did:web:example.com');
+
+      expect(result1).toEqual(result2);
+    });
+  });
+
+  describe('null return on 404', () => {
+    it('should return null for 404 response', async () => {
+      mockFetchProvider = createMockFetchProvider({}, 404);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null for 500 response', async () => {
+      mockFetchProvider = createMockFetchProvider({}, 500);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('null return on invalid JSON', () => {
+    it('should return null when JSON parsing fails', async () => {
+      mockFetchProvider = createMockFetchProviderWithJsonError();
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('null return on missing id field', () => {
+    it('should return null when id field is missing', async () => {
+      const invalidDocument = {
+        verificationMethod: [],
+      };
+
+      mockFetchProvider = createMockFetchProvider(invalidDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when id field is empty string', async () => {
+      const invalidDocument = {
+        id: '',
+        verificationMethod: [],
+      };
+
+      mockFetchProvider = createMockFetchProvider(invalidDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when id does not match requested DID', async () => {
+      const mismatchedDocument: DIDDocument = {
+        ...validDIDDocument,
+        id: 'did:web:other.com',
+      };
+
+      mockFetchProvider = createMockFetchProvider(mismatchedDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('null return on network error', () => {
+    it('should return null when fetch throws', async () => {
+      mockFetchProvider = createMockFetchProviderWithNetworkError();
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('null return for non-did:web', () => {
+    it('should return null for did:key', async () => {
+      const result = await resolver.resolve(
+        'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
+      );
+
+      expect(result).toBeNull();
+      expect(mockFetchProvider.fetch).not.toHaveBeenCalled();
+    });
+
+    it('should return null for invalid DID format', async () => {
+      const result = await resolver.resolve('not-a-did');
+
+      expect(result).toBeNull();
+      expect(mockFetchProvider.fetch).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('invalid DID document structure', () => {
+    it('should return null when response is not an object', async () => {
+      mockFetchProvider = createMockFetchProvider('not an object');
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when response is null', async () => {
+      mockFetchProvider = createMockFetchProvider(null);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when verificationMethod is not an array', async () => {
+      const invalidDocument = {
+        id: 'did:web:example.com',
+        verificationMethod: 'not an array',
+      };
+
+      mockFetchProvider = createMockFetchProvider(invalidDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when verificationMethod entry is invalid', async () => {
+      const invalidDocument = {
+        id: 'did:web:example.com',
+        verificationMethod: [
+          {
+            // Missing required id field
+            type: 'Ed25519VerificationKey2020',
+            controller: 'did:web:example.com',
+          },
+        ],
+      };
+
+      mockFetchProvider = createMockFetchProvider(invalidDocument);
+      resolver = new DidWebResolver(mockFetchProvider);
+
+      const result = await resolver.resolve('did:web:example.com');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('cache management', () => {
+    it('should clear all cache entries', async () => {
+      await resolver.resolve('did:web:example.com');
+
+      resolver.clearCache();
+
+      // Next call should fetch again
+      await resolver.resolve('did:web:example.com');
+
+      expect(mockFetchProvider.fetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should clear specific cache entry', async () => {
+      await resolver.resolve('did:web:example.com');
+
+      resolver.clearCacheEntry('did:web:example.com');
+
+      // Next call should fetch again
+      await resolver.resolve('did:web:example.com');
+
+      expect(mockFetchProvider.fetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('should expire cached entries after TTL', async () => {
+      // Use very short TTL
+      resolver = new DidWebResolver(mockFetchProvider, { cacheTtl: 10 });
+
+      await resolver.resolve('did:web:example.com');
+
+      // Wait for cache to expire
+      await new Promise((resolve) => setTimeout(resolve, 15));
+
+      await resolver.resolve('did:web:example.com');
+
+      expect(mockFetchProvider.fetch).toHaveBeenCalledTimes(2);
+    });
+  });
+});
+
+describe('createDidWebResolver', () => {
+  it('should create a resolver instance', () => {
+    const mockFetchProvider: FetchProvider = {
+      resolveDID: vi.fn(),
+      fetchStatusList: vi.fn(),
+      fetchDelegationChain: vi.fn(),
+      fetch: vi.fn(),
+    };
+
+    const resolver = createDidWebResolver(mockFetchProvider);
+
+    expect(resolver).toBeDefined();
+    expect(typeof resolver.resolve).toBe('function');
+  });
+
+  it('should pass options to resolver', async () => {
+    const validDIDDocument: DIDDocument = {
+      id: 'did:web:example.com',
+      verificationMethod: [],
+    };
+
+    const mockFetchProvider: FetchProvider = {
+      resolveDID: vi.fn(),
+      fetchStatusList: vi.fn(),
+      fetchDelegationChain: vi.fn(),
+      fetch: vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue(validDIDDocument),
+      }),
+    };
+
+    const resolver = createDidWebResolver(mockFetchProvider, { cacheTtl: 5000 });
+
+    const result = await resolver.resolve('did:web:example.com');
+
+    expect(result).not.toBeNull();
+  });
+});

package/src/delegation/__tests__/outbound-headers.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Outbound Delegation Headers Tests
+ *
+ * Tests for buildOutboundDelegationHeaders utility.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { decodeJwt, decodeProtectedHeader } from 'jose';
+import {
+  buildOutboundDelegationHeaders,
+  type OutboundDelegationContext,
+} from '../outbound-headers.js';
+import type { SessionContext, DelegationRecord } from '../../types/protocol.js';
+import { NodeCryptoProvider } from '../../__tests__/utils/node-crypto-provider.js';
+import { generateDidKeyFromBase64 } from '../../utils/did-helpers.js';
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+let cryptoProvider: NodeCryptoProvider;
+let serverKeyPair: { privateKey: string; publicKey: string };
+let serverDid: string;
+let serverKid: string;
+let agentKeyPair: { privateKey: string; publicKey: string };
+let agentDid: string;
+
+beforeAll(async () => {
+  cryptoProvider = new NodeCryptoProvider();
+
+  // Generate server identity
+  serverKeyPair = await cryptoProvider.generateKeyPair();
+  serverDid = generateDidKeyFromBase64(serverKeyPair.publicKey);
+  serverKid = `${serverDid}#keys-1`;
+
+  // Generate agent identity
+  agentKeyPair = await cryptoProvider.generateKeyPair();
+  agentDid = generateDidKeyFromBase64(agentKeyPair.publicKey);
+});
+
+function createTestSession(overrides: Partial<SessionContext> = {}): SessionContext {
+  return {
+    sessionId: 'mcpi_test-session-123',
+    audience: 'did:web:my-mcp-server.example.com',
+    nonce: 'test-nonce-abc',
+    timestamp: Math.floor(Date.now() / 1000),
+    createdAt: Date.now(),
+    lastActivity: Date.now(),
+    ttlMinutes: 30,
+    identityState: 'authenticated',
+    agentDid,
+    ...overrides,
+  };
+}
+
+function createTestDelegation(overrides: Partial<DelegationRecord> = {}): DelegationRecord {
+  return {
+    id: 'del-test-123',
+    issuerDid: serverDid,
+    subjectDid: agentDid,
+    vcId: 'urn:uuid:vc-test-456',
+    constraints: {
+      scopes: ['tool:execute', 'resource:read'],
+    },
+    signature: 'test-signature',
+    status: 'active',
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function createTestContext(
+  overrides: Partial<OutboundDelegationContext> = {}
+): OutboundDelegationContext {
+  return {
+    session: createTestSession(),
+    delegation: createTestDelegation(),
+    serverIdentity: {
+      did: serverDid,
+      kid: serverKid,
+      privateKey: serverKeyPair.privateKey,
+    },
+    targetUrl: 'https://downstream-api.example.com/resource',
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildOutboundDelegationHeaders', () => {
+  it('builds correct headers from a valid session + delegation', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    expect(headers).toHaveProperty('X-Agent-DID');
+    expect(headers).toHaveProperty('X-Delegation-Chain');
+    expect(headers).toHaveProperty('X-Session-ID');
+    expect(headers).toHaveProperty('X-Delegation-Proof');
+  });
+
+  it('X-Agent-DID matches session.agentDid', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    expect(headers['X-Agent-DID']).toBe(context.session.agentDid);
+  });
+
+  it('X-Delegation-Chain matches delegation.vcId', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    expect(headers['X-Delegation-Chain']).toBe(context.delegation.vcId);
+  });
+
+  it('X-Session-ID matches session.sessionId', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    expect(headers['X-Session-ID']).toBe(context.session.sessionId);
+  });
+
+  it('X-Delegation-Proof is a valid JWT with correct claims', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    const jwt = headers['X-Delegation-Proof'];
+
+    // Verify it's a valid JWT format (3 parts)
+    expect(jwt.split('.')).toHaveLength(3);
+
+    // Verify header
+    const header = decodeProtectedHeader(jwt);
+    expect(header.alg).toBe('EdDSA');
+    expect(header.kid).toBe(serverKid);
+
+    // Verify payload claims
+    const payload = decodeJwt(jwt);
+    expect(payload.iss).toBe(serverDid);           // server forwarding
+    expect(payload.sub).toBe(agentDid);            // original agent
+    expect(payload.aud).toBe('downstream-api.example.com');  // target hostname
+    expect(payload.scope).toBe('delegation:propagate');
+    expect(typeof payload.iat).toBe('number');
+    expect(typeof payload.exp).toBe('number');
+    expect(typeof payload.jti).toBe('string');
+  });
+
+  it('extracts hostname correctly from full URL for aud claim', async () => {
+    const context = createTestContext({
+      targetUrl: 'https://api.service.example.com:8443/v1/resource?query=test',
+    });
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    const payload = decodeJwt(headers['X-Delegation-Proof']);
+    expect(payload.aud).toBe('api.service.example.com');
+  });
+
+  it('works with http:// URLs', async () => {
+    const context = createTestContext({
+      targetUrl: 'http://internal-service.local/api',
+    });
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    const payload = decodeJwt(headers['X-Delegation-Proof']);
+    expect(payload.aud).toBe('internal-service.local');
+  });
+
+  it('works with https:// URLs', async () => {
+    const context = createTestContext({
+      targetUrl: 'https://secure.example.org/endpoint',
+    });
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    const payload = decodeJwt(headers['X-Delegation-Proof']);
+    expect(payload.aud).toBe('secure.example.org');
+  });
+
+  it('JWT exp is 60 seconds from iat', async () => {
+    const context = createTestContext();
+    const headers = await buildOutboundDelegationHeaders(context, cryptoProvider);
+
+    const payload = decodeJwt(headers['X-Delegation-Proof']);
+    expect((payload.exp as number) - (payload.iat as number)).toBe(60);
+  });
+
+  it('throws when session is missing agentDid', async () => {
+    const context = createTestContext({
+      session: createTestSession({ agentDid: undefined }),
+    });
+
+    await expect(
+      buildOutboundDelegationHeaders(context, cryptoProvider)
+    ).rejects.toThrow('Session must have agentDid');
+  });
+
+  it('throws when session is missing sessionId', async () => {
+    const context = createTestContext({
+      session: createTestSession({ sessionId: '' }),
+    });
+
+    await expect(
+      buildOutboundDelegationHeaders(context, cryptoProvider)
+    ).rejects.toThrow('Session must have sessionId');
+  });
+
+  it('throws when delegation is missing vcId', async () => {
+    const context = createTestContext({
+      delegation: createTestDelegation({ vcId: '' }),
+    });
+
+    await expect(
+      buildOutboundDelegationHeaders(context, cryptoProvider)
+    ).rejects.toThrow('Delegation must have vcId');
+  });
+
+  it('throws for non-did:key server DID', async () => {
+    const context = createTestContext({
+      serverIdentity: {
+        did: 'did:web:server.example.com',
+        kid: 'did:web:server.example.com#key-1',
+        privateKey: serverKeyPair.privateKey,
+      },
+    });
+
+    await expect(
+      buildOutboundDelegationHeaders(context, cryptoProvider)
+    ).rejects.toThrow('Server DID must be did:key with Ed25519');
+  });
+});