@mcp-i/core 0.1.0

package/src/__tests__/utils/node-crypto-provider.ts

@@ -0,0 +1,93 @@
+/**
+ * Node.js Crypto Provider for Testing
+ *
+ * Uses Node.js built-in crypto module for Ed25519 operations.
+ * Only used in tests — not included in the published package.
+ */
+
+import * as crypto from 'node:crypto';
+import { CryptoProvider } from '../../providers/base.js';
+
+export class NodeCryptoProvider extends CryptoProvider {
+  async sign(data: Uint8Array, privateKeyBase64: string): Promise<Uint8Array> {
+    const privateKey = Buffer.from(privateKeyBase64, 'base64');
+
+    // Handle both raw 32-byte and full 64-byte Ed25519 keys
+    const keyBytes =
+      privateKey.length === 64 ? privateKey.subarray(0, 32) : privateKey;
+
+    // Wrap in PKCS8 format for Node.js crypto
+    const pkcs8 = Buffer.concat([
+      Buffer.from('302e020100300506032b657004220420', 'hex'),
+      keyBytes,
+    ]);
+
+    const keyObject = crypto.createPrivateKey({
+      key: pkcs8,
+      format: 'der',
+      type: 'pkcs8',
+    });
+
+    const signature = crypto.sign(null, Buffer.from(data), keyObject);
+    return new Uint8Array(signature);
+  }
+
+  async verify(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKeyBase64: string
+  ): Promise<boolean> {
+    try {
+      const publicKey = Buffer.from(publicKeyBase64, 'base64');
+
+      // Wrap in SPKI format for Node.js crypto
+      const spki = Buffer.concat([
+        Buffer.from('302a300506032b6570032100', 'hex'),
+        publicKey,
+      ]);
+
+      const keyObject = crypto.createPublicKey({
+        key: spki,
+        format: 'der',
+        type: 'spki',
+      });
+
+      return crypto.verify(
+        null,
+        Buffer.from(data),
+        keyObject,
+        Buffer.from(signature)
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  async generateKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+      publicKeyEncoding: { type: 'spki', format: 'der' },
+      privateKeyEncoding: { type: 'pkcs8', format: 'der' },
+    });
+
+    // Extract raw keys from DER encoding
+    const rawPrivate = (privateKey as Buffer).subarray(16, 48);
+    const rawPublic = (publicKey as Buffer).subarray(12, 44);
+
+    return {
+      privateKey: rawPrivate.toString('base64'),
+      publicKey: rawPublic.toString('base64'),
+    };
+  }
+
+  async hash(data: Uint8Array): Promise<string> {
+    const hex = crypto
+      .createHash('sha256')
+      .update(Buffer.from(data))
+      .digest('hex');
+    return `sha256:${hex}`;
+  }
+
+  async randomBytes(length: number): Promise<Uint8Array> {
+    return new Uint8Array(crypto.randomBytes(length));
+  }
+}

package/src/auth/handshake.ts

