Skip to content

Resolve #2743: Document JWT Node crypto and decode trust boundaries#2763

Merged
ayden94 merged 1 commit into
mainfrom
issue-2743-document-jwt-node-crypto-decode-trust-boundaries
Jul 14, 2026
Merged

Resolve #2743: Document JWT Node crypto and decode trust boundaries#2763
ayden94 merged 1 commit into
mainfrom
issue-2743-document-jwt-node-crypto-decode-trust-boundaries

Conversation

@ayden94

@ayden94 ayden94 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Linked context: #2743

Document the Node runtime boundary for @fluojs/jwt signing, verification, JWKS key parsing, and refresh-token id generation, and explicitly prohibit authorization decisions from JwtService.decode() output before verification.

The audit issue flagged two documentation gaps:

  1. JWT documentation described lazy node:crypto loading as edge-safe without stating that signing and verification still require a Node.js-compatible node:crypto implementation.
  2. The trust boundary of the public 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-compatible node: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 the decode() trust boundary.
  • examples/auth-jwt-passport/README.md / README.ko.md: Added a "trust boundaries" section documenting the Node runtime requirement and the decode() 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).
  • Package unit tests were not re-run because this PR is docs-only and does not touch any source file under packages/*/src. The existing packages/jwt/src/runtime-boundary.test.ts already enforces the lazy node:crypto import boundary, and packages/jwt/src/service.ts already documents the decode() trust boundary in its TSDoc.

Release impact

  • This PR has no consumer-visible release impact.

Docs-only change. No public API surface, package contents, or runtime behavior changed. No .changeset/*.md required.

Public export documentation

  • Changed public exports include a source-level summary. — No public exports changed. The existing decode() TSDoc in packages/jwt/src/service.ts already states the trust boundary.
  • Changed exported functions document matching @param / @returns tags where applicable. — No exported functions changed.
  • Source @example blocks and README scenario examples still play complementary roles.

Behavioral contract

  • No documented behavioral contracts were removed without migration notes.
  • New behavioral contracts are documented in the affected package README. — The Node runtime boundary and decode() trust boundary are now documented in packages/jwt/README.md / README.ko.md and docs/architecture/auth-and-jwt.md / auth-and-jwt.ko.md.
  • Intentional limitations are explicitly stated (not silently removed). — Deno and Cloudflare Workers are explicitly stated as unsupported JWT signing/verification runtimes.
  • Runtime invariants are covered by regression tests. — The existing packages/jwt/src/runtime-boundary.test.ts already enforces the lazy node:crypto import invariant. No runtime behavior changed.

Platform consistency governance (SSOT)

  • SSOT English/Korean mirror structure remains synchronized for changed governance docs. — pnpm docs:sync-check passed.
  • If platform contract docs changed, companion updates include discoverability/docs index, tooling or CI enforcement, and regression-test evidence. — pnpm verify:platform-consistency-governance passed. The Node runtime boundary is backed by the existing packages/jwt/src/runtime-boundary.test.ts regression test.
  • Any package README alignment/conformance claims are backed by the applicable platform harness tests. — The lazy node:crypto import claim is backed by packages/jwt/src/runtime-boundary.test.ts.

Closes #2743

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
ayden94 merged commit bb7ef32 into main Jul 14, 2026
10 checks passed
@ayden94
ayden94 deleted the issue-2743-document-jwt-node-crypto-decode-trust-boundaries branch July 14, 2026 01:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[audit][area:auth] Document JWT Node crypto and decode trust boundaries (priority:p2)

1 participant