@mcp-i/core 0.1.0

package/src/delegation/did-key-resolver.ts

@@ -0,0 +1,181 @@
+/**
+ * DID:key Resolver
+ *
+ * Resolves did:key DIDs to DID Documents with verification methods.
+ * Supports Ed25519 keys (multicodec prefix 0xed01).
+ *
+ * did:key format: did:key:z<multibase-base58btc(<multicodec-prefix><public-key>)>
+ *
+ * For Ed25519:
+ * - Multicodec prefix: 0xed 0x01
+ * - Public key: 32 bytes
+ * - Multibase prefix: 'z' (base58btc)
+ *
+ * @see https://w3c-ccg.github.io/did-method-key/
+ */
+
+import { base58Decode } from '../utils/base58.js';
+import { base64urlEncodeFromBytes } from '../utils/base64.js';
+import type { DIDResolver, DIDDocument, VerificationMethod } from './vc-verifier.js';
+import { logger } from '../logging/index.js';
+
+/** Ed25519 multicodec prefix (0xed 0x01) */
+const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
+
+/** Ed25519 public key length */
+const ED25519_PUBLIC_KEY_LENGTH = 32;
+
+/**
+ * Check if a DID is a valid did:key with Ed25519 key
+ *
+ * Ed25519 keys in did:key start with 'z6Mk' after the method prefix.
+ * The 'z' is the multibase prefix for base58btc, and '6Mk' is the
+ * base58-encoded prefix for Ed25519 (0xed 0x01).
+ *
+ * @param did - The DID to check
+ * @returns true if it's a valid did:key with Ed25519 key
+ */
+export function isEd25519DidKey(did: string): boolean {
+  return did.startsWith('did:key:z6Mk');
+}
+
+/**
+ * Extract the public key bytes from a did:key DID
+ *
+ * @param did - The did:key DID
+ * @returns Public key bytes or null if invalid
+ */
+export function extractPublicKeyFromDidKey(did: string): Uint8Array | null {
+  if (!did.startsWith('did:key:z')) {
+    return null;
+  }
+
+  try {
+    // Extract the multibase-encoded part (after 'did:key:')
+    const multibaseKey = did.replace('did:key:', '');
+
+    // Remove the 'z' multibase prefix (base58btc)
+    const base58Encoded = multibaseKey.slice(1);
+
+    // Decode from base58
+    const multicodecBytes = base58Decode(base58Encoded);
+
+    // Check for Ed25519 multicodec prefix (0xed 0x01)
+    if (
+      multicodecBytes.length < ED25519_MULTICODEC_PREFIX.length + ED25519_PUBLIC_KEY_LENGTH ||
+      multicodecBytes[0] !== ED25519_MULTICODEC_PREFIX[0] ||
+      multicodecBytes[1] !== ED25519_MULTICODEC_PREFIX[1]
+    ) {
+      return null;
+    }
+
+    // Extract the public key (bytes after the prefix)
+    return multicodecBytes.slice(ED25519_MULTICODEC_PREFIX.length);
+  } catch (error) {
+    logger.debug('Failed to extract public key from did:key', error);
+    return null;
+  }
+}
+
+/**
+ * Convert Ed25519 public key bytes to JWK format
+ *
+ * @param publicKeyBytes - 32-byte Ed25519 public key
+ * @returns JWK object
+ */
+export function publicKeyToJwk(publicKeyBytes: Uint8Array): {
+  kty: string;
+  crv: string;
+  x: string;
+} {
+  return {
+    kty: 'OKP',
+    crv: 'Ed25519',
+    x: base64urlEncodeFromBytes(publicKeyBytes),
+  };
+}
+
+/**
+ * Create a DID:key resolver
+ *
+ * Returns a DIDResolver that can resolve did:key DIDs to DID Documents.
+ * Currently supports only Ed25519 keys.
+ *
+ * @returns DIDResolver implementation for did:key
+ */
+export function createDidKeyResolver(): DIDResolver {
+  return {
+    resolve: async (did: string): Promise<DIDDocument | null> => {
+      // Check if it's a did:key with Ed25519
+      if (!isEd25519DidKey(did)) {
+        return null;
+      }
+
+      // Extract the public key
+      const publicKeyBytes = extractPublicKeyFromDidKey(did);
+      if (!publicKeyBytes) {
+        return null;
+      }
+
+      // Convert to JWK
+      const publicKeyJwk = publicKeyToJwk(publicKeyBytes);
+
+      // Get the multibase-encoded key for publicKeyMultibase
+      const multibaseKey = did.replace('did:key:', '');
+
+      // Construct the verification method
+      const verificationMethod: VerificationMethod = {
+        id: `${did}#keys-1`,
+        type: 'Ed25519VerificationKey2020',
+        controller: did,
+        publicKeyJwk,
+        publicKeyMultibase: multibaseKey,
+      };
+
+      // Construct and return the DID Document
+      return {
+        id: did,
+        verificationMethod: [verificationMethod],
+        authentication: [`${did}#keys-1`],
+        assertionMethod: [`${did}#keys-1`],
+      };
+    },
+  };
+}
+
+/**
+ * Resolve a did:key DID synchronously
+ *
+ * Convenience function for cases where async is not needed.
+ *
+ * @param did - The did:key DID to resolve
+ * @returns DID Document or null if invalid
+ */
+export function resolveDidKeySync(did: string): DIDDocument | null {
+  if (!isEd25519DidKey(did)) {
+    return null;
+  }
+
+  const publicKeyBytes = extractPublicKeyFromDidKey(did);
+  if (!publicKeyBytes) {
+    return null;
+  }
+
+  const publicKeyJwk = publicKeyToJwk(publicKeyBytes);
+  const multibaseKey = did.replace('did:key:', '');
+
+  const verificationMethod: VerificationMethod = {
+    id: `${did}#keys-1`,
+    type: 'Ed25519VerificationKey2020',
+    controller: did,
+    publicKeyJwk,
+    publicKeyMultibase: multibaseKey,
+  };
+
+  return {
+    id: did,
+    verificationMethod: [verificationMethod],
+    authentication: [`${did}#keys-1`],
+    assertionMethod: [`${did}#keys-1`],
+  };
+}

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