@@ -0,0 +1,411 @@
+/**
+ * Authorization Handshake — Platform-agnostic Protocol Reference
+ *
+ * Orchestrates the MCP-I authorization flow:
+ * 1. Check agent reputation (optional)
+ * 2. Verify delegation exists
+ * 3. Return needs_authorization error if missing
+ *
+ * Uses only the global fetch API — no Node-specific imports.
+ * Safe to run on Node.js, Cloudflare Workers, and any fetch-capable runtime.
+ */
+
+import type {
+  NeedsAuthorizationError,
+  AuthorizationDisplay,
+} from '../types/protocol.js';
+import { createNeedsAuthorizationError } from '../types/protocol.js';
+import type { DelegationRecord } from '../types/protocol.js';
+import { logger } from '../logging/index.js';
+import type { DelegationVerifier, VerifyDelegationResult } from './types.js';
+
+export type { DelegationVerifier, VerifyDelegationResult };
+
+export interface AgentReputation {
+  agentDid: string;
+  score: number;
+  totalInteractions: number;
+  successRate: number;
+  riskLevel: 'low' | 'medium' | 'high' | 'unknown';
+  updatedAt: number;
+}
+
+export interface AuthHandshakeConfig {
+  delegationVerifier: DelegationVerifier;
+  resumeTokenStore: ResumeTokenStore;
+  reputationService?: {
+    apiUrl: string;
+    apiKey?: string;
+    apiFormat?: 'v1' | 'v2';
+  };
+  authorization: {
+    authorizationUrl: string;
+    resumeTokenTtl?: number;
+    requireAuthForUnknown?: boolean;
+    minReputationScore?: number;
+  };
+  debug?: boolean;
+}
+
+export interface VerifyOrHintsResult {
+  authorized: boolean;
+  delegation?: DelegationRecord;
+  credential?: {
+    agent_did: string;
+    user_did: string;
+    scopes: string[];
+    authorization: {
+      type:
+        | 'oauth'
+        | 'oauth2'
+        | 'password'
+        | 'credential'
+        | 'webauthn'
+        | 'siwe'
+        | 'none';
+      provider?: string;
+      credentialType?: string;
+      rpId?: string;
+      userVerification?: 'required' | 'preferred' | 'discouraged';
+      chainId?: number;
+      domain?: string;
+    };
+    [key: string]: unknown;
+  };
+  authError?: NeedsAuthorizationError;
+  reputation?: AgentReputation;
+  reason?: string;
+}
+
+export interface ResumeTokenStore {
+  create(
+    agentDid: string,
+    scopes: string[],
+    metadata?: Record<string, unknown>
+  ): Promise<string>;
+
+  get(token: string): Promise<{
+    agentDid: string;
+    scopes: string[];
+    createdAt: number;
+    expiresAt: number;
+    metadata?: Record<string, unknown>;
+  } | null>;
+
+  fulfill(token: string): Promise<void>;
+}
+
+export class MemoryResumeTokenStore implements ResumeTokenStore {
+  private tokens = new Map<
+    string,
+    {
+      agentDid: string;
+      scopes: string[];
+      createdAt: number;
+      expiresAt: number;
+      metadata?: Record<string, unknown>;
+      fulfilled: boolean;
+    }
+  >();
+  private ttl: number;
+
+  constructor(ttlMs = 600_000) {
+    this.ttl = ttlMs;
+  }
+
+  async create(
+    agentDid: string,
+    scopes: string[],
+    metadata?: Record<string, unknown>
+  ): Promise<string> {
+    const token = `rt_${Date.now()}_${Math.random().toString(36).substring(2, 18)}`;
+    const now = Date.now();
+
+    this.tokens.set(token, {
+      agentDid,
+      scopes,
+      createdAt: now,
+      expiresAt: now + this.ttl,
+      metadata,
+      fulfilled: false,
+    });
+
+    return token;
+  }
+
+  async get(token: string): Promise<{
+    agentDid: string;
+    scopes: string[];
+    createdAt: number;
+    expiresAt: number;
+    metadata?: Record<string, unknown>;
+  } | null> {
+    const data = this.tokens.get(token);
+    if (!data) return null;
+
+    if (Date.now() > data.expiresAt) {
+      this.tokens.delete(token);
+      return null;
+    }
+
+    if (data.fulfilled) return null;
+
+    return {
+      agentDid: data.agentDid,
+      scopes: data.scopes,
+      createdAt: data.createdAt,
+      expiresAt: data.expiresAt,
+      metadata: data.metadata,
+    };
+  }
+
+  async fulfill(token: string): Promise<void> {
+    const data = this.tokens.get(token);
+    if (data) {
+      data.fulfilled = true;
+    }
+  }
+
+  clear(): void {
+    this.tokens.clear();
+  }
+}
+
+/**
+ * Verify agent delegation or return authorization hints.
+ *
+ * Orchestrates the authorization flow:
+ * 1. Optionally check agent reputation against threshold
+ * 2. Verify existing delegation via DelegationVerifier
+ * 3. Return authorization hints if delegation is missing/invalid
+ *
+ * @param agentDid - The agent's DID to verify
+ * @param scopes - Required scopes for the operation
+ * @param config - Authorization configuration including verifier, token store, etc.
+ * @param _resumeToken - Optional resume token from previous authorization attempt
+ * @returns Result indicating authorization status, delegation, or auth hints
+ */
+export async function verifyOrHints(
+  agentDid: string,
+  scopes: string[],
+  config: AuthHandshakeConfig,
+  _resumeToken?: string
+): Promise<VerifyOrHintsResult> {
+  const startTime = Date.now();
+
+  if (config.debug) {
+    logger.debug(`[AuthHandshake] Verifying ${agentDid} for scopes: ${scopes.join(', ')}`);
+  }
+
+  let reputation: AgentReputation | undefined;
+  if (config.reputationService && config.authorization.minReputationScore !== undefined) {
+    try {
+      reputation = await fetchAgentReputation(agentDid, config.reputationService);
+
+      if (config.debug) {
+        logger.debug(`[AuthHandshake] Reputation score: ${reputation.score}`);
+      }
+
+      if (reputation.score < config.authorization.minReputationScore) {
+        if (config.debug) {
+          logger.debug(
+            `[AuthHandshake] Reputation ${reputation.score} < ${config.authorization.minReputationScore}, requiring authorization`
+          );
+        }
+
+        const authError = await buildNeedsAuthorizationError(
+          agentDid,
+          scopes,
+          config,
+          'Agent reputation score below threshold'
+        );
+
+        return {
+          authorized: false,
+          authError,
+          reputation,
+          reason: 'Low reputation score',
+        };
+      }
+    } catch (error) {
+      logger.warn('[AuthHandshake] Failed to check reputation:', error);
+    }
+  }
+
+  let delegationResult: VerifyDelegationResult;
+
+  try {
+    delegationResult = await config.delegationVerifier.verify(agentDid, scopes);
+  } catch (error) {
+    logger.error('[AuthHandshake] Delegation verification failed:', error);
+    const errorMessage = `Delegation verification error: ${error instanceof Error ? error.message : 'Unknown error'}`;
+
+    const authError = await buildNeedsAuthorizationError(agentDid, scopes, config, errorMessage);
+
+    return {
+      authorized: false,
+      authError,
+      reason: errorMessage,
+    };
+  }
+
+  if (delegationResult.valid && delegationResult.delegation) {
+    if (config.debug) {
+      logger.debug(
+        `[AuthHandshake] Delegation valid, authorized (${Date.now() - startTime}ms)`
+      );
+    }
+
+    return {
+      authorized: true,
+      delegation: delegationResult.delegation,
+      credential: delegationResult.credential,
+      reputation,
+      reason: 'Valid delegation found',
+    };
+  }
+
+  if (config.debug) {
+    logger.debug(
+      `[AuthHandshake] No delegation found, returning needs_authorization (${Date.now() - startTime}ms)`
+    );
+  }
+
+  const authError = await buildNeedsAuthorizationError(
+    agentDid,
+    scopes,
+    config,
+    delegationResult.reason ?? 'No valid delegation found'
+  );
+
+  return {
+    authorized: false,
+    authError,
+    reputation,
+    reason: delegationResult.reason ?? 'No delegation',
+  };
+}
+
+async function fetchAgentReputation(
+  agentDid: string,
+  reputationConfig: { apiUrl: string; apiKey?: string; apiFormat?: 'v1' | 'v2' }
+): Promise<AgentReputation> {
+  const apiUrl = reputationConfig.apiUrl.replace(/\/$/, '');
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (reputationConfig.apiKey) {
+    headers['X-API-Key'] = reputationConfig.apiKey;
+  }
+
+  const isV2Format = reputationConfig.apiFormat === 'v2';
+  let response: Response;
+
+  if (isV2Format) {
+    response = await fetch(
+      `${apiUrl}/v1/reputation/${encodeURIComponent(agentDid)}`,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ include_details: false }),
+      }
+    );
+  } else {
+    response = await fetch(
+      `${apiUrl}/api/v1/reputation/${encodeURIComponent(agentDid)}`,
+      { method: 'GET', headers }
+    );
+  }
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      return {
+        agentDid,
+        score: 50,
+        totalInteractions: 0,
+        successRate: 0,
+        riskLevel: 'unknown',
+        updatedAt: Date.now(),
+      };
+    }
+    throw new Error(`Reputation API error: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as Record<string, unknown>;
+
+  const score = (data['score'] as number | undefined) ?? 50;
+  const levelRaw = (
+    (data['level'] as string | undefined) ??
+    (data['riskLevel'] as string | undefined) ??
+    'unknown'
+  ).toLowerCase();
+  const riskLevel: AgentReputation['riskLevel'] =
+    levelRaw === 'low' || levelRaw === 'medium' || levelRaw === 'high' ? levelRaw : 'unknown';
+
+  return {
+    agentDid:
+      (data['agent_did'] as string | undefined) ??
+      (data['agentDid'] as string | undefined) ??
+      agentDid,
+    score,
+    totalInteractions: (data['totalInteractions'] as number | undefined) ?? 0,
+    successRate: (data['successRate'] as number | undefined) ?? 0,
+    riskLevel,
+    updatedAt: data['calculatedAt']
+      ? new Date(data['calculatedAt'] as string).getTime()
+      : ((data['updatedAt'] as number | undefined) ?? Date.now()),
+  };
+}
+
+async function buildNeedsAuthorizationError(
+  agentDid: string,
+  scopes: string[],
+  config: AuthHandshakeConfig,
+  message: string
+): Promise<NeedsAuthorizationError> {
+  const resumeToken = await config.resumeTokenStore.create(agentDid, scopes, {
+    requestedAt: Date.now(),
+  });
+
+  const expiresAt = Date.now() + (config.authorization.resumeTokenTtl ?? 600_000);
+
+  const authUrl = new URL(config.authorization.authorizationUrl);
+  authUrl.searchParams.set('agent_did', agentDid);
+  authUrl.searchParams.set('scopes', scopes.join(','));
+  authUrl.searchParams.set('resume_token', resumeToken);
+
+  const authCode = resumeToken.substring(0, 8).toUpperCase();
+
+  const display: AuthorizationDisplay = {
+    title: 'Authorization Required',
+    hint: ['link', 'qr'],
+    authorizationCode: authCode,
+    qrUrl: `https://api.qrserver.com/v1/create-qr-code/?data=${encodeURIComponent(authUrl.toString())}`,
+  };
+
+  return createNeedsAuthorizationError({
+    message,
+    authorizationUrl: authUrl.toString(),
+    resumeToken,
+    expiresAt,
+    scopes,
+    display,
+  });
+}
+
+export function hasSensitiveScopes(scopes: string[]): boolean {
+  const sensitivePatterns = [
+    'write',
+    'delete',
+    'admin',
+    'payment',
+    'transfer',
+    'execute',
+    'modify',
+  ];
+
+  return scopes.some((scope) =>
+    sensitivePatterns.some((pattern) => scope.toLowerCase().includes(pattern))
+  );
+}

