From f52c2ff0c3edbe30b32a4c9858199bfbc9f9367e Mon Sep 17 00:00:00 2001 From: Filip Skokan Date: Sun, 23 Feb 2025 19:12:32 +0100 Subject: [PATCH] docs: add various exported symbol descriptions --- docs/jwe/general/encrypt/interfaces/Recipient.md | 2 ++ docs/jws/general/sign/interfaces/Signature.md | 2 ++ docs/jwt/unsecured/interfaces/UnsecuredResult.md | 2 ++ .../interfaces/GenerateKeyPairOptions.md | 2 ++ .../interfaces/GenerateKeyPairResult.md | 2 ++ .../interfaces/GenerateSecretOptions.md | 2 ++ docs/key/import/interfaces/KeyImportOptions.md | 2 ++ docs/types/interfaces/FlattenedJWE.md | 2 +- docs/types/interfaces/FlattenedJWS.md | 4 ++-- docs/types/interfaces/GeneralJWE.md | 2 ++ docs/types/interfaces/GeneralJWS.md | 4 ++-- docs/types/interfaces/ResolvedKey.md | 2 ++ src/index.ts | 6 ++++++ src/jwe/general/encrypt.ts | 1 + src/jws/general/sign.ts | 1 + src/jwt/unsecured.ts | 1 + src/key/generate_key_pair.ts | 2 ++ src/key/generate_secret.ts | 1 + src/key/import.ts | 1 + src/lib/base64url.ts | 2 ++ src/types.d.ts | 12 +++++++----- 21 files changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/jwe/general/encrypt/interfaces/Recipient.md b/docs/jwe/general/encrypt/interfaces/Recipient.md index 4d3dca56a4..f8aaf3969b 100644 --- a/docs/jwe/general/encrypt/interfaces/Recipient.md +++ b/docs/jwe/general/encrypt/interfaces/Recipient.md @@ -4,6 +4,8 @@ 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). +Used to build General JWE object's individual recipients. + ## Methods ### addRecipient() diff --git a/docs/jws/general/sign/interfaces/Signature.md b/docs/jws/general/sign/interfaces/Signature.md index 6a0dda30e7..1828f01fe3 100644 --- a/docs/jws/general/sign/interfaces/Signature.md +++ b/docs/jws/general/sign/interfaces/Signature.md @@ -4,6 +4,8 @@ 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). +Used to build General JWS object's individual signatures. + ## Methods ### addSignature() diff --git a/docs/jwt/unsecured/interfaces/UnsecuredResult.md b/docs/jwt/unsecured/interfaces/UnsecuredResult.md index 40f3068ace..b4c3cb339b 100644 --- a/docs/jwt/unsecured/interfaces/UnsecuredResult.md +++ b/docs/jwt/unsecured/interfaces/UnsecuredResult.md @@ -4,6 +4,8 @@ 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). +Result of decoding an Unsecured JWT. + ## Type Parameters | Type Parameter | Default type | diff --git a/docs/key/generate_key_pair/interfaces/GenerateKeyPairOptions.md b/docs/key/generate_key_pair/interfaces/GenerateKeyPairOptions.md index 63f3b69814..b55a40f804 100644 --- a/docs/key/generate_key_pair/interfaces/GenerateKeyPairOptions.md +++ b/docs/key/generate_key_pair/interfaces/GenerateKeyPairOptions.md @@ -4,6 +4,8 @@ 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). +Asymmetric key pair generation function options. + ## Properties ### crv? diff --git a/docs/key/generate_key_pair/interfaces/GenerateKeyPairResult.md b/docs/key/generate_key_pair/interfaces/GenerateKeyPairResult.md index 142351189c..6402c7dead 100644 --- a/docs/key/generate_key_pair/interfaces/GenerateKeyPairResult.md +++ b/docs/key/generate_key_pair/interfaces/GenerateKeyPairResult.md @@ -4,6 +4,8 @@ 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). +Asymmetric key pair generation function result. + ## Properties ### privateKey diff --git a/docs/key/generate_secret/interfaces/GenerateSecretOptions.md b/docs/key/generate_secret/interfaces/GenerateSecretOptions.md index 958a24f016..266845b6f4 100644 --- a/docs/key/generate_secret/interfaces/GenerateSecretOptions.md +++ b/docs/key/generate_secret/interfaces/GenerateSecretOptions.md @@ -4,6 +4,8 @@ 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). +Secret generation function options. + ## Properties ### extractable? diff --git a/docs/key/import/interfaces/KeyImportOptions.md b/docs/key/import/interfaces/KeyImportOptions.md index 329881918b..d546338b6d 100644 --- a/docs/key/import/interfaces/KeyImportOptions.md +++ b/docs/key/import/interfaces/KeyImportOptions.md @@ -4,6 +4,8 @@ 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). +Key Import Function options. + ## Properties ### extractable? diff --git a/docs/types/interfaces/FlattenedJWE.md b/docs/types/interfaces/FlattenedJWE.md index 258dd96a44..f7fae92a30 100644 --- a/docs/types/interfaces/FlattenedJWE.md +++ b/docs/types/interfaces/FlattenedJWE.md @@ -4,7 +4,7 @@ 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). -Flattened JWE definition. +Flattened JWE JSON Serialization Syntax token. ## Properties diff --git a/docs/types/interfaces/FlattenedJWS.md b/docs/types/interfaces/FlattenedJWS.md index aa6721f86c..6aac294d52 100644 --- a/docs/types/interfaces/FlattenedJWS.md +++ b/docs/types/interfaces/FlattenedJWS.md @@ -4,8 +4,8 @@ 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). -Flattened JWS definition. Payload is returned as an empty string when JWS Unencoded Payload -([RFC7797](https://www.rfc-editor.org/rfc/rfc7797)) is used. +Flattened JWS JSON Serialization Syntax token. Payload is returned as an empty string when JWS +Unencoded Payload ([RFC7797](https://www.rfc-editor.org/rfc/rfc7797)) is used. ## Properties diff --git a/docs/types/interfaces/GeneralJWE.md b/docs/types/interfaces/GeneralJWE.md index 555c4a19db..5f12d5450d 100644 --- a/docs/types/interfaces/GeneralJWE.md +++ b/docs/types/interfaces/GeneralJWE.md @@ -4,6 +4,8 @@ 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). +General JWE JSON Serialization Syntax token. + ## Properties ### ciphertext diff --git a/docs/types/interfaces/GeneralJWS.md b/docs/types/interfaces/GeneralJWS.md index 3bcf00d3e4..e7d7222182 100644 --- a/docs/types/interfaces/GeneralJWS.md +++ b/docs/types/interfaces/GeneralJWS.md @@ -4,8 +4,8 @@ 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). -General JWS definition. Payload is returned as an empty string when JWS Unencoded Payload -([RFC7797](https://www.rfc-editor.org/rfc/rfc7797)) is used. +General JWS JSON Serialization Syntax token. Payload is returned as an empty string when JWS +Unencoded Payload ([RFC7797](https://www.rfc-editor.org/rfc/rfc7797)) is used. ## Properties diff --git a/docs/types/interfaces/ResolvedKey.md b/docs/types/interfaces/ResolvedKey.md index 81802e374d..6b57e27c08 100644 --- a/docs/types/interfaces/ResolvedKey.md +++ b/docs/types/interfaces/ResolvedKey.md @@ -4,6 +4,8 @@ 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). +When key resolver functions are used this becomes part of successful resolves + ## Properties ### key diff --git a/src/index.ts b/src/index.ts index 93c1453036..39840a32ed 100644 --- a/src/index.ts +++ b/src/index.ts @@ -110,4 +110,10 @@ export type { 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/src/jwe/general/encrypt.ts b/src/jwe/general/encrypt.ts index 93374ef531..02d9ee968d 100644 --- a/src/jwe/general/encrypt.ts +++ b/src/jwe/general/encrypt.ts @@ -16,6 +16,7 @@ import validateCrit from '../../lib/validate_crit.js' import normalizeKey from '../../lib/normalize_key.js' import checkKeyType from '../../lib/check_key_type.js' +/** Used to build General JWE object's individual recipients. */ export interface Recipient { /** * Sets the JWE Per-Recipient Unprotected Header on the Recipient object. diff --git a/src/jws/general/sign.ts b/src/jws/general/sign.ts index 89fdac3f71..21ba3c9885 100644 --- a/src/jws/general/sign.ts +++ b/src/jws/general/sign.ts @@ -8,6 +8,7 @@ import type * as types from '../../types.d.ts' import { FlattenedSign } from '../flattened/sign.js' import { JWSInvalid } from '../../util/errors.js' +/** Used to build General JWS object's individual signatures. */ export interface Signature { /** * Sets the JWS Protected Header on the Signature object. diff --git a/src/jwt/unsecured.ts b/src/jwt/unsecured.ts index 6b10560329..22d1546d6d 100644 --- a/src/jwt/unsecured.ts +++ b/src/jwt/unsecured.ts @@ -12,6 +12,7 @@ import { JWTInvalid } from '../util/errors.js' import jwtPayload from '../lib/jwt_claims_set.js' import { ProduceJWT } from './produce.js' +/** Result of decoding an Unsecured JWT. */ export interface UnsecuredResult { payload: PayloadType & types.JWTPayload header: types.JWSHeaderParameters diff --git a/src/key/generate_key_pair.ts b/src/key/generate_key_pair.ts index e564e49ef7..44a87ab8d6 100644 --- a/src/key/generate_key_pair.ts +++ b/src/key/generate_key_pair.ts @@ -8,6 +8,7 @@ import { JOSENotSupported } from '../util/errors.js' import type * as types from '../types.d.ts' +/** Asymmetric key pair generation function result. */ export interface GenerateKeyPairResult { /** The generated Private Key. */ privateKey: types.CryptoKey @@ -16,6 +17,7 @@ export interface GenerateKeyPairResult { publicKey: types.CryptoKey } +/** Asymmetric key pair generation function options. */ export interface GenerateKeyPairOptions { /** * The EC "crv" (Curve) or OKP "crv" (Subtype of Key Pair) value to generate. The curve must be diff --git a/src/key/generate_secret.ts b/src/key/generate_secret.ts index 2ac5c156ec..e2e9580a61 100644 --- a/src/key/generate_secret.ts +++ b/src/key/generate_secret.ts @@ -8,6 +8,7 @@ import { JOSENotSupported } from '../util/errors.js' import type * as types from '../types.d.ts' +/** Secret generation function options. */ export interface GenerateSecretOptions { /** The value to use as {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false. */ extractable?: boolean diff --git a/src/key/import.ts b/src/key/import.ts index 7f76ae7034..1f6817e17f 100644 --- a/src/key/import.ts +++ b/src/key/import.ts @@ -12,6 +12,7 @@ import { JOSENotSupported } from '../util/errors.js' import isObject from '../lib/is_object.js' import type * as types from '../types.d.ts' +/** Key Import Function options. */ export interface KeyImportOptions { /** * The value to use as {@link !SubtleCrypto.importKey} `extractable` argument. Default is false for diff --git a/src/lib/base64url.ts b/src/lib/base64url.ts index 5bfe3d825d..6084540969 100644 --- a/src/lib/base64url.ts +++ b/src/lib/base64url.ts @@ -16,6 +16,7 @@ export function encodeBase64(input: Uint8Array): string { return btoa(arr.join('')) } +/** Encodes an input using Base64URL with no padding. */ export function encode(input: Uint8Array | string): string { let unencoded = input if (typeof unencoded === 'string') { @@ -46,6 +47,7 @@ export function decodeBase64(encoded: string): Uint8Array { return bytes } +/** Decodes a Base64URL encoded input. */ export function decode(input: Uint8Array | string): Uint8Array { // @ts-ignore if (Uint8Array.fromBase64) { diff --git a/src/types.d.ts b/src/types.d.ts index 4a908d4693..397cb4e46b 100644 --- a/src/types.d.ts +++ b/src/types.d.ts @@ -216,8 +216,8 @@ export interface GeneralJWSInput { } /** - * Flattened JWS definition. Payload is returned as an empty string when JWS Unencoded Payload - * ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used. + * 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. */ export interface FlattenedJWS extends Partial { payload: string @@ -225,8 +225,8 @@ export interface FlattenedJWS extends Partial { } /** - * General JWS definition. Payload is returned as an empty string when JWS Unencoded Payload - * ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used. + * 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. */ export interface GeneralJWS { payload: string @@ -307,7 +307,7 @@ export interface JWEKeyManagementHeaderParameters { epk?: CryptoKey | KeyObject } -/** Flattened JWE definition. */ +/** Flattened JWE JSON Serialization Syntax token. */ export interface FlattenedJWE { /** * The "aad" member MUST be present and contain the value BASE64URL(JWE AAD)) when the JWE AAD @@ -361,6 +361,7 @@ export interface FlattenedJWE { unprotected?: JWEHeaderParameters } +/** General JWE JSON Serialization Syntax token. */ export interface GeneralJWE extends Omit { recipients: Pick[] } @@ -647,6 +648,7 @@ export interface JWTDecryptResult { protectedHeader: CompactJWEHeaderParameters } +/** When key resolver functions are used this becomes part of successful resolves */ export interface ResolvedKey { /** Key resolved from the key resolver function. */ key: CryptoKey | Uint8Array