release: WRNexusJS 0.8.0

.publish/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.

.publish/jwt/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@wrnexus/jwt",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
-  "description": "@wrnexus/jwt — part of the WrNexus framework.",
+  "description": "HS256 JSON Web Tokens, key rotation, access/refresh helpers, scopes, cookies, and auth middleware.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.workroot.in/WorkRoot/WRNexusJS.git",
+    "directory": "packages/jwt"
+  },
+  "homepage": "https://wrnexusjs.dev/packages/jwt",
+  "bugs": {
+    "url": "https://git.workroot.in/WorkRoot/WRNexusJS/issues"
+  },
+  "keywords": [
+    "wrnexus",
+    "bun",
+    "typescript",
+    "jwt"
+  ],
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +36,11 @@
       "import": "./dist/index.js"
     }
   },
+  "dependencies": {
+    "@wrnexus/core": "^0.8.0"
+  },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ]
 }