Token exchange gains input validation schemas

BGZStephen

·Mar 31, 2026·#27825feat(core): Add Zod validation schemas for token-exchange external input

Three Zod schemas validate JWT claims, key sources, and token exchange form bodies at the parse boundary, catching malformed external input before it reaches the application layer.

External input to the token-exchange flow now passes through validation schemas before processing. Three Zod schemas define the expected shape of JWT claims from identity providers, key source configurations, and RFC 8693 token exchange requests. Claims must include required fields like sub, iss, and aud, with optional fields for email, name, and roles. Key sources use a discriminated union—either static keys with inline public key data or remote JWKS endpoints with optional caching. Token exchange requests lock grant_type to the RFC 8693 URN and require a subject token. This validation-first approach closes the attack surface for external input, ensuring malformed or malicious data is rejected early.

The schemas live in the CLI package and are designed for sharing across services and controllers in subsequent tickets. Related to IAM-456.

View Original GitHub DescriptionFact Check

Summary

Introduces three Zod validation schemas for all data originating from external
sources in the token-exchange flow. These schemas act as the parse boundary for external input and are shared by services and controllers in subsequent tickets.

ExternalTokenClaimsSchema — validates JWT claims from an external identity provider:

Required: sub, iss (valid URL), aud (string or string[]), iat, exp, jti
Optional: email (valid email format), given_name, family_name, role (string or string[])

TrustedKeySourceSchema — discriminated union on type:

'static': inline public key with kid, algorithms[], key, issuer; optional
allowedRoles
'jwks': remote JWKS endpoint with url (valid URL), issuer; optional allowedRoles, cacheTtlSeconds (positive int)

TokenExchangeRequestSchema — RFC 8693 token exchange form body:

grant_type locked to urn:ietf:params:oauth:grant-type:token-exchange
subject_token required; all other RFC 8693 fields optional

All schemas export their inferred TypeScript types. 36 unit tests cover valid
input, optional fields, format validation (URL, email, positive int), and
discriminated union edge cases.

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/IAM-456

Review / Merge checklist

PR title and summary are descriptive.
(conventions)
Docs updated or follow-up ticket created.
Tests included.
PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)