release: WRNexusJS 0.8.0

packages/jwt/README.md

@@ -130,3 +130,62 @@ app.use(jwtAuth({ secret: process.env.JWT_SECRET!, required: false }));
 - Integrates with [`@wrnexus/core`](../core) for `Context`, `Middleware`, and
   `ctx.user`; it complements the framework's cookie/session auth with a
   stateless bearer-token flow for API and mobile clients.
+
+## Access, refresh, scope, and cookie helpers
+
+```ts
+import {
+  createAccessToken,
+  createRefreshToken,
+  verifyAccessToken,
+  verifyRefreshToken,
+  extractBearerToken,
+  requireScopes,
+  jwtCookie,
+} from "@wrnexus/jwt";
+```
+
+The helpers add explicit `type: "access" | "refresh"` claims, scope checks, refresh-token family metadata, no-store token responses, and secure cookie defaults. `__Host-` cookies are rejected unless they use `Path=/` and `Secure`; `SameSite=None` is rejected without `Secure`.
+
+## 0.8 helper kit
+
+```ts
+import {
+  createTokenPair,
+  verifyAccessToken,
+  verifyRefreshToken,
+  extractBearerToken,
+  readJwtCookie,
+  jwtCookie,
+  clearJwtCookie,
+  requireScopes,
+} from "@wrnexus/jwt";
+
+const pair = await createTokenPair(user.id, {
+  accessSecret: process.env.JWT_ACCESS_SECRET!,
+  refreshSecret: process.env.JWT_REFRESH_SECRET!,
+  scopes: ["profile:read"],
+  family: sessionFamily,
+});
+```
+
+The helper kit validates `__Host-` cookie invariants, cookie names and paths, `SameSite=None` security, typed access/refresh token types, scope requirements, and no-store token responses.
+In addition to local HS256 secrets/keyrings, the package verifies standards-based
+RS256 tokens through bounded remote JWKS caches:
+
+```ts
+import { createRemoteJwks, verifyJwtWithJwks } from "@wrnexus/jwt";
+
+const jwks = createRemoteJwks("https://issuer.example/.well-known/jwks.json");
+const claims = await verifyJwtWithJwks(token, jwks, {
+  issuer: "https://issuer.example",
+  audience: "my-api",
+  maxAge: 300,
+});
+```
+
+JWKS URLs must use HTTPS. Responses have key-count/byte limits, accept only
+RS256 signing RSA keys, deduplicate concurrent refreshes, cache imported public
+keys, and force an immediate refresh for an unknown `kid` so issuer rotation
+does not wait for cache expiry. Never use decoded-but-unverified claims for an
+authorization decision.