@mcp-i/core 0.1.0

package/src/utils/base58.ts

@@ -0,0 +1,115 @@
+/**
+ * Base58 Utilities (Bitcoin alphabet)
+ *
+ * Encoding and decoding utilities for Base58 (Bitcoin alphabet).
+ * Used for did:key multibase encoding (with 'z' prefix for base58btc).
+ *
+ * The Bitcoin alphabet excludes ambiguous characters (0, O, I, l).
+ */
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const ALPHABET_MAP = new Map<string, number>();
+
+// Build reverse lookup map
+for (let i = 0; i < ALPHABET.length; i++) {
+  const char = ALPHABET[i];
+  if (char !== undefined) {
+    ALPHABET_MAP.set(char, i);
+  }
+}
+
+/**
+ * Encode bytes to Base58 (Bitcoin alphabet)
+ *
+ * @param bytes - Bytes to encode
+ * @returns Base58-encoded string
+ */
+export function base58Encode(bytes: Uint8Array): string {
+  if (bytes.length === 0) return '';
+
+  // Convert bytes to big integer
+  let num = BigInt(0);
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    if (byte !== undefined) {
+      num = num * BigInt(256) + BigInt(byte);
+    }
+  }
+
+  // Convert to base58
+  let result = '';
+  while (num > 0) {
+    result = ALPHABET[Number(num % BigInt(58))] + result;
+    num = num / BigInt(58);
+  }
+
+  // Add leading zeros (encoded as '1' in base58)
+  for (let i = 0; i < bytes.length && bytes[i] === 0; i++) {
+    result = '1' + result;
+  }
+
+  return result;
+}
+
+/**
+ * Decode Base58 (Bitcoin alphabet) to bytes
+ *
+ * @param encoded - Base58-encoded string
+ * @returns Decoded bytes
+ * @throws Error if input contains invalid characters
+ */
+export function base58Decode(encoded: string): Uint8Array {
+  if (encoded.length === 0) return new Uint8Array(0);
+
+  // Convert base58 to big integer
+  let num = BigInt(0);
+  for (const char of encoded) {
+    const value = ALPHABET_MAP.get(char);
+    if (value === undefined) {
+      throw new Error(`Invalid base58 character: ${char}`);
+    }
+    num = num * BigInt(58) + BigInt(value);
+  }
+
+  // Convert big integer to bytes
+  const bytes: number[] = [];
+  while (num > 0) {
+    bytes.unshift(Number(num % BigInt(256)));
+    num = num / BigInt(256);
+  }
+
+  // Count leading zeros in input (encoded as '1')
+  let leadingZeros = 0;
+  for (const char of encoded) {
+    if (char === '1') {
+      leadingZeros++;
+    } else {
+      break;
+    }
+  }
+
+  // Prepend leading zero bytes
+  const result = new Uint8Array(leadingZeros + bytes.length);
+  // Leading zeros are already 0 in Uint8Array
+  result.set(bytes, leadingZeros);
+
+  return result;
+}
+
+/**
+ * Validate a Base58 string
+ *
+ * @param encoded - String to validate
+ * @returns true if valid Base58, false otherwise
+ */
+export function isValidBase58(encoded: string): boolean {
+  if (encoded.length === 0) return true;
+
+  for (const char of encoded) {
+    if (!ALPHABET_MAP.has(char)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/utils/base64.ts

@@ -0,0 +1,116 @@
+/**
+ * Base64URL Encoding/Decoding Utilities
+ *
+ * Environment-aware base64url helpers that work in both Node.js and Cloudflare Workers.
+ * Uses Buffer in Node.js, TextEncoder/Decoder fallback for Workers.
+ */
+
+export function base64urlDecodeToString(input: string): string {
+  const padded = addPadding(input);
+  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+
+  if (typeof Buffer !== 'undefined') {
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(base64)) {
+      throw new Error('Invalid base64url string: contains invalid characters');
+    }
+    return Buffer.from(base64, 'base64').toString('utf-8');
+  }
+
+  if (typeof atob !== 'undefined') {
+    const binaryString = atob(base64);
+    if (typeof TextDecoder !== 'undefined') {
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+      return new TextDecoder().decode(bytes);
+    }
+    return binaryString;
+  }
+
+  throw new Error('Neither Buffer nor atob is available');
+}
+
+export function base64urlDecodeToBytes(input: string): Uint8Array {
+  const padded = addPadding(input);
+  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+
+  if (typeof atob !== 'undefined') {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  return new Uint8Array(Buffer.from(base64, 'base64'));
+}
+
+export function base64urlEncodeFromString(input: string): string {
+  if (typeof Buffer !== 'undefined') {
+    const base64 = Buffer.from(input, 'utf-8').toString('base64');
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  if (typeof btoa !== 'undefined') {
+    const utf8Bytes = new TextEncoder().encode(input);
+    const binaryString = Array.from(utf8Bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join('');
+    const base64 = btoa(binaryString);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  throw new Error('Neither Buffer nor btoa is available');
+}
+
+export function base64urlEncodeFromBytes(bytes: Uint8Array): string {
+  if (typeof btoa !== 'undefined') {
+    const binaryString = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join('');
+    const base64 = btoa(binaryString);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  const base64 = Buffer.from(bytes).toString('base64');
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof btoa !== 'undefined') {
+    const binaryString = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join('');
+    return btoa(binaryString);
+  }
+
+  return Buffer.from(bytes).toString('base64');
+}
+
+export function base64ToBytes(base64: string): Uint8Array {
+  let standardBase64 = base64.replace(/-/g, '+').replace(/_/g, '/');
+  const paddingNeeded = (4 - (standardBase64.length % 4)) % 4;
+  standardBase64 += '='.repeat(paddingNeeded);
+
+  if (typeof atob !== 'undefined') {
+    const binaryString = atob(standardBase64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  return new Uint8Array(Buffer.from(standardBase64, 'base64'));
+}
+
+function addPadding(input: string): string {
+  const remainder = input.length % 4;
+  if (remainder === 0) {
+    return input;
+  }
+  return input + '='.repeat((4 - remainder) % 4);
+}

package/src/utils/crypto-service.ts

@@ -0,0 +1,209 @@
+/**
+ * CryptoService
+ *
+ * Centralized cryptographic operations service providing consistent
+ * signature verification across all platforms (Cloudflare, Node.js, etc.).
+ */
+
+import { CryptoProvider } from '../providers/base.js';
+import {
+  base64urlDecodeToString,
+  base64urlDecodeToBytes,
+  base64urlEncodeFromBytes,
+  bytesToBase64,
+} from './base64.js';
+
+/**
+ * Minimal Ed25519 JWK interface
+ */
+export interface Ed25519JWK {
+  kty: 'OKP';
+  crv: 'Ed25519';
+  x: string;
+  kid?: string;
+  use?: string;
+}
+
+export interface ParsedJWS {
+  header: Record<string, unknown>;
+  payload?: Record<string, unknown>;
+  signatureBytes: Uint8Array;
+  signingInput: string;
+}
+
+export class CryptoService {
+  constructor(private cryptoProvider: CryptoProvider) {}
+
+  async verifyEd25519(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: string
+  ): Promise<boolean> {
+    try {
+      const result = await this.cryptoProvider.verify(data, signature, publicKey);
+      return result === true;
+    } catch (error) {
+      console.error('[CryptoService] Ed25519 verification error:', error);
+      return false;
+    }
+  }
+
+  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;
+
+    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)}`
+      );
+    }
+
+    let payload: Record<string, unknown> | undefined;
+    if (payloadB64) {
+      try {
+        payload = JSON.parse(base64urlDecodeToString(payloadB64)) as Record<string, unknown>;
+      } catch (error) {
+        throw new Error(
+          `Invalid payload base64: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+
+    let signatureBytes: Uint8Array;
+    try {
+      signatureBytes = base64urlDecodeToBytes(signatureB64!);
+    } catch (error) {
+      throw new Error(
+        `Invalid signature base64: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    const signingInput = `${headerB64}.${payloadB64}`;
+
+    return { header, payload, signatureBytes, signingInput };
+  }
+
+  async verifyJWS(
+    jws: string,
+    publicKeyJwk: Ed25519JWK,
+    options?: {
+      detachedPayload?: Uint8Array | string;
+      expectedKid?: string;
+      alg?: 'EdDSA';
+    }
+  ): Promise<boolean> {
+    try {
+      if (!this.isValidEd25519JWK(publicKeyJwk)) {
+        console.error('[CryptoService] Invalid Ed25519 JWK format');
+        return false;
+      }
+
+      if (options?.expectedKid && publicKeyJwk.kid !== options.expectedKid) {
+        console.error('[CryptoService] Key ID mismatch');
+        return false;
+      }
+
+      let parsed: ParsedJWS;
+      try {
+        parsed = this.parseJWS(jws);
+      } catch (error) {
+        if (options?.detachedPayload !== undefined) {
+          const parts = jws.split('.');
+          if (parts.length === 3 && parts[1] === '') {
+            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: '' };
+            } 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;
+        }
+      }
+
+      const expectedAlg = options?.alg || 'EdDSA';
+      if (parsed.header['alg'] !== expectedAlg) {
+        console.error(
+          `[CryptoService] Unsupported algorithm: ${parsed.header['alg']}, expected ${expectedAlg}`
+        );
+        return false;
+      }
+
+      let signingInputBytes: Uint8Array;
+
+      if (options?.detachedPayload !== undefined) {
+        const headerB64 = jws.split('.')[0]!;
+        let payloadB64: string;
+
+        if (options.detachedPayload instanceof Uint8Array) {
+          payloadB64 = base64urlEncodeFromBytes(options.detachedPayload);
+        } else {
+          payloadB64 = base64urlEncodeFromBytes(
+            new TextEncoder().encode(options.detachedPayload)
+          );
+        }
+
+        signingInputBytes = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+      } else {
+        if (!parsed.signingInput) {
+          console.error('[CryptoService] Missing signing input for compact JWS');
+          return false;
+        }
+        signingInputBytes = new TextEncoder().encode(parsed.signingInput);
+      }
+
+      let publicKeyBase64: string;
+      try {
+        publicKeyBase64 = this.jwkToBase64PublicKey(publicKeyJwk);
+      } catch (error) {
+        console.error('[CryptoService] Failed to extract public key:', error);
+        return false;
+      }
+
+      return await this.verifyEd25519(signingInputBytes, parsed.signatureBytes, publicKeyBase64);
+    } catch (error) {
+      console.error('[CryptoService] JWS verification error:', error);
+      return false;
+    }
+  }
+
+  private isValidEd25519JWK(jwk: unknown): jwk is Ed25519JWK {
+    return (
+      typeof jwk === 'object' &&
+      jwk !== null &&
+      'kty' in jwk &&
+      (jwk as Record<string, unknown>)['kty'] === 'OKP' &&
+      'crv' in jwk &&
+      (jwk as Record<string, unknown>)['crv'] === 'Ed25519' &&
+      'x' in jwk &&
+      typeof (jwk as Record<string, unknown>)['x'] === 'string' &&
+      ((jwk as Record<string, unknown>)['x'] as string).length > 0
+    );
+  }
+
+  private jwkToBase64PublicKey(jwk: Ed25519JWK): string {
+    const publicKeyBytes = base64urlDecodeToBytes(jwk.x);
+    if (publicKeyBytes.length !== 32) {
+      throw new Error(`Invalid Ed25519 public key length: ${publicKeyBytes.length}`);
+    }
+    return bytesToBase64(publicKeyBytes);
+  }
+}

package/src/utils/did-helpers.ts

@@ -0,0 +1,210 @@
+/**
+ * DID Validation and Helper Utilities
+ *
+ * Centralized utilities for DID validation, normalization, and handling.
+ * Promotes DRY principle and consistency across the codebase.
+ *
+ * @package @mcp-i/core/utils
+ */
+
+import { base58Encode } from "./base58.js";
+
+/**
+ * Check if a string is a valid DID format
+ *
+ * @param did - String to validate
+ * @returns true if string starts with "did:"
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:key:z6Mk...") // true
+ * isValidDid("not-a-did") // false
+ * ```
+ */
+export function isValidDid(did: string): boolean {
+  return typeof did === "string" && did.startsWith("did:");
+}
+
+/**
+ * Get the DID method from a DID string
+ *
+ * @param did - DID string
+ * @returns DID method (e.g., "key", "web") or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getDidMethod("did:key:z6Mk...") // "key"
+ * getDidMethod("did:web:example.com") // "web"
+ * getDidMethod("invalid") // null
+ * ```
+ */
+export function getDidMethod(did: string): string | null {
+  if (!isValidDid(did)) {
+    return null;
+  }
+  const match = did.match(/^did:([^:]+):/);
+  return match?.[1] ?? null;
+}
+
+/**
+ * Normalize a DID string (trim whitespace)
+ *
+ * @param did - DID string to normalize
+ * @returns Normalized DID string
+ *
+ * @example
+ * ```typescript
+ * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
+ * ```
+ */
+export function normalizeDid(did: string): string {
+  return did.trim();
+}
+
+/**
+ * Compare two DIDs for equality (case-sensitive)
+ *
+ * @param did1 - First DID
+ * @param did2 - Second DID
+ * @returns true if DIDs are equal (after normalization)
+ *
+ * @example
+ * ```typescript
+ * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
+ * compareDids("did:key:z6Mk...", "did:web:example.com") // false
+ * ```
+ */
+export function compareDids(did1: string, did2: string): boolean {
+  return normalizeDid(did1) === normalizeDid(did2);
+}
+
+/**
+ * Extract server DID from config (supports both old and new field names)
+ *
+ * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
+ * Prefers `serverDid` if both are present.
+ *
+ * @param config - Config object with identity field
+ * @returns Server DID string
+ * @throws Error if neither serverDid nor agentDid is configured
+ *
+ * @example
+ * ```typescript
+ * // New config
+ * getServerDid({ identity: { serverDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Old config (backward compatibility)
+ * getServerDid({ identity: { agentDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Prefers serverDid over agentDid
+ * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
+ * ```
+ */
+export function getServerDid(config: {
+  identity: { serverDid?: string; agentDid?: string };
+}): string {
+  const serverDid = config.identity.serverDid || config.identity.agentDid;
+  if (!serverDid) {
+    throw new Error("Server DID not configured");
+  }
+  return serverDid;
+}
+
+/**
+ * Extract agent ID from DID
+ *
+ * The agent ID is the last component of the DID.
+ *
+ * @param did - DID string
+ * @returns Agent ID (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentId("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+ * ```
+ */
+export function extractAgentId(did: string): string {
+  const parts = did.split(':');
+  // split() always returns at least one element
+  return parts[parts.length - 1] ?? did;
+}
+
+/**
+ * Extract agent slug from DID
+ *
+ * Agent slug is the same as agent ID - the last component of the DID.
+ * For DID format: did:web:example.com:agents:my-agent
+ * Returns: my-agent
+ *
+ * @param did - DID string
+ * @returns Agent slug (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentSlug("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * ```
+ */
+export function extractAgentSlug(did: string): string {
+  return extractAgentId(did);
+}
+
+/**
+ * Ed25519 multicodec prefix for did:key encoding
+ * As per https://w3c-ccg.github.io/did-method-key/
+ */
+const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
+
+/**
+ * Generate a did:key from Ed25519 public key bytes
+ *
+ * Following spec: https://w3c-ccg.github.io/did-method-key/
+ * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
+ *
+ * @param publicKeyBytes - Ed25519 public key as Uint8Array (32 bytes)
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKey = new Uint8Array(32); // 32-byte Ed25519 public key
+ * const did = generateDidKeyFromBytes(publicKey);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBytes(publicKeyBytes: Uint8Array): string {
+  // Combine multicodec prefix + public key
+  const multicodecKey = new Uint8Array(
+    ED25519_MULTICODEC_PREFIX.length + publicKeyBytes.length
+  );
+  multicodecKey.set(ED25519_MULTICODEC_PREFIX);
+  multicodecKey.set(publicKeyBytes, ED25519_MULTICODEC_PREFIX.length);
+
+  // Base58-btc encode and add multibase prefix 'z'
+  const base58Encoded = base58Encode(multicodecKey);
+  return `did:key:z${base58Encoded}`;
+}
+
+/**
+ * Generate a did:key from base64-encoded Ed25519 public key
+ *
+ * Convenience wrapper around generateDidKeyFromBytes for base64-encoded keys.
+ *
+ * @param publicKeyBase64 - Ed25519 public key as base64 string
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKeyBase64 = "...base64 encoded key...";
+ * const did = generateDidKeyFromBase64(publicKeyBase64);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBase64(publicKeyBase64: string): string {
+  // Decode base64 to bytes
+  const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) =>
+    c.charCodeAt(0)
+  );
+  return generateDidKeyFromBytes(publicKeyBytes);
+}

package/src/utils/ed25519-constants.ts

@@ -0,0 +1,23 @@
+/**
+ * Ed25519 Key Format Constants
+ *
+ * DER-encoded headers for Ed25519 key formats per RFC 8410 and RFC 5958.
+ */
+
+/**
+ * DER-encoded PKCS#8 header for Ed25519 private keys (RFC 8410 §7, RFC 5958).
+ * Prepended to the 32-byte Ed25519 seed to form a valid PKCS#8 private key.
+ */
+export const ED25519_PKCS8_DER_HEADER = new Uint8Array([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05,
+  0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+
+/**
+ * DER-encoded SPKI header for Ed25519 public keys (RFC 8410 §4).
+ * The 32-byte public key follows after this header.
+ */
+export const ED25519_SPKI_DER_HEADER_LENGTH = 12;
+
+/** Ed25519 raw key size in bytes */
+export const ED25519_KEY_SIZE = 32;

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility exports
+ */
+
+export {
+  ED25519_PKCS8_DER_HEADER,
+  ED25519_SPKI_DER_HEADER_LENGTH,
+  ED25519_KEY_SIZE,
+} from './ed25519-constants.js';