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

package/src/delegation/audience-validator.ts

@@ -0,0 +1,52 @@
+/**
+ * Delegation Audience Validation
+ *
+ * Validates if a delegation's audience matches the server DID.
+ * Supports both single server DID and multiple server DIDs.
+ *
+ * @package @kya-os/mcp-i-core/delegation
+ */
+
+import type { DelegationRecord } from "@kya-os/contracts/delegation";
+
+/**
+ * Verify if a delegation's audience matches the server DID
+ *
+ * @param delegation - Delegation record to check
+ * @param serverDid - Server DID to verify against
+ * @returns true if delegation is valid for this server
+ *
+ * @example
+ * ```typescript
+ * // Delegation without audience - valid on any server
+ * verifyDelegationAudience(delegation, "did:web:server1.com") // true
+ *
+ * // Delegation with matching audience
+ * verifyDelegationAudience(delegation, "did:web:server1.com") // true
+ *
+ * // Delegation with non-matching audience
+ * verifyDelegationAudience(delegation, "did:web:server2.com") // false
+ *
+ * // Delegation with array audience containing server
+ * verifyDelegationAudience(delegation, "did:web:server1.com") // true
+ * ```
+ */
+export function verifyDelegationAudience(
+  delegation: DelegationRecord,
+  serverDid: string
+): boolean {
+  // If no audience specified, delegation is valid for any server
+  if (!delegation.constraints.audience) {
+    return true;
+  }
+
+  // Check if server DID matches audience
+  const audience = delegation.constraints.audience;
+  if (typeof audience === "string") {
+    return audience === serverDid;
+  }
+
+  // Array of server DIDs
+  return audience.includes(serverDid);
+}
+

package/src/delegation/bitstring.ts

