chore(release): 6.0.5

panva · Feb 23, 2025 · f6042ad · f6042ad
1 parent f52c2ff
commit f6042ad
Show file tree

Hide file tree

Showing 181 changed files with 20,882 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [6.0.5](https://github.com/panva/jose/compare/v6.0.4...v6.0.5) (2025-02-23)
+
+
+### Refactor
+
+* **types:** make JWKParameters.kty compatible with @types/node and @types/web ([bb6ccfe](https://github.com/panva/jose/commit/bb6ccfed3efd5c84c540c2a1f621b9d2951f2b84))
+
+
+### Documentation
+
+* add various exported symbol descriptions ([f52c2ff](https://github.com/panva/jose/commit/f52c2ff0c3edbe30b32a4c9858199bfbc9f9367e))
+
 ## [6.0.4](https://github.com/panva/jose/compare/v6.0.3...v6.0.4) (2025-02-22)
 
 

diff --git a/dist/deno/README.md b/dist/deno/README.md
@@ -0,0 +1,96 @@
+# `jose` API Documentation
+
+`jose` is JavaScript module for JSON Object Signing and Encryption, providing support for JSON Web Tokens (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), JSON Web Key Set (JWKS), and more. The module is designed to work across various Web-interoperable runtimes including Node.js, browsers, Cloudflare Workers, Deno, Bun, and others.
+
+## Sponsor
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../sponsor/Auth0byOkta_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="../sponsor/Auth0byOkta_light.png">
+  <img height="65" align="left" alt="Auth0 by Okta" src="../sponsor/Auth0byOkta_light.png">
+</picture>
+
+If you want to quickly add JWT authentication to JavaScript apps, feel free to check out Auth0's JavaScript SDK and free plan. [Create an Auth0 account; it's free!][sponsor-auth0]<br><br>
+
+## [💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+## Available modules
+
+**`example`** Deno import
+```js
+import * as jose from 'https://deno.land/x/[email protected]/index.ts'
+```
+
+### JSON Web Tokens (JWT)
+
+The `jose` module supports JSON Web Tokens (JWT) and provides functionality for signing and verifying tokens, as well as their JWT Claims Set validation.
+
+- [JWT Claims Set Validation & Signature Verification](https://github.com/panva/jose/blob/v6.0.5/docs/jwt/verify/functions/jwtVerify.md) using the `jwtVerify` function
+  - [Using a remote JSON Web Key Set (JWKS)](https://github.com/panva/jose/blob/v6.0.5/docs/jwks/remote/functions/createRemoteJWKSet.md)
+  - [Using a local JSON Web Key Set (JWKS)](https://github.com/panva/jose/blob/v6.0.5/docs/jwks/local/functions/createLocalJWKSet.md)
+- [Signing](https://github.com/panva/jose/blob/v6.0.5/docs/jwt/sign/classes/SignJWT.md) using the `SignJWT` class
+- Utility functions
+  - [Decoding Token's Protected Header](https://github.com/panva/jose/blob/v6.0.5/docs/util/decode_protected_header/functions/decodeProtectedHeader.md)
+  - [Decoding JWT Claims Set](https://github.com/panva/jose/blob/v6.0.5/docs/util/decode_jwt/functions/decodeJwt.md) prior to its validation
+
+### Encrypted JSON Web Tokens
+
+The `jose` module supports encrypted JSON Web Tokens and provides functionality for encrypting and decrypting tokens, as well as their JWT Claims Set validation.
+
+- [Decryption & JWT Claims Set Validation](https://github.com/panva/jose/blob/v6.0.5/docs/jwt/decrypt/functions/jwtDecrypt.md) using the `jwtDecrypt` function
+- [Encryption](https://github.com/panva/jose/blob/v6.0.5/docs/jwt/encrypt/classes/EncryptJWT.md) using the `EncryptJWT` class
+- Utility functions
+  - [Decoding Token's Protected Header](https://github.com/panva/jose/blob/v6.0.5/docs/util/decode_protected_header/functions/decodeProtectedHeader.md)
+
+### Key Utilities
+
+The `jose` module supports importing, exporting, and generating keys and secrets in various formats, including PEM formats like SPKI, X.509 certificate, and PKCS #8, as well as JSON Web Key (JWK).
+
+- Key Import Functions
+  - [JWK Import](https://github.com/panva/jose/blob/v6.0.5/docs/key/import/functions/importJWK.md)
+  - [Public Key Import (SPKI)](https://github.com/panva/jose/blob/v6.0.5/docs/key/import/functions/importSPKI.md)
+  - [Public Key Import (X.509 Certificate)](https://github.com/panva/jose/blob/v6.0.5/docs/key/import/functions/importX509.md)
+  - [Private Key Import (PKCS #8)](https://github.com/panva/jose/blob/v6.0.5/docs/key/import/functions/importPKCS8.md)
+- Key and Secret Generation Functions
+  - [Asymmetric Key Pair Generation](https://github.com/panva/jose/blob/v6.0.5/docs/key/generate_key_pair/functions/generateKeyPair.md)
+  - [Symmetric Secret Generation](https://github.com/panva/jose/blob/v6.0.5/docs/key/generate_secret/functions/generateSecret.md)
+- Key Export Functions
+  - [JWK Export](https://github.com/panva/jose/blob/v6.0.5/docs/key/export/functions/exportJWK.md)
+  - [Private Key Export](https://github.com/panva/jose/blob/v6.0.5/docs/dkey/export/functions/exportPKCS8.md)
+  - [Public Key Export](https://github.com/panva/jose/blob/v6.0.5/docs/dkey/export/functions/exportSPKI.md)
+
+### JSON Web Signature (JWS)
+
+The `jose` module supports signing and verification of JWS messages with arbitrary payloads in Compact, Flattened JSON, and General JSON serialization syntaxes.
+
+- Signing - [Compact](https://github.com/panva/jose/blob/v6.0.5/docs/jws/compact/sign/classes/CompactSign.md), [Flattened JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jws/flattened/sign/classes/FlattenedSign.md), [General JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jws/general/sign/classes/GeneralSign.md)
+- Verification - [Compact](https://github.com/panva/jose/blob/v6.0.5/docs/jws/compact/verify/functions/compactVerify.md), [Flattened JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jws/flattened/verify/functions/flattenedVerify.md), [General JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jws/general/verify/functions/generalVerify.md)
+  - [Using a remote JSON Web Key Set (JWKS)](https://github.com/panva/jose/blob/v6.0.5/docs/jwks/remote/functions/createRemoteJWKSet.md)
+  - [Using a local JSON Web Key Set (JWKS)](https://github.com/panva/jose/blob/v6.0.5/docs/jwks/local/functions/createLocalJWKSet.md)
+- Utility functions
+  - [Decoding Token's Protected Header](https://github.com/panva/jose/blob/v6.0.5/docs/util/decode_protected_header/functions/decodeProtectedHeader.md)
+
+### JSON Web Encryption (JWE)
+
+The `jose` module supports encryption and decryption of JWE messages with arbitrary plaintext in Compact, Flattened JSON, and General JSON serialization syntaxes.
+
+- Encryption - [Compact](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/compact/encrypt/classes/CompactEncrypt.md), [Flattened JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/flattened/encrypt/classes/FlattenedEncrypt.md), [General JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/general/encrypt/classes/GeneralEncrypt.md)
+- Decryption - [Compact](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/compact/decrypt/functions/compactDecrypt.md), [Flattened JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/flattened/decrypt/functions/flattenedDecrypt.md), [General JSON](https://github.com/panva/jose/blob/v6.0.5/docs/jwe/general/decrypt/functions/generalDecrypt.md)
+- Utility functions
+  - [Decoding Token's Protected Header](https://github.com/panva/jose/blob/v6.0.5/docs/util/decode_protected_header/functions/decodeProtectedHeader.md)
+
+### Other
+
+The following are additional features and utilities provided by the `jose` module:
+
+- [Calculating JWK Thumbprint](https://github.com/panva/jose/blob/v6.0.5/docs/jwk/thumbprint/functions/calculateJwkThumbprint.md)
+- [Calculating JWK Thumbprint URI](https://github.com/panva/jose/blob/v6.0.5/docs/jwk/thumbprint/functions/calculateJwkThumbprintUri.md)
+- [Verification using a JWK Embedded in a JWS Header](https://github.com/panva/jose/blob/v6.0.5/docs/jwk/embedded/functions/EmbeddedJWK.md)
+- [Unsecured JWT](https://github.com/panva/jose/blob/v6.0.5/docs/jwt/unsecured/classes/UnsecuredJWT.md)
+- [JOSE Errors](https://github.com/panva/jose/blob/v6.0.5/docs/util/errors/README.md)
+
+[sponsor-auth0]: https://a0.to/signup/panva
+
+[^cjs]: CJS style `let jose = require('jose')` is possible in Node.js versions where `process.features.require_module` is `true` or with the `--experimental-require-module` Node.js CLI flag.
diff --git a/dist/deno/index.ts b/dist/deno/index.ts
@@ -0,0 +1,119 @@
+export { compactDecrypt } from './jwe/compact/decrypt.ts'
+export type { CompactDecryptGetKey } from './jwe/compact/decrypt.ts'
+export { flattenedDecrypt } from './jwe/flattened/decrypt.ts'
+export type { FlattenedDecryptGetKey } from './jwe/flattened/decrypt.ts'
+export { generalDecrypt } from './jwe/general/decrypt.ts'
+export type { GeneralDecryptGetKey } from './jwe/general/decrypt.ts'
+export { GeneralEncrypt } from './jwe/general/encrypt.ts'
+export type { Recipient } from './jwe/general/encrypt.ts'
+
+export { compactVerify } from './jws/compact/verify.ts'
+export type { CompactVerifyGetKey } from './jws/compact/verify.ts'
+export { flattenedVerify } from './jws/flattened/verify.ts'
+export type { FlattenedVerifyGetKey } from './jws/flattened/verify.ts'
+export { generalVerify } from './jws/general/verify.ts'
+export type { GeneralVerifyGetKey } from './jws/general/verify.ts'
+
+export { jwtVerify } from './jwt/verify.ts'
+export type { JWTVerifyOptions, JWTVerifyGetKey } from './jwt/verify.ts'
+export { jwtDecrypt } from './jwt/decrypt.ts'
+export type { JWTDecryptOptions, JWTDecryptGetKey } from './jwt/decrypt.ts'
+export type { ProduceJWT } from './jwt/produce.ts'
+
+export { CompactEncrypt } from './jwe/compact/encrypt.ts'
+export { FlattenedEncrypt } from './jwe/flattened/encrypt.ts'
+
+export { CompactSign } from './jws/compact/sign.ts'
+export { FlattenedSign } from './jws/flattened/sign.ts'
+export { GeneralSign } from './jws/general/sign.ts'
+export type { Signature } from './jws/general/sign.ts'
+
+export { SignJWT } from './jwt/sign.ts'
+export { EncryptJWT } from './jwt/encrypt.ts'
+
+export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbprint.ts'
+export { EmbeddedJWK } from './jwk/embedded.ts'
+
+export { createLocalJWKSet } from './jwks/local.ts'
+export { createRemoteJWKSet, jwksCache } from './jwks/remote.ts'
+export type {
+  RemoteJWKSetOptions,
+  JWKSCacheInput,
+  ExportedJWKSCache,
+  customFetch,
+  FetchImplementation,
+} from './jwks/remote.ts'
+
+export { UnsecuredJWT } from './jwt/unsecured.ts'
+export type { UnsecuredResult } from './jwt/unsecured.ts'
+
+export { exportPKCS8, exportSPKI, exportJWK } from './key/export.ts'
+
+export { importSPKI, importPKCS8, importX509, importJWK } from './key/import.ts'
+export type { KeyImportOptions } from './key/import.ts'
+
+export { decodeProtectedHeader } from './util/decode_protected_header.ts'
+export { decodeJwt } from './util/decode_jwt.ts'
+export type { ProtectedHeaderParameters } from './util/decode_protected_header.ts'
+
+export * as errors from './util/errors.ts'
+
+export { generateKeyPair } from './key/generate_key_pair.ts'
+export type { GenerateKeyPairResult, GenerateKeyPairOptions } from './key/generate_key_pair.ts'
+export { generateSecret } from './key/generate_secret.ts'
+export type { GenerateSecretOptions } from './key/generate_secret.ts'
+
+export * as base64url from './util/base64url.ts'
+
+export type {
+  CompactDecryptResult,
+  CompactJWEHeaderParameters,
+  CompactJWSHeaderParameters,
+  CompactVerifyResult,
+  CritOption,
+  CryptoKey,
+  DecryptOptions,
+  EncryptOptions,
+  FlattenedDecryptResult,
+  FlattenedJWE,
+  FlattenedJWS,
+  FlattenedJWSInput,
+  FlattenedVerifyResult,
+  GeneralDecryptResult,
+  GeneralJWE,
+  GeneralJWS,
+  GeneralJWSInput,
+  GeneralVerifyResult,
+  GetKeyFunction,
+  JoseHeaderParameters,
+  JSONWebKeySet,
+  JWEHeaderParameters,
+  JWEKeyManagementHeaderParameters,
+  JWK_EC_Private,
+  JWK_EC_Public,
+  JWK_oct,
+  JWK_OKP_Private,
+  JWK_OKP_Public,
+  JWK_RSA_Private,
+  JWK_RSA_Public,
+  JWK,
+  JWKParameters,
+  JWSHeaderParameters,
+  JWTClaimVerificationOptions,
+  JWTDecryptResult,
+  JWTHeaderParameters,
+  JWTPayload,
+  JWTVerifyResult,
+  KeyObject,
+  ResolvedKey,
+  SignOptions,
+  VerifyOptions,
+} from './types.d.ts'
+
+/**
+ * In prior releases this indicated whether a Node.js-specific build was loaded, this is now fixed
+ * to `"WebCryptoAPI"`
+ *
+ * @deprecated
+ */
+export const cryptoRuntime = 'WebCryptoAPI'
diff --git a/dist/deno/jwe/compact/decrypt.ts b/dist/deno/jwe/compact/decrypt.ts
@@ -0,0 +1,90 @@
+/**
+ * Decrypting JSON Web Encryption (JWE) in Compact Serialization
+ *
+ * @module
+ */
+
+import { flattenedDecrypt } from '../flattened/decrypt.ts'
+import { JWEInvalid } from '../../util/errors.ts'
+import { decoder } from '../../lib/buffer_utils.ts'
+import type * as types from '../../types.d.ts'
+
+/**
+ * Interface for Compact JWE Decryption dynamic key resolution. No token components have been
+ * verified at the time of this function call.
+ */
+export interface CompactDecryptGetKey
+  extends types.GetKeyFunction<types.CompactJWEHeaderParameters, types.FlattenedJWE> {}
+
+/**
+ * Decrypts a Compact JWE.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/jwe/compact/decrypt'`.
+ *
+ * @param jwe Compact JWE.
+ * @param key Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param options JWE Decryption options.
+ */
+export async function compactDecrypt(
+  jwe: string | Uint8Array,
+  key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array,
+  options?: types.DecryptOptions,
+): Promise<types.CompactDecryptResult>
+/**
+ * @param jwe Compact JWE.
+ * @param getKey Function resolving Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param options JWE Decryption options.
+ */
+export async function compactDecrypt(
+  jwe: string | Uint8Array,
+  getKey: CompactDecryptGetKey,
+  options?: types.DecryptOptions,
+): Promise<types.CompactDecryptResult & types.ResolvedKey>
+export async function compactDecrypt(
+  jwe: string | Uint8Array,
+  key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array | CompactDecryptGetKey,
+  options?: types.DecryptOptions,
+) {
+  if (jwe instanceof Uint8Array) {
+    jwe = decoder.decode(jwe)
+  }
+
+  if (typeof jwe !== 'string') {
+    throw new JWEInvalid('Compact JWE must be a string or Uint8Array')
+  }
+  const {
+    0: protectedHeader,
+    1: encryptedKey,
+    2: iv,
+    3: ciphertext,
+    4: tag,
+    length,
+  } = jwe.split('.')
+
+  if (length !== 5) {
+    throw new JWEInvalid('Invalid Compact JWE')
+  }
+
+  const decrypted = await flattenedDecrypt(
+    {
+      ciphertext,
+      iv: iv || undefined,
+      protected: protectedHeader,
+      tag: tag || undefined,
+      encrypted_key: encryptedKey || undefined,
+    },
+    key as Parameters<typeof flattenedDecrypt>[1],
+    options,
+  )
+
+  const result = { plaintext: decrypted.plaintext, protectedHeader: decrypted.protectedHeader! }
+
+  if (typeof key === 'function') {
+    return { ...result, key: decrypted.key }
+  }
+
+  return result
+}