jose

Fixes

• jose: consume serialization members once (9bee285)
• jose: reject empty protected and JWE AAD members (8da4145)
• jose: validate serialized header values (b711d8f)
• jwe: conceal invalid decrypted CEK lengths (41fafe0)
• jwe: enforce AES-GCM tag boundaries (9a5b744)
• jwe: validate explicit encryption parameters (7a02697)
• jwk: accept empty octet-sequence keys (3f871e7)
• jwk: normalize key resolution inputs (f54ee7b)
• jwks: enforce verification key metadata (f9ba510)
• jwks: order overlapping remote reloads (9a1a913)
• jwks: reject invalid remote duration values (7bdb9e5)
• jwk: validate ext and key_ops parameters (4d91c37)
• jws: reject mixed payload encoding modes (dc69713)
• jws: validate unencoded payload strings (541f282)
• jwt: enforce explicit verification policies (b347182)
• jwt: prevent replacing protected headers (ae07d09)
• jwt: reject invalid duration inputs (282f9aa)
• jwt: validate builder claim values (ea03f83)
• jwt: validate unsecured protected headers (230c14e)
• key: validate generation and import options (15d880e)
• reject mixed b64 modes for empty General JWS payloads (61a2ef7)
• x509: reject DER truncated past its outer length (d8db9f6)

Documentation

• jwks: correct cache timestamp units (01a44d9)

Refactor

• jose: share binary input validation (eedb124)
• jose: share compact token processing internals (85e30ed)
• jwe: consolidate CBC decryption failures (1ee6f61)
• jwe: specialize compact processing (a998927)
• jwe: streamline single-recipient encryption (290aaa6)
• jwks: compact JWK Set shape validation (930c7df), references Array#every
• jwks: compact local key selection (4cb5ae5)
• jwks: compact remote resolver state (ef5eaf4)
• jws: specialize compact processing (021abf4)
• jwt: compact claim validation helpers (f390683)
• jwt: consolidate replicated claim checks (7dd5591)
• jwt: share producer claim state (52ba159)
• key: compact JWK algorithm selection (a6b29da)
• key: compact secret length parsing (cc03be8)

Fixes

• reject a JWE whose generated Key Management Parameters collide (6ed19a6)
• types: undeprecate PBES2 p2c parameter (33bf832)

Fixes

• enforce a single recipient when decrypting dir and ECDH-ES (505c383)
• reject a non-string "alg" in EmbeddedJWK (714f870)

Refactor

• index the JWS and JWE registries without a wrapper (925f3bb)
• name the "alg" source in unsupported algorithm failures (1500459)

Fixes

• require own JOSE properties for presence checks (90ab09c)

Refactor

• reduce bundle size (767d7f1)

Fixes

• types: accept host CryptoKey declarations (b48a15b)

Fixes

• compare claim values for falsy validation options (eb86956)
• forward key management parameters for a single JWE recipient (2d4f801)
• handle a zero-length JWE additional authenticated data (16ca398)
• reject a generateKeyPair crv option the algorithm does not imply (76364e9)
• reject an unencoded payload in the JWS Compact Serialization (01d053f)
• reject characters outside the Base64URL alphabet (0ebb971), references #879
• reject duplicate "crit" values when producing (31d60e1)
• reject invalid UTF-8 in JOSE Headers and JWT Claims Sets (5df3fed)
• reject truncated ASN.1 key data (7a16c66)
• surface non-ASCII token segments as JOSE errors (194fe11)
• types: correct JWK and CryptoKey types (62a196d)
• types: correct key resolver and JWT header types (e95f8c4)
• validate the clockTolerance and currentDate options are finite (ab2f18d)

Documentation

• correct subpaths and API documentation (2daec38)
• document consumer-supplied type parameters (9e9f66c)
• stop claiming the JWK "use" parameter is used during import (47a07b2)
• update CHANGELOG.md (fc51bf5)

Refactor

