@mcp-i/core 0.1.0

package/src/delegation/audience-validator.ts

@@ -0,0 +1,24 @@
+/**
+ * Delegation Audience Validation
+ *
+ * Validates if a delegation's audience matches the server DID.
+ * Supports both single server DID and multiple server DIDs.
+ */
+
+import type { DelegationRecord } from '../types/protocol.js';
+
+export function verifyDelegationAudience(
+  delegation: DelegationRecord,
+  serverDid: string
+): boolean {
+  if (!delegation.constraints.audience) {
+    return true;
+  }
+
+  const audience = delegation.constraints.audience;
+  if (typeof audience === 'string') {
+    return audience === serverDid;
+  }
+
+  return audience.includes(serverDid);
+}

package/src/delegation/bitstring.ts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ */
+
+export interface CompressionFunction {
+  compress(data: Uint8Array): Promise<Uint8Array>;
+}
+
+export interface DecompressionFunction {
+  decompress(data: Uint8Array): Promise<Uint8Array>;
+}
+
+export class BitstringManager {
+  private bits: Uint8Array;
+  private size: number;
+
+  constructor(
+    size: number,
+    private compressor: CompressionFunction,
+    private decompressor: DecompressionFunction
+  ) {
+    this.size = size;
+    const byteCount = Math.ceil(size / 8);
+    this.bits = new Uint8Array(byteCount);
+  }
+
+  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) {
+      this.bits[byteIndex]! |= 1 << bitIndex;
+    } else {
+      this.bits[byteIndex]! &= ~(1 << bitIndex);
+    }
+  }
+
+  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;
+  }
+
+  getSetBits(): number[] {
+    const setBits: number[] = [];
+    for (let i = 0; i < this.size; i++) {
+      if (this.getBit(i)) {
+        setBits.push(i);
+      }
+    }
+    return setBits;
+  }
+
+  async encode(): Promise<string> {
+    const compressed = await this.compressor.compress(this.bits);
+    return this.base64urlEncode(compressed);
+  }
+
+  static async decode(
+    encodedList: string,
+    compressor: CompressionFunction,
+    decompressor: DecompressionFunction
+  ): Promise<BitstringManager> {
+    const compressed = BitstringManager.base64urlDecode(encodedList);
+    const decompressed = await decompressor.decompress(compressed);
+
+    const size = decompressed.length * 8;
+    const manager = new BitstringManager(size, compressor, decompressor);
+    manager.bits = decompressed;
+    return manager;
+  }
+
+  getRawBits(): Uint8Array {
+    return this.bits;
+  }
+
+  getSize(): number {
+    return this.size;
+  }
+
+  private base64urlEncode(data: Uint8Array): string {
+    const base64 = this.bytesToBase64(data);
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  private static base64urlDecode(encoded: string): Uint8Array {
+    let base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) {
+      base64 += '=';
+    }
+    return BitstringManager.base64ToBytes(base64);
+  }
+
+  private bytesToBase64(bytes: Uint8Array): string {
+    const binary = Array.from(bytes)
+      .map((byte) => String.fromCharCode(byte))
+      .join('');
+    return btoa(binary);
+  }
+
+  private static base64ToBytes(base64: string): Uint8Array {
+    let standardBase64 = base64.replace(/-/g, '+').replace(/_/g, '/');
+    const paddingNeeded = (4 - (standardBase64.length % 4)) % 4;
+    standardBase64 += '='.repeat(paddingNeeded);
+
+    const binary = atob(standardBase64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  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;
+  }
+}
+
+export async function isIndexSet(
+  encodedList: string,
+  index: number,
+  decompressor: DecompressionFunction
+): Promise<boolean> {
+  const compressed = (BitstringManager as unknown as { base64urlDecode: (s: string) => Uint8Array })['base64urlDecode'](encodedList);
+  const decompressed = await decompressor.decompress(compressed);
+
+  const byteIndex = Math.floor(index / 8);
+  const bitIndex = index % 8;
+
+  if (byteIndex >= decompressed.length) {
+    return false;
+  }
+
+  return (decompressed[byteIndex]! & (1 << bitIndex)) !== 0;
+}

package/src/delegation/cascading-revocation.ts