package/src/auth/index.ts

@@ -0,0 +1,11 @@
+export {
+  verifyOrHints,
+  hasSensitiveScopes,
+  MemoryResumeTokenStore,
+  type AuthHandshakeConfig,
+  type VerifyOrHintsResult,
+  type AgentReputation,
+  type ResumeTokenStore,
+} from './handshake.js';
+
+export type { DelegationVerifier, VerifyDelegationResult } from './types.js';

package/src/auth/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Authorization types for the auth module.
+ *
+ * Minimal interfaces required by the auth handshake.
+ */
+
+import type { DelegationRecord } from '../types/protocol.js';
+
+export interface VerifyDelegationResult {
+  valid: boolean;
+  delegation?: DelegationRecord;
+  credential?: {
+    agent_did: string;
+    user_did: string;
+    scopes: string[];
+    authorization: {
+      type:
+        | 'oauth'
+        | 'oauth2'
+        | 'password'
+        | 'credential'
+        | 'webauthn'
+        | 'siwe'
+        | 'none';
+      provider?: string;
+      credentialType?: string;
+      rpId?: string;
+      userVerification?: 'required' | 'preferred' | 'discouraged';
+      chainId?: number;
+      domain?: string;
+    };
+    [key: string]: unknown;
+  };
+  reason?: string;
+  cached?: boolean;
+}
+
+export interface DelegationVerifier {
+  verify(agentDid: string, scopes: string[]): Promise<VerifyDelegationResult>;
+}