• assert key shape and type from the entry (971057e)
• avoid 32-bit truncation of the AES-CBC-HMAC AAD bit length (1c8c6e9)
• correct swapped JWE unprotected header type error messages (894c498)
• describe each JWS algorithm once (7375028)
• discriminate a key once (0b59a69)
• fold single-consumer modules into their consumers (c2f0ca3)
• generate and import keys from the entry (da69b68)
• keep JWE out of the JWKS and embedded-JWK paths (241dd48)
• keep JWS and JWE out of each other's bundles (2a98564)
• parse a Protected Header in one place (30f72af)
• resolve the content encryption algorithm once (98b50ab)
• tighten key property checks (fe0dc3b)
• types: add discriminated JOSE error types (f7f764e)
• types: add JOSE identifier unions and JWK narrowing (2a20f49)
• types: improve key and result inference (cb25e77)
• types: trim published declaration comments (544f179)
• unify base64 decode errors (3a91833)
• validate each token once rather than once per layer (bbdae09)
• write each algorithm identifier once (73d83b5)

Documentation

• update README.md and SECURITY.md to reflect passed EOL dates (2a84032)

Refactor

• normalize JWK export members from runtime quirks (386a3eb)

Refactor

• cleanly reject invalid PBES2 p2c (0cdb851)

Fixes

• reject failed decompression with JWEInvalid error (043b181)

Refactor

• reorganize internals, less files, smaller footprint (d4231f9)

Features

• re-introduce JWE "zip" (Compression Algorithm) Header Parameter support (b13b446)

Documentation

• clarify return of general jws and jwe (56682b4)

Refactor

• avoid export * as for google closure's compiler sake (6303d98), closes #832

Refactor

• fallback to checking instanceof for CryptoKey (901cd90), closes #765 #803 #821 #827 #828

Documentation

• add link to RFC9864 (767edde)
• link to ML-DSA for JOSE (ed4252c)
• remove mention of Edge Runtime from the readme (94fdde7)
• update README.md (25098ef)

Refactor

• eliminate named exports in the source code (f6ae30d)
• expose setKeyManagementParameters also on a GeneralEncrypt Recipient (16e6b23)
• faster path for symmetric key checks (a44c2ec)
• improve en/decoding overheads (daee426)

Features

• support AKP JWKs in calculateJwkThumbprint and calculateJwkThumbprintUri (cf2092a)
• support for the ML-DSA PQC Algorithm Identifiers (25ddce4)

Refactor

• more readability in ecdhes.ts (84da9de)
• update asn1.ts helpers (b4f8fb3)

Documentation

• add known caveats to customFetch (02e1f1e)
• mention the apu/apv parameter names in setKeyManagementParameters (6274d5a)
• update compact setKeyManagementParameters (2f44381)
• use GitHub Flavored Markdown for notes and warnings (f6b4ffc)

Refactor

• createPublicKey is not a constructor (61ded78)
• update asn1.ts helper functions (b2b611c)

Fixes

• typ checking edge-cases when it contains a slash (/) character (31e4baf)

Refactor

• removed unused claims methods (74719cf)
• reorganize jwt claim set utils (1f12d88)

Documentation

• add more symbol document, ignore ts-private fields (8b73687)
• bump typedoc (6163a8b)
• drop cdnjs links in README (a910038)
• drop denoland/x links in README and add jsr (3662b9e)
• fix key export links from docs/README.md (c8edfc2)

Refactor

• always assume structuredClone is present (f7898a9)
• hide internal private fields and drop ProduceJWT inheritance (ab18881)
• less objects when JWE JWT Replicated Header Parameters are used (c763a0e)

Fixes

• export [customFetch] symbol from the default entrypoint (1615614), closes #762

Documentation

• improve generate key/secret and import function descriptions (cd06359)

Fixes

• use [customFetch] when provided to createRemoteJWKSet (35f6509), closes #760

Refactor

• move base64url around (e1350ef)

Documentation

• add various exported symbol descriptions (3b8ff71)
• add various exported symbol descriptions (fc4e7da)
• add various exported symbol descriptions (74f02c8)
• update base64url function descriptions (03d72c8)

Refactor

• types: make JWKParameters.kty compatible with @types/node and @types/web (bb6ccfe)

Documentation

