@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0

package/src/services/authorization/authorization-registry.ts

@@ -0,0 +1,66 @@
+/**
+ * Authorization Registry
+ *
+ * Registry for managing available authorization services.
+ * Allows looking up the appropriate service for a given authorization type.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { AuthorizationService } from "./types.js";
+import type { ToolProtection, AuthorizationRequirement } from "@kya-os/contracts/tool-protection";
+
+export class AuthorizationRegistry {
+  private services: Map<string, AuthorizationService> = new Map();
+
+  /**
+   * Register an authorization service
+   */
+  register(service: AuthorizationService): void {
+    this.services.set(service.type, service);
+  }
+
+  /**
+   * Get an authorization service by type
+   */
+  getService(type: string): AuthorizationService | null {
+    return this.services.get(type) || null;
+  }
+
+  /**
+   * Resolve authorization requirement for a tool
+   * 
+   * Determines the authorization requirement based on the tool protection config.
+   * Handles backward compatibility with legacy `oauthProvider` field.
+   */
+  resolveRequirement(
+    toolProtection: ToolProtection
+  ): AuthorizationRequirement | null {
+    if (!toolProtection.requiresDelegation) {
+      return null;
+    }
+
+    // Use the explicit authorization field if present
+    if (toolProtection.authorization) {
+      return toolProtection.authorization;
+    }
+
+    // Legacy fallback: oauthProvider field
+    if (toolProtection.oauthProvider) {
+      return {
+        type: 'oauth',
+        provider: toolProtection.oauthProvider,
+      };
+    }
+
+    // If requiresDelegation is true but no auth specified, default to 'none' (consent only)
+    // UNLESS we are in a transition period where ProviderResolver might infer scopes.
+    // This logic will be refined as we move logic from ProviderResolver to here.
+    // For now, return null to let downstream logic handle fallbacks if needed,
+    // or return 'none' if we want to enforce explicit config.
+    
+    // Returning null allows the legacy ProviderResolver to attempt scope inference
+    return null;
+  }
+}
+

