Resolve #2743: Document JWT Node crypto and decode trust boundaries#2763
Merged
ayden94 merged 1 commit intoJul 14, 2026
Merged
Conversation
State the Node runtime boundary for @fluojs/jwt signing, verification, JWKS key parsing, and refresh-token id generation. Lazy node:crypto loading is an import-time safety property only and does not make signing or verification portable across runtimes. Bun satisfies the node:crypto requirement through its Node compatibility layer; Deno and Cloudflare Workers are not supported JWT signing/verification runtimes. Explicitly prohibit authorization decisions from JwtService.decode() output. decode() reads the payload without verifying the signature or any claim, so the returned object is unverified input. Use verify() first and read identity from the normalized JwtPrincipal. Updates EN/KO mirrors across: - packages/jwt/README.md and README.ko.md - docs/architecture/auth-and-jwt.md and auth-and-jwt.ko.md - book/beginner/ch14-jwt.md and ch14-jwt.ko.md - examples/auth-jwt-passport/README.md and README.ko.md - apps/docs/content/docs/guides/auth.mdx and auth.ko.mdx Closes #2743
ayden94
deleted the
issue-2743-document-jwt-node-crypto-decode-trust-boundaries
branch
July 14, 2026 01:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Linked context: #2743
Document the Node runtime boundary for
@fluojs/jwtsigning, verification, JWKS key parsing, and refresh-token id generation, and explicitly prohibit authorization decisions fromJwtService.decode()output before verification.The audit issue flagged two documentation gaps:
node:cryptoloading as edge-safe without stating that signing and verification still require a Node.js-compatiblenode:cryptoimplementation.decode()method was not documented, leaving decoded claims usable for authorization decisions despite being unverified input.Changes
packages/jwt/README.md/README.ko.md: Added "Node runtime boundary" and "decode()trust boundary" subsections under Configuration Guardrails. Lazy loading is documented as an import-time safety property only; signing/verification/JWKS/refresh-token id generation require Node.js-compatiblenode:crypto.decode()output is unverified input and must never be used for authorization decisions.docs/architecture/auth-and-jwt.md/auth-and-jwt.ko.md: Added "Node Crypto Runtime Boundary" and "decode()Trust Boundary" contract tables with source anchors.book/beginner/ch14-jwt.md/ch14-jwt.ko.md: Added two best-practice bullets covering the Node runtime boundary and thedecode()trust boundary.examples/auth-jwt-passport/README.md/README.ko.md: Added a "trust boundaries" section documenting the Node runtime requirement and thedecode()trust boundary.apps/docs/content/docs/guides/auth.mdx/auth.ko.mdx: Added "Node runtime" and "decode()trust" rows to the Operational guardrails table and two rows to the Common mistakes table.Testing
pnpm verify:platform-consistency-governance— passed.pnpm docs:sync-check— passed (42 en/ko page pairs and 10 navigation metadata pairs).packages/*/src. The existingpackages/jwt/src/runtime-boundary.test.tsalready enforces the lazynode:cryptoimport boundary, andpackages/jwt/src/service.tsalready documents thedecode()trust boundary in its TSDoc.Release impact
Docs-only change. No public API surface, package contents, or runtime behavior changed. No
.changeset/*.mdrequired.Public export documentation
decode()TSDoc inpackages/jwt/src/service.tsalready states the trust boundary.@param/@returnstags where applicable. — No exported functions changed.@exampleblocks and README scenario examples still play complementary roles.Behavioral contract
decode()trust boundary are now documented inpackages/jwt/README.md/README.ko.mdanddocs/architecture/auth-and-jwt.md/auth-and-jwt.ko.md.packages/jwt/src/runtime-boundary.test.tsalready enforces the lazynode:cryptoimport invariant. No runtime behavior changed.Platform consistency governance (SSOT)
pnpm docs:sync-checkpassed.pnpm verify:platform-consistency-governancepassed. The Node runtime boundary is backed by the existingpackages/jwt/src/runtime-boundary.test.tsregression test.node:cryptoimport claim is backed bypackages/jwt/src/runtime-boundary.test.ts.Closes #2743