@enbox/agent 0.0.1

package/dist/types/prototyping/crypto/jose/jwe-compact.d.ts

@@ -0,0 +1,135 @@
+import type { Jwk, KeyIdentifier } from '@enbox/crypto';
+import type { CryptoApi } from '../types/crypto-api.js';
+import type { KeyManager } from '../types/key-manager.js';
+import type { JweDecryptOptions, JweEncryptOptions, JweHeaderParams } from './jwe.js';
+/**
+ * Parameters required for decrypting a JWE in Compact Serialization format.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface CompactJweDecryptParams<TKeyManager, TCrypto> {
+    /** The JWE string in Compact Serialization format. */
+    jwe: string;
+    /**
+     * The decryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager?: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto?: TCrypto;
+    /** {@inheritDoc JweDecryptOptions} */
+    options?: JweDecryptOptions;
+}
+/**
+ * Result of decrypting a JWE in Compact Serialization format.
+ */
+export interface CompactJweDecryptResult {
+    /** Decrypted plaintext as a byte array. */
+    plaintext: Uint8Array;
+    /** The protected header of the JWE. */
+    protectedHeader: JweHeaderParams;
+}
+/**
+ * Parameters required for encrypting data into a JWE in Compact Serialization format.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface CompactJweEncryptParams<TKeyManager, TCrypto> {
+    /** The plaintext data to be encrypted as a byte array. */
+    plaintext: Uint8Array;
+    /** JWE Protected Header containing encryption algorithm details. */
+    protectedHeader: JweHeaderParams;
+    /**
+     * The encryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager?: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto?: TCrypto;
+    /** {@inheritDoc JweEncryptOptions} */
+    options?: JweEncryptOptions;
+}
+/**
+ * The `CompactJwe` class facilitates encryption and decryption processes using the JSON Web
+ * Encryption (JWE) Compact Serialization format. This class adheres to the specifications
+ * outlined in {@link https://datatracker.ietf.org/doc/html/rfc7516 | RFC 7516}, enabling secure
+ * data encapsulation through various cryptographic algorithms.
+ *
+ * Compact Serialization is a space-efficient representation of JWE, suitable for contexts
+ * where verbose data structures are impractical, such as HTTP headers. It provides mechanisms to
+ * encrypt content and protect its integrity with authenticated encryption, ensuring
+ * confidentiality, authenticity, and non-repudiation.
+ *
+ * This class supports the following operations:
+ * - Decrypting data from a compact serialized JWE string.
+ * - Encrypting data and producing a compact serialized JWE string.
+ *
+ * Usage involves specifying the cryptographic details, such as keys and algorithms, and the class
+ * handles the complexities of the JWE processing, including parsing, validating, and applying the
+ * cryptographic operations defined in the JWE specification.
+ *
+ * @example
+ * ```ts
+ *  // Example usage of encrypt method
+ * const plaintext = new TextEncoder().encode("Secret Message");
+ * const key = { kty: "oct", k: "your-secret-key" }; // Example symmetric key
+ * const protectedHeader = { alg: "dir", enc: "A256GCM" };
+ * const encryptedJweString = await CompactJwe.encrypt({
+ *   plaintext,
+ *   protectedHeader,
+ *   key,
+ * });
+ * console.log(encryptedJweString); // Outputs the JWE string in Compact Serialization format
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example usage of decrypt method
+ * const jweString = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // A JWE in Compact Serialization
+ * const decryptionKey = { kty: "oct", k: "your-secret-key" }; // The key must match the one used for encryption
+ * const { plaintext, protectedHeader } = await CompactJwe.decrypt({
+ *   jwe: jweString,
+ *   key: decryptionKey,
+ * });
+ * console.log(new TextDecoder().decode(plaintext)); // Outputs the decrypted message
+ * ```
+ */
+export declare class CompactJwe {
+    /**
+     * Decrypts a JWE string in Compact Serialization format, extracting the plaintext and
+     * reconstructing the JWE Protected Header.
+     *
+     * This method parses the compact JWE, validates its structure, and applies the appropriate
+     * decryption algorithm as specified in the JWE Protected Header. It returns the decrypted
+     * plaintext along with the reconstructed protected header, ensuring the data's authenticity
+     * and integrity.
+     *
+     * @param params - The decryption parameters including the JWE string, cryptographic key, and
+     *                 optional instances of Key Manager and Crypto API.
+     * @returns A promise resolving to the decrypted content and the JWE Protected Header.
+     * @throws {@link CryptoError} if the JWE format is invalid or decryption fails.
+     */
+    static decrypt<TKeyManager extends KeyManager | undefined = KeyManager, TCrypto extends CryptoApi | undefined = CryptoApi>({ jwe, key, keyManager, crypto, options }: CompactJweDecryptParams<TKeyManager, TCrypto>): Promise<CompactJweDecryptResult>;
+    /**
+     * Encrypts plaintext to a JWE string in Compact Serialization format, encapsulating the content
+     * with the specified cryptographic protections.
+     *
+     * It constructs the JWE by encrypting the plaintext, then serializing the output to the
+     * compact format, which includes concatenating various components like the protected header,
+     * encrypted key, initialization vector, ciphertext, and authentication tag.
+     *
+     * @param params - The encryption parameters, including plaintext, JWE Protected Header,
+     *                 cryptographic key, and optional Key Manager and Crypto API instances.
+     * @returns A promise that resolves to a string representing the JWE in Compact Serialization
+     *          format.
+     * @throws {@link CryptoError} if encryption fails or the input parameters are invalid.
+     */
+    static encrypt<TKeyManager extends KeyManager | undefined = KeyManager, TCrypto extends CryptoApi | undefined = CryptoApi>({ plaintext, protectedHeader, key, keyManager, crypto, options }: CompactJweEncryptParams<TKeyManager, TCrypto>): Promise<string>;
+}
+//# sourceMappingURL=jwe-compact.d.ts.map