package/src/services/authorization/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Authorization Service Types
+ *
+ * Shared types for authorization services and flows.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { ToolProtection } from "@kya-os/contracts/tool-protection";
+
+/**
+ * Authorization Flow Result
+ */
+export interface AuthorizationResult {
+  success: boolean;
+  credential?: unknown; // VC or token
+  userDid?: string;
+  metadata?: Record<string, unknown>;
+  error?: Error;
+}
+
+/**
+ * Authorization Flow
+ * Represents an initiated authorization flow
+ */
+export interface AuthorizationFlow {
+  /** URL to redirect the user to */
+  url: string;
+  
+  /** Unique identifier for this flow */
+  flowId?: string;
+  
+  /** Metadata about the flow */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Authorization Service Interface
+ * Each authorization type implements this
+ */
+export interface AuthorizationService {
+  /** Unique type identifier (e.g., 'oauth', 'mdl', 'idv') */
+  type: string;
+  
+  /**
+   * Check if authorization is required for the given tool protection
+   */
+  isRequired(toolProtection: ToolProtection): boolean;
+  
+  /**
+   * Initiate authorization flow
+   * Returns URL or flow identifier
+   */
+  initiateFlow(
+    toolProtection: ToolProtection,
+    sessionId: string,
+    projectId: string,
+    agentDid: string,
+    serverUrl: string
+  ): Promise<AuthorizationFlow>;
+  
+  /**
+   * Verify authorization result
+   * Called after user completes flow
+   */
+  verifyAuthorization(
+    flowId: string,
+    result: unknown
+  ): Promise<AuthorizationResult>;
+}
+

package/src/services/batch-delegation.service.ts

@@ -0,0 +1,137 @@
+/**
+ * Batch Delegation Service
+ *
+ * Groups tools by OAuth provider for batch delegation flows.
+ * Enables single OAuth flow for multiple tools requiring the same provider.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type { ToolProtection } from "@kya-os/contracts/tool-protection";
+import type { ProviderResolver } from "./provider-resolver.js";
+import type { ToolProtectionService } from "./tool-protection.service.js";
+
+/**
+ * Tool group by provider
+ */
+export interface ToolGroup {
+  /** OAuth provider name */
+  provider: string;
+
+  /** Tool names in this group */
+  tools: string[];
+
+  /** Merged scopes from all tools in group */
+  scopes: string[];
+
+  /** Highest risk level in group */
+  riskLevel: "low" | "medium" | "high";
+}
+
+/**
+ * Service for grouping tools by OAuth provider
+ */
+export class BatchDelegationService {
+  constructor(
+    private providerResolver: ProviderResolver,
+    private toolProtectionService: ToolProtectionService
+  ) {}
+
+  /**
+   * Group tools by OAuth provider
+   *
+   * Returns a map of provider → tools that require that provider.
+   * Tools that don't require delegation are skipped.
+   *
+   * @param toolNames - Array of tool names to group
+   * @param projectId - Project ID for provider resolution
+   * @param agentDid - Agent DID for fetching tool protections
+   * @returns Map of provider name to ToolGroup
+   */
+  async groupToolsByProvider(
+    toolNames: string[],
+    projectId: string,
+    agentDid: string
+  ): Promise<Map<string, ToolGroup>> {
+    const groups = new Map<string, ToolGroup>();
+
+    for (const toolName of toolNames) {
+      const protection = await this.toolProtectionService.checkToolProtection(
+        toolName,
+        agentDid
+      );
+
+      if (!protection?.requiresDelegation) {
+        continue; // Skip tools that don't require delegation
+      }
+
+      // Resolve provider for this tool
+      let provider: string;
+      try {
+        provider = await this.providerResolver.resolveProvider(
+          protection,
+          projectId
+        );
+      } catch (error) {
+        console.warn(
+          `[BatchDelegation] Could not resolve provider for tool "${toolName}", skipping`,
+          error instanceof Error ? error.message : String(error)
+        );
+        continue;
+      }
+
+      // Get or create group for this provider
+      if (!groups.has(provider)) {
+        groups.set(provider, {
+          provider,
+          tools: [],
+          scopes: [],
+          riskLevel: "medium", // Default
+        });
+      }
+
+      const group = groups.get(provider)!;
+      group.tools.push(toolName);
+
+      // Merge scopes (deduplicate)
+      const allScopes = new Set([
+        ...group.scopes,
+        ...(protection.requiredScopes || []),
+      ]);
+      group.scopes = Array.from(allScopes);
+
+      // Use highest risk level
+      if (protection.riskLevel) {
+        const riskOrder: Record<string, number> = { low: 1, medium: 2, high: 3, critical: 4 };
+        const currentRisk = riskOrder[group.riskLevel] || 1;
+        const toolRisk = riskOrder[protection.riskLevel] || 1;
+        if (toolRisk > currentRisk) {
+          // Map critical to high for ToolGroup interface
+          group.riskLevel = protection.riskLevel === "critical" ? "high" : protection.riskLevel;
+        }
+      }
+    }
+
+    return groups;
+  }
+
+  /**
+   * Get all tools that require a specific provider
+   *
+   * @param provider - Provider name to filter by
+   * @param projectId - Project ID for provider resolution
+   * @param agentDid - Agent DID for fetching tool protections
+   * @returns Array of tool names requiring the specified provider
+   */
+  async getToolsForProvider(
+    provider: string,
+    projectId: string,
+    agentDid: string
+  ): Promise<string[]> {
+    // This would require fetching all tool protections
+    // For now, return empty array (can be enhanced later)
+    // TODO: Implement if needed for Phase 4 batch delegation UI
+    return [];
+  }
+}
+

package/src/services/crypto.service.ts

@@ -0,0 +1,302 @@
+/**
+ * CryptoService
+ *
+ * Centralized cryptographic operations service that provides consistent
+ * signature verification across all platforms (Cloudflare, Node.js, etc.).
+ *
+ * This service eliminates code duplication and ensures cryptographic operations
+ * behave identically everywhere.
+ */
+
+import { CryptoProvider } from "../providers/base.js";
+import {
+  base64urlDecodeToString,
+  base64urlDecodeToBytes,
+  base64urlEncodeFromBytes,
+  bytesToBase64,
+  base64ToBytes,
+} from "../utils/base64.js";
+
+/**
+ * Minimal JWK interface to avoid external dependencies
+ */
+export interface Ed25519JWK {
+  kty: "OKP";
+  crv: "Ed25519";
+  x: string; // Base64url encoded public key
+  kid?: string;
+  use?: string;
+}
+
+/**
+ * JWS parsing result
+ */
+export interface ParsedJWS {
+  header: Record<string, unknown>;
+  payload?: Record<string, unknown>;
+  signatureBytes: Uint8Array;
+  signingInput: string;
+}
+
+export class CryptoService {
+  constructor(private cryptoProvider: CryptoProvider) {}
+
+  /**
+   * Verify raw Ed25519 signature
+   * @param data - Data that was signed
+   * @param signature - Signature bytes
+   * @param publicKey - Base64 encoded Ed25519 public key (32 bytes)
+   */
+  async verifyEd25519(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: string
+  ): Promise<boolean> {
+    try {
+      const result = await this.cryptoProvider.verify(
+        data,
+        signature,
+        publicKey
+      );
+      // Ensure we always return a boolean (handle undefined from unmocked providers)
+      return result === true;
+    } catch (error) {
+      // Log error for debugging but return false for invalid signatures
+      console.error("[CryptoService] Ed25519 verification error:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Parse JWS into components
+   * @param jws - Full compact JWS string (header.payload.signature)
+   * @returns Parsed JWS components
+   */
+  parseJWS(jws: string): ParsedJWS {
+    const parts = jws.split(".");
+    if (parts.length !== 3) {
+      throw new Error("Invalid JWS format: expected header.payload.signature");
+    }
+
+    const [headerB64, payloadB64, signatureB64] = parts;
+
+    // Decode header
+    let header: Record<string, unknown>;
+    try {
+      header = JSON.parse(base64urlDecodeToString(headerB64)) as Record<
+        string,
+        unknown
+      >;
+    } catch (error) {
+      throw new Error(
+        `Invalid header base64: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    // Decode payload (optional, may be detached)
+    let payload: Record<string, unknown> | undefined;
+    if (payloadB64) {
+      try {
+        payload = JSON.parse(base64urlDecodeToString(payloadB64)) as Record<
+          string,
+          unknown
+        >;
+      } catch (error) {
+        // Payload decoding failed - this is an error for non-detached JWS
+        // Re-throw to let caller handle it (they can check if it's detached format)
+        throw new Error(
+          `Invalid payload base64: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+
+    // Decode signature bytes
+    let signatureBytes: Uint8Array;
+    try {
+      signatureBytes = base64urlDecodeToBytes(signatureB64);
+    } catch (error) {
+      // Invalid signature base64 - this is a fatal error
+      throw new Error(
+        `Invalid signature base64: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    // Create signing input (header.payload)
+    const signingInput = `${headerB64}.${payloadB64}`;
+
+    return {
+      header,
+      payload,
+      signatureBytes,
+      signingInput,
+    };
+  }
+
+  /**
+   * Verify JWS signature (full compact format: header.payload.signature)
+   * @param jws - Full compact JWS string (or detached format: header..signature)
+   * @param publicKeyJwk - Ed25519 public key in JWK format
+   * @param options - Verification options
+   * @param options.detachedPayload - Optional detached payload (Uint8Array or string) for detached JWS format
+   * @param options.expectedKid - Optional expected key ID to validate
+   * @param options.alg - Optional expected algorithm (defaults to 'EdDSA')
+   */
+  async verifyJWS(
+    jws: string,
+    publicKeyJwk: Ed25519JWK,
+    options?: {
+      detachedPayload?: Uint8Array | string;
+      expectedKid?: string;
+      alg?: "EdDSA";
+    }
+  ): Promise<boolean> {
+    try {
+      // Validate JWK format
+      if (!this.isValidEd25519JWK(publicKeyJwk)) {
+        console.error("[CryptoService] Invalid Ed25519 JWK format");
+        return false;
+      }
+
+      // Validate expected kid if provided
+      if (options?.expectedKid && publicKeyJwk.kid !== options.expectedKid) {
+        console.error("[CryptoService] Key ID mismatch");
+        return false;
+      }
+
+      // Parse JWS components - handle malformed JWS gracefully
+      let parsed: ParsedJWS;
+      try {
+        parsed = this.parseJWS(jws);
+      } catch (error) {
+        // Malformed JWS - check if it's detached format with provided payload
+        if (options?.detachedPayload !== undefined) {
+          const parts = jws.split(".");
+          if (parts.length === 3 && parts[1] === "") {
+            // Detached format: header..signature
+            try {
+              const headerB64 = parts[0];
+              const signatureB64 = parts[2];
+              const header = JSON.parse(
+                base64urlDecodeToString(headerB64)
+              ) as Record<string, unknown>;
+              const signatureBytes = base64urlDecodeToBytes(signatureB64);
+
+              parsed = {
+                header,
+                payload: undefined,
+                signatureBytes,
+                signingInput: "", // Will be reconstructed below
+              };
+            } catch {
+              console.error("[CryptoService] Invalid detached JWS format");
+              return false;
+            }
+          } else {
+            console.error("[CryptoService] Invalid JWS format:", error);
+            return false;
+          }
+        } else {
+          console.error("[CryptoService] Invalid JWS format:", error);
+          return false;
+        }
+      }
+
+      // Validate algorithm
+      const expectedAlg = options?.alg || "EdDSA";
+      if (parsed.header.alg !== expectedAlg) {
+        console.error(
+          `[CryptoService] Unsupported algorithm: ${parsed.header.alg}, expected ${expectedAlg}`
+        );
+        return false;
+      }
+
+      // Handle detached payload if provided
+      let signingInput: string;
+      let signingInputBytes: Uint8Array;
+
+      if (options?.detachedPayload !== undefined) {
+        // Detached format: reconstruct signing input from header + detached payload
+        const headerB64 = jws.split(".")[0];
+        let payloadB64: string;
+
+        if (options.detachedPayload instanceof Uint8Array) {
+          // Uint8Array payload
+          payloadB64 = base64urlEncodeFromBytes(options.detachedPayload);
+        } else {
+          // String payload (backward compatibility)
+          payloadB64 = base64urlEncodeFromBytes(
+            new TextEncoder().encode(options.detachedPayload)
+          );
+        }
+
+        signingInput = `${headerB64}.${payloadB64}`;
+        signingInputBytes = new TextEncoder().encode(signingInput);
+      } else {
+        // Full compact format: use parsed signing input
+        if (!parsed.signingInput) {
+          console.error(
+            "[CryptoService] Missing signing input for compact JWS"
+          );
+          return false;
+        }
+        signingInput = parsed.signingInput;
+        signingInputBytes = new TextEncoder().encode(signingInput);
+      }
+
+      // Extract raw public key from JWK
+      let publicKeyBase64: string;
+      try {
+        publicKeyBase64 = this.jwkToBase64PublicKey(publicKeyJwk);
+      } catch (error) {
+        console.error("[CryptoService] Failed to extract public key:", error);
+        return false;
+      }
+
+      // Verify signature
+      return await this.verifyEd25519(
+        signingInputBytes,
+        parsed.signatureBytes,
+        publicKeyBase64
+      );
+    } catch (error) {
+      // Security-safe failure: never throw, always return false
+      console.error("[CryptoService] JWS verification error:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Validate Ed25519 JWK format
+   */
+  private isValidEd25519JWK(jwk: unknown): jwk is Ed25519JWK {
+    return (
+      typeof jwk === "object" &&
+      jwk !== null &&
+      "kty" in jwk &&
+      jwk.kty === "OKP" &&
+      "crv" in jwk &&
+      jwk.crv === "Ed25519" &&
+      "x" in jwk &&
+      typeof jwk.x === "string" &&
+      jwk.x.length > 0
+    );
+  }
+
+  /**
+   * Convert Ed25519 JWK to base64 encoded public key
+   */
+  private jwkToBase64PublicKey(jwk: Ed25519JWK): string {
+    // The 'x' field contains the base64url encoded public key
+    // Convert from base64url to standard base64
+    const publicKeyBytes = base64urlDecodeToBytes(jwk.x);
+
+    // Verify key length (Ed25519 public keys are 32 bytes)
+    if (publicKeyBytes.length !== 32) {
+      throw new Error(
+        `Invalid Ed25519 public key length: ${publicKeyBytes.length}`
+      );
+    }
+
+    return bytesToBase64(publicKeyBytes);
+  }
+}

package/src/services/errors.ts

@@ -0,0 +1,76 @@
+/**
+ * Proof Verification Error Codes and Types
+ *
+ * Specific error codes for proof verification failures to enable
+ * better error handling and debugging.
+ */
+
+/**
+ * Error codes for proof verification
+ */
+export const PROOF_VERIFICATION_ERROR_CODES = {
+  // Proof structure errors
+  INVALID_PROOF_STRUCTURE: "INVALID_PROOF_STRUCTURE",
+  MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD",
+  
+  // Security errors
+  NONCE_REPLAY_DETECTED: "NONCE_REPLAY_DETECTED",
+  TIMESTAMP_SKEW_EXCEEDED: "TIMESTAMP_SKEW_EXCEEDED",
+  TIMESTAMP_INVALID: "TIMESTAMP_INVALID",
+  
+  // Signature errors
+  INVALID_JWS_SIGNATURE: "INVALID_JWS_SIGNATURE",
+  INVALID_JWS_FORMAT: "INVALID_JWS_FORMAT",
+  INVALID_JWS_HEADER: "INVALID_JWS_HEADER",
+  INVALID_JWS_PAYLOAD: "INVALID_JWS_PAYLOAD",
+  INVALID_JWS_SIGNATURE_BASE64: "INVALID_JWS_SIGNATURE_BASE64",
+  UNSUPPORTED_ALGORITHM: "UNSUPPORTED_ALGORITHM",
+  
+  // JWK errors
+  INVALID_JWK_FORMAT: "INVALID_JWK_FORMAT",
+  INVALID_JWK_KTY: "INVALID_JWK_KTY",
+  INVALID_JWK_CRV: "INVALID_JWK_CRV",
+  INVALID_JWK_X_FIELD: "INVALID_JWK_X_FIELD",
+  INVALID_JWK_KEY_LENGTH: "INVALID_JWK_KEY_LENGTH",
+  JWK_KID_MISMATCH: "JWK_KID_MISMATCH",
+  
+  // DID resolution errors
+  DID_RESOLUTION_FAILED: "DID_RESOLUTION_FAILED",
+  DID_DOCUMENT_NOT_FOUND: "DID_DOCUMENT_NOT_FOUND",
+  VERIFICATION_METHOD_NOT_FOUND: "VERIFICATION_METHOD_NOT_FOUND",
+  PUBLIC_KEY_NOT_FOUND: "PUBLIC_KEY_NOT_FOUND",
+  UNSUPPORTED_DID_METHOD: "UNSUPPORTED_DID_METHOD",
+  
+  // Generic errors
+  VERIFICATION_ERROR: "VERIFICATION_ERROR",
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+} as const;
+
+export type ProofVerificationErrorCode =
+  typeof PROOF_VERIFICATION_ERROR_CODES[keyof typeof PROOF_VERIFICATION_ERROR_CODES];
+
+/**
+ * Proof verification error with specific error code
+ */
+export class ProofVerificationError extends Error {
+  constructor(
+    public readonly code: ProofVerificationErrorCode,
+    message: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "ProofVerificationError";
+  }
+}
+
+/**
+ * Create a proof verification error
+ */
+export function createProofVerificationError(
+  code: ProofVerificationErrorCode,
+  message: string,
+  details?: Record<string, unknown>
+): ProofVerificationError {
+  return new ProofVerificationError(code, message, details);
+}
+

package/src/services/index.ts

@@ -0,0 +1,9 @@
+export { CryptoService } from './crypto.service.js';
+export type { Ed25519JWK, ParsedJWS } from './crypto.service.js';
+
+export { AccessControlApiService } from './access-control.service.js';
+export type {
+  AccessControlApiServiceConfig,
+  AccessControlApiServiceMetrics,
+} from './access-control.service.js';
+