jose 4.5.3 → 4.6.0

package/dist/types/jwt/unsecured.d.ts

@@ -4,7 +4,41 @@ export interface UnsecuredResult {
     payload: JWTPayload;
     header: JWSHeaderParameters;
 }
+/**
+ * The UnsecuredJWT class is a utility for dealing with `{ "alg": "none" }` Unsecured JWTs.
+ *
+ * @example Encoding
+ * ```js
+ * const unsecuredJwt = new jose.UnsecuredJWT({ 'urn:example:claim': true })
+ *   .setIssuedAt()
+ *   .setIssuer('urn:example:issuer')
+ *   .setAudience('urn:example:audience')
+ *   .setExpirationTime('2h')
+ *   .encode()
+ *
+ * console.log(unsecuredJwt)
+ * ```
+ *
+ * @example Decoding
+ * ```js
+ * const payload = jose.UnsecuredJWT.decode(jwt, {
+ *   issuer: 'urn:example:issuer',
+ *   audience: 'urn:example:audience'
+ * })
+ *
+ * console.log(payload)
+ * ```
+ */
 export declare class UnsecuredJWT extends ProduceJWT {
+    /**
+     * Encodes the Unsecured JWT.
+     */
     encode(): string;
+    /**
+     * Decodes an unsecured JWT.
+     *
+     * @param jwt Unsecured JWT to decode the payload of.
+     * @param options JWT Claims Set validation options.
+     */
     static decode(jwt: string, options?: JWTClaimVerificationOptions): UnsecuredResult;
 }

package/dist/types/jwt/verify.d.ts

@@ -1,7 +1,42 @@
 import type { KeyLike, VerifyOptions, JWTClaimVerificationOptions, JWTHeaderParameters, GetKeyFunction, FlattenedJWSInput, JWTVerifyResult, ResolvedKey } from '../types';
+/**
+ * Combination of JWS Verification options and JWT Claims Set verification options.
+ */
 export interface JWTVerifyOptions extends VerifyOptions, JWTClaimVerificationOptions {
 }
+/**
+ * Interface for JWT Verification dynamic key resolution.
+ * No token components have been verified at the time of this function call.
+ *
+ * See [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset)
+ * to verify using a remote JSON Web Key Set.
+ */
 export interface JWTVerifyGetKey extends GetKeyFunction<JWTHeaderParameters, FlattenedJWSInput> {
 }
+/**
+ * Verifies the JWT format (to be a JWS Compact format), verifies the JWS signature, validates the JWT Claims Set.
+ *
+ * @param jwt JSON Web Token value (encoded as JWS).
+ * @param key Key to verify the JWT with.
+ * @param options JWT Decryption and JWT Claims Set validation options.
+ *
+ * @example Usage
+ * ```js
+ * const jwt = 'eyJhbGciOiJFUzI1NiJ9.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6dHJ1ZSwiaWF0IjoxNjA0MzE1MDc0LCJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSJ9.hx1nOfAT5LlXuzu8O-bhjXBGpklWDt2EsHw7-MDn49NrnwvVsstNhEnkW2ddauB7eSikFtUNeumLpFI9CWDBsg'
+ *
+ * const { payload, protectedHeader } = await jose.jwtVerify(jwt, publicKey, {
+ *   issuer: 'urn:example:issuer',
+ *   audience: 'urn:example:audience'
+ * })
+ *
+ * console.log(protectedHeader)
+ * console.log(payload)
+ * ```
+ */
 export declare function jwtVerify(jwt: string | Uint8Array, key: KeyLike | Uint8Array, options?: JWTVerifyOptions): Promise<JWTVerifyResult>;
+/**
+ * @param jwt JSON Web Token value (encoded as JWS).
+ * @param getKey Function resolving a key to verify the JWT with.
+ * @param options JWT Decryption and JWT Claims Set validation options.
+ */
 export declare function jwtVerify(jwt: string | Uint8Array, getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): Promise<JWTVerifyResult & ResolvedKey>;

package/dist/types/key/export.d.ts

@@ -1,4 +1,42 @@
 import type { JWK, KeyLike } from '../types';
+/**
+ * Exports a runtime-specific public key representation (KeyObject or CryptoKey) to an PEM-encoded SPKI string format.
+ *
+ * @param key Key representation to transform to an PEM-encoded SPKI string format.
+ *
+ * @example Usage
+ * ```js
+ * const spkiPem = await jose.exportSPKI(publicKey)
+ *
+ * console.log(spkiPem)
+ * ```
+ */
 export declare function exportSPKI(key: KeyLike): Promise<string>;
