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

package/src/delegation/storage/memory-graph-storage.ts

@@ -0,0 +1,178 @@
+/**
+ * In-Memory Delegation Graph Storage Provider
+ *
+ * Memory-based implementation for testing and development.
+ * NOT suitable for production (no persistence).
+ *
+ * SOLID: Implements DelegationGraphStorageProvider interface
+ */
+
+import type {
+  DelegationGraphStorageProvider,
+  DelegationNode,
+} from '../delegation-graph';
+
+/**
+ * Memory-based Delegation Graph storage
+ *
+ * Stores delegation nodes in memory with efficient graph queries.
+ * Useful for:
+ * - Unit tests
+ * - Integration tests
+ * - Development/debugging
+ * - Examples
+ */
+export class MemoryDelegationGraphStorage
+  implements DelegationGraphStorageProvider
+{
+  private nodes = new Map<string, DelegationNode>();
+
+  /**
+   * Get a delegation node by ID
+   */
+  async getNode(delegationId: string): Promise<DelegationNode | null> {
+    return this.nodes.get(delegationId) || null;
+  }
+
+  /**
+   * Save a delegation node
+   */
+  async setNode(node: DelegationNode): Promise<void> {
+    this.nodes.set(node.id, node);
+  }
+
+  /**
+   * Get all children of a delegation
+   */
+  async getChildren(delegationId: string): Promise<DelegationNode[]> {
+    const parent = this.nodes.get(delegationId);
+    if (!parent) return [];
+
+    return parent.children
+      .map((childId) => this.nodes.get(childId))
+      .filter((node): node is DelegationNode => node !== undefined);
+  }
+
+  /**
+   * Get the full chain from root to this delegation
+   */
+  async getChain(delegationId: string): Promise<DelegationNode[]> {
+    const chain: DelegationNode[] = [];
+    let currentId: string | null = delegationId;
+
+    // Walk up the tree to root
+    while (currentId) {
+      const node = this.nodes.get(currentId);
+      if (!node) break;
+
+      chain.unshift(node); // Add to front (root first)
+      currentId = node.parentId;
+    }
+
+    return chain;
+  }
+
+  /**
+   * Get all descendants (children, grandchildren, etc.)
+   *
+   * Uses BFS for efficiency.
+   */
+  async getDescendants(delegationId: string): Promise<DelegationNode[]> {
+    const descendants: DelegationNode[] = [];
+    const queue: string[] = [delegationId];
+    const visited = new Set<string>();
+
+    while (queue.length > 0) {
+      const currentId = queue.shift()!;
+
+      // Skip if already visited (prevent infinite loops)
+      if (visited.has(currentId)) continue;
+      visited.add(currentId);
+
+      const node = this.nodes.get(currentId);
+      if (!node) continue;
+
+      // Add children to queue
+      for (const childId of node.children) {
+        if (!visited.has(childId)) {
+          queue.push(childId);
+
+          const childNode = this.nodes.get(childId);
+          if (childNode) {
+            descendants.push(childNode);
+          }
+        }
+      }
+    }
+
+    return descendants;
+  }
+
+  /**
+   * Delete a node
+   */
+  async deleteNode(delegationId: string): Promise<void> {
+    this.nodes.delete(delegationId);
+  }
+
+  /**
+   * Clear all data (for testing)
+   */
+  clear(): void {
+    this.nodes.clear();
+  }
+
+  /**
+   * Get all node IDs (for testing)
+   */
+  getAllNodeIds(): string[] {
+    return Array.from(this.nodes.keys());
+  }
+
+  /**
+   * Get graph statistics (for testing/debugging)
+   */
+  getStats(): {
+    totalNodes: number;
+    rootNodes: number;
+    leafNodes: number;
+    maxDepth: number;
+  } {
+    const nodes = Array.from(this.nodes.values());
+
+    const rootNodes = nodes.filter((n) => n.parentId === null).length;
+    const leafNodes = nodes.filter((n) => n.children.length === 0).length;
+
+    // Calculate max depth
+    let maxDepth = 0;
+    for (const node of nodes) {
+      const chain = this.getChainSync(node.id);
+      maxDepth = Math.max(maxDepth, chain.length - 1);
+    }
+
+    return {
+      totalNodes: nodes.length,
+      rootNodes,
+      leafNodes,
+      maxDepth,
+    };
+  }
+
+  /**
+   * Synchronous chain retrieval (for stats)
+   */
+  private getChainSync(delegationId: string): DelegationNode[] {
+    const chain: DelegationNode[] = [];
+    let currentId: string | null = delegationId;
+
+    while (currentId) {
+      const node = this.nodes.get(currentId);
+      if (!node) break;
+
+      chain.unshift(node);
+      currentId = node.parentId;
+    }
+
+    return chain;
+  }
+}