• add various exported symbol descriptions (f52c2ff)

Refactor

• optimize base64 with tc39/proposal-arraybuffer-base64 (8a0da69), closes #752
• update getSPKI to use crypto.createPublicKey when available (92392a0), closes #752
• use Double HMAC pattern for AES-CBC tag comparison (f3ba4c7), closes #752

Documentation

• remove root module tag so that README.md shows up on jsr.io (ee70698)

Documentation

• add module tags to all entrypoints (a5687aa)

Fixes

• types: update build to include extensions in type imports (9b96672)

⚠ BREAKING CHANGES

• The PEMImportOptions type interface is renamed to KeyImportOptions.
• all builds and bundles now use ES2022 as target
• createRemoteJWKSet now uses fetch, because of that its Node.js only options.agent property has been removed and new fetch-related options were added
• drop support for Ed448 and X448
• drop support for JWK key_ops and CryptoKey usages "(un)wrapKey" and "deriveKey"
• resolved keys returned as part of verify/decrypt operations (when get key functions are used) are always normalized to either Uint8Array / CryptoKey depending on what's more efficient for the executed operation
• Key "Type" Generics are removed
• CJS-style require is now only possible when require(esm) support is present in the Node.js runtime
• private KeyObject instances can no longer be used for verify operations
• private KeyObject instances can no longer be used for encryption operations
• generateSecret, generateKeyPair, importPKCS8, importSPKI, importJWK, and importX509 now yield a CryptoKey instead of a KeyObject in Node.js
• drop support for Node.js 18.x and earlier
• runtime-specific npm releases (jose-browser-runtime, jose-node-cjs-runtime, and jose-node-esm-runtime) are no longer maintained or supported
• removed secp256k1 JWS support
• removed deprecated experimental APIs
• removed RSA1_5 JWE support

Features

• enable CryptoKey and KeyObject inputs in JWK thumbprint functions (6fc9c44)
• JSON Web Key is now an allowed input everywhere (ebda967)

Refactor

• always use infered CryptoKey (c4abaa2)
• backport the Ed25519 JWS Algorithm Identifier support (7a94cb9)
• drop support for Ed448 and X448 (2fae1c4)
• drop support for JWK key_ops and CryptoKey usages "(un)wrapKey" and "deriveKey" (ef918be)
• ensure export functions continue to work with KeyObject inputs (28e9e68)
• hardcode the cryptoRuntime export since it is now always WebCryptoAPI (e00f273)
• JWK import extractable default for public keys is now true (64dcebe)
• PEM import extractable default for public keys is now true (4e9f114)
• removed deprecated APIs (5352083)
• removed secp256k1 JWS support (e2b58a5)
• restructure src/lib and src/runtime now that runtime is fixed (9b236ce)
• target is now ES2022 everywhere (aa590d5)
• update importJWK args to align with other import functions (355a2dd)
• WebCryptoAPI is now the only crypto used (161de46)

Features

• support fully specified Ed25519 algorithm identifier (c39f57d)

Reverts

• Revert "refactor(build): simplify package exports" (2ef3a52)

Refactor

• build: simplify package exports (4783f7f)

Refactor

• types: update error definitions (510c5ca)

Refactor

• use as Type for type assertions instead of <Type> (c4dc24d)

Refactor

• types: remove index signatures from JWK interfaces (ccf0cda)

Fixes

• types: add missing index signature on the convenience JWK types (90a93dc)

Features

• allow JWK objects as "key" input to sign and verify (c6302ea)

This method of passing private or public keys does not yield the same performance as passing a CryptoKey or KeyObject instances, its main purpose is for convenience or for when you're not going to be re-using the same set of keys for the operation, in which case you should use one of the import key methods to obtain a CryptoKey or KeyObject.

Example Signing

