@sourceregistry/node-jwt 1.4.0 → 1.5.0

package/README.md

@@ -138,6 +138,7 @@ Autodetection fails for unsupported keys:
 * Support **x5c/x5t** (X.509 cert chain + SHA-1 thumbprint)
 * Normalize **JWKS** with auto-generated `kid` and `x5t`
 * Resolve keys from **JWKS** by `kid` for verification
+* Load remote **JWKS** with caching via `JWKS.fromWeb()`
 
 ### 🔹 Example: JWKS Key Selection
 
@@ -151,6 +152,45 @@ const jwks = JWKS.normalize({ keys: [jwk] });
 // Retrieve key by kid
 const keyObject = JWKS.toKeyObject(jwks, jwk.kid);
 ```
+
+### 🔹 Example: Remote JWKS (`fromWeb`)
+
+```ts
+import { JWKS } from '@sourceregistry/node-jwt';
+
+const jwks = await JWKS.fromWeb('https://issuer.example', {
+  ttl: 60_000,
+  timeoutMs: 2_000
+});
+
+const jwk = await jwks.key('my-kid');
+const keys = await jwks.list();
+const rsaKeys = await jwks.find({ kty: 'RSA' });
+const firstSigKey = await jwks.findFirst({ use: 'sig' });
+
+// Force refresh
+await jwks.reload();
+
+// Access cached JWKS snapshot
+const current = jwks.export();
+```
+
+`fromWeb()` options:
+
+* `fetch` — custom fetch implementation (for runtimes/framework adapters)
+* `ttl` — cache TTL in ms (`0` disables automatic refresh)
+* `timeoutMs` — network timeout in ms
+* `endpointOverride` — custom endpoint (absolute or relative)
+* `overrideEndpointCheck` — skip automatic `/.well-known/jwks.json` append
+* `cache` — custom cache backend with `{ get(key), set(key, value) }`
+
+### 🔹 Local Examples
+
+See runnable examples in:
+
+* `examples/jwt.example.ts`
+* `examples/jwks.example.ts`
+
 ---
 
 ## 🛡️ Security Features
@@ -166,6 +206,42 @@ const keyObject = JWKS.toKeyObject(jwks, jwk.kid);
 
 ---
 
+## 🔏 ECDSA Signature Format: DER vs JOSE (New)
+
+For **ECDSA** algorithms (`ES256`, `ES384`, `ES512`, `ES256K`) there are two common signature encodings:
+
+- **DER** (ASN.1) — what Node.js produces by default
+- **JOSE** (`r || s` raw signature) — required by the JWT/JWS spec and used by systems like **VAPID/Web Push (WNS)**
+
+### Default behavior
+By default, this library outputs **DER** signatures for `ES*` algorithms to match Node.js/OpenSSL defaults.
+
+### Enable JOSE output
+To generate spec-compliant JOSE ECDSA signatures, set:
+
+- `signatureFormat: "jose"` in `sign()`
+
+```ts
+import { sign, verify } from "@sourceregistry/node-jwt";
+
+const token = sign(
+  { sub: "123", iat: Math.floor(Date.now() / 1000) },
+  ecPrivateKey,
+  { alg: "ES256", signatureFormat: "jose" }
+);
+
+// Verify JOSE-signed token
+const result = verify(token, ecPublicKey, { signatureFormat: "jose" });
+````
+
+### Auto-detect verification (optional)
+
+If enabled in your version, `verify()` can also validate JOSE ECDSA signatures without specifying `signatureFormat` (it will try DER first, then JOSE).
+If you want strict behavior, pass `signatureFormat: "der"` or `signatureFormat: "jose"` explicitly.
+
+> 💡 For VAPID/Web Push (e.g. Windows WNS endpoints), you typically need `ES256` with `signatureFormat: "jose"`.
+
+
 ## 📚 API Reference
 
 ### `sign(payload, secret, options?)`
@@ -197,7 +273,7 @@ Decode a JWT without verification (**unsafe**).
 
 ## 🧪 Testing
 
-* 100% branch coverage
+* High branch coverage
 * All algorithms + autodetection paths
 * All failure modes
 * Sync + Promise APIs