package/src/delegation/storage/memory-statuslist-storage.ts

@@ -0,0 +1,77 @@
+/**
+ * In-Memory StatusList Storage Provider
+ *
+ * Memory-based implementation for testing and development.
+ * NOT suitable for production (no persistence).
+ *
+ * SOLID: Implements StatusListStorageProvider interface
+ */
+
+import type { StatusList2021Credential } from '@kya-os/contracts';
+import type { StatusListStorageProvider } from '../statuslist-manager';
+
+/**
+ * Memory-based StatusList storage
+ *
+ * Stores status lists in memory. Thread-safe index allocation.
+ * Useful for:
+ * - Unit tests
+ * - Integration tests
+ * - Development/debugging
+ * - Examples
+ */
+export class MemoryStatusListStorage implements StatusListStorageProvider {
+  private statusLists = new Map<string, StatusList2021Credential>();
+  private indexCounters = new Map<string, number>();
+
+  /**
+   * Get a status list credential by ID
+   */
+  async getStatusList(
+    statusListId: string
+  ): Promise<StatusList2021Credential | null> {
+    return this.statusLists.get(statusListId) || null;
+  }
+
+  /**
+   * Save a status list credential
+   */
+  async setStatusList(
+    statusListId: string,
+    credential: StatusList2021Credential
+  ): Promise<void> {
+    this.statusLists.set(statusListId, credential);
+  }
+
+  /**
+   * Allocate a new index (thread-safe)
+   */
+  async allocateIndex(statusListId: string): Promise<number> {
+    const current = this.indexCounters.get(statusListId) || 0;
+    const allocated = current;
+    this.indexCounters.set(statusListId, current + 1);
+    return allocated;
+  }
+
+  /**
+   * Get current index count (for testing)
+   */
+  getIndexCount(statusListId: string): number {
+    return this.indexCounters.get(statusListId) || 0;
+  }
+
+  /**
+   * Clear all data (for testing)
+   */
+  clear(): void {
+    this.statusLists.clear();
+    this.indexCounters.clear();
+  }
+
+  /**
+   * Get all status list IDs (for testing)
+   */
+  getAllStatusListIds(): string[] {
+    return Array.from(this.statusLists.keys());
+  }
+}

package/src/delegation/utils.ts

@@ -0,0 +1,42 @@
+/**
+ * Delegation Utilities
+ *
+ * Shared utility functions for delegation credential operations.
+ * Following DRY (Don't Repeat Yourself) principle.
+ */
+
+/**
+ * JSON canonicalization (RFC 8785)
+ *
+ * Creates a deterministic representation of JSON for signing.
+ * Per W3C VC spec, canonicalization ensures identical VCs produce identical signatures.
+ *
+ * DRY: Single implementation shared across vc-issuer and statuslist-manager.
+ *
+ * @param obj - The object to canonicalize
+ * @returns Canonical JSON string
+ */
+export function canonicalizeJSON(obj: any): string {
+  if (obj === null) return 'null';
+  if (typeof obj === 'boolean') return obj.toString();
+  if (typeof obj === 'number') {
+    if (!isFinite(obj)) {
+      throw new Error('Cannot canonicalize non-finite number');
+    }
+    return JSON.stringify(obj);
+  }
+  if (typeof obj === 'string') return JSON.stringify(obj);
+  if (Array.isArray(obj)) {
+    const elements = obj.map((item) => canonicalizeJSON(item));
+    return '[' + elements.join(',') + ']';
+  }
+  if (typeof obj === 'object') {
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((key) => {
+      const value = canonicalizeJSON(obj[key]);
+      return JSON.stringify(key) + ':' + value;
+    });
+    return '{' + pairs.join(',') + '}';
+  }
+  throw new Error(`Cannot canonicalize type: ${typeof obj}`);
+}