@@ -0,0 +1,224 @@
+/**
+ * Cascading Revocation Manager
+ *
+ * Implements cascading revocation per Python POC design.
+ * When a parent delegation is revoked, all children are automatically revoked.
+ *
+ * Related Spec: MCP-I §4.4, Delegation Chains
+ */
+
+import type { CredentialStatus } from '../types/protocol.js';
+import { DelegationGraphManager, type DelegationNode } from './delegation-graph.js';
+import { StatusList2021Manager } from './statuslist-manager.js';
+
+export interface RevocationEvent {
+  delegationId: string;
+  isRoot: boolean;
+  parentId?: string;
+  timestamp: number;
+  reason?: string;
+}
+
+export type RevocationHook = (event: RevocationEvent) => Promise<void> | void;
+
+export interface CascadingRevocationOptions {
+  reason?: string;
+  onRevoke?: RevocationHook;
+  maxDepth?: number;
+  dryRun?: boolean;
+}
+
+export class CascadingRevocationManager {
+  constructor(
+    private graph: DelegationGraphManager,
+    private statusList: StatusList2021Manager
+  ) {}
+
+  async revokeDelegation(
+    delegationId: string,
+    options: CascadingRevocationOptions = {}
+  ): Promise<RevocationEvent[]> {
+    const maxDepth = options.maxDepth || 100;
+    const events: RevocationEvent[] = [];
+
+    const targetNode = await this.graph.getNode(delegationId);
+    if (!targetNode) {
+      throw new Error(`Delegation not found: ${delegationId}`);
+    }
+
+    const depth = await this.graph.getDepth(delegationId);
+    if (depth > maxDepth) {
+      throw new Error(`Delegation depth ${depth} exceeds maximum ${maxDepth}`);
+    }
+
+    const rootEvent = await this.revokeNode(
+      targetNode,
+      true,
+      options.reason,
+      options.dryRun
+    );
+    events.push(rootEvent);
+
+    if (options.onRevoke) {
+      await options.onRevoke(rootEvent);
+    }
+
+    const descendants = await this.graph.getDescendants(delegationId);
+
+    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;
+  }
+
+  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;
+    }
+
+    if (node.credentialStatusId) {
+      const credentialStatus = this.parseCredentialStatus(node.credentialStatusId);
+      if (credentialStatus) {
+        await this.statusList.updateStatus(credentialStatus, true);
+      }
+    }
+
+    return 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;
+  }
+
+  async isRevoked(delegationId: string): Promise<{
+    revoked: boolean;
+    reason?: string;
+    revokedAncestor?: string;
+  }> {
+    const chain = await this.graph.getChain(delegationId);
+
+    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 };
+  }
+
+  async getRevokedInSubtree(rootId: string): Promise<string[]> {
+    const descendants = await this.graph.getDescendants(rootId);
+    const revoked: string[] = [];
+
+    const rootRevoked = await this.isRevoked(rootId);
+    if (rootRevoked.revoked) {
+      revoked.push(rootId);
+    }
+
+    for (const node of descendants) {
+      const isRevoked = await this.isRevoked(node.id);
+      if (isRevoked.revoked) {
+        revoked.push(node.id);
+      }
+    }
+
+    return revoked;
+  }
+
+  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',
+      statusListIndex: index.toString(),
+      statusListCredential: statusListCredential!,
+    };
+  }
+
+  async validateDelegation(delegationId: string): Promise<{ valid: boolean; reason?: string }> {
+    const revokedCheck = await this.isRevoked(delegationId);
+    if (revokedCheck.revoked) {
+      return {
+        valid: false,
+        reason: revokedCheck.revokedAncestor
+          ? `Ancestor ${revokedCheck.revokedAncestor} is revoked`
+          : 'Delegation is revoked',
+      };
+    }
+
+    const chainValidation = await this.graph.validateChain(delegationId);
+    if (!chainValidation.valid) {
+      return chainValidation;
+    }
+
+    return { valid: true };
+  }
+}
+
+export function createCascadingRevocationManager(
+  graph: DelegationGraphManager,
+  statusList: StatusList2021Manager
+): CascadingRevocationManager {
+  return new CascadingRevocationManager(graph, statusList);
+}

package/src/delegation/delegation-graph.ts

@@ -0,0 +1,143 @@
+/**
+ * Delegation Graph Manager
+ *
+ * Tracks parent-child relationships between delegation credentials.
+ * Critical for cascading revocation per Delegation-Revocation.md.
+ *
+ * Related Spec: MCP-I §4.4, Delegation Chains
+ */
+
+export interface DelegationNode {
+  id: string;
+  parentId: string | null;
+  children: string[];
+  issuerDid: string;
+  subjectDid: string;
+  credentialStatusId?: string;
+}
+
+export interface DelegationGraphStorageProvider {
+  getNode(delegationId: string): Promise<DelegationNode | null>;
+  setNode(node: DelegationNode): Promise<void>;
+  getChildren(delegationId: string): Promise<DelegationNode[]>;
+  getChain(delegationId: string): Promise<DelegationNode[]>;
+  getDescendants(delegationId: string): Promise<DelegationNode[]>;
+  deleteNode(delegationId: string): Promise<void>;
+}
+
+export class DelegationGraphManager {
+  constructor(private storage: DelegationGraphStorageProvider) {}
+
+  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,
+    };
+
+    await this.storage.setNode(node);
+
+    if (params.parentId) {
+      await this.addChildToParent(params.parentId, params.id);
+    }
+
+    return node;
+  }
+
+  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}`);
+    }
+
+    if (!parent.children.includes(childId)) {
+      parent.children.push(childId);
+      await this.storage.setNode(parent);
+    }
+  }
+
+  async getNode(delegationId: string): Promise<DelegationNode | null> {
+    return this.storage.getNode(delegationId);
+  }
+
+  async getChildren(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getChildren(delegationId);
+  }
+
+  async getDescendants(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getDescendants(delegationId);
+  }
+
+  async getChain(delegationId: string): Promise<DelegationNode[]> {
+    return this.storage.getChain(delegationId);
+  }
+
+  async isAncestor(ancestorId: string, descendantId: string): Promise<boolean> {
+    const chain = await this.getChain(descendantId);
+    return chain.some((node) => node.id === ancestorId);
+  }
+
+  async getDepth(delegationId: string): Promise<number> {
+    const chain = await this.getChain(delegationId);
+    return chain.length - 1;
+  }
+
+  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' };
+    }
+
+    for (let i = 1; i < chain.length; i++) {
+      const parent = chain[i - 1]!;
+      const child = chain[i]!;
+
+      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}`,
+        };
+      }
+
+      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 };
+  }
+
+  async removeDelegation(delegationId: string): Promise<void> {
+    const node = await this.storage.getNode(delegationId);
+    if (!node) return;
+
+    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);
+      }
+    }
+
+    await this.storage.deleteNode(delegationId);
+  }
+}
+
+export function createDelegationGraph(
+  storage: DelegationGraphStorageProvider
+): DelegationGraphManager {
+  return new DelegationGraphManager(storage);
+}