// src/core/security/ICapabilityToken.ts

/**
 * Capability token - unforgeable reference to a right.
 *
 * Mark Miller's capability model:
 * - Holding a capability = having the right
 * - Capabilities can be attenuated but never amplified
 * - Delegation creates chains (parent field)
 *
 * See: Vision/27-SECURITY-FEDERATION-DRAFT.md Section 3
 */

// ═══════════════════════════════════════════════════════════════════════════
// CAPABILITY RIGHTS (Expert Consensus: Mark Miller + Uncle Bob)
// Well-known rights get compile-time checking.
// Custom namespace-prefixed rights allow extensibility.
// ═══════════════════════════════════════════════════════════════════════════

/** Well-known capability rights (compile-time checked) */
export type WellKnownRight = 'read' | 'write' | 'spawn' | 'delegate' | 'invoke' | 'emit';

/** Custom namespace-prefixed rights (extensible) */
export type CustomRight = `${string}:${string}`;

/**
 * Capability right - typed core + extensible namespace.
 *
 * Examples:
 * - 'read', 'write', 'invoke' - well-known, typos caught at compile time
 * - 'acme:approve-invoice' - custom namespace right, validated at runtime
 *
 * Mark Miller: "This preserves extensibility while catching typos.
 * 'wirte' fails. 'acme:approve' passes."
 */
export type CapabilityRight = WellKnownRight | CustomRight;

// ═══════════════════════════════════════════════════════════════════════════

export interface ICapabilityToken {
  /** Unique token ID (e.g., 'cap-1702500000000-abc123') */
  id: string;

  /** Who minted this capability (realm mount path) */
  issuer: string;

  /** What this capability grants access to (mount path or pattern) */
  subject: string;

  /** Rights granted - typed for safety, extensible for custom namespaces */
  rights: CapabilityRight[];

  /** Additional restrictions (e.g., { maxCalls: 100, expiresAfterUse: true }) */
  caveats: Record<string, unknown>;

  /** Timestamp when issued (ms since epoch) */
  issuedAt: number;

  /** Timestamp when expires (ms since epoch) */
  expiresAt: number;

  /** Parent token ID if delegated (for chain verification) */
  parent?: string;

  /** Cryptographic signature (Phase 2+ - not implemented in Phase 1) */
  signature?: string;
}