package/dist/types/prototyping/crypto/jose/jwe-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwe-compact.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/jose/jwe-compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAIxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAOtF;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,WAAW,EAAE,OAAO;IAC3D,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAE,aAAa,GAAG,GAAG,GAAG,UAAU,CAAC;IAEtC,yEAAyE;IACzE,UAAU,CAAC,EAAE,WAAW,CAAC;IAEzB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,sCAAsC;IACtC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,SAAS,EAAE,UAAU,CAAC;IAEtB,uCAAuC;IACvC,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,WAAW,EAAE,OAAO;IAC3D,0DAA0D;IAC1D,SAAS,EAAE,UAAU,CAAC;IAEtB,oEAAoE;IACpE,eAAe,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,GAAG,EAAE,aAAa,GAAG,GAAG,GAAG,UAAU,CAAC;IAEtC,yEAAyE;IACzE,UAAU,CAAC,EAAE,WAAW,CAAC;IAEzB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,sCAAsC;IACtC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,UAAU;IACrB;;;;;;;;;;;;;OAaG;WACiB,OAAO,CACzB,WAAW,SAAS,UAAU,GAAG,SAAS,GAAG,UAAU,EACvD,OAAO,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS,EACjD,EACA,GAAG,EACH,GAAG,EACH,UAAkC,EAClC,MAA6B,EAC7B,OAAY,EACb,EAAE,uBAAuB,CAAC,WAAW,EAAE,OAAO,CAAC,GAC7C,OAAO,CAAC,uBAAuB,CAAC;IA0CnC;;;;;;;;;;;;;OAaG;WACiB,OAAO,CACzB,WAAW,SAAS,UAAU,GAAG,SAAS,GAAG,UAAU,EACvD,OAAO,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS,EACjD,EACA,SAAS,EACT,eAAe,EACf,GAAG,EACH,UAAkC,EAClC,MAA6B,EAC7B,OAAY,EACb,EAAE,uBAAuB,CAAC,WAAW,EAAE,OAAO,CAAC,GAC7C,OAAO,CAAC,MAAM,CAAC;CAQnB"}

package/dist/types/prototyping/crypto/jose/jwe-flattened.d.ts

