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

package/src/delegation/delegation-graph.ts

@@ -0,0 +1,299 @@
+/**
+ * Delegation Graph Manager
+ *
+ * Tracks parent-child relationships between delegation credentials.
+ * Critical for cascading revocation per Delegation-Revocation.md.
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Only manages delegation relationships
+ * - Open/Closed: Extensible via storage provider interface
+ * - Liskov Substitution: Any storage provider can be used
+ * - Interface Segregation: Minimal graph operations interface
+ * - Dependency Inversion: Depends on storage abstraction
+ *
+ * Related Spec: MCP-I §4.4, Delegation Chains
+ * Python Reference: Delegation-Revocation.md:45-67
+ */
+
+/**
+ * Delegation node in the graph
+ */
+export interface DelegationNode {
+  /** Delegation credential ID */
+  id: string;
+
+  /** Parent delegation ID (null for root) */
+  parentId: string | null;
+
+  /** Child delegation IDs */
+  children: string[];
+
+  /** Issuer DID */
+  issuerDid: string;
+
+  /** Subject DID */
+  subjectDid: string;
+
+  /** Credential status reference (for revocation) */
+  credentialStatusId?: string;
+}
+
+/**
+ * Storage provider interface for delegation graphs
+ *
+ * Platform-specific implementations (CloudflareKV, DynamoDB, etc.)
+ */
+export interface DelegationGraphStorageProvider {
+  /**
+   * Get a delegation node by ID
+   */
+  getNode(delegationId: string): Promise<DelegationNode | null>;
+
+  /**
+   * Save a delegation node
+   */
+  setNode(node: DelegationNode): Promise<void>;
+
+  /**
+   * Get all children of a delegation
+   */
+  getChildren(delegationId: string): Promise<DelegationNode[]>;
+
+  /**
+   * Get the full chain from root to this delegation
+   */
+  getChain(delegationId: string): Promise<DelegationNode[]>;
+
+  /**
+   * Get all descendants (children, grandchildren, etc.)
+   */
+  getDescendants(delegationId: string): Promise<DelegationNode[]>;
+
+  /**
+   * Delete a node (used for cleanup)
+   */
+  deleteNode(delegationId: string): Promise<void>;
+}
+
+/**
+ * Delegation Graph Manager
+ *
+ * Manages the tree/graph structure of delegations.
+ * Per Delegation-Revocation.md:
+ * - Track parent-child relationships
+ * - Support chain validation
+ * - Enable cascading revocation
+ */
+export class DelegationGraphManager {
+  constructor(private storage: DelegationGraphStorageProvider) {}
+
+  /**
+   * Register a new delegation in the graph
+   *
+   * @param delegation - The delegation to register
+   * @returns The created node
+   */
+  async registerDelegation(params: {
+    id: string;
+    parentId: string | null;
+    issuerDid: string;
+    subjectDid: string;
+    credentialStatusId?: string;
+  }): Promise<DelegationNode> {
+    const node: DelegationNode = {
+      id: params.id,
+      parentId: params.parentId,
+      children: [],
+      issuerDid: params.issuerDid,
+      subjectDid: params.subjectDid,
+      credentialStatusId: params.credentialStatusId,
+    };
+
+    // Save the node
+    await this.storage.setNode(node);
+
+    // If has parent, add this as a child to parent
+    if (params.parentId) {
+      await this.addChildToParent(params.parentId, params.id);
+    }
+
+    return node;
+  }
+
+  /**
+   * Add a child to a parent node
+   *
+   * @param parentId - Parent delegation ID
+   * @param childId - Child delegation ID
+   */
+  private async addChildToParent(
+    parentId: string,
+    childId: string
+  ): Promise<void> {
+    const parent = await this.storage.getNode(parentId);
+    if (!parent) {
+      throw new Error(`Parent delegation not found: ${parentId}`);
+    }
+
+    // Add child if not already present
+    if (!parent.children.includes(childId)) {
+      parent.children.push(childId);
+      await this.storage.setNode(parent);
+    }
+  }
+
+  /**
+   * Get a delegation node
+   *
+   * @param delegationId - The delegation ID
+   * @returns The node, or null if not found
+   */
+  async getNode(delegationId: string): Promise<DelegationNode | null> {
+    return this.storage.getNode(delegationId);
+  }
+
+  /**
+   * Get all direct children of a delegation
+   *
+   * @param delegationId - The parent delegation ID
+   * @returns Array of child nodes
+   */
+  async getChildren(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getChildren(delegationId);
+  }
+
+  /**
+   * Get all descendants (children, grandchildren, etc.)
+   *
+   * Used for cascading revocation.
+   * Per Delegation-Revocation.md:56-67
+   *
+   * @param delegationId - The parent delegation ID
+   * @returns Array of all descendant nodes
+   */
+  async getDescendants(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getDescendants(delegationId);
+  }
+
+  /**
+   * Get the full delegation chain from root to this node
+   *
+   * Used for chain validation.
+   *
+   * @param delegationId - The delegation ID
+   * @returns Array of nodes from root to this node
+   */
+  async getChain(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getChain(delegationId);
+  }
+
+  /**
+   * Check if delegation A is an ancestor of delegation B
+   *
+   * @param ancestorId - Potential ancestor ID
+   * @param descendantId - Potential descendant ID
+   * @returns true if ancestorId is an ancestor of descendantId
+   */
+  async isAncestor(
+    ancestorId: string,
+    descendantId: string
+  ): Promise<boolean> {
+    const chain = await this.getChain(descendantId);
+    return chain.some((node) => node.id === ancestorId);
+  }
+
+  /**
+   * Get the depth of a delegation in the tree
+   *
+   * @param delegationId - The delegation ID
+   * @returns Depth (0 for root, 1 for immediate child, etc.)
+   */
+  async getDepth(delegationId: string): Promise<number> {
+    const chain = await this.getChain(delegationId);
+    return chain.length - 1; // -1 because chain includes the node itself
+  }
+
+  /**
+   * Validate that a delegation chain is properly formed
+   *
+   * Checks that:
+   * - Each child's issuer is the parent's subject
+   * - No cycles exist
+   * - Chain is continuous
+   *
+   * @param delegationId - The delegation ID to validate
+   * @returns Validation result
+   */
+  async validateChain(delegationId: string): Promise<{
+    valid: boolean;
+    reason?: string;
+  }> {
+    const chain = await this.getChain(delegationId);
+
+    if (chain.length === 0) {
+      return { valid: false, reason: 'Delegation not found' };
+    }
+
+    // Check each link in the chain
+    for (let i = 1; i < chain.length; i++) {
+      const parent = chain[i - 1];
+      const child = chain[i];
+
+      // Child's issuer must be parent's subject
+      if (child.issuerDid !== parent.subjectDid) {
+        return {
+          valid: false,
+          reason: `Invalid chain: ${child.id} issued by ${child.issuerDid} but parent ${parent.id} subject is ${parent.subjectDid}`,
+        };
+      }
+
+      // Child's parent pointer must match parent's ID
+      if (child.parentId !== parent.id) {
+        return {
+          valid: false,
+          reason: `Invalid chain: ${child.id} parentId=${child.parentId} but actual parent is ${parent.id}`,
+        };
+      }
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Remove a delegation from the graph
+   *
+   * Note: This doesn't cascade - use CascadingRevocationManager for that.
+   *
+   * @param delegationId - The delegation ID to remove
+   */
+  async removeDelegation(delegationId: string): Promise<void> {
+    const node = await this.storage.getNode(delegationId);
+    if (!node) return;
+
+    // Remove from parent's children list
+    if (node.parentId) {
+      const parent = await this.storage.getNode(node.parentId);
+      if (parent) {
+        parent.children = parent.children.filter((id) => id !== delegationId);
+        await this.storage.setNode(parent);
+      }
+    }
+
+    // Delete the node
+    await this.storage.deleteNode(delegationId);
+  }
+}
+
+/**
+ * Create a delegation graph manager
+ *
+ * Convenience factory function.
+ *
+ * @param storage - Storage provider
+ * @returns DelegationGraphManager instance
+ */
+export function createDelegationGraph(
+  storage: DelegationGraphStorageProvider
+): DelegationGraphManager {
+  return new DelegationGraphManager(storage);
+}

package/src/delegation/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Delegation Module Exports (Platform-Agnostic)
+ *
+ * W3C VC-based delegation issuance and verification.
+ * Platform-specific adapters (Node.js, Cloudflare) provide signing/verification functions.
+ */
+
+export * from './vc-issuer';
+export * from './vc-verifier';
+export * from './bitstring';
+export * from './statuslist-manager';
+export * from './delegation-graph';
+export * from './cascading-revocation';
+export * from './utils';

package/src/delegation/statuslist-manager.ts

@@ -0,0 +1,353 @@
+/**
+ * StatusList2021 Manager
+ *
+ * Manages StatusList2021 credentials for efficient delegation revocation.
+ * Follows the Python POC design from Delegation-Revocation.md.
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Manages status list allocation and updates
+ * - Open/Closed: Extensible via storage provider interface
+ * - Liskov Substitution: Any storage provider can be used
+ * - Interface Segregation: Minimal storage interface
+ * - Dependency Inversion: Depends on abstractions (storage, signing)
+ *
+ * Related Spec: W3C StatusList2021
+ * Python Reference: Delegation-Revocation.md
+ */
+
+import type {
+  StatusList2021Credential,
+  CredentialStatus,
+} from '@kya-os/contracts';
+import { BitstringManager, CompressionFunction, DecompressionFunction } from './bitstring';
+import { VCSigningFunction } from './vc-issuer';
+import { canonicalizeJSON } from './utils';
+
+/**
+ * Storage provider interface for status lists
+ *
+ * Platform-specific implementations (CloudflareKV, DynamoDB, Redis, etc.)
+ * implement this interface.
+ */
+export interface StatusListStorageProvider {
+  /**
+   * Get a status list credential by ID
+   *
+   * @param statusListId - The status list URL
+   * @returns The status list credential, or null if not found
+   */
+  getStatusList(statusListId: string): Promise<StatusList2021Credential | null>;
+
+  /**
+   * Save a status list credential
+   *
+   * @param statusListId - The status list URL
+   * @param credential - The status list credential
+   */
+  setStatusList(
+    statusListId: string,
+    credential: StatusList2021Credential
+  ): Promise<void>;
+
+  /**
+   * Allocate a new index in a status list
+   *
+   * Thread-safe allocation of the next available index.
+   *
+   * @param statusListId - The status list URL
+   * @returns The allocated index
+   */
+  allocateIndex(statusListId: string): Promise<number>;
+}
+
+/**
+ * Identity provider for signing status list credentials
+ */
+export interface StatusListIdentityProvider {
+  /** Get the DID of this identity */
+  getDid(): string;
+
+  /** Get the key ID of this identity */
+  getKeyId(): string;
+}
+
+/**
+ * StatusList2021 Manager
+ *
+ * Manages status lists for efficient delegation revocation.
+ * Per Delegation-Revocation.md:
+ * - StatusList2021 for efficient revocation distribution
+ * - Compressed bitstrings for scalability
+ * - Separate lists for revocation vs suspension
+ */
+export class StatusList2021Manager {
+  private statusListBaseUrl: string;
+  private defaultListSize: number;
+
+  constructor(
+    private storage: StatusListStorageProvider,
+    private identity: StatusListIdentityProvider,
+    private signingFunction: VCSigningFunction,
+    private compressor: CompressionFunction,
+    private decompressor: DecompressionFunction,
+    options?: {
+      /** Base URL for status lists (e.g., "https://example.com/status") */
+      statusListBaseUrl?: string;
+      /** Default size for new status lists (number of entries) */
+      defaultListSize?: number;
+    }
+  ) {
+    this.statusListBaseUrl = options?.statusListBaseUrl || 'https://status.example.com';
+    this.defaultListSize = options?.defaultListSize || 131072; // 128K entries (16KB compressed)
+  }
+
+  /**
+   * Allocate a status entry for a new delegation credential
+   *
+   * Per Delegation-Revocation.md: Each delegation gets a unique status list entry.
+   *
+   * @param purpose - "revocation" or "suspension"
+   * @returns CredentialStatus entry for the delegation VC
+   */
+  async allocateStatusEntry(
+    purpose: 'revocation' | 'suspension'
+  ): Promise<CredentialStatus> {
+    // Determine which status list to use
+    const statusListId = `${this.statusListBaseUrl}/${purpose}/v1`;
+
+    // Allocate index in the status list (thread-safe)
+    const index = await this.storage.allocateIndex(statusListId);
+
+    // Ensure the status list exists
+    await this.ensureStatusListExists(statusListId, purpose);
+
+    // Create the credential status entry
+    const credentialStatus: CredentialStatus = {
+      id: `${statusListId}#${index}`,
+      type: 'StatusList2021Entry',
+      statusPurpose: purpose,
+      statusListIndex: index.toString(),
+      statusListCredential: statusListId,
+    };
+
+    return credentialStatus;
+  }
+
+  /**
+   * Revoke or suspend a delegation by updating its status
+   *
+   * @param credentialStatus - The credential status entry from the VC
+   * @param revoked - true to revoke/suspend, false to restore
+   */
+  async updateStatus(
+    credentialStatus: CredentialStatus,
+    revoked: boolean
+  ): Promise<void> {
+    const { statusListCredential, statusListIndex } = credentialStatus;
+
+    // Get the current status list
+    const statusList = await this.storage.getStatusList(statusListCredential);
+    if (!statusList) {
+      throw new Error(`Status list not found: ${statusListCredential}`);
+    }
+
+    // Decode the bitstring
+    const manager = await BitstringManager.decode(
+      statusList.credentialSubject.encodedList,
+      this.compressor,
+      this.decompressor
+    );
+
+    // Update the bit
+    const index = parseInt(statusListIndex, 10);
+    manager.setBit(index, revoked);
+
+    // Re-encode
+    const encodedList = await manager.encode();
+
+    // Update the credential
+    const updatedCredential: StatusList2021Credential = {
+      ...statusList,
+      credentialSubject: {
+        ...statusList.credentialSubject,
+        encodedList,
+      },
+    };
+
+    // Re-sign the credential (proof changes when content changes)
+    const unsignedCredential = { ...updatedCredential };
+    delete (unsignedCredential as any).proof;
+
+    const canonicalVC = canonicalizeJSON(unsignedCredential);
+    const proof = await this.signingFunction(
+      canonicalVC,
+      this.identity.getDid(),
+      this.identity.getKeyId()
+    );
+
+    const signedCredential: StatusList2021Credential = {
+      ...updatedCredential,
+      proof,
+    };
+
+    // Save the updated status list
+    await this.storage.setStatusList(statusListCredential, signedCredential);
+  }
+
+  /**
+   * Check if a credential is revoked
+   *
+   * @param credentialStatus - The credential status entry
+   * @returns true if revoked/suspended, false otherwise
+   */
+  async checkStatus(credentialStatus: CredentialStatus): Promise<boolean> {
+    const { statusListCredential, statusListIndex } = credentialStatus;
+
+    // Get the status list
+    const statusList = await this.storage.getStatusList(statusListCredential);
+    if (!statusList) {
+      // Status list doesn't exist = not revoked
+      return false;
+    }
+
+    // Decode and check the bit
+    const manager = await BitstringManager.decode(
+      statusList.credentialSubject.encodedList,
+      this.compressor,
+      this.decompressor
+    );
+
+    const index = parseInt(statusListIndex, 10);
+    return manager.getBit(index);
+  }
+
+  /**
+   * Get all revoked indices in a status list
+   *
+   * Useful for debugging or auditing.
+   *
+   * @param statusListId - The status list URL
+   * @returns Array of revoked indices
+   */
+  async getRevokedIndices(statusListId: string): Promise<number[]> {
+    const statusList = await this.storage.getStatusList(statusListId);
+    if (!statusList) {
+      return [];
+    }
+
+    const manager = await BitstringManager.decode(
+      statusList.credentialSubject.encodedList,
+      this.compressor,
+      this.decompressor
+    );
+
+    return manager.getSetBits();
+  }
+
+  /**
+   * Ensure a status list exists, creating it if needed
+   *
+   * @param statusListId - The status list URL
+   * @param purpose - "revocation" or "suspension"
+   */
+  private async ensureStatusListExists(
+    statusListId: string,
+    purpose: 'revocation' | 'suspension'
+  ): Promise<void> {
+    // Check if it already exists
+    const existing = await this.storage.getStatusList(statusListId);
+    if (existing) {
+      return;
+    }
+
+    // Create a new status list
+    const manager = new BitstringManager(
+      this.defaultListSize,
+      this.compressor,
+      this.decompressor
+    );
+    const encodedList = await manager.encode();
+
+    // Create the unsigned credential
+    const unsignedCredential = {
+      '@context': [
+        'https://www.w3.org/2018/credentials/v1',
+        'https://w3id.org/vc/status-list/2021/v1',
+      ] as [string, string],
+      id: statusListId,
+      type: ['VerifiableCredential', 'StatusList2021Credential'] as ['VerifiableCredential', 'StatusList2021Credential'],
+      issuer: this.identity.getDid(),
+      issuanceDate: new Date().toISOString(),
+      credentialSubject: {
+        id: `${statusListId}#list`,
+        type: 'StatusList2021' as const,
+        statusPurpose: purpose,
+        encodedList,
+      },
+    };
+
+    // Sign it
+    const canonicalVC = canonicalizeJSON(unsignedCredential);
+    const proof = await this.signingFunction(
+      canonicalVC,
+      this.identity.getDid(),
+      this.identity.getKeyId()
+    );
+
+    const signedCredential: StatusList2021Credential = {
+      ...unsignedCredential,
+      proof,
+    };
+
+    // Store it
+    await this.storage.setStatusList(statusListId, signedCredential);
+  }
+
+  /**
+   * Get the status list base URL
+   */
+  getStatusListBaseUrl(): string {
+    return this.statusListBaseUrl;
+  }
+
+  /**
+   * Get the default list size
+   */
+  getDefaultListSize(): number {
+    return this.defaultListSize;
+  }
+}
+
+/**
+ * Create a StatusList2021 manager
+ *
+ * Convenience factory function.
+ *
+ * @param storage - Storage provider
+ * @param identity - Identity provider
+ * @param signingFunction - VC signing function
+ * @param compressor - Compression function
+ * @param decompressor - Decompression function
+ * @param options - Manager options
+ * @returns StatusList2021Manager instance
+ */
+export function createStatusListManager(
+  storage: StatusListStorageProvider,
+  identity: StatusListIdentityProvider,
+  signingFunction: VCSigningFunction,
+  compressor: CompressionFunction,
+  decompressor: DecompressionFunction,
+  options?: {
+    statusListBaseUrl?: string;
+    defaultListSize?: number;
+  }
+): StatusList2021Manager {
+  return new StatusList2021Manager(
+    storage,
+    identity,
+    signingFunction,
+    compressor,
+    decompressor,
+    options
+  );
+}