+/**
+ * Exports a runtime-specific private key representation (KeyObject or CryptoKey) to an PEM-encoded PKCS8 string format.
+ *
+ * @param key Key representation to transform to an PEM-encoded PKCS8 string format.
+ *
+ * @example Usage
+ * ```js
+ * const pkcs8Pem = await jose.exportPKCS8(privateKey)
+ *
+ * console.log(pkcs8Pem)
+ * ```
+ */
 export declare function exportPKCS8(key: KeyLike): Promise<string>;
+/**
+ * Exports a runtime-specific key representation (KeyLike) to a JWK.
+ *
+ * @param key Key representation to export as JWK.
+ *
+ * @example Usage
+ * ```js
+ * const privateJwk = await jose.exportJWK(privateKey)
+ * const publicJwk = await jose.exportJWK(publicKey)
+ *
+ * console.log(privateJwk)
+ * console.log(publicJwk)
+ * ```
+ */
 export declare function exportJWK(key: KeyLike | Uint8Array): Promise<JWK>;

package/dist/types/key/generate_key_pair.d.ts

@@ -1,11 +1,49 @@
 import type { KeyLike } from '../types';
 export interface GenerateKeyPairResult {
+    /**
+     * The generated Private Key.
+     */
     privateKey: KeyLike;
+    /**
+     * Public Key corresponding to the generated Private Key.
+     */
     publicKey: KeyLike;
 }
 export interface GenerateKeyPairOptions {
+    /**
+     * The EC "crv" (Curve) or OKP "crv" (Subtype of Key Pair) value to generate.
+     * The curve must be both supported on the runtime as well as applicable for
+     * the given JWA algorithm identifier.
+     */
     crv?: string;
+    /**
+     * A hint for RSA algorithms to generate an RSA key of a given `modulusLength`
+     * (Key size in bits). JOSE requires 2048 bits or larger. Default is 2048.
+     */
     modulusLength?: number;
+    /**
+     * (Web Cryptography API specific) The value to use as
+     * [SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
+     * `extractable` argument. Default is false.
+     */
     extractable?: boolean;
 }
+/**
+ * Generates a private and a public key for a given JWA algorithm identifier.
+ * This can only generate asymmetric key pairs. For symmetric secrets use the
+ * `generateSecret` function.
+ *
+ * Note: Under Web Cryptography API runtime the `privateKey` is generated with
+ * `extractable` set to `false` by default.
+ *
+ * @param alg JWA Algorithm Identifier to be used with the generated key pair.
+ * @param options Additional options passed down to the key pair generation.
+ *
+ * @example Usage
+ * ```js
+ * const { publicKey, privateKey } = await jose.generateKeyPair('PS256')
+ * console.log(publicKey)
+ * console.log(privateKey)
+ * ```
+ */
 export declare function generateKeyPair(alg: string, options?: GenerateKeyPairOptions): Promise<GenerateKeyPairResult>;

package/dist/types/key/generate_secret.d.ts

@@ -1,5 +1,25 @@
 import type { KeyLike } from '../types';
 export interface GenerateSecretOptions {
+    /**
+     * (Web Cryptography API specific) The value to use as
+     * [SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
+     * `extractable` argument. Default is false.
+     */
     extractable?: boolean;
 }
+/**
+ * Generates a symmetric secret key for a given JWA algorithm identifier.
+ *
+ * Note: Under Web Cryptography API runtime the secret key is generated with
+ * `extractable` set to `false` by default.
+ *
+ * @example Usage
+ * ```js
+ * const secret = await jose.generateSecret('HS256')
+ * console.log(secret)
+ * ```
+ *
+ * @param alg JWA Algorithm Identifier to be used with the generated secret.
+ * @param options Additional options passed down to the secret generation.
+ */
 export declare function generateSecret(alg: string, options?: GenerateSecretOptions): Promise<KeyLike | Uint8Array>;

package/dist/types/key/import.d.ts

@@ -1,8 +1,104 @@
 import type { JWK, KeyLike } from '../types';
 export interface PEMImportOptions {
+    /**
+     * (Web Cryptography API specific) The value to use as
+     * [SubtleCrypto.importKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
+     * `extractable` argument. Default is false.
+     */
     extractable?: boolean;
 }
+/**
+ * Imports an PEM-encoded SPKI string as a runtime-specific public key representation (KeyObject or CryptoKey).
+ * See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
+ * requirements and mapping.
+ *
+ * @param pem PEM-encoded SPKI string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key.
+ *
+ * @example Usage
+ * ```js
+ * const algorithm = 'ES256'
+ * const spki = `-----BEGIN PUBLIC KEY-----
+ * MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFlHHWfLk0gLBbsLTcuCrbCqoHqmM
+ * YJepMC+Q+Dd6RBmBiA41evUsNMwLeN+PNFqib+xwi9JkJ8qhZkq8Y/IzGg==
+ * -----END PUBLIC KEY-----`
+ * const ecPublicKey = await jose.importSPKI(spki, algorithm)
+ * ```
+ */
 export declare function importSPKI(spki: string, alg: string, options?: PEMImportOptions): Promise<KeyLike>;