@@ -0,0 +1,134 @@
+import type { Jwk, KeyIdentifier } from '@enbox/crypto';
+import type { CryptoApi } from '../types/crypto-api.js';
+import type { KeyManager } from '../types/key-manager.js';
+import type { JweDecryptOptions, JweEncryptOptions, JweHeaderParams } from './jwe.js';
+/**
+ * Parameters required for decrypting a flattened JWE.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface FlattenedJweDecryptParams<TKeyManager, TCrypto> {
+    /** The flattened JWE. */
+    jwe: FlattenedJweParams | FlattenedJwe;
+    /**
+     * The decryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager?: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto?: TCrypto;
+    /** {@inheritDoc JweDecryptOptions} */
+    options?: JweDecryptOptions;
+}
+/**
+ * Result of decrypting a flattened JWE, containing the plaintext and related information.
+ */
+export interface FlattenedJweDecryptResult {
+    /** JWE Additional Authenticated Data (AAD). */
+    additionalAuthenticatedData?: Uint8Array;
+    /** Plaintext. */
+    plaintext: Uint8Array;
+    /** JWE Protected Header. */
+    protectedHeader?: Partial<JweHeaderParams>;
+    /** JWE Shared Unprotected Header. */
+    sharedUnprotectedHeader?: Partial<JweHeaderParams>;
+    /** JWE Per-Recipient Unprotected Header. */
+    unprotectedHeader?: Partial<JweHeaderParams>;
+}
+/**
+ * Parameters for encrypting data into a flattened JWE format.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface FlattenedJweEncryptParams<TKeyManager, TCrypto> extends FlattenedJweDecryptResult {
+    /**
+     * The encryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager?: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto?: TCrypto;
+    /** {@inheritDoc JweEncryptOptions} */
+    options?: JweEncryptOptions;
+}
+/**
+ * Represents the parameters for a flattened JWE object, typically used in single-recipient
+ * scenarios.
+ */
+export interface FlattenedJweParams {
+    /** Base64URL encoded additional authenticated data. */
+    aad?: string;
+    /** Base64URL encoded ciphertext. */
+    ciphertext: string;
+    /** Base64URL encoded encrypted key. */
+    encrypted_key?: string;
+    /** Per-Recipient Unprotected Header parameters. */
+    header?: Partial<JweHeaderParams>;
+    /** Base64URL encoded initialization vector. */
+    iv?: string;
+    /** Base64URL encoded string of the Protected Header. */
+    protected?: string;
+    /** Base64URL encoded authentication tag. */
+    tag?: string;
+    /** Shared Unprotected Header parameters. */
+    unprotected?: Partial<JweHeaderParams>;
+}
+/**
+ * The `FlattenedJwe` class handles the encryption and decryption of JSON Web Encryption (JWE)
+ * objects in the flattened serialization format. This format is a compact, URL-safe means of
+ * representing encrypted content, typically used when dealing with a single recipient or when
+ * bandwidth efficiency is important.
+ *
+ * This class provides methods to encrypt plaintext to a flattened JWE and decrypt a flattened JWE
+ * back to plaintext, utilizing a variety of supported cryptographic algorithms as specified in the
+ * JWE header parameters.
+ *
+ * @example
+ * ```ts
+ *  // Example usage of encrypt method
+ * const plaintext = new TextEncoder().encode("Secret Message");
+ * const key = { kty: "oct", k: "your-secret-key" }; // Example symmetric key
+ * const protectedHeader = { alg: "dir", enc: "A256GCM" };
+ * const encryptedJwe = await FlattenedJwe.encrypt({
+ *   plaintext,
+ *   protectedHeader,
+ *   key,
+ * });
+ * ```
+ *
+ * @example
+ * // Decryption example
+ * const { plaintext, protectedHeader } = await FlattenedJwe.decrypt({
+ *   jwe: yourFlattenedJweObject,
+ *   key: yourDecryptionKey,
+ *   crypto: new YourCryptoApi(),
+ * });
+ */
+export declare class FlattenedJwe {
+    /** Base64URL encoded additional authenticated data. */
+    aad?: string;
+    /** Base64URL encoded ciphertext. */
+    ciphertext: string;
+    /** Base64URL encoded encrypted key. */
+    encrypted_key?: string;
+    /** Per-Recipient Unprotected Header parameters. */
+    header?: Partial<JweHeaderParams>;
+    /** Base64URL encoded initialization vector. */
+    iv?: string;
+    /** Base64URL encoded string of the Protected Header. */
+    protected?: string;
+    /** Base64URL encoded authentication tag. */
+    tag?: string;
+    /** Shared Unprotected Header parameters. */
+    unprotected?: Partial<JweHeaderParams>;
+    constructor(params: FlattenedJweParams);
+    static decrypt<TKeyManager extends KeyManager | undefined = KeyManager, TCrypto extends CryptoApi | undefined = CryptoApi>({ jwe, key, keyManager, crypto, options }: FlattenedJweDecryptParams<TKeyManager, TCrypto>): Promise<FlattenedJweDecryptResult>;
+    static encrypt<TKeyManager extends KeyManager | undefined = KeyManager, TCrypto extends CryptoApi | undefined = CryptoApi>({ key, plaintext, additionalAuthenticatedData, protectedHeader, sharedUnprotectedHeader, unprotectedHeader, keyManager, crypto, }: FlattenedJweEncryptParams<TKeyManager, TCrypto>): Promise<FlattenedJwe>;
+}
+//# sourceMappingURL=jwe-flattened.d.ts.map

