// src/core/security/ICapabilityRegistry.ts

import type { ICapabilityToken } from './ICapabilityToken';

/**
 * Registry for looking up capability tokens by ID.
 *
 * Mark Miller (Capability Security, E Language):
 *   "Capabilities are unforgeable references. The registry provides
 *    a way to look up capabilities by their identifier for verification."
 *
 * This enables cross-realm verification by providing a shared lookup
 * mechanism for capability tokens referenced in message headers.
 *
 * See: Vision/27-SECURITY-FEDERATION-DRAFT.md
 */
export interface ICapabilityRegistry {
  /**
   * Get a capability token by its ID.
   *
   * @param id - Capability token ID
   * @returns The capability token, or undefined if not found
   */
  get(id: string): ICapabilityToken | undefined;

  /**
   * Register a capability token.
   *
   * @param token - The capability token to register
   */
  register(token: ICapabilityToken): void;

  /**
   * Revoke a capability token by its ID.
   *
   * Mark Miller: "Revocation is fundamental to capability security.
   * A capability can be revoked at any time by its issuer."
   *
   * @param id - Capability token ID to revoke
   * @returns true if token was found and revoked, false otherwise
   */
  revoke(id: string): boolean;

  /**
   * Check if a capability token is valid (registered and not revoked).
   *
   * @param id - Capability token ID
   * @returns true if token is valid
   */
  isValid(id: string): boolean;

  /**
   * Get all capability tokens issued to a specific principal.
   *
   * @param principal - Principal identifier (e.g., mount path)
   * @returns Array of capability tokens for this principal
   */
  getForPrincipal(principal: string): ICapabilityToken[];
}