package/src/delegation/vc-issuer.ts

@@ -0,0 +1,232 @@
+/**
+ * Delegation Credential Issuer (Platform-Agnostic)
+ *
+ * Issues W3C Verifiable Credentials for delegations with Ed25519 signatures.
+ * Follows the Python POC design (Delegation-Service.md:136-163) where
+ * delegations are issued AS W3C VCs.
+ *
+ * Related Spec: MCP-I §4.1, §4.2, W3C VC Data Model 1.1
+ * Python Reference: Delegation-Service.md
+ */
+
+import type {
+  DelegationCredential,
+  DelegationRecord,
+  CredentialStatus,
+  Proof,
+} from '@kya-os/contracts';
+import { wrapDelegationAsVC } from '@kya-os/contracts';
+import { canonicalizeJSON } from './utils';
+
+/**
+ * Options for issuing a delegation credential
+ */
+export interface IssueDelegationOptions {
+  /** VC ID (optional, will be generated if not provided) */
+  id?: string;
+
+  /** Issuance date (optional, defaults to now) */
+  issuanceDate?: string;
+
+  /** Expiration date (optional, derived from constraints if not provided) */
+  expirationDate?: string;
+
+  /** Credential status for StatusList2021 (optional) */
+  credentialStatus?: CredentialStatus;
+
+  /** Additional context URIs (optional) */
+  additionalContexts?: string[];
+}
+
+/**
+ * Signing function interface
+ *
+ * Platform-specific implementations provide this function to sign VCs.
+ * For example:
+ * - Node.js: Uses jose library with importPKCS8
+ * - Cloudflare: Uses Web Crypto API
+ */
+export interface VCSigningFunction {
+  /**
+   * Sign a canonicalized VC
+   *
+   * @param canonicalVC - The canonical JSON string to sign
+   * @param issuerDid - The DID of the issuer
+   * @param kid - The key ID
+   * @returns Ed25519Signature2020 proof
+   */
+  (canonicalVC: string, issuerDid: string, kid: string): Promise<Proof>;
+}
+
+/**
+ * Identity provider interface
+ *
+ * Platform-specific implementations provide identity details.
+ */
+export interface IdentityProvider {
+  /** Get the DID of this identity */
+  getDid(): string;
+
+  /** Get the key ID of this identity */
+  getKeyId(): string;
+
+  /** Get the private key (base64 encoded) */
+  getPrivateKey(): string;
+}
+
+/**
+ * Delegation Credential Issuer (Platform-Agnostic)
+ *
+ * Issues W3C Verifiable Credentials for delegations.
+ * Per Python POC (Delegation-Service.md:136-146):
+ * - Every delegation MUST be issued as a VC
+ * - VC is signed with Ed25519 (Ed25519Signature2020)
+ * - StatusList2021 support for efficient revocation
+ */
+export class DelegationCredentialIssuer {
+  constructor(
+    private identity: IdentityProvider,
+    private signingFunction: VCSigningFunction
+  ) {}
+
+  /**
+   * Issue a delegation credential
+   *
+   * Creates a W3C Verifiable Credential from a delegation record.
+   * Signs it with Ed25519 and returns the complete DelegationCredential.
+   *
+   * @param delegation - The delegation record to issue as a VC
+   * @param options - Issuance options
+   * @returns Signed DelegationCredential
+   */
+  async issueDelegationCredential(
+    delegation: DelegationRecord,
+    options: IssueDelegationOptions = {}
+  ): Promise<DelegationCredential> {
+    // Step 1: Create unsigned VC
+    let unsignedVC = wrapDelegationAsVC(delegation, {
+      id: options.id,
+      issuanceDate: options.issuanceDate,
+      expirationDate: options.expirationDate,
+      credentialStatus: options.credentialStatus,
+    });
+
+    // Add additional contexts if provided
+    if (options.additionalContexts && options.additionalContexts.length > 0) {
+      const existingContexts = unsignedVC['@context'] as Array<
+        string | Record<string, any>
+      >;
+      unsignedVC = {
+        ...unsignedVC,
+        '@context': [...existingContexts, ...options.additionalContexts],
+      };
+    }
+
+    // Step 2: Canonicalize VC (for signing)
+    const canonicalVC = this.canonicalizeVC(unsignedVC);
+
+    // Step 3: Sign with Ed25519 using platform-specific signing function
+    const proof = await this.signingFunction(
+      canonicalVC,
+      this.identity.getDid(),
+      this.identity.getKeyId()
+    );
+
+    // Step 4: Return signed VC
+    return {
+      ...unsignedVC,
+      proof,
+    } as DelegationCredential;
+  }
+
+  /**
+   * Create a delegation record and issue it as a VC in one step
+   *
+   * Convenience method for creating a new delegation from scratch.
+   *
+   * @param params - Delegation parameters
+   * @param options - Issuance options
+   * @returns Signed DelegationCredential
+   */
+  async createAndIssueDelegation(
+    params: {
+      id: string;
+      issuerDid: string;
+      subjectDid: string;
+      controller?: string;
+      parentId?: string;
+      constraints: DelegationRecord['constraints'];
+      status?: DelegationRecord['status'];
+      metadata?: Record<string, any>;
+    },
+    options: IssueDelegationOptions = {}
+  ): Promise<DelegationCredential> {
+    const now = Date.now();
+
+    // Create delegation record
+    const delegation: DelegationRecord = {
+      id: params.id,
+      issuerDid: params.issuerDid,
+      subjectDid: params.subjectDid,
+      controller: params.controller,
+      vcId: options.id || `urn:uuid:${params.id}`,
+      parentId: params.parentId,
+      constraints: params.constraints,
+      signature: '', // Will be filled by VC proof
+      status: params.status || 'active',
+      createdAt: now,
+      metadata: params.metadata,
+    };
+
+    // Issue as VC
+    return this.issueDelegationCredential(delegation, options);
+  }
+
+  /**
+   * Canonicalize VC for signing
+   *
+   * Uses JCS (JSON Canonicalization Scheme, RFC 8785) to create
+   * a deterministic representation of the VC.
+   *
+   * @param vc - The unsigned VC
+   * @returns Canonical JSON string
+   */
+  private canonicalizeVC(vc: Omit<DelegationCredential, 'proof'>): string {
+    // DRY: Use shared canonicalization utility
+    return canonicalizeJSON(vc);
+  }
+
+  /**
+   * Get issuer DID
+   *
+   * @returns The DID of this issuer
+   */
+  getIssuerDid(): string {
+    return this.identity.getDid();
+  }
+
+  /**
+   * Get issuer key ID
+   *
+   * @returns The key ID of this issuer
+   */
+  getIssuerKeyId(): string {
+    return this.identity.getKeyId();
+  }
+}
+
+/**
+ * Create a delegation credential issuer
+ *
+ * Convenience factory function.
+ *
+ * @param identity - Identity provider
+ * @param signingFunction - Platform-specific signing function
+ * @returns DelegationCredentialIssuer instance
+ */
+export function createDelegationIssuer(
+  identity: IdentityProvider,
+  signingFunction: VCSigningFunction
+): DelegationCredentialIssuer {
+  return new DelegationCredentialIssuer(identity, signingFunction);
+}