const alg = "RS256";
const jwk = {
  kty: "RSA",
  n: "whYOFK2Ocbbpb_zVypi9SeKiNUqKQH0zTKN1-6fpCTu6ZalGI82s7XK3tan4dJt90ptUPKD2zvxqTzFNfx4HHHsrYCf2-FMLn1VTJfQazA2BvJqAwcpW1bqRUEty8tS_Yv4hRvWfQPcc2Gc3-_fQOOW57zVy-rNoJc744kb30NjQxdGp03J2S3GLQu7oKtSDDPooQHD38PEMNnITf0pj-KgDPjymkMGoJlO3aKppsjfbt_AH6GGdRghYRLOUwQU-h-ofWHR3lbYiKtXPn5dN24kiHy61e3VAQ9_YAZlwXC_99GGtw_NpghFAuM4P1JDn0DppJldy3PGFC0GfBCZASw",
  e: "AQAB",
  d: "VuVE_KEP6323WjpbBdAIv7HGahGrgGANvbxZsIhm34lsVOPK0XDegZkhAybMZHjRhp-gwVxX5ChC-J3cUpOBH5FNxElgW6HizD2Jcq6t6LoLYgPSrfEHm71iHg8JsgrqfUnGYFzMJmv88C6WdCtpgG_qJV1K00_Ly1G1QKoBffEs-v4fAMJrCbUdCz1qWto-PU-HLMEo-krfEpGgcmtZeRlDADh8cETMQlgQfQX2VWq_aAP4a1SXmo-j0cvRU4W5Fj0RVwNesIpetX2ZFz4p_JmB5sWFEj_fC7h5z2lq-6Bme2T3BHtXkIxoBW0_pYVnASC8P2puO5FnVxDmWuHDYQ",
  p: "07rgXd_tLUhVRF_g1OaqRZh5uZ8hiLWUSU0vu9coOaQcatSqjQlIwLW8UdKv_38GrmpIfgcEVQjzq6rFBowUm9zWBO9Eq6enpasYJBOeD8EMeDK-nsST57HjPVOCvoVC5ZX-cozPXna3iRNZ1TVYBY3smn0IaxysIK-zxESf4pM",
  q: "6qrE9TPhCS5iNR7QrKThunLu6t4H_8CkYRPLbvOIt2MgZyPLiZCsvdkTVSOX76QQEXt7Y0nTNua69q3K3Jhf-YOkPSJsWTxgrfOnjoDvRKzbW3OExIMm7D99fVBODuNWinjYgUwGSqGAsb_3TKhtI-Gr5ls3fn6B6oEjVL0dpmk",
  dp: "mHqjrFdgelT2OyiFRS3dAAPf3cLxJoAGC4gP0UoQyPocEP-Y17sQ7t-ygIanguubBy65iDFLeGXa_g0cmSt2iAzRAHrDzI8P1-pQl2KdWSEg9ssspjBRh_F_AiJLLSPRWn_b3-jySkhawtfxwO8Kte1QsK1My765Y0zFvJnjPws",
  dq: "KmjaV4YcsVAUp4z-IXVa5htHWmLuByaFjpXJOjABEUN0467wZdgjn9vPRp-8Ia8AyGgMkJES_uUL_PDDrMJM9gb4c6P4-NeUkVtreLGMjFjA-_IQmIMrUZ7XywHsWXx0c2oLlrJqoKo3W-hZhR0bPFTYgDUT_mRWjk7wV6wl46E",
  qi: "iYltkV_4PmQDfZfGFpzn2UtYEKyhy-9t3Vy8Mw2VHLAADKGwJvVK5ficQAr2atIF1-agXY2bd6KV-w52zR8rmZfTr0gobzYIyqHczOm13t7uXJv2WygY7QEC2OGjdxa2Fr9RnvS99ozMa5nomZBqTqT7z5QV33czjPRCjvg6FcE",
};

const jwt = await new jose.SignJWT({ "urn:example:claim": true })
  .setProtectedHeader({ alg })
  .setIssuedAt()
  .setIssuer("urn:example:issuer")
  .setAudience("urn:example:audience")
  .setExpirationTime("2h")
  .sign(jwk);

console.log(jwt);

Example Verification