+/**
+ * Imports the SPKI from an X.509 string certificate as a runtime-specific public key representation (KeyObject or CryptoKey).
+ * See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
+ * requirements and mapping.
+ *
+ * @param pem X.509 certificate string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key.
+ *
+ * @example Usage
+ * ```js
+ * const algorithm = 'ES256'
+ * const x509 = `-----BEGIN CERTIFICATE-----
+ * MIIBXjCCAQSgAwIBAgIGAXvykuMKMAoGCCqGSM49BAMCMDYxNDAyBgNVBAMMK3Np
+ * QXBNOXpBdk1VaXhXVWVGaGtjZXg1NjJRRzFyQUhXaV96UlFQTVpQaG8wHhcNMjEw
+ * OTE3MDcwNTE3WhcNMjIwNzE0MDcwNTE3WjA2MTQwMgYDVQQDDCtzaUFwTTl6QXZN
+ * VWl4V1VlRmhrY2V4NTYyUUcxckFIV2lfelJRUE1aUGhvMFkwEwYHKoZIzj0CAQYI
+ * KoZIzj0DAQcDQgAE8PbPvCv5D5xBFHEZlBp/q5OEUymq7RIgWIi7tkl9aGSpYE35
+ * UH+kBKDnphJO3odpPZ5gvgKs2nwRWcrDnUjYLDAKBggqhkjOPQQDAgNIADBFAiEA
+ * 1yyMTRe66MhEXID9+uVub7woMkNYd0LhSHwKSPMUUTkCIFQGsfm1ecXOpeGOufAh
+ * v+A1QWZMuTWqYt+uh/YSRNDn
+ * -----END CERTIFICATE-----`
+ * const ecPublicKey = await jose.importX509(x509, algorithm)
+ * ```
+ */
 export declare function importX509(x509: string, alg: string, options?: PEMImportOptions): Promise<KeyLike>;
+/**
+ * Imports an PEM-encoded PKCS8 string as a runtime-specific private key representation (KeyObject or CryptoKey).
+ * See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
+ * requirements and mapping. Encrypted keys are not supported.
+ *
+ * @param pem PEM-encoded PKCS8 string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key.
+ *
+ * @example Usage
+ * ```js
+ * const algorithm = 'ES256'
+ * const pkcs8 = `-----BEGIN PRIVATE KEY-----
+ * MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgiyvo0X+VQ0yIrOaN
+ * nlrnUclopnvuuMfoc8HHly3505OhRANCAAQWUcdZ8uTSAsFuwtNy4KtsKqgeqYxg
+ * l6kwL5D4N3pEGYGIDjV69Sw0zAt43480WqJv7HCL0mQnyqFmSrxj8jMa
+ * -----END PRIVATE KEY-----`
+ * const ecPrivateKey = await jose.importPKCS8(pkcs8, algorithm)
+ * ```
+ */
 export declare function importPKCS8(pkcs8: string, alg: string, options?: PEMImportOptions): Promise<KeyLike>;
+/**
+ * Imports a JWK to a runtime-specific key representation (KeyLike). Either
+ * JWK "alg" (Algorithm) Parameter must be present or the optional "alg" argument. When
+ * running on a runtime using [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/)
+ * the jwk parameters "use", "key_ops", and "ext" are also used in the resulting `CryptoKey`.
+ * See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
+ * requirements and mapping.
+ *
+ * @param jwk JSON Web Key.
+ * @param alg JSON Web Algorithm identifier to be used with the imported key.
+ * Default is the "alg" property on the JWK.
+ * @param octAsKeyObject Forces a symmetric key to be imported to a KeyObject or
+ * CryptoKey. Default is true unless JWK "ext" (Extractable) is true.
+ *
+ * @example Usage
+ * ```js
+ * const ecPublicKey = await jose.importJWK({
+ *   crv: 'P-256',
+ *   kty: 'EC',
+ *   x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
+ *   y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo'
+ * }, 'ES256')
+ *
+ * const rsaPublicKey = await jose.importJWK({
+ *   kty: 'RSA',
+ *   e: 'AQAB',
+ *   n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ'
+ * }, 'PS256')
+ * ```
+ */
 export declare function importJWK(jwk: JWK, alg?: string, octAsKeyObject?: boolean): Promise<KeyLike | Uint8Array>;