Implement a secure signed capability token codec for internal GuildPass authorisation

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): security, access-control, backend, expert

Background

GuildPass may need to represent short-lived internal authorisation capabilities that can be passed between trusted components without requiring each consumer to query a central store for every operation.

This issue introduces a generic signed capability token primitive only. It is not an authentication system and must not replace user sessions or wallet authentication.

Problem

There is currently no standard Core mechanism for issuing and verifying compact, tamper-evident capability payloads with clear expiry and scope semantics.

A poorly designed token can be replayed indefinitely, modified by clients or accepted outside its intended audience.

Expected Outcome

Build a dependency-light capability token codec that signs a constrained payload and verifies integrity, expiry, audience and optional scope requirements.

Suggested Implementation

Define a payload similar to:

interface CapabilityPayload {
  version: 1;
  subject: string;
  audience: string;
  scopes: string[];
  issuedAt: number;
  expiresAt: number;
  nonce: string;
}

The implementation should:

• encode payloads into a URL-safe token;
• sign the token using HMAC-SHA256 or another justified symmetric mechanism;
• accept the secret/key through explicit configuration;
• reject modified payloads or signatures;
• verify expiry;
• reject tokens issued unreasonably far in the future;
• enforce an expected audience;
• optionally enforce required scopes;
• validate payload shape at runtime;
• support token versioning;
• impose maximum token size;
• use timing-safe signature comparison;
• avoid storing token state in a database;
• clearly document that revocation is outside the scope of this primitive.

Acceptance Criteria

• Valid signed capability tokens can be issued and verified.
• Payload tampering causes verification failure.
• Signature tampering causes verification failure.
• Expired tokens are rejected.
• Future-dated tokens beyond an allowed tolerance are rejected.
• Audience mismatches are rejected.
• Required-scope checks behave deterministically.
• Unsupported token versions are rejected.
• Malformed payloads fail safely.
• Signature comparison is timing-safe.
• Secrets are never hard-coded or emitted in errors.
• Unit tests include fixed deterministic vectors.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No session, wallet-authentication or persistence feature is introduced.

Likely Affected Files/Directories

packages/capability-token/ or equivalent isolated package
unit tests

Independence Requirement

This issue must be independently implementable from main and must not rely on an authentication, membership or API issue being completed first.

[safal207]

Hi — one boundary question before implementation:

Should the nonce be treated only as a unique token identifier, or is any replay-prevention guarantee expected despite this primitive intentionally having no persistence or revocation store?

That distinction matters because it is easy to build a token that is correctly signed but still unsafe in practice: it may be accepted for the wrong audience, outside its valid time window, with malformed scopes, or repeatedly reused while appearing “secure.”

I’d like to take this issue. My recent work has focused on exactly these boundaries: deterministic request binding, authenticated actor identity, replay semantics, and fail-closed verification.

My implementation approach would be:

• define a versioned, runtime-validated capability payload with deterministic canonical encoding;
• issue URL-safe HMAC-SHA256 tokens using explicit key configuration;
• verify signatures with timing-safe comparison before evaluating time, audience, and scope policy;
• enforce token-size, clock-skew, expiry, malformed-input, and future-issued bounds;
• add fixed deterministic vectors and negative controls for payload/signature tampering, audience mismatch, scope mismatch, expiry, oversized tokens, and input mutation.

I will keep the security claim precise: without durable consumed-nonce state, this codec can provide integrity, expiry, audience, and scope enforcement, but it cannot honestly guarantee single-use replay prevention.

I can deliver a focused, tested PR within 24 hours of assignment and will wait for assignment before coding.

[El-swaggerito]

Better give me that ting

[grantfox-oss]

🦊 GrantFox — @El-swaggerito has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #371)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@El-swaggerito's PR #406 was approved and merged by @Lakes41.

🏆 @El-swaggerito: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (956 total points). Track your full progress on GrantFox.

👏 Great work, @El-swaggerito! Keep contributing to Adamantine-guild.