@@ -0,0 +1,270 @@
+/**
+ * DID:web Resolver
+ *
+ * Resolves did:web DIDs by fetching /.well-known/did.json from the domain.
+ * Supports both root domain DIDs and path-based DIDs.
+ *
+ * Examples:
+ *   did:web:example.com → https://example.com/.well-known/did.json
+ *   did:web:example.com:agents:bot1 → https://example.com/agents/bot1/did.json
+ *
+ * @see https://w3c-ccg.github.io/did-method-web/
+ */
+
+import type { FetchProvider } from '../providers/base.js';
+import type { DIDResolver, DIDDocument, VerificationMethod } from './vc-verifier.js';
+import { logger } from '../logging/index.js';
+
+/**
+ * Parsed components of a did:web DID
+ */
+interface ParsedDidWeb {
+  domain: string;
+  path: string[];
+}
+
+/**
+ * Type guard for checking if value is a valid DID Document structure
+ */
+function isValidDIDDocument(value: unknown): value is DIDDocument {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const doc = value as Record<string, unknown>;
+
+  // id is required and must be a string
+  if (typeof doc['id'] !== 'string' || doc['id'].length === 0) {
+    return false;
+  }
+
+  // verificationMethod is optional but if present must be an array
+  if (doc['verificationMethod'] !== undefined) {
+    if (!Array.isArray(doc['verificationMethod'])) {
+      return false;
+    }
+
+    // Each verification method must have required fields
+    for (const vm of doc['verificationMethod']) {
+      if (!isValidVerificationMethod(vm)) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Type guard for checking if value is a valid VerificationMethod
+ */
+function isValidVerificationMethod(value: unknown): value is VerificationMethod {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const vm = value as Record<string, unknown>;
+
+  // id, type, and controller are required strings
+  if (typeof vm['id'] !== 'string' || vm['id'].length === 0) {
+    return false;
+  }
+  if (typeof vm['type'] !== 'string' || vm['type'].length === 0) {
+    return false;
+  }
+  if (typeof vm['controller'] !== 'string' || vm['controller'].length === 0) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if a DID is a did:web DID
+ *
+ * @param did - The DID to check
+ * @returns true if it's a did:web DID
+ */
+export function isDidWeb(did: string): boolean {
+  return did.startsWith('did:web:');
+}
+
+/**
+ * Parse a did:web DID into its components
+ *
+ * @param did - The did:web DID to parse
+ * @returns Parsed components or null if invalid
+ */
+export function parseDidWeb(did: string): ParsedDidWeb | null {
+  if (!isDidWeb(did)) {
+    return null;
+  }
+
+  // Remove the 'did:web:' prefix
+  const remainder = did.slice(8);
+
+  if (remainder.length === 0) {
+    return null;
+  }
+
+  // Split by ':' to get domain and path components
+  const parts = remainder.split(':');
+
+  // First part is the domain (URL-decoded)
+  const domain = decodeURIComponent(parts[0]!);
+
+  if (domain.length === 0) {
+    return null;
+  }
+
+  // Remaining parts form the path
+  const path = parts.slice(1).map((p) => decodeURIComponent(p));
+
+  return { domain, path };
+}
+
+/**
+ * Convert a did:web DID to its resolution URL
+ *
+ * did:web:example.com → https://example.com/.well-known/did.json
+ * did:web:example.com:path:to:doc → https://example.com/path/to/doc/did.json
+ *
+ * @param did - The did:web DID
+ * @returns The resolution URL or null if invalid
+ */
+export function didWebToUrl(did: string): string | null {
+  const parsed = parseDidWeb(did);
+
+  if (!parsed) {
+    return null;
+  }
+
+  const { domain, path } = parsed;
+
+  // Build the URL
+  // Note: did:web specification requires HTTPS
+  let url = `https://${domain}`;
+
+  if (path.length === 0) {
+    // Root domain: use /.well-known/did.json
+    url += '/.well-known/did.json';
+  } else {
+    // Path-based: use /path/to/resource/did.json
+    url += '/' + path.join('/') + '/did.json';
+  }
+
+  return url;
+}
+
+/**
+ * DID:web resolver implementation
+ */
+export class DidWebResolver implements DIDResolver {
+  private fetchProvider: FetchProvider;
+  private cache: Map<string, { document: DIDDocument; expiresAt: number }>;
+  private cacheTtl: number;
+
+  constructor(fetchProvider: FetchProvider, options?: { cacheTtl?: number }) {
+    this.fetchProvider = fetchProvider;
+    this.cache = new Map();
+    this.cacheTtl = options?.cacheTtl ?? 300_000; // 5 minutes default
+  }
+
+  /**
+   * Resolve a did:web DID to its DID Document
+   *
+   * @param did - The did:web DID to resolve
+   * @returns The DID Document or null if resolution fails
+   */
+  async resolve(did: string): Promise<DIDDocument | null> {
+    // Check if it's a did:web
+    if (!isDidWeb(did)) {
+      return null;
+    }
+
+    // Check cache
+    const cached = this.cache.get(did);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.document;
+    }
+
+    // Convert to URL
+    const url = didWebToUrl(did);
+    if (!url) {
+      logger.warn(`[DidWebResolver] Invalid did:web format: ${did}`);
+      return null;
+    }
+
+    try {
+      // Fetch the DID document
+      const response = await this.fetchProvider.fetch(url);
+
+      if (!response.ok) {
+        logger.warn(`[DidWebResolver] HTTP ${response.status} fetching ${url}`);
+        return null;
+      }
+
+      // Parse JSON
+      let json: unknown;
+      try {
+        json = await response.json();
+      } catch {
+        logger.warn(`[DidWebResolver] Invalid JSON from ${url}`);
+        return null;
+      }
+
+      // Validate structure
+      if (!isValidDIDDocument(json)) {
+        logger.warn(`[DidWebResolver] Invalid DID Document structure from ${url}`);
+        return null;
+      }
+
+      // Verify the id matches the DID
+      if (json.id !== did) {
+        logger.warn(`[DidWebResolver] DID Document id mismatch: expected ${did}, got ${json.id}`);
+        return null;
+      }
+
+      // Cache the result
+      this.cache.set(did, {
+        document: json,
+        expiresAt: Date.now() + this.cacheTtl,
+      });
+
+      return json;
+    } catch (error) {
+      logger.warn(
+        `[DidWebResolver] Error resolving ${did}: ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Clear the resolution cache
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Clear a specific entry from the cache
+   */
+  clearCacheEntry(did: string): void {
+    this.cache.delete(did);
+  }
+}
+
+/**
+ * Create a did:web resolver with the given fetch provider
+ *
+ * @param fetchProvider - Provider for making HTTP requests
+ * @param options - Optional configuration
+ * @returns DIDResolver implementation for did:web
+ */
+export function createDidWebResolver(
+  fetchProvider: FetchProvider,
+  options?: { cacheTtl?: number }
+): DIDResolver {
+  return new DidWebResolver(fetchProvider, options);
+}

package/src/delegation/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Delegation Module Exports (Platform-Agnostic)
+ *
+ * W3C VC-based delegation issuance and verification.
+ * Platform-specific adapters (Node.js, Cloudflare) provide signing/verification functions.
+ */
+
+export * from './vc-issuer.js';
+export * from './vc-verifier.js';
+export * from './bitstring.js';
+export * from './statuslist-manager.js';
+export * from './delegation-graph.js';
+export * from './cascading-revocation.js';
+export * from './utils.js';
+export * from './outbound-proof.js';
+export * from './outbound-headers.js';
+export * from './audience-validator.js';
+export {
+  createDidKeyResolver,
+  resolveDidKeySync,
+  isEd25519DidKey,
+  extractPublicKeyFromDidKey,
+  publicKeyToJwk,
+} from './did-key-resolver.js';
+export {
+  DidWebResolver,
+  createDidWebResolver,
+  isDidWeb,
+  parseDidWeb,
+  didWebToUrl,
+} from './did-web-resolver.js';
+export { MemoryStatusListStorage } from './storage/memory-statuslist-storage.js';
+export { MemoryDelegationGraphStorage } from './storage/memory-graph-storage.js';

package/src/delegation/outbound-headers.ts

@@ -0,0 +1,193 @@
+/**
+ * Outbound Delegation Headers
+ *
+ * Builds the full set of outbound delegation headers for forwarding
+ * delegation context to downstream services.
+ *
+ * Headers (MCP-I §7):
+ * - X-Agent-DID: the original agent's DID
+ * - X-Delegation-Chain: the delegation chain ID (vcId of the root delegation)
+ * - X-Session-ID: the current session ID
+ * - X-Delegation-Proof: a signed JWT proving the delegation is being forwarded
+ *
+ * Related Spec: MCP-I §7 — Outbound Delegation Propagation
+ */
+
+import type { SessionContext, DelegationRecord } from '../types/protocol.js';
+import type { CryptoProvider } from '../providers/base.js';
+import { buildDelegationProofJWT, type Ed25519PrivateJWK } from './outbound-proof.js';
+import { extractPublicKeyFromDidKey, isEd25519DidKey } from './did-key-resolver.js';
+import { base64ToBytes, base64urlEncodeFromBytes } from '../utils/base64.js';
+import { logger } from '../logging/index.js';
+
+/**
+ * Header names for outbound delegation propagation
+ */
+export const OUTBOUND_HEADER_NAMES = {
+  AGENT_DID: 'X-Agent-DID',
+  DELEGATION_CHAIN: 'X-Delegation-Chain',
+  SESSION_ID: 'X-Session-ID',
+  DELEGATION_PROOF: 'X-Delegation-Proof',
+} as const;
+
+/**
+ * Context required to build outbound delegation headers
+ */
+export interface OutboundDelegationContext {
+  /** The current session context */
+  session: SessionContext;
+  /** The delegation record being forwarded */
+  delegation: DelegationRecord;
+  /** The MCP server's identity for signing the proof */
+  serverIdentity: {
+    did: string;
+    kid: string;
+    privateKey: string;
+  };
+  /** The downstream URL being called */
+  targetUrl: string;
+}
+
+/**
+ * Outbound delegation headers to attach to downstream requests
+ */
+export interface OutboundDelegationHeaders {
+  'X-Agent-DID': string;
+  'X-Delegation-Chain': string;
+  'X-Session-ID': string;
+  'X-Delegation-Proof': string;
+}
+
+/**
+ * Extract hostname from a URL
+ */
+function extractHostname(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    logger.warn('Failed to parse target URL, using as-is', { url });
+    return url;
+  }
+}
+
+/**
+ * Convert base64 private key and DID to Ed25519 JWK format
+ */
+function buildPrivateKeyJwk(
+  privateKeyBase64: string,
+  serverDid: string
+): Ed25519PrivateJWK {
+  // Decode the private key from base64
+  const privateKeyBytes = base64ToBytes(privateKeyBase64);
+
+  // Extract the 32-byte seed (handle both 32-byte and 64-byte formats)
+  const seed = privateKeyBytes.length === 64
+    ? privateKeyBytes.subarray(0, 32)
+    : privateKeyBytes;
+
+  // Extract public key from did:key
+  if (!isEd25519DidKey(serverDid)) {
+    throw new Error(`Server DID must be did:key with Ed25519: ${serverDid}`);
+  }
+
+  const publicKeyBytes = extractPublicKeyFromDidKey(serverDid);
+  if (!publicKeyBytes) {
+    throw new Error(`Failed to extract public key from DID: ${serverDid}`);
+  }
+
+  return {
+    kty: 'OKP',
+    crv: 'Ed25519',
+    x: base64urlEncodeFromBytes(publicKeyBytes),
+    d: base64urlEncodeFromBytes(seed),
+  };
+}
+
+/**
+ * Build outbound delegation headers for forwarding to downstream services.
+ *
+ * When an MCP server calls a downstream service on behalf of an agent,
+ * it MUST forward the delegation context using these headers so the
+ * downstream service can independently verify the delegation chain.
+ *
+ * @param context - The delegation context including session, delegation, and server identity
+ * @param _cryptoProvider - CryptoProvider (reserved for future use)
+ * @returns Headers object to attach to the outbound request
+ *
+ * @throws {Error} If session is missing agentDid or sessionId
+ * @throws {Error} If delegation is missing vcId
+ * @throws {Error} If serverIdentity.did is not a valid Ed25519 did:key
+ *
+ * @example
+ * ```typescript
+ * const headers = await buildOutboundDelegationHeaders({
+ *   session,
+ *   delegation,
+ *   serverIdentity: { did: serverDid, kid: serverKid, privateKey },
+ *   targetUrl: 'https://downstream-api.example.com/resource',
+ * }, cryptoProvider);
+ *
+ * // Attach headers to your HTTP request
+ * fetch(targetUrl, { headers });
+ * ```
+ */
+export async function buildOutboundDelegationHeaders(
+  context: OutboundDelegationContext,
+  _cryptoProvider: CryptoProvider
+): Promise<OutboundDelegationHeaders> {
+  const { session, delegation, serverIdentity, targetUrl } = context;
+
+  // Validate required fields
+  if (!session.agentDid) {
+    throw new Error('Session must have agentDid for outbound delegation');
+  }
+
+  if (!session.sessionId) {
+    throw new Error('Session must have sessionId for outbound delegation');
+  }
+
+  if (!delegation.vcId) {
+    throw new Error('Delegation must have vcId for outbound delegation');
+  }
+
+  // Extract hostname for JWT audience
+  const targetHostname = extractHostname(targetUrl);
+
+  // Build the private key JWK from the server identity
+  const privateKeyJwk = buildPrivateKeyJwk(
+    serverIdentity.privateKey,
+    serverIdentity.did
+  );
+
+  // Build the delegation proof JWT
+  // Per MCP-I §7, the JWT has:
+  // - iss: serverDid (the MCP server forwarding the request)
+  // - sub: agentDid (the original agent)
+  // - aud: targetHostname (the downstream service)
+  // - scope: "delegation:propagate"
+  const jwt = await buildDelegationProofJWT({
+    agentDid: serverIdentity.did,     // becomes iss (server forwarding)
+    userDid: session.agentDid,        // becomes sub (original agent)
+    delegationId: delegation.id,
+    delegationChain: delegation.vcId,
+    scopes: ['delegation:propagate'],
+    privateKeyJwk,
+    kid: serverIdentity.kid,
+    targetHostname,
+  });
+
+  logger.debug('Built outbound delegation headers', {
+    agentDid: session.agentDid,
+    delegationChain: delegation.vcId,
+    sessionId: session.sessionId,
+    targetHostname,
+  });
+
+  return {
+    'X-Agent-DID': session.agentDid,
+    'X-Delegation-Chain': delegation.vcId,
+    'X-Session-ID': session.sessionId,
+    'X-Delegation-Proof': jwt,
+  };
+}