Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): api, backend, security, advanced
Background
GuildPass Core will expose list endpoints for communities, memberships, events and other resources. Cursor pagination is preferable to leaking implementation-specific database offsets or exposing internal pagination state directly to clients.
This issue introduces a standalone cursor encoding and decoding primitive that API modules can reuse later.
Problem
There is currently no standard GuildPass representation for opaque pagination cursors.
Plain base64 encoding alone is not tamper resistant, and accepting arbitrary decoded client state could allow malformed or manipulated pagination inputs to reach application services.
Expected Outcome
Implement a reusable cursor codec that serialises a small typed cursor payload into an opaque token and validates it when decoding.
The implementation must be storage-independent and route-independent.
Suggested Implementation
Use a compact payload with fields such as:
interface CursorPayload {
version: 1;
sortValue: string;
id: string;
}The codec should:
- serialise the payload deterministically;
- encode the token using a URL-safe representation;
- protect the cursor from undetected tampering using HMAC or an equivalent integrity mechanism;
- accept a secret/key through explicit configuration rather than hard-coding one;
- support explicit cursor versioning;
- reject unsupported versions;
- reject malformed encoding;
- reject invalid signatures using timing-safe comparison where applicable;
- impose a maximum cursor length;
- return typed decode results or controlled errors;
- never expose secrets inside the cursor.
Do not connect the codec to Prisma queries as part of this task.
Acceptance Criteria
- Valid cursor payloads can be encoded and decoded losslessly.
- Encoded cursors are URL-safe.
- Client modification of the payload causes validation failure.
- Client modification of the signature causes validation failure.
- Unsupported cursor versions are rejected.
- Malformed base64 or token structure is handled safely.
- Oversized cursor input is rejected.
- Secrets are supplied externally to the codec.
- Signature verification does not use a naive string equality check where timing-safe comparison is appropriate.
- Unit tests cover valid, malformed, tampered and version-mismatch cases.
pnpm typecheck passes.pnpm build passes.pnpm test passes.- No database or HTTP endpoint work is included.
Likely Affected Files/Directories
packages/cursor-codec/ or equivalent isolated package
unit tests
Independence Requirement
This issue must be implemented as a standalone API primitive and must not depend on pagination endpoints, Prisma models or another campaign contribution.
Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): api, backend, security, advanced
Background
GuildPass Core will expose list endpoints for communities, memberships, events and other resources. Cursor pagination is preferable to leaking implementation-specific database offsets or exposing internal pagination state directly to clients.
This issue introduces a standalone cursor encoding and decoding primitive that API modules can reuse later.
Problem
There is currently no standard GuildPass representation for opaque pagination cursors.
Plain base64 encoding alone is not tamper resistant, and accepting arbitrary decoded client state could allow malformed or manipulated pagination inputs to reach application services.
Expected Outcome
Implement a reusable cursor codec that serialises a small typed cursor payload into an opaque token and validates it when decoding.
The implementation must be storage-independent and route-independent.
Suggested Implementation
Use a compact payload with fields such as:
The codec should:
Do not connect the codec to Prisma queries as part of this task.
Acceptance Criteria
pnpm typecheckpasses.pnpm buildpasses.pnpm testpasses.Likely Affected Files/Directories
Independence Requirement
This issue must be implemented as a standalone API primitive and must not depend on pagination endpoints, Prisma models or another campaign contribution.