package/src/delegation/__tests__/audience-validator.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Tests for Delegation Audience Validation
+ */
+
+import { describe, it, expect } from "vitest";
+import { verifyDelegationAudience } from "../audience-validator.js";
+import type { DelegationRecord } from "../../types/protocol.js";
+
+describe("verifyDelegationAudience", () => {
+  const serverDid = "did:web:server.example.com";
+
+  it("should return true when delegation has no audience", () => {
+    const delegation: DelegationRecord = {
+      id: "del_001",
+      issuerDid: "did:web:user.com",
+      subjectDid: "did:key:zagent123",
+      controller: "user_alice",
+      vcId: "vc_001",
+      constraints: {
+        scopes: ["tool:execute"],
+        // No audience field
+      },
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 3600000,
+    };
+
+    expect(verifyDelegationAudience(delegation, serverDid)).toBe(true);
+  });
+
+  it("should return true when delegation audience matches server DID", () => {
+    const delegation: DelegationRecord = {
+      id: "del_002",
+      issuerDid: "did:web:user.com",
+      subjectDid: "did:key:zagent123",
+      controller: "user_bob",
+      vcId: "vc_002",
+      constraints: {
+        scopes: ["tool:execute"],
+        audience: serverDid, // Matches server DID
+      },
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 3600000,
+    };
+
+    expect(verifyDelegationAudience(delegation, serverDid)).toBe(true);
+  });
+
+  it("should return false when delegation audience does not match server DID", () => {
+    const delegation: DelegationRecord = {
+      id: "del_003",
+      issuerDid: "did:web:user.com",
+      subjectDid: "did:key:zagent123",
+      controller: "user_charlie",
+      vcId: "vc_003",
+      constraints: {
+        scopes: ["tool:execute"],
+        audience: "did:web:other-server.com", // Different server
+      },
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 3600000,
+    };
+
+    expect(verifyDelegationAudience(delegation, serverDid)).toBe(false);
+  });
+
+  it("should return true when server DID is in audience array", () => {
+    const delegation: DelegationRecord = {
+      id: "del_004",
+      issuerDid: "did:web:user.com",
+      subjectDid: "did:key:zagent123",
+      controller: "user_dave",
+      vcId: "vc_004",
+      constraints: {
+        scopes: ["tool:execute"],
+        audience: [
+          "did:web:server1.com",
+          serverDid, // Server DID is in array
+          "did:web:server3.com",
+        ],
+      },
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 3600000,
+    };
+
+    expect(verifyDelegationAudience(delegation, serverDid)).toBe(true);
+  });
+
+  it("should return false when server DID is not in audience array", () => {
+    const delegation: DelegationRecord = {
+      id: "del_005",
+      issuerDid: "did:web:user.com",
+      subjectDid: "did:key:zagent123",
+      controller: "user_eve",
+      vcId: "vc_005",
+      constraints: {
+        scopes: ["tool:execute"],
+        audience: [
+          "did:web:server1.com",
+          "did:web:server2.com",
+          // serverDid not in array
+        ],
+      },
+      createdAt: Date.now(),
+      expiresAt: Date.now() + 3600000,
+    };
+
+    expect(verifyDelegationAudience(delegation, serverDid)).toBe(false);
+  });
+});
+