@@ -0,0 +1,278 @@
+/**
+ * Bitstring Utilities for StatusList2021
+ *
+ * Implements GZIP compression + base64url encoding for efficient status lists.
+ * Per W3C StatusList2021 spec, each bit represents credential status:
+ * - 0: Not revoked/suspended
+ * - 1: Revoked/suspended
+ *
+ * Related Spec: W3C StatusList2021
+ * Python Reference: Delegation-Revocation.md
+ */
+
+/**
+ * Platform-agnostic bitstring operations
+ *
+ * Implementations must provide compression/decompression functions
+ * since these are platform-specific (Node.js uses zlib, Cloudflare uses CompressionStream)
+ */
+
+/**
+ * Compression function interface
+ */
+export interface CompressionFunction {
+  /**
+   * Compress data using GZIP
+   * @param data - Data to compress
+   * @returns Compressed data
+   */
+  compress(data: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * Decompression function interface
+ */
+export interface DecompressionFunction {
+  /**
+   * Decompress GZIP data
+   * @param data - Compressed data
+   * @returns Decompressed data
+   */
+  decompress(data: Uint8Array): Promise<Uint8Array>;
+}
+
+/**
+ * Bitstring encoder/decoder
+ *
+ * Manages a bitstring for credential status tracking.
+ * Platform-agnostic - requires compression functions to be injected.
+ */
+export class BitstringManager {
+  private bits: Uint8Array;
+  private size: number;
+
+  constructor(
+    size: number,
+    private compressor: CompressionFunction,
+    private decompressor: DecompressionFunction
+  ) {
+    this.size = size;
+    // Allocate bytes (8 bits per byte)
+    const byteCount = Math.ceil(size / 8);
+    this.bits = new Uint8Array(byteCount);
+  }
+
+  /**
+   * Set a bit at a specific index
+   *
+   * @param index - The bit index (0-based)
+   * @param value - true to set (revoked), false to clear (active)
+   */
+  setBit(index: number, value: boolean): void {
+    if (index < 0 || index >= this.size) {
+      throw new Error(`Bit index ${index} out of range (0-${this.size - 1})`);
+    }
+
+    const byteIndex = Math.floor(index / 8);
+    const bitIndex = index % 8;
+
+    if (value) {
+      // Set bit to 1
+      this.bits[byteIndex] |= 1 << bitIndex;
+    } else {
+      // Clear bit to 0
+      this.bits[byteIndex] &= ~(1 << bitIndex);
+    }
+  }
+
+  /**
+   * Get a bit at a specific index
+   *
+   * @param index - The bit index (0-based)
+   * @returns true if set (revoked), false if clear (active)
+   */
+  getBit(index: number): boolean {
+    if (index < 0 || index >= this.size) {
+      throw new Error(`Bit index ${index} out of range (0-${this.size - 1})`);
+    }
+
+    const byteIndex = Math.floor(index / 8);
+    const bitIndex = index % 8;
+
+    return (this.bits[byteIndex] & (1 << bitIndex)) !== 0;
+  }
+
+  /**
+   * Get all set bit indices
+   *
+   * @returns Array of indices where bits are set to 1
+   */
+  getSetBits(): number[] {
+    const setBits: number[] = [];
+    for (let i = 0; i < this.size; i++) {
+      if (this.getBit(i)) {
+        setBits.push(i);
+      }
+    }
+    return setBits;
+  }
+
+  /**
+   * Encode bitstring to base64url (GZIP compressed)
+   *
+   * Per StatusList2021 spec:
+   * 1. GZIP compress the bitstring
+   * 2. Base64url encode the compressed data
+   *
+   * @returns Base64url-encoded compressed bitstring
+   */
+  async encode(): Promise<string> {
+    // Step 1: GZIP compress
+    const compressed = await this.compressor.compress(this.bits);
+
+    // Step 2: Base64url encode
+    return this.base64urlEncode(compressed);
+  }
+
+  /**
+   * Decode base64url bitstring (GZIP compressed)
+   *
+   * @param encodedList - Base64url-encoded compressed bitstring
+   * @returns BitstringManager instance
+   */
+  static async decode(
+    encodedList: string,
+    compressor: CompressionFunction,
+    decompressor: DecompressionFunction
+  ): Promise<BitstringManager> {
+    // Step 1: Base64url decode
+    const compressed = BitstringManager.base64urlDecode(encodedList);
+
+    // Step 2: GZIP decompress
+    const decompressed = await decompressor.decompress(compressed);
+
+    // Step 3: Create manager with decoded bits
+    const size = decompressed.length * 8;
+    const manager = new BitstringManager(size, compressor, decompressor);
+    manager.bits = decompressed;
+    return manager;
+  }
+
+  /**
+   * Get the raw bitstring
+   */
+  getRawBits(): Uint8Array {
+    return this.bits;
+  }
+
+  /**
+   * Get the size (number of bits)
+   */
+  getSize(): number {
+    return this.size;
+  }
+
+  /**
+   * Base64url encode (RFC 4648)
+   *
+   * Platform-agnostic implementation.
+   */
+  private base64urlEncode(data: Uint8Array): string {
+    // Convert to base64
+    const base64 = this.bytesToBase64(data);
+
+    // Convert base64 to base64url
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  /**
+   * Base64url decode (RFC 4648)
+   */
+  private static base64urlDecode(encoded: string): Uint8Array {
+    // Convert base64url to base64
+    let base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+
+    // Add padding if needed
+    while (base64.length % 4 !== 0) {
+      base64 += '=';
+    }
+
+    // Convert base64 to bytes
+    return BitstringManager.base64ToBytes(base64);
+  }
+
+  /**
+   * Convert bytes to base64
+   *
+   * Platform-agnostic implementation (works in Node and browsers/Cloudflare)
+   */
+  private bytesToBase64(bytes: Uint8Array): string {
+    const binary = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join('');
+    return btoa(binary);
+  }
+
+  /**
+   * Convert base64 to bytes
+   */
+  private static base64ToBytes(base64: string): Uint8Array {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  /**
+   * Create a bitstring from a list of indices to set
+   *
+   * @param size - Total size of the bitstring
+   * @param setBits - Indices to set to 1
+   * @param compressor - Compression function
+   * @param decompressor - Decompression function
+   * @returns BitstringManager instance
+   */
+  static fromSetBits(
+    size: number,
+    setBits: number[],
+    compressor: CompressionFunction,
+    decompressor: DecompressionFunction
+  ): BitstringManager {
+    const manager = new BitstringManager(size, compressor, decompressor);
+    for (const index of setBits) {
+      manager.setBit(index, true);
+    }
+    return manager;
+  }
+}
+
+/**
+ * Helper to check if an index is set in an encoded status list
+ *
+ * Convenience function for quick status checks without creating a full manager.
+ *
+ * @param encodedList - Base64url-encoded compressed bitstring
+ * @param index - The bit index to check
+ * @param decompressor - Decompression function
+ * @returns true if bit is set (revoked), false otherwise
+ */
+export async function isIndexSet(
+  encodedList: string,
+  index: number,
+  decompressor: DecompressionFunction
+): Promise<boolean> {
+  // Decode without needing compressor (we're only reading)
+  const compressed = BitstringManager['base64urlDecode'](encodedList);
+  const decompressed = await decompressor.decompress(compressed);
+
+  const byteIndex = Math.floor(index / 8);
+  const bitIndex = index % 8;
+
+  if (byteIndex >= decompressed.length) {
+    return false; // Out of range = not set
+  }
+
+  return (decompressed[byteIndex] & (1 << bitIndex)) !== 0;
+}

package/src/delegation/cascading-revocation.ts

@@ -0,0 +1,370 @@
+/**
+ * Cascading Revocation Manager
+ *
+ * Implements cascading revocation per Python POC design.
+ * When a parent delegation is revoked, all children are automatically revoked.
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Only handles cascading revocation logic
+ * - Open/Closed: Extensible via hooks/callbacks
+ * - Liskov Substitution: Works with any graph/statuslist implementations
+ * - Interface Segregation: Minimal interface
+ * - Dependency Inversion: Depends on abstractions (graph, statuslist)
+ *
+ * Related Spec: MCP-I §4.4, Delegation Chains
+ * Python Reference: Delegation-Revocation.md:45-67
+ */
+
+import type { DelegationCredential, CredentialStatus } from '@kya-os/contracts';
+import { DelegationGraphManager, DelegationNode } from './delegation-graph';
+import { StatusList2021Manager } from './statuslist-manager';
+
+/**
+ * Revocation event for auditing/logging
+ */
+export interface RevocationEvent {
+  /** Delegation ID that was revoked */
+  delegationId: string;
+
+  /** Whether this was the root of the cascade or a child */
+  isRoot: boolean;
+
+  /** Parent delegation ID (if cascaded) */
+  parentId?: string;
+
+  /** Timestamp */
+  timestamp: number;
+
+  /** Reason for revocation */
+  reason?: string;
+}
+
+/**
+ * Revocation hook function
+ *
+ * Called for each delegation during cascading revocation.
+ * Useful for auditing, logging, or custom logic.
+ */
+export type RevocationHook = (event: RevocationEvent) => Promise<void> | void;
+
+/**
+ * Options for cascading revocation
+ */
+export interface CascadingRevocationOptions {
+  /** Reason for revocation (for audit trail) */
+  reason?: string;
+
+  /** Optional hook called for each revocation */
+  onRevoke?: RevocationHook;
+
+  /** Maximum depth to cascade (prevents infinite loops) */
+  maxDepth?: number;
+
+  /** Dry run - don't actually revoke, just return what would be revoked */
+  dryRun?: boolean;
+}
+
+/**
+ * Cascading Revocation Manager
+ *
+ * Coordinates revocation across the delegation graph.
+ * Per Delegation-Revocation.md:45-67:
+ * - When parent revoked → all descendants revoked
+ * - Uses StatusList2021 for efficient updates
+ * - Maintains audit trail
+ */
+export class CascadingRevocationManager {
+  constructor(
+    private graph: DelegationGraphManager,
+    private statusList: StatusList2021Manager
+  ) {}
+
+  /**
+   * Revoke a delegation and all its descendants
+   *
+   * Per Delegation-Revocation.md:56-67:
+   * 1. Revoke the target delegation
+   * 2. Find all descendants
+   * 3. Revoke each descendant
+   * 4. Trigger hooks for auditing
+   *
+   * @param delegationId - The delegation ID to revoke
+   * @param options - Revocation options
+   * @returns Array of revoked delegation IDs
+   */
+  async revokeDelegation(
+    delegationId: string,
+    options: CascadingRevocationOptions = {}
+  ): Promise<RevocationEvent[]> {
+    const maxDepth = options.maxDepth || 100; // Safety limit
+    const events: RevocationEvent[] = [];
+
+    // Get the target delegation
+    const targetNode = await this.graph.getNode(delegationId);
+    if (!targetNode) {
+      throw new Error(`Delegation not found: ${delegationId}`);
+    }
+
+    // Check depth to prevent infinite loops
+    const depth = await this.graph.getDepth(delegationId);
+    if (depth > maxDepth) {
+      throw new Error(
+        `Delegation depth ${depth} exceeds maximum ${maxDepth}`
+      );
+    }
+
+    // Revoke the target delegation
+    const rootEvent = await this.revokeNode(
+      targetNode,
+      true,
+      options.reason,
+      options.dryRun
+    );
+    events.push(rootEvent);
+
+    if (options.onRevoke) {
+      await options.onRevoke(rootEvent);
+    }
+
+    // Get all descendants
+    const descendants = await this.graph.getDescendants(delegationId);
+
+    // Revoke each descendant
+    for (const descendant of descendants) {
+      const event = await this.revokeNode(
+        descendant,
+        false,
+        `Cascaded from ${delegationId}`,
+        options.dryRun,
+        delegationId
+      );
+      events.push(event);
+
+      if (options.onRevoke) {
+        await options.onRevoke(event);
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * Revoke a single node
+   *
+   * @param node - The delegation node
+   * @param isRoot - Whether this is the root of the cascade
+   * @param reason - Reason for revocation
+   * @param dryRun - If true, don't actually revoke
+   * @param parentId - Parent ID if cascaded
+   * @returns Revocation event
+   */
+  private async revokeNode(
+    node: DelegationNode,
+    isRoot: boolean,
+    reason?: string,
+    dryRun?: boolean,
+    parentId?: string
+  ): Promise<RevocationEvent> {
+    const event: RevocationEvent = {
+      delegationId: node.id,
+      isRoot,
+      parentId,
+      timestamp: Date.now(),
+      reason,
+    };
+
+    if (dryRun) {
+      return event;
+    }
+
+    // Parse the credential status from the node
+    if (node.credentialStatusId) {
+      const credentialStatus = this.parseCredentialStatus(node.credentialStatusId);
+      if (credentialStatus) {
+        await this.statusList.updateStatus(credentialStatus, true);
+      }
+    }
+
+    return event;
+  }
+
+  /**
+   * Restore (un-revoke) a delegation
+   *
+   * Note: This does NOT cascade to children.
+   * Only the specific delegation is restored.
+   *
+   * @param delegationId - The delegation ID to restore
+   * @returns Revocation event
+   */
+  async restoreDelegation(delegationId: string): Promise<RevocationEvent> {
+    const node = await this.graph.getNode(delegationId);
+    if (!node) {
+      throw new Error(`Delegation not found: ${delegationId}`);
+    }
+
+    const event: RevocationEvent = {
+      delegationId: node.id,
+      isRoot: true,
+      timestamp: Date.now(),
+      reason: 'Restored',
+    };
+
+    if (node.credentialStatusId) {
+      const credentialStatus = this.parseCredentialStatus(node.credentialStatusId);
+      if (credentialStatus) {
+        await this.statusList.updateStatus(credentialStatus, false);
+      }
+    }
+
+    return event;
+  }
+
+  /**
+   * Check if a delegation is revoked
+   *
+   * Checks both:
+   * 1. The delegation itself
+   * 2. Any of its ancestors (cascading check)
+   *
+   * Per Delegation-Revocation.md:56: If any ancestor is revoked, this is revoked.
+   *
+   * @param delegationId - The delegation ID
+   * @returns true if revoked (directly or via cascade)
+   */
+  async isRevoked(delegationId: string): Promise<{
+    revoked: boolean;
+    reason?: string;
+    revokedAncestor?: string;
+  }> {
+    // Get the chain from root to this delegation
+    const chain = await this.graph.getChain(delegationId);
+
+    // Check each node in the chain (bottom-up, most specific first)
+    for (const node of chain.reverse()) {
+      if (node.credentialStatusId) {
+        const credentialStatus = this.parseCredentialStatus(node.credentialStatusId);
+        if (credentialStatus) {
+          const isRevoked = await this.statusList.checkStatus(credentialStatus);
+          if (isRevoked) {
+            return {
+              revoked: true,
+              reason:
+                node.id === delegationId
+                  ? 'Directly revoked'
+                  : 'Ancestor revoked',
+              revokedAncestor: node.id === delegationId ? undefined : node.id,
+            };
+          }
+        }
+      }
+    }
+
+    return { revoked: false };
+  }
+
+  /**
+   * Get all revoked delegations in a subtree
+   *
+   * @param rootId - The root delegation ID
+   * @returns Array of revoked delegation IDs
+   */
+  async getRevokedInSubtree(rootId: string): Promise<string[]> {
+    const descendants = await this.graph.getDescendants(rootId);
+    const revoked: string[] = [];
+
+    // Check root
+    const rootRevoked = await this.isRevoked(rootId);
+    if (rootRevoked.revoked) {
+      revoked.push(rootId);
+    }
+
+    // Check each descendant
+    for (const node of descendants) {
+      const isRevoked = await this.isRevoked(node.id);
+      if (isRevoked.revoked) {
+        revoked.push(node.id);
+      }
+    }
+
+    return revoked;
+  }
+
+  /**
+   * Parse credential status from stored ID
+   *
+   * The credentialStatusId is stored as a composite:
+   * "statusListUrl#index"
+   *
+   * @param credentialStatusId - The stored credential status ID
+   * @returns Parsed CredentialStatus, or null if invalid
+   */
+  private parseCredentialStatus(
+    credentialStatusId: string
+  ): CredentialStatus | null {
+    const match = credentialStatusId.match(/^(.+)#(\d+)$/);
+    if (!match) return null;
+
+    const [, statusListCredential, indexStr] = match;
+    const index = parseInt(indexStr, 10);
+
+    return {
+      id: credentialStatusId,
+      type: 'StatusList2021Entry',
+      statusPurpose: 'revocation', // Assume revocation (could be enhanced)
+      statusListIndex: index.toString(),
+      statusListCredential,
+    };
+  }
+
+  /**
+   * Validate that a delegation can be used
+   *
+   * Checks:
+   * 1. The delegation itself is not revoked
+   * 2. No ancestors are revoked
+   * 3. The chain is valid
+   *
+   * @param delegationId - The delegation ID
+   * @returns Validation result
+   */
+  async validateDelegation(delegationId: string): Promise<{
+    valid: boolean;
+    reason?: string;
+  }> {
+    // Check if revoked
+    const revokedCheck = await this.isRevoked(delegationId);
+    if (revokedCheck.revoked) {
+      return {
+        valid: false,
+        reason: revokedCheck.revokedAncestor
+          ? `Ancestor ${revokedCheck.revokedAncestor} is revoked`
+          : 'Delegation is revoked',
+      };
+    }
+
+    // Validate chain structure
+    const chainValidation = await this.graph.validateChain(delegationId);
+    if (!chainValidation.valid) {
+      return chainValidation;
+    }
+
+    return { valid: true };
+  }
+}
+
+/**
+ * Create a cascading revocation manager
+ *
+ * Convenience factory function.
+ *
+ * @param graph - Delegation graph manager
+ * @param statusList - StatusList2021 manager
+ * @returns CascadingRevocationManager instance
+ */
+export function createCascadingRevocationManager(
+  graph: DelegationGraphManager,
+  statusList: StatusList2021Manager
+): CascadingRevocationManager {
+  return new CascadingRevocationManager(graph, statusList);
+}