const alg = "RS256";
const jwk = {
  kty: "RSA",
  n: "whYOFK2Ocbbpb_zVypi9SeKiNUqKQH0zTKN1-6fpCTu6ZalGI82s7XK3tan4dJt90ptUPKD2zvxqTzFNfx4HHHsrYCf2-FMLn1VTJfQazA2BvJqAwcpW1bqRUEty8tS_Yv4hRvWfQPcc2Gc3-_fQOOW57zVy-rNoJc744kb30NjQxdGp03J2S3GLQu7oKtSDDPooQHD38PEMNnITf0pj-KgDPjymkMGoJlO3aKppsjfbt_AH6GGdRghYRLOUwQU-h-ofWHR3lbYiKtXPn5dN24kiHy61e3VAQ9_YAZlwXC_99GGtw_NpghFAuM4P1JDn0DppJldy3PGFC0GfBCZASw",
  e: "AQAB",
};

const jwt =
  "eyJhbGciOiJSUzI1NiJ9.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6dHJ1ZSwiaWF0IjoxNjY5MDU2NDg4LCJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSJ9.gXrPZ3yM_60dMXGE69dusbpzYASNA-XIOwsb5D5xYnSxyj6_D6OR_uR_1vqhUm4AxZxcrH1_-XJAve9HCw8az_QzHcN-nETt-v6stCsYrn6Bv1YOc-mSJRZ8ll57KVqLbCIbjKwerNX5r2_Qg2TwmJzQdRs-AQDhy-s_DlJd8ql6wR4n-kDZpar-pwIvz4fFIN0Fj57SXpAbLrV6Eo4Byzl0xFD8qEYEpBwjrMMfxCZXTlAVhAq6KCoGlDTwWuExps342-0UErEtyIqDnDGcrfNWiUsoo8j-29IpKd-w9-C388u-ChCxoHz--H8WmMSZzx3zTXsZ5lXLZ9IKfanDKg";

const { payload, protectedHeader } = await jose.jwtVerify(jwt, jwk, {
  issuer: "urn:example:issuer",
  audience: "urn:example:audience",
});

console.log(protectedHeader);
console.log(payload);

Features

• add subpath module exports (72ecff6)

Refactor

• omit LocalJWKSet export since it's no longer needed for RemoteJWKSet (c502731)

Features

• graduate jwksCache to stable API (0f09c12)

Fixes

• add sideEffects:false to nested ESM package.json files (f3aff1c)

Refactor

• CryptoKey normalization is not always async (b7751f5)
• weak cache normalized CryptoKey instances (32b25a5)

Fixes

• ensure KeyObject type in Web API encrypt/decrypt (b7920bd)

Refactor

• normalize is always defined for Web API runtimes (7bcb103)

Fixes

• workaround turbo's eager optimizations (723a042), closes #690

Features

• support KeyObject inputs in WebCryptoAPI runtimes given compatibility (e178b8f)

Features

• add experimental support for edge compute runtimes JWKS caching (ab166e2), closes #551 #661 #653 #415
  • see docs

Fixes

• ensure latest release on npm is v5.x (a9b2a30)

Features

• expose JWT's payload in JWTClaimValidationFailed instances (58bcffb), closes #680

Refactor

• add explicit return types everywhere (cc2b2d7)

Features

• allow observing remote JWKS resolver state and its manual reload (fa8b639)

Refactor

• if should not be the only statement in else blocks (a6b716b)

Refactor

• use createLocalJWKSet instead of LocalJWKSet in createRemoteJWKSet (a7c566c)

Refactor

• move iv generation and optional outputs around (05c4351)

Fixes

• types: iv and tag is optional in JSON serializations (53019cd)

Fixes

• build: refactor export targets for browser, node cjs, and node esm builds (50cbc65)

Features

• extend JWT NumericDate setter syntax (ae363c3)

Build

• add errors and base64url submodule exports (564412d)

Fixes

• do not mutate JWTVerifyOptions.requiredClaims (1bf9cec), closes #610

Refactor

• deprecate the RSA1_5 JWE Algorithm (f746da1)

Features

• add payload generics to jose.decodeJwt (9de49e2), closes #604

Fixes

• createRemoteJWKSet: ensure a default user-agent header is present (887dd3c), closes #600

Fixes

• also use ES2020 in the CDN bundles (8c4d390)