package/dist/types/prototyping/crypto/jose/jwe-flattened.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwe-flattened.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/jose/jwe-flattened.ts"],"names":[],"mappings":"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"}

package/dist/types/prototyping/crypto/jose/jwe.d.ts

@@ -0,0 +1,378 @@
+import type { JoseHeaderParams, Jwk, KeyIdentifier } from '@enbox/crypto';
+import type { CryptoApi } from '../types/crypto-api.js';
+import type { KeyManager } from '../types/key-manager.js';
+/**
+ * Specifies options for decrypting a JWE, allowing the caller to define constraints on the JWE
+ * decryption process, particularly regarding the algorithms used.
+ *
+ * These options ensure that only expected and permitted algorithms are utilized during the
+ * decryption, enhancing security by preventing unexpected algorithm usage.
+ */
+export interface JweDecryptOptions {
+    /**
+     * The allowed "alg" (Algorithm) Header Parameter values.
+     *
+     * These values specify the cryptographic algorithms that are permissible for decrypting
+     * the Content Encryption Key (CEK) or for key agreement to determine the CEK.
+     *
+     * Note: If not specified, all algorithm values are considered allowed, which might not be
+     * desirable in all contexts.
+     */
+    allowedAlgValues?: string[];
+    /**
+     * The allowed "enc" (Encryption) Header Parameter values.
+     *
+     * These values determine the cryptographic algorithms that can be used for decrypting the
+     * ciphertext and protecting the integrity of the plaintext and Additional Authenticated Data.
+     *
+     * Note: If left unspecified, it implies that all encryption algorithms are acceptable, which may
+     * not be secure in every scenario.
+     *
+     */
+    allowedEncValues?: string[];
+}
+/**
+ * Placeholder for specifying options during the JWE encryption process. Currently, this interface
+ * does not define any specific options but can be extended in the future to include parameters
+ * that control various aspects of the JWE encryption workflow.
+ */
+export interface JweEncryptOptions {
+}
+/**
+ * JSON Web Encryption (JWE) Header Parameters
+ *
+ * The Header Parameter names for use in JWEs are registered in the IANA "JSON Web Signature and
+ * Encryption Header Parameters" registry.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1 | RFC 7516, Section 4.1}
+ */
+export interface JweHeaderParams extends JoseHeaderParams {
+    /**
+     * Algorithm Header Parameter
+     *
+     * Identifies the cryptographic algorithm used to encrypt or determine the value of the Content
+     * Encryption Key (CEK). The encrypted content is not usable if the "alg" value does not represent
+     * a supported algorithm, or if the recipient does not have a key that can be used with that
+     * algorithm.
+     *
+     * "alg" values should either be registered in the IANA "JSON Web Signature and Encryption
+     * Algorithms" registry or be a value that contains a Collision-Resistant Name. The "alg" value is
+     * a case-sensitive ASCII string.  This Header Parameter MUST be present and MUST be understood
+     * and processed by implementations.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.1 | RFC 7516, Section 4.1.1}
+     */
+    alg: 'A128KW' | 'A192KW' | 'A256KW' | 'dir' | 'ECDH-ES' | 'ECDH-ES+A128KW' | 'ECDH-ES+A192KW' | 'ECDH-ES+A256KW' | 'A128GCMKW' | 'A192GCMKW' | 'A256GCMKW' | 'PBES2-HS256+A128KW' | 'PBES2-HS384+A192KW' | 'PBES2-HS512+A256KW' | 'PBES2-HS512+XC20PKW' | string;
+    /**
+     * Agreement PartyUInfo Header Parameter
+     *
+     * The "apu" (agreement PartyUInfo) value is a base64url-encoded octet sequence containing
+     * information about the producer of the JWE.  This information is used by the recipient to
+     * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+     *
+     * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+     * that uses public key cryptography.
+     */
+    apu?: string;
+    /**
+     * Agreement PartyVInfo Header Parameter
+     *
+     * The "apv" (agreement PartyVInfo) value is a base64url-encoded octet sequence containing
+     * information about the recipient of the JWE.  This information is used by the recipient to
+     * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+     *
+     * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+     * that uses public key cryptography.
+     */
+    apv?: string;
+    /**
+     * Critical Header Parameter
+     *
+     * Indicates that extensions to JOSE RFCs are being used that MUST be understood and processed.
+     */
+    crit?: string[];
+    /**
+     * Encryption Algorithm Header Parameter
+     *
+     * Identifies the content encryption algorithm used to encrypt and integrity-protect (also
+     * known as "authenticated encryption") the plaintext and to integrity-protect the Additional
+     * Authenticated Data (AAD), if any.  This algorithm MUST be an AEAD algorithm with a specified
+     * key length.
+     *
+     * The encrypted content is not usable if the "enc" value does not represent a supported
+     * algorithm.  "enc" values should either be registered in the IANA "JSON Web Signature and
+     * Encryption Algorithms" registry or be a value that contains a Collision-Resistant Name. The
+     * "enc" value is a case-sensitive ASCII string containing a StringOrURI value. This Header
+     * Parameter MUST be present and MUST be understood and processed by implementations.
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2 | RFC 7516, Section 4.1.2}
+     */
+    enc: 'A128CBC-HS256' | 'A192CBC-HS384' | 'A256CBC-HS512' | 'A128GCM' | 'A192GCM' | 'A256GCM' | 'XC20P' | string;
+    /**
+     * Ephemeral Public Key Header Parameter
+     *
+     * The "epk" (ephemeral public key) value created by the originator for the use in key agreement
+     * algorithms.  It is the ephemeral public key that corresponds to the key used to encrypt the
+     * JWE.  This value is represented as a JSON Web Key (JWK).
+     *
+     * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+     * that uses public key cryptography.
+     */
+    epk?: Jwk;
+    /**
+     * Initialization Vector Header Parameter
+     *
+     * The "iv" (initialization vector) value is a base64url-encoded octet sequence used by the
+     * specified "enc" algorithm.  The length of this Initialization Vector value MUST be exactly
+     * equal to the value that would be produced by the "enc" algorithm.
+     *
+     * Note: With symmetric encryption algorithms such as AES GCM, this Header Parameter MUST
+     * be present and MUST be understood and processed by implementations.
+     */
+    iv?: string;
+    /**
+     * PBES2 Count Header Parameter
+     *
+     * The "p2c" (PBES2 count) value is an integer indicating the number of iterations of the PBKDF2
+     * algorithm performed during key derivation.
+     *
+     * Note: The iteration count adds computational expense, ideally compounded by the possible range
+     * of keys introduced by the salt.  A minimum iteration count of 1000 is RECOMMENDED.
+     */
+    p2c?: number;
+    /**
+     * PBES2 Salt Input Header Parameter
+     *
+     * The "p2s" (PBES2 salt) value is a base64url-encoded octet sequence used as the salt value
+     * input to the PBKDF2 algorithm during key derivation.
+     *
+     * The salt value used is (UTF8(Alg) || 0x00 || Salt Input), where Alg is the "alg" (algorithm)
+     * Header Parameter value.
+     *
+     * Note: The salt value is used to ensure that each key derived from the master key is
+     * independent of every other key. A suitable source of salt value is a sequence of
+     * cryptographically random bytes containing 8 or more octets.
+     */
+    p2s?: string;
+    /**
+     * Authentication Tag Header Parameter
+     *
+     * The "tag" value is a base64url-encoded octet sequence containing the value of the
+     * Authentication Tag output by the specified "enc" algorithm.  The length of this
+     * Authentication Tag value MUST be exactly equal to the value that would be produced by the
+     * "enc" algorithm.
+     *
+     * Note: With authenticated encryption algorithms such as AES GCM, this Header Parameter MUST
+     * be present and MUST be understood and processed by implementations.
+     */
+    tag?: string;
+    /**
+     * Additional Public or Private Header Parameter names.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Represents the result of the JWE key management encryption process, encapsulating the Content
+ * Encryption Key (CEK) and optionally the encrypted CEK.
+ */
+export interface JweKeyManagementEncryptResult {
+    /**
+     * The Content Encryption Key (CEK) used for encrypting the JWE payload. It can be a Key
+     * Identifier such as a KMS URI or a JSON Web Key (JWK).
+     */
+    cek: KeyIdentifier | Jwk;
+    /**
+     * The encrypted version of the CEK, provided as a byte array. The encrypted version of the CEK
+     * is returned for all key management modes other than "dir" (Direct Encryption Mode).
+     */
+    encryptedKey?: Uint8Array;
+}
+/**
+ * Defines the parameters required to decrypt a JWE encrypted key, including the key management
+ * details.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface JweKeyManagementDecryptParams<TKeyManager, TCrypto> {
+    /**
+     * The decryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /**
+     * The encrypted key extracted from the JWE, represented as a byte array. This parameter is
+     * optional and is used when the key is wrapped.
+     */
+    encryptedKey?: Uint8Array;
+    /**
+     * The JWE header parameters that define the characteristics of the decryption process, specifying
+     * the algorithm and encryption method among other settings.
+     */
+    joseHeader: JweHeaderParams;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto: TCrypto;
+}
+/**
+ * Defines the parameters required for encrypting a JWE CEK, including the key management details.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface JweKeyManagementEncryptParams<TKeyManager, TCrypto> {
+    /**
+     * The encryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+     * or raw key material represented as a byte array.
+     */
+    key: KeyIdentifier | Jwk | Uint8Array;
+    /**
+     * The JWE header parameters that define the characteristics of the encryption process, specifying
+     * the algorithm and encryption method among other settings.
+     */
+    joseHeader: JweHeaderParams;
+    /** Key Manager instanceß responsible for managing cryptographic keys. */
+    keyManager: TKeyManager;
+    /** Crypto API instance that provides the necessary cryptographic operations. */
+    crypto: TCrypto;
+}
+/**
+ * Checks if the provided object is a valid JWE (JSON Web Encryption) header.
+ *
+ * This function evaluates whether the given object adheres to the structure expected for
+ * a JWE header, specifically looking for the presence and proper format of the "alg" (algorithm)
+ * and "enc" (encryption algorithm) properties, which are essential for defining the JWE's
+ * cryptographic operations.
+ *
+ * @example
+ * ```ts
+ * const header = {
+ *   alg: 'dir',
+ *   enc: 'A256GCM'
+ * };
+ *
+ * if (isValidJweHeader(header)) {
+ *   console.log('The object is a valid JWE header.');
+ * } else {
+ *   console.log('The object is not a valid JWE header.');
+ * }
+ * ```
+ *
+ * @param obj - The object to be validated as a JWE header.
+ * @returns Returns `true` if the object is a valid JWE header, otherwise `false`.
+ */
+export declare function isValidJweHeader(obj: unknown): obj is JweHeaderParams;
+/**
+ * The `JweKeyManagement` class implements the key management aspects of JSON Web Encryption (JWE)
+ * as specified in {@link https://datatracker.ietf.org/doc/html/rfc7516 | RFC 7516}.
+ *
+ * It supports algorithms for encrypting and decrypting keys, thereby enabling the secure
+ * transmission of information where the payload is encrypted, and the encryption key is also
+ * encrypted or agreed upon using key agreement techniques.
+ *
+ * The choice of algorithm is determined by the "alg" parameter in the JWE
+ * header, and the class is designed to handle the intricacies associated with each algorithm,
+ * ensuring the secure handling of the encryption keys.
+ *
+ * Supported algorithms include:
+ * - `"dir"`: Direct Encryption Mode
+ * - `"PBES2-HS256+A128KW"`, `"PBES2-HS384+A192KW"`, `"PBES2-HS512+A256KW"`: Password-Based
+ *   Encryption Mode with Key Wrapping (PBES2) using HMAC-SHA and AES Key Wrap algorithms for key
+ *   wrapping and encryption.
+ *
+ * @example
+ * // To encrypt a key:
+ * const keyEncryptionKey = Convert.string(passphrase).toUint8Array()
+ * const { cek, encryptedKey: encryptedCek } = await JweKeyManagement.encrypt({
+ *   key: keyEncryptionKey,
+ *   joseHeader: {
+ *     alg: 'PBES2-HS512+A256KW',
+ *     enc: 'A256GCM',
+ *     p2c : 210_000,
+       p2s : Convert.uint8Array(saltInput).toBase64Url()
+ *   },
+ *   crypto: new AgentCryptoApi(),
+ * });
+ *
+ * // To decrypt a key:
+ * const cek = await JweKeyManagement.decrypt({
+ *   key: keyEncryptionKey,
+ *   encryptedKey: encryptedCek,
+ *   joseHeader: {
+ *     alg: 'PBES2-HS512+A256KW',
+ *     enc: 'A256GCM',
+ *     p2c : 210_000,
+       p2s : Convert.uint8Array(saltInput).toBase64Url()
+ *   },
+ *   crypto: new AgentCryptoApi(),
+ * });
+ */
+export declare class JweKeyManagement {
+    /**
+     * Decrypts the encrypted key (JWE Encrypted Key) using the specified key encryption algorithm
+     * defined in the JWE Header's "alg" parameter.
+     *
+     * This method supports multiple key management algorithms, including Direct Encryption (dir) and
+     * PBES2 schemes with key wrapping.
+     *
+     * The method takes a key, which can be a Key Identifier, JWK, or raw byte array, and the
+     * encrypted key along with the JWE header. It returns the decrypted Content Encryption Key (CEK)
+     * which can then be used to decrypt the JWE ciphertext.
+     *
+     * @example
+     * ```ts
+     * // Decrypting the CEK with the PBES2-HS512+A256KW algorithm
+     * const cek = await JweKeyManagement.decrypt({
+     *   key: Convert.string(passphrase).toUint8Array(),
+     *   encryptedKey: encryptedCek,
+     *   joseHeader: {
+     *     alg: 'PBES2-HS512+A256KW',
+     *     enc: 'A256GCM',
+     *     p2c: 210_000,
+     *     p2s: Convert.uint8Array(saltInput).toBase64Url(),
+     *   },
+     *   crypto: new AgentCryptoApi()
+     * });
+     * ```
+     *
+     * @param params - The decryption parameters.
+     * @throws Throws an error if the key management algorithm is not supported or if required
+     *         parameters are missing or invalid.
+     */
+    static decrypt<TKeyManager extends KeyManager, TCrypto extends CryptoApi>({ key, encryptedKey, joseHeader, crypto }: JweKeyManagementDecryptParams<TKeyManager, TCrypto>): Promise<KeyIdentifier | Jwk>;
+    /**
+     * Encrypts a Content Encryption Key (CEK) using the key management algorithm specified in the
+     * JWE Header's "alg" parameter.
+     *
+     * This method supports various key management algorithms, including Direct Encryption (dir) and
+     * PBES2 with key wrapping.
+     *
+     * It generates a random CEK for the specified encryption algorithm in the JWE header, which
+     * can then be used to encrypt the actual payload. For algorithms that require an encrypted key,
+     * it returns the CEK along with the encrypted key.
+     *
+     * @example
+     * ```ts
+     * // Encrypting the CEK with the PBES2-HS512+A256KW algorithm
+     * const { cek, encryptedKey } = await JweKeyManagement.encrypt({
+     *   key: Convert.string(passphrase).toUint8Array(),
+     *   joseHeader: {
+     *     alg: 'PBES2-HS512+A256KW',
+     *     enc: 'A256GCM',
+     *     p2c: 210_000,
+     *     p2s: Convert.uint8Array(saltInput).toBase64Url(),
+     *   },
+     *   crypto: crypto: new AgentCryptoApi()
+     * });
+     * ```
+     *
+     * @param params - The encryption parameters.
+     * @returns The encrypted key result containing the CEK and optionally the encrypted CEK
+     *          (JWE Encrypted Key).
+     * @throws Throws an error if the key management algorithm is not supported or if required
+     *         parameters are missing or invalid.
+     */
+    static encrypt<TKeyManager extends KeyManager, TCrypto extends CryptoApi>({ key, joseHeader, crypto }: JweKeyManagementEncryptParams<TKeyManager, TCrypto>): Promise<JweKeyManagementEncryptResult>;
+}
+//# sourceMappingURL=jwe.d.ts.map

package/dist/types/prototyping/crypto/jose/jwe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwe.d.ts","sourceRoot":"","sources":["../../../../../src/prototyping/crypto/jose/jwe.ts"],"names":[],"mappings":"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"}