Implemented the capability token codec

[El-swaggerito]

Description

Implemented a dependency-light capability token codec for GuildPass Core that signs constrained payloads and verifies integrity, expiry, audience, and optional scope requirements. This is a generic signed capability token primitive only - it is not an authentication system and does not replace user sessions or wallet authentication.

Linked Issue

Closes #371

Type of Change

• ✨ New feature / endpoint

Changes Made

• Created new package: @guildpass/capability-token - A standalone capability token codec with no dependencies on authentication, membership, or API services
• Implemented CapabilityPayload: Versioned payload structure with subject, audience, scopes, issuedAt, expiresAt, and nonce
• Built HMAC-SHA256 signing: Using Node.js crypto module with timing-safe signature comparison to prevent timing attacks
• Implemented URL-safe token encoding: Base64url encoding for compact, web-friendly tokens
• Token verification: Signature validation, payload decoding, and comprehensive validation
• Expiry validation: Rejects expired tokens based on expiresAt timestamp
• Future-date tolerance: Rejects tokens issued beyond allowed clock skew (default: 60 seconds)
• Audience enforcement: Optionally validates expected audience to prevent token misuse
• Scope validation: Optionally validates required scopes for fine-grained access control
• Version support: Supports version 1 with extensible versioning for future compatibility
• Maximum token size: Enforces 4KB default limit to prevent denial-of-service attacks
• Security properties: Timing-safe signature comparison, secrets never emitted in errors
• Utility functions: hasScope(), hasAllScopes(), hasAnyScope(), verifyTokenOrThrow() for common operations
• No persistence: Tokens are stateless - revocation is explicitly out of scope

Test Evidence

pnpm --filter @guildpass/capability-token test

Output:

✔ Capability Token Codec (23.490347ms)
ℹ tests 51
ℹ suites 18
ℹ pass 51
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 344.079514

Smart Contract Checklist (complete if ⛓️ checked above)

N/A - This is a TypeScript package, not a smart contract

General Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue
• npm run typecheck passes (or pnpm typecheck)
• npm run lint passes (N/A - no linting configured for this package)
• npm run test passes — all tests green (or pnpm test)
• Prisma schema changes include a migration file (N/A - no database changes)
• New API endpoints are documented in OpenAPI (N/A - this is a library package, not an API)
• No secrets, keys, or wallet addresses introduced
• .env.example updated if new env variables were added (N/A - no env variables)
• Documentation updated if new behaviour was introduced (comprehensive JSDoc comments in source)

Additional Notes

• Independence: This package is independently implementable and does not depend on authentication, membership, or API issues being completed first
• No external dependencies: Uses only Node.js built-in crypto module
• Security: Timing-safe signature comparison prevents timing attacks, secrets are never exposed in error messages
• Stateless: No database storage required - tokens are self-contained and verifiable
• Revocation: Explicitly out of scope as documented - this is a codec primitive only
• Not authentication: This is NOT an authentication system and must not replace user sessions or wallet authentication
• Short-lived: Designed for short-lived internal authorization capabilities between trusted components