@kya-os/mcp-i-core 1.3.12 → 1.3.14

package/src/delegation/statuslist-manager.ts

@@ -1,353 +0,0 @@
-/**
- * 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
-  );
-}