jose 4.5.2 → 4.6.1

package/dist/types/types.d.ts

@@ -87,17 +87,37 @@
  * ```
  */
 export type KeyLike = { type: string }
+
+/**
+ * JSON Web Key ([JWK](https://www.rfc-editor.org/rfc/rfc7517)).
+ * "RSA", "EC", "OKP", and "oct" key types are supported.
+ */
 export interface JWK {
+  /**
+   * JWK "alg" (Algorithm) Parameter.
+   */
   alg?: string
   crv?: string
   d?: string
   dp?: string
   dq?: string
   e?: string
+  /**
+   * JWK "ext" (Extractable) Parameter.
+   */
   ext?: boolean
   k?: string
+  /**
+   * JWK "key_ops" (Key Operations) Parameter.
+   */
   key_ops?: string[]
+  /**
+   * JWK "kid" (Key ID) Parameter.
+   */
   kid?: string
+  /**
+   * JWK "kty" (Key Type) Parameter.
+   */
   kty?: string
   n?: string
   oth?: Array<{
@@ -108,166 +128,643 @@ export interface JWK {
   p?: string
   q?: string
   qi?: string
+  /**
+   * JWK "use" (Public Key Use) Parameter.
+   */
   use?: string
   x?: string
   y?: string
+  /**
+   * JWK "x5c" (X.509 Certificate Chain) Parameter.
+   */
   x5c?: string[]
+  /**
+   * JWK "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter.
+   */
   x5t?: string
+  /**
+   * "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter.
+   */
   'x5t#S256'?: string
+  /**
+   * JWK "x5u" (X.509 URL) Parameter.
+   */
   x5u?: string
+
   [propName: string]: unknown
 }
+
+/**
+ * Generic Interface for consuming operations dynamic key resolution.
+ * No token components have been verified at the time of this function call.
+ *
+ * If you cannot match a key suitable for the token, throw an error instead.
+ *
+ * @param protectedHeader JWE or JWS Protected Header.
+ * @param token The consumed JWE or JWS token.
+ */
 export interface GetKeyFunction<T, T2> {
   (protectedHeader: T, token: T2): Promise<KeyLike | Uint8Array> | KeyLike | Uint8Array
 }
+
+/**
+ * Flattened JWS definition for verify function inputs, allows payload as
+ * Uint8Array for detached signature validation.
+ */
 export interface FlattenedJWSInput {
+  /**
+   * The "header" member MUST be present and contain the value JWS
+   * Unprotected Header when the JWS Unprotected Header value is non-
+   * empty; otherwise, it MUST be absent.  This value is represented as
+   * an unencoded JSON object, rather than as a string.  These Header
+   * Parameter values are not integrity protected.
+   */
   header?: JWSHeaderParameters
+
+  /**
+   * The "payload" member MUST be present and contain the value
+   * BASE64URL(JWS Payload). When RFC7797 "b64": false is used
+   * the value passed may also be a Uint8Array.
+   */
   payload: string | Uint8Array
+
+  /**
+   * The "protected" member MUST be present and contain the value
+   * BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected
+   * Header value is non-empty; otherwise, it MUST be absent.  These
+   * Header Parameter values are integrity protected.
+   */
   protected?: string
+
+  /**
+   * The "signature" member MUST be present and contain the value
+   * BASE64URL(JWS Signature).
+   */
   signature: string
 }
+
+/**
+ * General JWS definition for verify function inputs, allows payload as
+ * Uint8Array for detached signature validation.
+ */
 export interface GeneralJWSInput {
+  /**
+   * The "payload" member MUST be present and contain the value
+   * BASE64URL(JWS Payload). When RFC7797 "b64": false is used
+   * the value passed may also be a Uint8Array.
+   */
   payload: string | Uint8Array
+
+  /**
+   * The "signatures" member value MUST be an array of JSON objects.
+   * Each object represents a signature or MAC over the JWS Payload and
+   * the JWS Protected Header.
+   */
   signatures: Omit<FlattenedJWSInput, 'payload'>[]
 }
+
+/**
+ * Flattened JWS definition. Payload is returned as an empty
+ * string when JWS Unencoded Payload Option
+ * [RFC7797](https://www.rfc-editor.org/rfc/rfc7797) is used.
+ */
 export interface FlattenedJWS extends Partial<FlattenedJWSInput> {
   payload: string
   signature: string
 }
+
+/**
+ * General JWS definition. Payload is returned as an empty
+ * string when JWS Unencoded Payload Option
+ * [RFC7797](https://www.rfc-editor.org/rfc/rfc7797) is used.
+ */
 export interface GeneralJWS {
   payload: string
   signatures: Omit<FlattenedJWSInput, 'payload'>[]
 }
+
 export interface JoseHeaderParameters {
+  /**
+   * "kid" (Key ID) Header Parameter.
+   */
   kid?: string
+
+  /**
+   * "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter.
+   */
   x5t?: string
+
+  /**
+   * "x5c" (X.509 Certificate Chain) Header Parameter.
+   */
   x5c?: string[]
+
+  /**
+   * "x5u" (X.509 URL) Header Parameter.
+   */
   x5u?: string
+
+  /**
+   * "jku" (JWK Set URL) Header Parameter.
+   */
   jku?: string
+
+  /**
+   * "jwk" (JSON Web Key) Header Parameter.
+   */
   jwk?: Pick<JWK, 'kty' | 'crv' | 'x' | 'y' | 'e' | 'n'>
+
+  /**
+   * "typ" (Type) Header Parameter.
+   */
   typ?: string
+
+  /**
+   * "cty" (Content Type) Header Parameter.
+   */
   cty?: string
 }
+
+/**
+ * Recognized JWS Header Parameters, any other Header Members
+ * may also be present.
+ */
 export interface JWSHeaderParameters extends JoseHeaderParameters {
+  /**
+   * JWS "alg" (Algorithm) Header Parameter.
+   */
   alg?: string
+
+  /**
+   * This JWS Extension Header Parameter modifies the JWS Payload
+   * representation and the JWS Signing Input computation as per
+   * [RFC7797](https://www.rfc-editor.org/rfc/rfc7797).
+   */
   b64?: boolean
+
+  /**
+   * JWS "crit" (Critical) Header Parameter.
+   */
   crit?: string[]
+
+  /**
+   * Any other JWS Header member.
+   */
   [propName: string]: unknown
 }
+
+/**
+ * Recognized JWE Key Management-related Header Parameters.
+ */
 export interface JWEKeyManagementHeaderParameters {
   apu?: Uint8Array
   apv?: Uint8Array
-  epk?: KeyLike
-  iv?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
   p2c?: number
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
   p2s?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
+  iv?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
+  epk?: KeyLike
 }
+
+/**
+ * Flattened JWE definition.
+ */
 export interface FlattenedJWE {
+  /**
+   * The "aad" member MUST be present and contain the value
+   * BASE64URL(JWE AAD)) when the JWE AAD value is non-empty;
+   * otherwise, it MUST be absent.  A JWE AAD value can be included to
+   * supply a base64url-encoded value to be integrity protected but not
+   * encrypted.
+   */
   aad?: string
+
+  /**
+   * The "ciphertext" member MUST be present and contain the value
+   * BASE64URL(JWE Ciphertext).
+   */
   ciphertext: string
+
+  /**
+   * The "encrypted_key" member MUST be present and contain the value
+   * BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is
+   * non-empty; otherwise, it MUST be absent.
+   */
   encrypted_key?: string
+
+  /**
+   * The "header" member MUST be present and contain the value JWE Per-
+   * Recipient Unprotected Header when the JWE Per-Recipient
+   * Unprotected Header value is non-empty; otherwise, it MUST be
+   * absent.  This value is represented as an unencoded JSON object,
+   * rather than as a string.  These Header Parameter values are not
+   * integrity protected.
+   */
   header?: JWEHeaderParameters
+
+  /**
+   * The "iv" member MUST be present and contain the value
+   * BASE64URL(JWE Initialization Vector) when the JWE Initialization
+   * Vector value is non-empty; otherwise, it MUST be absent.
+   */
   iv: string
+
+  /**
+   * The "protected" member MUST be present and contain the value
+   * BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected
+   * Header value is non-empty; otherwise, it MUST be absent.  These
+   * Header Parameter values are integrity protected.
+   */
   protected?: string
+
+  /**
+   * The "tag" member MUST be present and contain the value
+   * BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag
+   * value is non-empty; otherwise, it MUST be absent.
+   */
   tag: string
+
+  /**
+   * The "unprotected" member MUST be present and contain the value JWE
+   * Shared Unprotected Header when the JWE Shared Unprotected Header
+   * value is non-empty; otherwise, it MUST be absent.  This value is
+   * represented as an unencoded JSON object, rather than as a string.
+   * These Header Parameter values are not integrity protected.
+   */
   unprotected?: JWEHeaderParameters
 }
+
 export interface GeneralJWE extends Omit<FlattenedJWE, 'encrypted_key' | 'header'> {
   recipients: Pick<FlattenedJWE, 'encrypted_key' | 'header'>[]
 }
+
+/**
+ * Recognized JWE Header Parameters, any other Header members
+ * may also be present.
+ */
 export interface JWEHeaderParameters extends JoseHeaderParameters {
+  /**
+   * JWE "alg" (Algorithm) Header Parameter.
+   */
   alg?: string
+
+  /**
+   * JWE "enc" (Encryption Algorithm) Header Parameter.
+   */
   enc?: string
+
+  /**
+   * JWE "crit" (Critical) Header Parameter.
+   */
   crit?: string[]
+
+  /**
+   * JWE "zip" (Compression Algorithm) Header Parameter.
+   */
   zip?: string
+
+  /**
+   * Any other JWE Header member.
+   */
   [propName: string]: unknown
 }
+
+/**
+ * Shared Interface with a "crit" property for all sign, verify, encrypt and decrypt
+ * operations.
+ */
 export interface CritOption {
+  /**
+   * An object with keys representing recognized "crit" (Critical) Header Parameter
+   * names. The value for those is either `true` or `false`. `true` when the
+   * Header Parameter MUST be integrity protected, `false` when it's irrelevant.
+   *
+   * This makes the "Extension Header Parameter "${parameter}" is not recognized"
+   * error go away.
+   *
+   * Use this when a given JWS/JWT/JWE profile requires the use of proprietary
+   * non-registered "crit" (Critical) Header Parameters. This will only make sure
+   * the Header Parameter is syntactically correct when provided and that it is
+   * optionally integrity protected. It will not process the Header Parameter in
+   * any way or reject the operation if it is missing. You MUST still
+   * verify the Header Parameter was present and process it according to the
+   * profile's validation steps after the operation succeeds.
+   *
+   * The JWS extension Header Parameter `b64` is always recognized and processed
+   * properly. No other registered Header Parameters that need this kind of
+   * default built-in treatment are currently available.
+   */
   crit?: {
     [propName: string]: boolean
   }
 }
+
+/**
+ * JWE Decryption options.
+ */
 export interface DecryptOptions extends CritOption {
+  /**
+   * A list of accepted JWE "alg" (Algorithm) Header Parameter values.
+   */
   keyManagementAlgorithms?: string[]
+
+  /**
+   * A list of accepted JWE "enc" (Encryption Algorithm) Header Parameter values.
+   * By default all "enc" (Encryption Algorithm) values applicable for the used
+   * key/secret are allowed.
+   */
   contentEncryptionAlgorithms?: string[]
+
+  /**
+   * In a browser runtime you have to provide an implementation for Inflate Raw
+   * when you expect JWEs with compressed plaintext.
+   */
   inflateRaw?: InflateFunction
 }
+
+/**
+ * JWE Deflate option.
+ */
 export interface DeflateOption {
+  /**
+   * In a browser runtime you have to provide an implementation for Deflate Raw
+   * when you will be producing JWEs with compressed plaintext.
+   */
   deflateRaw?: DeflateFunction
 }
+
+/**
+ * JWE Encryption options.
+ */
 export interface EncryptOptions extends CritOption, DeflateOption {}
+
+/**
+ * JWT Claims Set verification options.
+ */
 export interface JWTClaimVerificationOptions {
+  /**
+   * Expected JWT "aud" (Audience) Claim value(s).
+   */
   audience?: string | string[]
+
+  /**
+   * Expected clock tolerance
+   * - in seconds when number (e.g. 5)
+   * - parsed as seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   */
   clockTolerance?: string | number
+
+  /**
+   * Expected JWT "iss" (Issuer) Claim value(s).
+   */
   issuer?: string | string[]
+
+  /**
+   * Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
+   * - in seconds when number (e.g. 5)
+   * - parsed as seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
+   */
   maxTokenAge?: string | number
+
+  /**
+   * Expected JWT "sub" (Subject) Claim value.
+   */
   subject?: string
+
+  /**
+   * Expected JWT "typ" (Type) Header Parameter value.
+   */
   typ?: string
+
+  /**
+   * Date to use when comparing NumericDate claims, defaults to `new Date()`.
+   */
   currentDate?: Date
 }
+
+/**
+ * JWS Verification options.
+ */
 export interface VerifyOptions extends CritOption {
+  /**
+   * A list of accepted JWS "alg" (Algorithm) Header Parameter values.
+   * By default all "alg" (Algorithm) values applicable for the used
+   * key/secret are allowed. Note: "none" is never accepted.
+   */
   algorithms?: string[]
 }
+
+/**
+ * JWS Signing options.
+ */
 export interface SignOptions extends CritOption {}
+
+/**
+ * Recognized JWT Claims Set members, any other members
+ * may also be present.
+ */
 export interface JWTPayload {
+  /**
+   * JWT Issuer - [RFC7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1).
+   */
   iss?: string
+
+  /**
+   * JWT Subject - [RFC7519#section-4.1.2](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2).
+   */
   sub?: string
+
+  /**
+   * JWT Audience [RFC7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3).
+   */
   aud?: string | string[]
+
+  /**
+   * JWT ID - [RFC7519#section-4.1.7](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7).
+   */
   jti?: string
+
+  /**
+   * JWT Not Before - [RFC7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5).
+   */
   nbf?: number
+
+  /**
+   * JWT Expiration Time - [RFC7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4).
+   */
   exp?: number
+
+  /**
+   * JWT Issued At - [RFC7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6).
+   */
   iat?: number
+
+  /**
+   * Any other JWT Claim Set member.
+   */
   [propName: string]: unknown
 }
+
+/**
+ * Deflate Raw implementation, e.g. promisified [zlib.deflateRaw](https://nodejs.org/api/zlib.html#zlib_zlib_deflateraw_buffer_options_callback).
+ */
 export interface DeflateFunction {
   (input: Uint8Array): Promise<Uint8Array>
 }
+
+/**
+ * Inflate Raw implementation, e.g. promisified [zlib.inflateRaw](https://nodejs.org/api/zlib.html#zlib_zlib_inflateraw_buffer_options_callback).
+ */
 export interface InflateFunction {
   (input: Uint8Array): Promise<Uint8Array>
 }
+
 export interface FlattenedDecryptResult {
+  /**
+   * JWE AAD.
+   */
   additionalAuthenticatedData?: Uint8Array
+
+  /**
+   * Plaintext.
+   */
   plaintext: Uint8Array
+
+  /**
+   * JWE Protected Header.
+   */
   protectedHeader?: JWEHeaderParameters
+
+  /**
+   * JWE Shared Unprotected Header.
+   */
   sharedUnprotectedHeader?: JWEHeaderParameters
+
+  /**
+   * JWE Per-Recipient Unprotected Header.
+   */
   unprotectedHeader?: JWEHeaderParameters
 }
+
 export interface GeneralDecryptResult extends FlattenedDecryptResult {}
+
 export interface CompactDecryptResult {
+  /**
+   * Plaintext.
+   */
   plaintext: Uint8Array
+
+  /**
+   * JWE Protected Header.
+   */
   protectedHeader: CompactJWEHeaderParameters
 }
+
 export interface FlattenedVerifyResult {
+  /**
+   * JWS Payload.
+   */
   payload: Uint8Array
+
+  /**
+   * JWS Protected Header.
+   */
   protectedHeader?: JWSHeaderParameters
+
+  /**
+   * JWS Unprotected Header.
+   */
   unprotectedHeader?: JWSHeaderParameters
 }
+
 export interface GeneralVerifyResult extends FlattenedVerifyResult {}
+
 export interface CompactVerifyResult {
+  /**
+   * JWS Payload.
+   */
   payload: Uint8Array
+
+  /**
+   * JWS Protected Header.
+   */
   protectedHeader: CompactJWSHeaderParameters
 }
+
 export interface JWTVerifyResult {
+  /**
+   * JWT Claims Set.
+   */
   payload: JWTPayload
+
+  /**
+   * JWS Protected Header.
+   */
   protectedHeader: JWTHeaderParameters
 }
+
 export interface JWTDecryptResult {
+  /**
+   * JWT Claims Set.
+   */
   payload: JWTPayload
+
+  /**
+   * JWE Protected Header.
+   */
   protectedHeader: CompactJWEHeaderParameters
 }
+
 export interface ResolvedKey {
+  /**
+   * Key resolved from the key resolver function.
+   */
   key: KeyLike | Uint8Array
 }
+
+/**
+ * Recognized Compact JWS Header Parameters, any other Header Members
+ * may also be present.
+ */
 export interface CompactJWSHeaderParameters extends JWSHeaderParameters {
   alg: string
 }
+
+/**
+ * Recognized Signed JWT Header Parameters, any other Header Members
+ * may also be present.
+ */
 export interface JWTHeaderParameters extends CompactJWSHeaderParameters {
   b64?: true
 }
+
+/**
+ * Recognized Compact JWE Header Parameters, any other Header Members
+ * may also be present.
+ */
 export interface CompactJWEHeaderParameters extends JWEHeaderParameters {
   alg: string
   enc: string
 }
+
+/**
+ * JSON Web Key Set
+ */
 export interface JSONWebKeySet {
   keys: JWK[]
 }

package/dist/types/util/base64url.d.ts

@@ -1,6 +1,16 @@
+/**
+ * Utility function to encode a string or Uint8Array as a base64url string.
+ *
+ * @param input Value that will be base64url-encoded.
+ */
 interface Base64UrlEncode {
     (input: Uint8Array | string): string;
 }
+/**
+ * Utility function to decode a base64url encoded string.
+ *
+ * @param input Value that will be base64url-decoded.
+ */
 interface Base64UrlDecode {
     (input: Uint8Array | string): Uint8Array;
 }

package/dist/types/util/decode_jwt.d.ts

@@ -1,2 +1,16 @@
 import type { JWTPayload } from '../types';
+/**
+ * Decodes a signed JSON Web Token payload. This does not validate the JWT Claims Set
+ * types or values. This does not validate the JWS Signature. For a proper
+ * Signed JWT Claims Set validation and JWS signature verification use `jose.jwtVerify()`.
+ * For an encrypted JWT Claims Set validation and JWE decryption use `jose.jwtDecrypt()`.
+ *
+ * @param jwt JWT token in compact JWS serialization.
+ *
+ * @example Usage
+ * ```js
+ * const claims = jose.decodeJwt(token)
+ * console.log(claims)
+ * ```
+ */
 export declare function decodeJwt(jwt: string): JWTPayload;