@kya-os/mcp-i-core 1.3.10-canary.clientinfo.20251126124133 → 1.3.10

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

@@ -0,0 +1,265 @@
+import { describe, it, expect } from "vitest";
+import {
+  createDidKeyResolver,
+  isEd25519DidKey,
+  extractPublicKeyFromDidKey,
+  publicKeyToJwk,
+  resolveDidKeySync,
+} from "../did-key-resolver";
+import { base58Encode, base58Decode, isValidBase58 } from "../../utils/base58";
+
+/**
+ * Tests for did:key resolver and base58 utilities
+ *
+ * These tests verify the Phase 3 VC verification infrastructure:
+ * - Base58 encoding/decoding for multibase keys
+ * - did:key resolution to DID Documents
+ * - Ed25519 public key extraction
+ */
+
+describe("Base58 Utilities", () => {
+  describe("base58Encode", () => {
+    it("should encode empty bytes", () => {
+      expect(base58Encode(new Uint8Array([]))).toBe("");
+    });
+
+    it("should encode single byte", () => {
+      expect(base58Encode(new Uint8Array([0]))).toBe("1");
+      expect(base58Encode(new Uint8Array([1])).length).toBeGreaterThan(0);
+    });
+
+    it("should encode known values", () => {
+      // 'Hello' in bytes
+      const helloBytes = new TextEncoder().encode("Hello");
+      const encoded = base58Encode(helloBytes);
+      expect(encoded.length).toBeGreaterThan(0);
+      expect(isValidBase58(encoded)).toBe(true);
+    });
+
+    it("should handle leading zeros", () => {
+      const withLeadingZeros = new Uint8Array([0, 0, 1, 2, 3]);
+      const encoded = base58Encode(withLeadingZeros);
+      // Leading zeros become '1' in base58
+      expect(encoded.startsWith("11")).toBe(true);
+    });
+  });
+
+  describe("base58Decode", () => {
+    it("should decode empty string", () => {
+      expect(base58Decode("")).toEqual(new Uint8Array([]));
+    });
+
+    it("should decode leading '1' as zero bytes", () => {
+      const result = base58Decode("111");
+      expect(result).toEqual(new Uint8Array([0, 0, 0]));
+    });
+
+    it("should throw on invalid characters", () => {
+      // '0', 'O', 'I', 'l' are not in base58 alphabet
+      expect(() => base58Decode("0invalid")).toThrow("Invalid base58 character");
+      expect(() => base58Decode("testO")).toThrow("Invalid base58 character");
+      expect(() => base58Decode("testI")).toThrow("Invalid base58 character");
+      expect(() => base58Decode("testl")).toThrow("Invalid base58 character");
+    });
+
+    it("should roundtrip with base58Encode", () => {
+      const originalBytes = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+      const encoded = base58Encode(originalBytes);
+      const decoded = base58Decode(encoded);
+      expect(decoded).toEqual(originalBytes);
+    });
+
+    it("should roundtrip Ed25519 key bytes", () => {
+      // Simulate a 32-byte Ed25519 public key with multicodec prefix
+      const ed25519Prefix = new Uint8Array([0xed, 0x01]);
+      const mockPublicKey = new Uint8Array(32).fill(42);
+      const fullBytes = new Uint8Array([...ed25519Prefix, ...mockPublicKey]);
+
+      const encoded = base58Encode(fullBytes);
+      const decoded = base58Decode(encoded);
+      expect(decoded).toEqual(fullBytes);
+    });
+  });
+
+  describe("isValidBase58", () => {
+    it("should return true for empty string", () => {
+      expect(isValidBase58("")).toBe(true);
+    });
+
+    it("should return true for valid base58 strings", () => {
+      expect(isValidBase58("123456789")).toBe(true);
+      expect(isValidBase58("ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")).toBe(true);
+    });
+
+    it("should return false for invalid characters", () => {
+      expect(isValidBase58("0")).toBe(false);
+      expect(isValidBase58("O")).toBe(false);
+      expect(isValidBase58("I")).toBe(false);
+      expect(isValidBase58("l")).toBe(false);
+    });
+  });
+});
+
+describe("did:key Resolver", () => {
+  // Known test vector for Ed25519 did:key
+  // This creates a deterministic did:key from known public key bytes
+  const createTestDidKey = (publicKeyBytes: Uint8Array): string => {
+    const prefix = new Uint8Array([0xed, 0x01]); // Ed25519 multicodec
+    const fullBytes = new Uint8Array([...prefix, ...publicKeyBytes]);
+    return `did:key:z${base58Encode(fullBytes)}`;
+  };
+
+  describe("isEd25519DidKey", () => {
+    it("should return true for Ed25519 did:key", () => {
+      // Ed25519 keys start with z6Mk
+      expect(isEd25519DidKey("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK")).toBe(true);
+    });
+
+    it("should return false for non-did:key", () => {
+      expect(isEd25519DidKey("did:web:example.com")).toBe(false);
+      expect(isEd25519DidKey("did:example:123")).toBe(false);
+    });
+
+    it("should return false for non-Ed25519 did:key", () => {
+      // Secp256k1 keys start with z6Ls or other prefixes
+      expect(isEd25519DidKey("did:key:z7r8os")).toBe(false);
+      expect(isEd25519DidKey("did:key:zQ3s")).toBe(false);
+    });
+
+    it("should return false for invalid did:key format", () => {
+      expect(isEd25519DidKey("did:key:")).toBe(false);
+      expect(isEd25519DidKey("did:key:invalid")).toBe(false);
+    });
+  });
+
+  describe("extractPublicKeyFromDidKey", () => {
+    it("should extract public key bytes from valid did:key", () => {
+      const mockPublicKey = new Uint8Array(32).map((_, i) => i);
+      const didKey = createTestDidKey(mockPublicKey);
+
+      const extractedKey = extractPublicKeyFromDidKey(didKey);
+      expect(extractedKey).not.toBeNull();
+      expect(extractedKey).toEqual(mockPublicKey);
+    });
+
+    it("should return null for non-did:key", () => {
+      expect(extractPublicKeyFromDidKey("did:web:example.com")).toBeNull();
+    });
+
+    it("should return null for invalid multicodec prefix", () => {
+      // Create a did:key with wrong prefix (not Ed25519)
+      const wrongPrefix = new Uint8Array([0x00, 0x00]); // Not Ed25519
+      const mockPublicKey = new Uint8Array(32).fill(1);
+      const fullBytes = new Uint8Array([...wrongPrefix, ...mockPublicKey]);
+      const invalidDid = `did:key:z${base58Encode(fullBytes)}`;
+
+      expect(extractPublicKeyFromDidKey(invalidDid)).toBeNull();
+    });
+
+    it("should return null for too short key", () => {
+      const shortBytes = new Uint8Array([0xed, 0x01, 1, 2, 3]); // Only 3 bytes of key
+      const shortDid = `did:key:z${base58Encode(shortBytes)}`;
+
+      expect(extractPublicKeyFromDidKey(shortDid)).toBeNull();
+    });
+  });
+
+  describe("publicKeyToJwk", () => {
+    it("should convert public key bytes to JWK format", () => {
+      const publicKeyBytes = new Uint8Array(32).map((_, i) => i);
+      const jwk = publicKeyToJwk(publicKeyBytes);
+
+      expect(jwk.kty).toBe("OKP");
+      expect(jwk.crv).toBe("Ed25519");
+      expect(jwk.x).toBeDefined();
+      expect(typeof jwk.x).toBe("string");
+    });
+
+    it("should produce base64url-encoded x value", () => {
+      const publicKeyBytes = new Uint8Array(32).fill(0);
+      const jwk = publicKeyToJwk(publicKeyBytes);
+
+      // Base64url should not contain +, /, or =
+      expect(jwk.x).not.toMatch(/[+/=]/);
+    });
+  });
+
+  describe("createDidKeyResolver", () => {
+    it("should resolve Ed25519 did:key to DID Document", async () => {
+      const mockPublicKey = new Uint8Array(32).map((_, i) => i);
+      const didKey = createTestDidKey(mockPublicKey);
+
+      const resolver = createDidKeyResolver();
+      const didDoc = await resolver.resolve(didKey);
+
+      expect(didDoc).not.toBeNull();
+      expect(didDoc?.id).toBe(didKey);
+      expect(didDoc?.verificationMethod).toHaveLength(1);
+      expect(didDoc?.verificationMethod?.[0].type).toBe("Ed25519VerificationKey2020");
+      expect(didDoc?.verificationMethod?.[0].controller).toBe(didKey);
+      expect(didDoc?.verificationMethod?.[0].publicKeyJwk).toBeDefined();
+      expect(didDoc?.authentication).toContain(`${didKey}#keys-1`);
+      expect(didDoc?.assertionMethod).toContain(`${didKey}#keys-1`);
+    });
+
+    it("should return null for non-Ed25519 did:key", async () => {
+      const resolver = createDidKeyResolver();
+      const result = await resolver.resolve("did:key:z7r8os");
+
+      expect(result).toBeNull();
+    });
+
+    it("should return null for non-did:key DIDs", async () => {
+      const resolver = createDidKeyResolver();
+      const result = await resolver.resolve("did:web:example.com");
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("resolveDidKeySync", () => {
+    it("should synchronously resolve Ed25519 did:key", () => {
+      const mockPublicKey = new Uint8Array(32).map((_, i) => i);
+      const didKey = createTestDidKey(mockPublicKey);
+
+      const didDoc = resolveDidKeySync(didKey);
+
+      expect(didDoc).not.toBeNull();
+      expect(didDoc?.id).toBe(didKey);
+      expect(didDoc?.verificationMethod).toHaveLength(1);
+    });
+
+    it("should return null for invalid DIDs", () => {
+      expect(resolveDidKeySync("did:web:example.com")).toBeNull();
+      expect(resolveDidKeySync("did:key:invalid")).toBeNull();
+    });
+  });
+});
+
+describe("VC-JWT Roundtrip Integration", () => {
+  it("should correctly resolve did:key generated by UserDidManager pattern", async () => {
+    // This test simulates the pattern used in UserDidManager.generateKeyPair()
+    // which creates did:key DIDs for users
+
+    // Simulate generating a random Ed25519 key (32 bytes)
+    const mockPublicKey = crypto.getRandomValues(new Uint8Array(32));
+
+    // Encode as did:key (same pattern as UserDidManager)
+    const multicodecPrefix = new Uint8Array([0xed, 0x01]);
+    const multicodecBytes = new Uint8Array([...multicodecPrefix, ...mockPublicKey]);
+    const multibaseEncoded = base58Encode(multicodecBytes);
+    const didKey = `did:key:z${multibaseEncoded}`;
+
+    // Verify we can resolve this did:key back to get the public key
+    const resolver = createDidKeyResolver();
+    const didDoc = await resolver.resolve(didKey);
+
+    expect(didDoc).not.toBeNull();
+    expect(didDoc?.id).toBe(didKey);
+    expect(didDoc?.verificationMethod?.[0]?.publicKeyJwk).toBeDefined();
+
+    // Extract public key and verify it matches
+    const extractedKey = extractPublicKeyFromDidKey(didKey);
+    expect(extractedKey).toEqual(mockPublicKey);
+  });
+});

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

@@ -0,0 +1,179 @@
+/**
+ * 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';
+import { base64urlEncodeFromBytes } from '../utils/base64';
+import type { DIDResolver, DIDDocument, VerificationMethod } from './vc-verifier';
+
+/** 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 {
+    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/utils.ts

@@ -5,6 +5,8 @@
  * Following DRY (Don't Repeat Yourself) principle.
  */
 
+import { base64urlEncodeFromString } from '../utils/base64';
+
 /**
  * JSON canonicalization (RFC 8785)
  *
@@ -40,3 +42,180 @@ export function canonicalizeJSON(obj: any): string {
   }
   throw new Error(`Cannot canonicalize type: ${typeof obj}`);
 }
+
+/**
+ * JWT Header for EdDSA (Ed25519) signed credentials
+ */
+export interface VCJWTHeader {
+  alg: 'EdDSA';
+  typ: 'JWT';
+  kid?: string;
+}
+
+/**
+ * VC-JWT Payload structure
+ *
+ * Per W3C VC-JWT spec, the VC is embedded in the JWT claims.
+ * Standard claims (iss, sub, exp, iat, jti) are derived from the VC.
+ */
+export interface VCJWTPayload {
+  /** Issuer DID (from vc.issuer) */
+  iss: string;
+  /** Subject DID (from vc.credentialSubject.id) */
+  sub?: string;
+  /** Expiration time (from vc.expirationDate) */
+  exp?: number;
+  /** Issued at time (from vc.issuanceDate) */
+  iat?: number;
+  /** JWT ID (from vc.id) */
+  jti?: string;
+  /** The complete VC (without proof) */
+  vc: Record<string, unknown>;
+}
+
+/**
+ * Options for encoding a VC as JWT
+ */
+export interface EncodeVCAsJWTOptions {
+  /** Key ID for the JWT header */
+  keyId?: string;
+}
+
+/**
+ * Create unsigned JWT parts (header + payload) for a VC
+ *
+ * Prepares the VC for signing by extracting standard claims and
+ * encoding the header and payload as base64url strings.
+ *
+ * @param vc - The Verifiable Credential (without proof)
+ * @param options - Encoding options
+ * @returns Object with encoded parts and signing input
+ */
+export function createUnsignedVCJWT(
+  vc: Record<string, unknown>,
+  options: EncodeVCAsJWTOptions = {}
+): {
+  header: VCJWTHeader;
+  payload: VCJWTPayload;
+  encodedHeader: string;
+  encodedPayload: string;
+  signingInput: string;
+} {
+  // Create JWT header
+  const header: VCJWTHeader = {
+    alg: 'EdDSA',
+    typ: 'JWT',
+  };
+  if (options.keyId) {
+    header.kid = options.keyId;
+  }
+
+  // Extract standard claims from VC
+  const issuer = typeof vc.issuer === 'string' ? vc.issuer : (vc.issuer as Record<string, unknown>)?.id as string;
+  const subject = (vc.credentialSubject as Record<string, unknown>)?.id as string | undefined;
+
+  // Parse dates to Unix timestamps
+  let exp: number | undefined;
+  let iat: number | undefined;
+
+  if (vc.expirationDate && typeof vc.expirationDate === 'string') {
+    exp = Math.floor(new Date(vc.expirationDate).getTime() / 1000);
+  }
+  if (vc.issuanceDate && typeof vc.issuanceDate === 'string') {
+    iat = Math.floor(new Date(vc.issuanceDate).getTime() / 1000);
+  }
+
+  // Remove proof from VC for JWT payload (signature is in JWT itself)
+  const vcWithoutProof = { ...vc };
+  delete vcWithoutProof.proof;
+
+  // Build JWT payload
+  const payload: VCJWTPayload = {
+    iss: issuer,
+    vc: vcWithoutProof,
+  };
+
+  if (subject) payload.sub = subject;
+  if (exp) payload.exp = exp;
+  if (iat) payload.iat = iat;
+  if (vc.id && typeof vc.id === 'string') payload.jti = vc.id;
+
+  // Encode header and payload
+  const encodedHeader = base64urlEncodeFromString(JSON.stringify(header));
+  const encodedPayload = base64urlEncodeFromString(JSON.stringify(payload));
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+
+  return {
+    header,
+    payload,
+    encodedHeader,
+    encodedPayload,
+    signingInput,
+  };
+}
+
+/**
+ * Complete a JWT with a signature
+ *
+ * Takes the signing input and a base64url-encoded signature to create the final JWT.
+ *
+ * @param signingInput - The header.payload string that was signed
+ * @param signature - Base64url-encoded signature
+ * @returns Complete JWT string (header.payload.signature)
+ */
+export function completeVCJWT(signingInput: string, signature: string): string {
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Parse a VC-JWT and extract the VC
+ *
+ * Does NOT verify the signature - use with a verification function.
+ *
+ * @param jwt - The JWT string
+ * @returns Parsed JWT parts
+ */
+export function parseVCJWT(jwt: string): {
+  header: VCJWTHeader;
+  payload: VCJWTPayload;
+  signature: string;
+  signingInput: string;
+} | null {
+  const parts = jwt.split('.');
+  if (parts.length !== 3) {
+    return null;
+  }
+
+  try {
+    // Decode header and payload
+    const headerJson = base64urlDecodeToString(parts[0]);
+    const payloadJson = base64urlDecodeToString(parts[1]);
+
+    const header = JSON.parse(headerJson) as VCJWTHeader;
+    const payload = JSON.parse(payloadJson) as VCJWTPayload;
+
+    return {
+      header,
+      payload,
+      signature: parts[2],
+      signingInput: `${parts[0]}.${parts[1]}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decode base64url string to string (internal helper)
+ */
+function base64urlDecodeToString(input: string): string {
+  // Add padding if needed
+  const padded = input + '='.repeat((4 - input.length % 4) % 4);
+  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+
+  if (typeof atob !== 'undefined') {
+    return atob(base64);
+  }
+
+  return Buffer.from(base64, 'base64').toString('utf-8');
+}