[jeffrey-graham]

Summary

Implements HMAC-SHA256 signed, expiring, and scoped capability tokens for sensitive actions in Trellis-API.

Closes #273

Key Changes

• Capability Token Authority (src/core/auth/capability-tokens/):
  • CapabilityTokenService: issues and verifies cap_v1.<header>.<claims>.<signature> tokens with bounded TTL (MIN_CAPABILITY_TTL_SECONDS = 5, MAX_CAPABILITY_TTL_SECONDS = 900), nbf/exp checks, constant-time HMAC signature verification (timingSafeEqual), and keyring rotation (kid).
  • Action, Resource & Parameter Scope Enforcement: verifies subject binding (sub), exact or domain-wildcard action (SensitiveAction), resourceType/resourceId, and numeric/scalar operation constraints (maxAmount, minAmount, exact field match).
  • Single-Use Replay Prevention, Idempotent Retry & Rollback: tracks token consumption by jti, allows safe network retries carrying the same idempotencyKey, and rolls back consumption via executeWithCapability() / releaseConsumption() when a downstream operation fails prior to committing side effects.
  • Revocation & Subject Cutoffs: supports immediate per-token revocation (revokeToken) and subject-wide capability cutoffs (revokeSubjectCapabilities), integrating with TokenBlacklistService.
  • CapabilityTokenGuard & @RequireCapability() decorator for declarative route protection.
• Documentation & Verification:
  • Added operational, retry/rollback, and migration documentation in docs/EXPIRING_CAPABILITY_TOKENS.md.
  • Added 15 unit tests in capability-token.service.spec.ts and capability-token.guard.spec.ts.

Verification

npm run check:circular
npx jest src/core/auth/capability-tokens --runInBand