Implement a framework-independent SDK response schema guard system

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): validation, type-safety, security, expert

Background

TypeScript types disappear at runtime. GuildPass SDK cannot safely assume that every response received from a remote API matches its compile-time interfaces.

A malformed or incompatible response should fail at the SDK boundary with useful context rather than propagating invalid data throughout an application.

This issue introduces a lightweight runtime response validation system that remains independent of any specific endpoint.

Problem

The SDK currently has no common mechanism for verifying unknown runtime data before exposing it as typed public data.

Blind type assertions such as response as Membership can hide server incompatibilities and malformed payloads.

Expected Outcome

Implement a small framework-independent validation abstraction that can build reusable response guards and return structured validation failures.

Suggested Implementation

Define a contract conceptually similar to:

interface Schema<T> {
  parse(input: unknown): ValidationResult<T>;
}

The implementation should support primitives required for normal SDK response schemas, such as:

• string;
• finite number;
• boolean;
• null;
• literal values;
• optional values;
• arrays;
• objects with explicitly declared keys;
• unions where practical.

The system should:

• validate unknown runtime data;
• return strongly typed successful output;
• provide structured errors including a path such as data.members[2].id;
• reject unexpected value types;
• define whether unknown object keys are preserved, stripped, or rejected;
• limit validation depth to avoid pathological recursive data;
• avoid executing arbitrary code from input;
• remain small enough for an SDK dependency footprint;
• either use a lightweight dependency with clear justification or implement the required subset directly.

Acceptance Criteria

• Primitive schemas validate correctly.
• Object schemas validate nested fields.
• Array validation reports the failing index.
• Optional values behave correctly.
• Literal and union validation are supported if included in the public design.
• Validation failures provide machine-readable path information.
• Invalid values are never returned as successful typed data.
• Unknown-key behaviour is explicit and tested.
• Deeply nested hostile input is bounded safely.
• Unit tests cover nested valid payloads and multiple malformed response shapes.
• The public API does not require Fastify, Zod, or GuildPass Core internals.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No concrete membership or access response schema is required for completion.

Likely Affected Files/Directories

src/validation/ or equivalent focused module
src/types/
tests/

Independence Requirement

This issue must be independently implementable against the current SDK baseline and must not depend on any API endpoint, transport, or domain feature issue.

[Santia2004]

Hi team! I’d love to work on this issue. I have solid experience with the tech stack, understand the requirements, and can deliver a clean implementation with full test coverage following your project guidelines. Could you please assign this to me? Thanks!

[Okorie2000-code]

Hi Maintainer, I’ve reviewed the issue and the scope is clear. I’m ready to implement it and deliver a clean PR within 10hrs. Kindly assign it to me.

[Code-Paragon]

Hi @Lakes41
I am very experienced with this
I’d love to resolve

[grantfox-oss]

🦊 GrantFox — @Code-Paragon 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 #451)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.