repocairn 0.1.2 → 0.1.4

package/node_modules/jose/dist/types/types.d.ts

@@ -1,19 +1,85 @@
-/** Generic JSON Web Key Parameters. */
-export interface JWKParameters {
+/**
+ * JWS "alg" (Algorithm) Header Parameter values supported by this module. Availability of a given
+ * identifier additionally depends on the runtime.
+ */
+export type JWSAlgorithm =
+  | 'HS256'
+  | 'HS384'
+  | 'HS512'
+  | 'RS256'
+  | 'RS384'
+  | 'RS512'
+  | 'PS256'
+  | 'PS384'
+  | 'PS512'
+  | 'ES256'
+  | 'ES384'
+  | 'ES512'
+  | 'EdDSA'
+  | 'Ed25519'
+  | 'ML-DSA-44'
+  | 'ML-DSA-65'
+  | 'ML-DSA-87'
+  | (string & {})
+
+/**
+ * JWE "alg" (Algorithm) Header Parameter values supported by this module. Availability of a given
+ * identifier additionally depends on the runtime.
+ */
+export type JWEKeyManagementAlgorithm =
+  | 'dir'
+  | 'A128KW'
+  | 'A192KW'
+  | 'A256KW'
+  | 'A128GCMKW'
+  | 'A192GCMKW'
+  | 'A256GCMKW'
+  | 'ECDH-ES'
+  | 'ECDH-ES+A128KW'
+  | 'ECDH-ES+A192KW'
+  | 'ECDH-ES+A256KW'
+  | 'RSA-OAEP'
+  | 'RSA-OAEP-256'
+  | 'RSA-OAEP-384'
+  | 'RSA-OAEP-512'
+  | 'PBES2-HS256+A128KW'
+  | 'PBES2-HS384+A192KW'
+  | 'PBES2-HS512+A256KW'
+  | (string & {})
+
+/**
+ * JWE "enc" (Encryption Algorithm) Header Parameter values supported by this module. Availability
+ * of a given identifier additionally depends on the runtime.
+ */
+export type JWEContentEncryptionAlgorithm =
+  | 'A128CBC-HS256'
+  | 'A192CBC-HS384'
+  | 'A256CBC-HS512'
+  | 'A128GCM'
+  | 'A192GCM'
+  | 'A256GCM'
+  | (string & {})
+
+/** JWK "kty" (Key Type) Parameter values supported by this module. */
+export type JWKKeyType = 'EC' | 'RSA' | 'OKP' | 'AKP' | 'oct' | (string & {})
+
+/**
+ * Generic JSON Web Key Parameters.
+ *
+ * > Note: This is declared as a type alias rather than an interface so that it satisfies the implicit index
+ * > signature of the `JsonWebKey` types shipped by `@types/node` and `lib.dom`.
+ */
+export type JWKParameters = {
   /** JWK "kty" (Key Type) Parameter */
-  kty?: string
-  /**
-   * JWK "alg" (Algorithm) Parameter
-   *
-   * @see {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}
-   */
-  alg?: string
+  kty?: JWKKeyType
+  /** JWK "alg" (Algorithm) Parameter */
+  alg?: JWSAlgorithm | JWEKeyManagementAlgorithm | JWEContentEncryptionAlgorithm
   /** JWK "key_ops" (Key Operations) Parameter */
   key_ops?: string[]
   /** JWK "ext" (Extractable) Parameter */
   ext?: boolean
   /** JWK "use" (Public Key Use) Parameter */
-  use?: string
+  use?: 'sig' | 'enc' | (string & {})
   /** JWK "x5c" (X.509 Certificate Chain) Parameter */
   x5c?: string[]
   /** JWK "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter */
@@ -101,20 +167,35 @@ export interface JWK_oct extends JWKParameters {
 }
 
 /**
- * JSON Web Key ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK}). "RSA", "EC", "OKP", "AKP", and
- * "oct" key types are supported.
+ * JSON Web Key ({@link https://www.rfc-editor.org/info/rfc7517/ JWK}). "RSA", "EC", "OKP", "AKP",
+ * and "oct" key types are supported.
  *
- * @see {@link JWK_AKP_Public}
- * @see {@link JWK_AKP_Private}
- * @see {@link JWK_OKP_Public}
- * @see {@link JWK_OKP_Private}
- * @see {@link JWK_EC_Public}
- * @see {@link JWK_EC_Private}
- * @see {@link JWK_RSA_Public}
- * @see {@link JWK_RSA_Private}
- * @see {@link JWK_oct}
+ * > Note: This is declared as a type alias rather than an interface so that it satisfies the implicit index
+ * > signature of the `JsonWebKey` types shipped by `@types/node` and `lib.dom`. It spells out the
+ * > {@link JWKParameters} members rather than intersecting them so that every JWK member is documented
+ * > in one place.
  */
-export interface JWK extends JWKParameters {
+export type JWK = {
+  /** JWK "kty" (Key Type) Parameter */
+  kty?: JWKKeyType
+  /** JWK "alg" (Algorithm) Parameter */
+  alg?: JWSAlgorithm | JWEKeyManagementAlgorithm | JWEContentEncryptionAlgorithm
+  /** JWK "key_ops" (Key Operations) Parameter */
+  key_ops?: string[]
+  /** JWK "ext" (Extractable) Parameter */
+  ext?: boolean
+  /** JWK "use" (Public Key Use) Parameter */
+  use?: 'sig' | 'enc' | (string & {})
+  /** JWK "x5c" (X.509 Certificate Chain) Parameter */
+  x5c?: string[]
+  /** JWK "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter */
+  x5t?: string
+  /** JWK "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter */
+  'x5t#S256'?: string
+  /** JWK "x5u" (X.509 URL) Parameter */
+  x5u?: string
+  /** JWK "kid" (Key ID) Parameter */
+  kid?: string
   /**
    * - EC JWK "crv" (Curve) Parameter
    * - OKP JWK "crv" (The Subtype of Key Pair) Parameter
@@ -153,19 +234,47 @@ export interface JWK extends JWKParameters {
   pub?: string
   /** AKP JWK "priv" (Private key) Parameter */
   priv?: string
+  /**
+   * RSA JWK "oth" (Other Primes Info) Parameter
+   *
+   * > Note: Multi-prime RSA keys are not supported; importing a JWK with this parameter present throws.
+   */
+  oth?: Array<{
+    /** The Factor CRT Exponent */
+    d?: string
+    /** The Prime Factor */
+    r?: string
+    /** The Factor CRT Coefficient */
+    t?: string
+  }>
 }
 
 /**
- * @private
- *
- * @internal
+ * Discriminated union of the JSON Web Key shapes supported by this module. Unlike {@link JWK}, each
+ * member requires and fixes the "kty" (Key Type) Parameter to its key type so that the union can be
+ * narrowed on it.
  */
+// The "kty" is intersected into each arm one at a time rather than distributed over a parenthesised
+// union - `X & (A | B)` means the same thing, but typedoc renders it without the parentheses, which
+// reads as though the second arm carried no "kty" at all.
+export type AnyJWK =
+  | (JWK_EC_Private & { kty: 'EC' })
+  | (JWK_EC_Public & { kty: 'EC' })
+  | (JWK_RSA_Private & { kty: 'RSA' })
+  | (JWK_RSA_Public & { kty: 'RSA' })
+  | (JWK_OKP_Private & { kty: 'OKP' })
+  | (JWK_OKP_Public & { kty: 'OKP' })
+  | (JWK_AKP_Private & { kty: 'AKP' })
+  | (JWK_AKP_Public & { kty: 'AKP' })
+  | (JWK_oct & { kty: 'oct' })
+
+/** Key or secret input accepted by all sign, verify, encrypt, and decrypt operations. */
+export type KeyInput = CryptoKey | KeyObject | JWK | Uint8Array
+
 export interface GenericGetKeyFunction<IProtectedHeader, IToken, ReturnKeyTypes> {
   /**
    * Dynamic key resolution function. No token components have been verified at the time of this
-   * function call.
-   *
-   * If a suitable key for the token cannot be matched, throw an error instead.
+   * function call. If a suitable key for the token cannot be matched, throw an error instead.
    *
    * @param protectedHeader JWE or JWS Protected Header.
    * @param token The consumed JWE or JWS token.
@@ -173,17 +282,12 @@ export interface GenericGetKeyFunction<IProtectedHeader, IToken, ReturnKeyTypes>
   (protectedHeader: IProtectedHeader, token: IToken): Promise<ReturnKeyTypes> | ReturnKeyTypes
 }
 
-/**
- * Generic Interface for consuming operations dynamic key resolution.
- *
- * @param IProtectedHeader Type definition of the JWE or JWS Protected Header.
- * @param IToken Type definition of the consumed JWE or JWS token.
- */
-export interface GetKeyFunction<IProtectedHeader, IToken> extends GenericGetKeyFunction<
+/** Interface for consuming operations dynamic key resolution. */
+export interface GetKeyFunction<
   IProtectedHeader,
   IToken,
-  CryptoKey | KeyObject | JWK | Uint8Array
-> {}
+  KeyTypes extends KeyInput = KeyInput,
+> extends GenericGetKeyFunction<IProtectedHeader, IToken, KeyTypes> {}
 
 /**
  * Flattened JWS definition for verify function inputs, allows payload as {@link !Uint8Array} for
@@ -222,7 +326,7 @@ export interface FlattenedJWSInput {
 export interface GeneralJWSInput {
   /**
    * The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When when
-   * JWS Unencoded Payload ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) "b64": false is
+   * JWS Unencoded Payload ({@link https://www.rfc-editor.org/info/rfc7797/ RFC7797}) "b64": false is
    * used the value passed may also be a {@link !Uint8Array}.
    */
   payload: string | Uint8Array
@@ -236,7 +340,7 @@ export interface GeneralJWSInput {
 
 /**
  * Flattened JWS JSON Serialization Syntax token. Payload is returned as an empty string when JWS
- * Unencoded Payload ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used.
+ * Unencoded Payload ({@link https://www.rfc-editor.org/info/rfc7797/ RFC7797}) is used.
  */
 export interface FlattenedJWS extends Partial<FlattenedJWSInput> {
   payload: string
@@ -245,7 +349,7 @@ export interface FlattenedJWS extends Partial<FlattenedJWSInput> {
 
 /**
  * General JWS JSON Serialization Syntax token. Payload is returned as an empty string when JWS
- * Unencoded Payload ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used.
+ * Unencoded Payload ({@link https://www.rfc-editor.org/info/rfc7797/ RFC7797}) is used.
  */
 export interface GeneralJWS {
   payload: string
@@ -269,8 +373,11 @@ export interface JoseHeaderParameters {
   /** "jku" (JWK Set URL) Header Parameter */
   jku?: string
 
-  /** "jwk" (JSON Web Key) Header Parameter */
-  jwk?: Pick<JWK, 'kty' | 'crv' | 'x' | 'y' | 'e' | 'n' | 'alg' | 'pub'>
+  /**
+   * "jwk" (JSON Web Key) Header Parameter. This must be a public JSON Web Key; private and
+   * symmetric key parameters are not permitted.
+   */
+  jwk?: Omit<JWK, 'd' | 'dp' | 'dq' | 'k' | 'p' | 'q' | 'qi' | 'priv' | 'oth'>
 
   /** "typ" (Type) Header Parameter */
   typ?: string
@@ -281,16 +388,12 @@ export interface JoseHeaderParameters {
 
 /** Recognized JWS Header Parameters, any other Header Members may also be present. */
 export interface JWSHeaderParameters extends JoseHeaderParameters {
-  /**
-   * JWS "alg" (Algorithm) Header Parameter
-   *
-   * @see {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}
-   */
-  alg?: string
+  /** JWS "alg" (Algorithm) Header Parameter */
+  alg?: JWSAlgorithm
 
   /**
    * This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing
-   * Input computation as per {@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}.
+   * Input computation as per {@link https://www.rfc-editor.org/info/rfc7797/ RFC7797}.
    */
   b64?: boolean
 
@@ -314,11 +417,13 @@ export interface JWEKeyManagementHeaderParameters {
    * used in ECDH's ConcatKDF.
    */
   apv?: Uint8Array
+
   /**
-   * @deprecated You should not use this parameter. It is only intended for testing and vector
-   *   validation purposes.
+   * PBES2 "p2c" (PBES2 Count). This will be used as a JOSE Header Parameter and as the PBKDF2
+   * iteration count.
    */
   p2c?: number
+
   /**
    * @deprecated You should not use this parameter. It is only intended for testing and vector
    *   validation purposes.
@@ -397,32 +502,21 @@ export interface GeneralJWE extends Omit<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
-   *
-   * @see {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}
-   */
-  alg?: string
+  /** JWE "alg" (Algorithm) Header Parameter */
+  alg?: JWEKeyManagementAlgorithm
 
-  /**
-   * JWE "enc" (Encryption Algorithm) Header Parameter
-   *
-   * @see {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}
-   */
-  enc?: string
+  /** JWE "enc" (Encryption Algorithm) Header Parameter */
+  enc?: JWEContentEncryptionAlgorithm
 
   /** JWE "crit" (Critical) Header Parameter */
   crit?: string[]
 
   /**
-   * JWE "zip" (Compression Algorithm) Header Parameter.
-   *
-   * The only supported value is `"DEF"` (DEFLATE). Requires the `CompressionStream` /
-   * `DecompressionStream` APIs to be available in the runtime.
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7516#section-4.1.3 JWE "zip" Header Parameter}
+   * JWE "zip" (Compression Algorithm) Header Parameter. The only supported value is `"DEF"`
+   * (DEFLATE), and it requires the `CompressionStream` / `DecompressionStream` APIs to be available
+   * in the runtime.
    */
-  zip?: string
+  zip?: 'DEF' | (string & {})
 
   /** Any other JWE Header member. */
   [propName: string]: unknown
@@ -433,20 +527,14 @@ 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 "..." is not recognized" error go away.
+   * protected, `false` when it's irrelevant. The JWS extension Header Parameter `b64` is always
+   * recognized and processed properly; no other registered Header Parameters currently receive this
+   * built-in treatment.
    *
-   * 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.
+   * > Warning: This only checks that the Header Parameter is syntactically correct when provided and,
+   * > optionally, integrity protected. It does not process the Header Parameter or reject the
+   * > operation when it is missing. You MUST still verify its presence and process it according to
+   * > the profile's validation steps after the operation succeeds.
    */
   crit?: {
     [propName: string]: boolean
@@ -460,13 +548,13 @@ export interface DecryptOptions extends CritOption {
    * (Algorithm) Header Parameter values applicable for the used key/secret are allowed except for
    * all PBES2 Key Management Algorithms, these need to be explicitly allowed using this option.
    */
-  keyManagementAlgorithms?: string[]
+  keyManagementAlgorithms?: JWEKeyManagementAlgorithm[]
 
   /**
    * 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[]
+  contentEncryptionAlgorithms?: JWEContentEncryptionAlgorithm[]
 
   /**
    * (PBES2 Key Management Algorithms only) Maximum allowed "p2c" (PBES2 Count) Header Parameter
@@ -478,11 +566,8 @@ export interface DecryptOptions extends CritOption {
   /**
    * Maximum allowed size (in bytes) of the decompressed plaintext when the JWE `"zip"` (Compression
    * Algorithm) Header Parameter is present. By default this value is set to 250000 (250 KB). The
-   * value must be `0`, a positive safe integer, or `Infinity`.
-   *
-   * Set to `0` to reject all compressed JWEs during decryption.
-   *
-   * Set to `Infinity` to disable the decompressed size limit.
+   * value must be `0`, a positive safe integer, or `Infinity`. Set it to `0` to reject all
+   * compressed JWEs during decryption or to `Infinity` to disable the decompressed size limit.
    */
   maxDecompressedLength?: number
 }
@@ -493,51 +578,41 @@ export interface EncryptOptions extends CritOption {}
 /** JWT Claims Set verification options. */
 export interface JWTClaimVerificationOptions {
   /**
-   * Expected JWT "aud" (Audience) Claim value(s).
-   *
-   * This option makes the JWT "aud" (Audience) Claim presence required.
+   * Expected JWT "aud" (Audience) Claim value(s). This option makes the JWT "aud" (Audience) Claim
+   * presence required.
    */
   audience?: string | string[]
 
   /**
-   * Clock skew tolerance
-   *
-   * - In seconds when number (e.g. 5)
-   * - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
-   *
-   * Used when validating the JWT "nbf" (Not Before) and "exp" (Expiration Time) claims, and when
-   * validating the "iat" (Issued At) claim if the {@link maxTokenAge `maxTokenAge` option} is set.
+   * Clock skew tolerance in seconds when a number (e.g. 5), or resolved into seconds when a string
+   * (e.g. "5 seconds", "10 minutes", "2 hours"). Used when validating the JWT "nbf" (Not Before)
+   * and "exp" (Expiration Time) claims, and when validating the "iat" (Issued At) claim if the
+   * {@link maxTokenAge `maxTokenAge` option} is set.
    */
   clockTolerance?: string | number
 
   /**
-   * Expected JWT "iss" (Issuer) Claim value(s).
-   *
-   * This option makes the JWT "iss" (Issuer) Claim presence required.
+   * Expected JWT "iss" (Issuer) Claim value(s). This option makes the JWT "iss" (Issuer) Claim
+   * presence required.
    */
   issuer?: string | string[]
 
   /**
-   * Maximum time elapsed (in seconds) from the JWT "iat" (Issued At) Claim value.
-   *
-   * - In seconds when number (e.g. 5)
-   * - Resolved into a number of seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours").
-   *
-   * This option makes the JWT "iat" (Issued At) Claim presence required.
+   * Maximum time elapsed from the JWT "iat" (Issued At) Claim value, in seconds when a number (e.g.
+   * 5), or resolved into seconds when a string (e.g. "5 seconds", "10 minutes", "2 hours"). This
+   * option makes the JWT "iat" (Issued At) Claim presence required.
    */
   maxTokenAge?: string | number
 
   /**
-   * Expected JWT "sub" (Subject) Claim value.
-   *
-   * This option makes the JWT "sub" (Subject) Claim presence required.
+   * Expected JWT "sub" (Subject) Claim value. This option makes the JWT "sub" (Subject) Claim
+   * presence required.
    */
   subject?: string
 
   /**
-   * Expected JWT "typ" (Type) Header Parameter value.
-   *
-   * This option makes the JWT "typ" (Type) Header Parameter presence required.
+   * Expected JWT "typ" (Type) Header Parameter value. This option makes the JWT "typ" (Type) Header
+   * Parameter presence required.
    */
   typ?: string
 
@@ -561,10 +636,9 @@ 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]\
-   * > Unsecured JWTs (`{ "alg": "none" }`) are never accepted by this API.
+   * > Note: Unsecured JWTs (`{ "alg": "none" }`) are never accepted by this API.
    */
-  algorithms?: string[]
+  algorithms?: JWSAlgorithm[]
 }
 
 /** JWS Signing options. */
@@ -572,53 +646,25 @@ export interface SignOptions extends CritOption {}
 
 /** Recognized JWT Claims Set members, any other members may also be present. */
 export interface JWTPayload {
-  /**
-   * JWT Issuer
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
-   */
+  /** JWT Issuer */
   iss?: string
 
-  /**
-   * JWT Subject
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
-   */
+  /** JWT Subject */
   sub?: string
 
-  /**
-   * JWT Audience
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
-   */
+  /** JWT Audience */
   aud?: string | string[]
 
-  /**
-   * JWT ID
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
-   */
+  /** JWT ID */
   jti?: string
 
-  /**
-   * JWT Not Before
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
-   */
+  /** JWT Not Before */
   nbf?: number
 
-  /**
-   * JWT Expiration Time
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
-   */
+  /** JWT Expiration Time */
   exp?: number
 
-  /**
-   * JWT Issued At
-   *
-   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
-   */
+  /** JWT Issued At */
   iat?: number
 
   /** Any other JWT Claim Set member. */
@@ -682,7 +728,9 @@ export interface CompactVerifyResult {
 /** Signed JSON Web Token (JWT) verification result */
 export interface JWTVerifyResult<PayloadType = JWTPayload> {
   /** JWT Claims Set. */
-  payload: PayloadType & JWTPayload
+  payload: PayloadType &
+    JWTPayload &
+    ([PayloadType] extends [object] ? unknown : unknown extends PayloadType ? unknown : never)
 
   /** JWS Protected Header. */
   protectedHeader: JWTHeaderParameters
@@ -691,32 +739,34 @@ export interface JWTVerifyResult<PayloadType = JWTPayload> {
 /** Encrypted JSON Web Token (JWT) decryption result */
 export interface JWTDecryptResult<PayloadType = JWTPayload> {
   /** JWT Claims Set. */
-  payload: PayloadType & JWTPayload
+  payload: PayloadType &
+    JWTPayload &
+    ([PayloadType] extends [object] ? unknown : unknown extends PayloadType ? unknown : never)
 
   /** JWE Protected Header. */
   protectedHeader: CompactJWEHeaderParameters
 }
 
 /** When key resolver functions are used this becomes part of successful resolves */
-export interface ResolvedKey {
+export interface ResolvedKey<KeyType extends CryptoKey | Uint8Array = CryptoKey | Uint8Array> {
   /** Key resolved from the key resolver function. */
-  key: CryptoKey | Uint8Array
+  key: KeyType
 }
 
 /** Recognized Compact JWS Header Parameters, any other Header Members may also be present. */
 export interface CompactJWSHeaderParameters extends JWSHeaderParameters {
-  alg: string
+  alg: JWSAlgorithm
 }
 
 /** Recognized Signed JWT Header Parameters, any other Header Members may also be present. */
 export interface JWTHeaderParameters extends CompactJWSHeaderParameters {
-  b64?: true
+  b64?: boolean
 }
 
 /** Recognized Compact JWE Header Parameters, any other Header Members may also be present. */
 export interface CompactJWEHeaderParameters extends JWEHeaderParameters {
-  alg: string
-  enc: string
+  alg: JWEKeyManagementAlgorithm
+  enc: JWEContentEncryptionAlgorithm
 }
 
 /** JSON Web Key Set */
@@ -739,10 +789,24 @@ export interface KeyObject {
  * {@link !SubtleCrypto.importKey} API to obtain a {@link !CryptoKey} from your existing key
  * material.
  */
-export type CryptoKey = Extract<
-  Awaited<ReturnType<typeof crypto.subtle.generateKey>>,
-  { type: string }
->
+export type CryptoKey = typeof globalThis extends {
+  crypto: { subtle: { generateKey(...args: any[]): Promise<infer R> } }
+}
+  ? Extract<R, { type: string }>
+  : CryptoKeyStructuralFallback
+
+/**
+ * Used as {@link CryptoKey} when the host runtime's `crypto` global is not exposed on `typeof
+ * globalThis`, including when it is absent from ambient types or declared with `const` or `let`. It
+ * remains structurally compatible with host {@link !CryptoKey} declarations so values flow freely to
+ * and from {@link !SubtleCrypto} APIs.
+ */
+export interface CryptoKeyStructuralFallback {
+  readonly algorithm: { name: string }
+  readonly extractable: boolean
+  readonly type: string
+  readonly usages: string[]
+}
 
 /** Generic interface for JWT producing classes. */
 export interface ProduceJWT {
@@ -775,78 +839,33 @@ export interface ProduceJWT {
   setJti(jwtId: string): this
 
   /**
-   * Set the "nbf" (Not Before) Claim.
-   *
-   * - If a `number` is passed as an argument it is used as the claim directly.
-   * - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
-   *   claim.
-   * - If a `string` is passed as an argument it is resolved to a time span, and then added to the
-   *   current unix timestamp and used as the claim.
-   *
-   * Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
-   * day".
-   *
-   * Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
-   * "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
-   * "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
-   * alias for a year.
-   *
-   * If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
-   * subtracted from the current unix timestamp. A "from now" suffix can also be used for
-   * readability when adding to the current unix timestamp.
+   * Set the "nbf" (Not Before) Claim. A `number` is used directly, a `Date` is converted to a Unix
+   * timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
+   * String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
+   * a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
    *
    * @param input "nbf" (Not Before) Claim value to set on the JWT Claims Set.
    */
   setNotBefore(input: number | string | Date): this
 
   /**
-   * Set the "exp" (Expiration Time) Claim.
-   *
-   * - If a `number` is passed as an argument it is used as the claim directly.
-   * - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
-   *   claim.
-   * - If a `string` is passed as an argument it is resolved to a time span, and then added to the
-   *   current unix timestamp and used as the claim.
-   *
-   * Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
-   * day".
-   *
-   * Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
-   * "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
-   * "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
-   * alias for a year.
-   *
-   * If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
-   * subtracted from the current unix timestamp. A "from now" suffix can also be used for
-   * readability when adding to the current unix timestamp.
+   * Set the "exp" (Expiration Time) Claim. A `number` is used directly, a `Date` is converted to a
+   * Unix timestamp, and a `string` is parsed as a time span relative to the current Unix timestamp.
+   * String units may be seconds, minutes, hours, days, weeks, or years; months are unsupported and
+   * a year is 365.25 days. A leading `-` or trailing `"ago"` subtracts the time span.
    *
    * @param input "exp" (Expiration Time) Claim value to set on the JWT Claims Set.
    */
   setExpirationTime(input: number | string | Date): this
 
   /**
-   * Set the "iat" (Issued At) Claim.
-   *
-   * - If no argument is used the current unix timestamp is used as the claim.
-   * - If a `number` is passed as an argument it is used as the claim directly.
-   * - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
-   *   claim.
-   * - If a `string` is passed as an argument it is resolved to a time span, and then added to the
-   *   current unix timestamp and used as the claim.
-   *
-   * Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
-   * day".
-   *
-   * Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
-   * "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
-   * "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
-   * alias for a year.
-   *
-   * If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
-   * subtracted from the current unix timestamp. A "from now" suffix can also be used for
-   * readability when adding to the current unix timestamp.
+   * Set the "iat" (Issued At) Claim. With no argument the current Unix timestamp is used. A
+   * `number` is used directly, a `Date` is converted to a Unix timestamp, and a `string` is parsed
+   * as a time span relative to the current Unix timestamp. String units may be seconds, minutes,
+   * hours, days, weeks, or years; months are unsupported and a year is 365.25 days. A leading `-`
+   * or trailing `"ago"` subtracts the time span.
    *
-   * @param input "iat" (Expiration Time) Claim value to set on the JWT Claims Set.
+   * @param input "iat" (Issued At) Claim value to set on the JWT Claims Set.
    */
   setIssuedAt(input?: number | string | Date): this
 }