@hpke/jose 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Ajitomi Daisuke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @hpke/jose
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript implementation of
+[JOSE-HPKE](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-encrypt/)
+encryption based on [@hpke/core](https://github.com/dajiaji/hpke-js).
+
+## Features
+
+- **JWE Integrated Encryption** — direct HPKE encryption for single-recipient
+  JWE.
+- **JWE Key Encryption** — HPKE key wrapping with standard JWE content
+  encryption (A128GCM, A256GCM) for multi-recipient JWE.
+- `seal()` produces the Compact Serialization for Integrated Encryption and the
+  General JSON Serialization for Key Encryption. `open()` accepts the Compact,
+  Flattened JSON and General JSON Serializations for both.
+- PSK mode. The `psk_id` header parameter carries `BASE64URL(id)`.
+
+## Supported Environments
+
+This package is distributed as ESM only. On Node.js, version 20 or later is
+required.
+
+## Supported Algorithms
+
+Implements
+[draft-ietf-jose-hpke-encrypt-22](https://datatracker.ietf.org/doc/html/draft-ietf-jose-hpke-encrypt-22).
+
+| Integrated | Key Encryption | KEM                        | KDF         | AEAD             |
+| ---------- | -------------- | -------------------------- | ----------- | ---------------- |
+| HPKE-0     | HPKE-0-KE      | DHKEM(P-256, HKDF-SHA256)  | HKDF-SHA256 | AES-128-GCM      |
+| HPKE-1     | HPKE-1-KE      | DHKEM(P-384, HKDF-SHA384)  | HKDF-SHA384 | AES-256-GCM      |
+| HPKE-2     | HPKE-2-KE      | DHKEM(P-521, HKDF-SHA512)  | HKDF-SHA512 | AES-256-GCM      |
+| HPKE-3     | HPKE-3-KE      | DHKEM(X25519, HKDF-SHA256) | HKDF-SHA256 | AES-128-GCM      |
+| HPKE-4     | -              | DHKEM(X25519, HKDF-SHA256) | HKDF-SHA256 | ChaCha20Poly1305 |
+| HPKE-5     | HPKE-5-KE      | DHKEM(X448, HKDF-SHA512)   | HKDF-SHA512 | AES-256-GCM      |
+| HPKE-6     | -              | DHKEM(X448, HKDF-SHA512)   | HKDF-SHA512 | ChaCha20Poly1305 |
+| HPKE-7     | HPKE-7-KE      | DHKEM(P-256, HKDF-SHA256)  | HKDF-SHA256 | AES-256-GCM      |
+
+## Usage
+
+### Integrated Encryption (Compact JWE)
+
+```typescript
+import { createJoseHpke3 } from "@hpke/jose";
+
+const enc0 = createJoseHpke3();
+const rkp = await enc0.suite.kem.generateKeyPair();
+
+const plaintext = new TextEncoder().encode("Hello, JOSE-HPKE!");
+const jwe = await enc0.seal(rkp.publicKey, plaintext);
+
+const pt = await enc0.open(rkp, jwe);
+// pt === plaintext
+```
+
+### Key Encryption (JSON JWE) with A128GCM
+
+```typescript
+import { Aes128Gcm, createJoseHpke3Ke } from "@hpke/jose";
+
+const enc = createJoseHpke3Ke(new Aes128Gcm());
+const rkp = await enc.generateKemKeyPair();
+
+const plaintext = new TextEncoder().encode("Hello, JOSE-HPKE KE!");
+const jwe = await enc.seal(
+  [{ recipientPublicKey: rkp.publicKey }],
+  plaintext,
+);
+
+const pt = await enc.open(rkp, jwe);
+// pt === plaintext
+```
+
+The factory selects the HPKE suite for key wrapping; its AEAD argument selects
+content encryption independently. This example uses AES-128-GCM for key wrapping
+and AES-256-GCM for content encryption:
+
+```typescript
+import { Aes256Gcm, createJoseHpke3Ke } from "@hpke/jose";
+
+const enc = createJoseHpke3Ke(new Aes256Gcm());
+```
+
+Supported content AEADs are `Aes128Gcm` and `Aes256Gcm`; other AEADs are
+rejected when constructing the instance.
+
+### Key Encryption with Multiple Recipients
+
+```typescript
+import { Aes128Gcm, createJoseHpke3Ke } from "@hpke/jose";
+
+const enc = createJoseHpke3Ke(new Aes128Gcm());
+const rkp1 = await enc.generateKemKeyPair();
+const rkp2 = await enc.generateKemKeyPair();
+
+const plaintext = new TextEncoder().encode("Multi-recipient!");
+const jwe = await enc.seal(
+  [
+    { recipientPublicKey: rkp1.publicKey },
+    { recipientPublicKey: rkp2.publicKey },
+  ],
+  plaintext,
+);
+
+// Both recipients can decrypt
+const pt1 = await enc.open(rkp1, jwe);
+const pt2 = await enc.open(rkp2, jwe);
+```
+
+## License
+
+MIT

package/esm/mod.d.ts

@@ -0,0 +1,17 @@
+export type { AeadInterface } from "@hpke/core";
+export { Aes128Gcm, Aes256Gcm } from "@hpke/core";
+export { ContentEncAlg, JoseHpkeAlg } from "./src/alg.js";
+export type { JoseEncrypt0, JoseEncrypt0Options } from "./src/encrypt0.js";
+export type { JoseEncrypt } from "./src/encrypt.js";
+export type { JoseEncryptOpenOptions, JoseEncryptSealOptions, JoseRecipient, } from "./src/encrypt.js";
+export type { JweFlattenedJson, JweGeneralJson, JweGeneralRecipientJson, JweJson, JweRecipientJson, } from "./src/serialization.js";
+export { JoseError } from "./src/errors.js";
+export { createJoseHpke0, createJoseHpke0Ke } from "./src/hpke0.js";
+export { createJoseHpke1, createJoseHpke1Ke } from "./src/hpke1.js";
+export { createJoseHpke2, createJoseHpke2Ke } from "./src/hpke2.js";
+export { createJoseHpke3, createJoseHpke3Ke } from "./src/hpke3.js";
+export { createJoseHpke4 } from "./src/hpke4.js";
+export { createJoseHpke5, createJoseHpke5Ke } from "./src/hpke5.js";
+export { createJoseHpke6 } from "./src/hpke6.js";
+export { createJoseHpke7, createJoseHpke7Ke } from "./src/hpke7.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,OAAO,EACP,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/esm/mod.js

@@ -0,0 +1,11 @@
+export { Aes128Gcm, Aes256Gcm } from "@hpke/core";
+export { ContentEncAlg, JoseHpkeAlg } from "./src/alg.js";
+export { JoseError } from "./src/errors.js";
+export { createJoseHpke0, createJoseHpke0Ke } from "./src/hpke0.js";
+export { createJoseHpke1, createJoseHpke1Ke } from "./src/hpke1.js";
+export { createJoseHpke2, createJoseHpke2Ke } from "./src/hpke2.js";
+export { createJoseHpke3, createJoseHpke3Ke } from "./src/hpke3.js";
+export { createJoseHpke4 } from "./src/hpke4.js";
+export { createJoseHpke5, createJoseHpke5Ke } from "./src/hpke5.js";
+export { createJoseHpke6 } from "./src/hpke6.js";
+export { createJoseHpke7, createJoseHpke7Ke } from "./src/hpke7.js";

package/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/esm/src/alg.d.ts

@@ -0,0 +1,58 @@
+import { type AeadInterface } from "@hpke/core";
+/**
+ * JOSE HPKE algorithm identifiers from draft-ietf-jose-hpke-encrypt-22.
+ *
+ * Integrated Encryption: "HPKE-0" through "HPKE-7".
+ * Key Encryption: "HPKE-0-KE" through "HPKE-7-KE", except "HPKE-4-KE" and
+ * "HPKE-6-KE", which the draft does not define.
+ */
+export declare const JoseHpkeAlg: {
+    /** DHKEM(P-256), HKDF-SHA256, AES-128-GCM */
+    readonly HPKE_0: "HPKE-0";
+    /** DHKEM(P-384), HKDF-SHA384, AES-256-GCM */
+    readonly HPKE_1: "HPKE-1";
+    /** DHKEM(P-521), HKDF-SHA512, AES-256-GCM */
+    readonly HPKE_2: "HPKE-2";
+    /** DHKEM(X25519), HKDF-SHA256, AES-128-GCM */
+    readonly HPKE_3: "HPKE-3";
+    /** DHKEM(X25519), HKDF-SHA256, ChaCha20Poly1305 */
+    readonly HPKE_4: "HPKE-4";
+    /** DHKEM(X448), HKDF-SHA512, AES-256-GCM */
+    readonly HPKE_5: "HPKE-5";
+    /** DHKEM(X448), HKDF-SHA512, ChaCha20Poly1305 */
+    readonly HPKE_6: "HPKE-6";
+    /** DHKEM(P-256), HKDF-SHA256, AES-256-GCM */
+    readonly HPKE_7: "HPKE-7";
+    /** Key Encryption: DHKEM(P-256), HKDF-SHA256, AES-128-GCM */
+    readonly HPKE_0_KE: "HPKE-0-KE";
+    /** Key Encryption: DHKEM(P-384), HKDF-SHA384, AES-256-GCM */
+    readonly HPKE_1_KE: "HPKE-1-KE";
+    /** Key Encryption: DHKEM(P-521), HKDF-SHA512, AES-256-GCM */
+    readonly HPKE_2_KE: "HPKE-2-KE";
+    /** Key Encryption: DHKEM(X25519), HKDF-SHA256, AES-128-GCM */
+    readonly HPKE_3_KE: "HPKE-3-KE";
+    /** Key Encryption: DHKEM(X448), HKDF-SHA512, AES-256-GCM */
+    readonly HPKE_5_KE: "HPKE-5-KE";
+    /** Key Encryption: DHKEM(P-256), HKDF-SHA256, AES-256-GCM */
+    readonly HPKE_7_KE: "HPKE-7-KE";
+};
+export type JoseHpkeAlg = (typeof JoseHpkeAlg)[keyof typeof JoseHpkeAlg];
+/** JWE content-encryption algorithm identifiers. */
+export declare const ContentEncAlg: {
+    /** AES-128-GCM */
+    readonly A128GCM: "A128GCM";
+    /** AES-256-GCM */
+    readonly A256GCM: "A256GCM";
+};
+export type ContentEncAlg = (typeof ContentEncAlg)[keyof typeof ContentEncAlg];
+/**
+ * Map an HPKE AEAD object to its supported JWE content-encryption algorithm.
+ *
+ * @throws {JoseError} if the AEAD has no supported JWE equivalent.
+ */
+export declare function contentEncAlgFromAead(aead: AeadInterface): ContentEncAlg;
+/** Whether the algorithm is for Key Encryption. */
+export declare function isKeyEncryption(alg: JoseHpkeAlg): boolean;
+/** Whether the algorithm is for Integrated Encryption. */
+export declare function isIntegratedEncryption(alg: JoseHpkeAlg): boolean;
+//# sourceMappingURL=alg.d.ts.map

package/esm/src/alg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alg.d.ts","sourceRoot":"","sources":["../../src/src/alg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAIxD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACtB,6CAA6C;;IAE7C,6CAA6C;;IAE7C,6CAA6C;;IAE7C,8CAA8C;;IAE9C,mDAAmD;;IAEnD,4CAA4C;;IAE5C,iDAAiD;;IAEjD,6CAA6C;;IAE7C,6DAA6D;;IAE7D,6DAA6D;;IAE7D,6DAA6D;;IAE7D,8DAA8D;;IAE9D,4DAA4D;;IAE5D,6DAA6D;;CAErD,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE,oDAAoD;AACpD,eAAO,MAAM,aAAa;IACxB,kBAAkB;;IAElB,kBAAkB;;CAEV,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CA2BxE;AAqBD,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED,0DAA0D;AAC1D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAEhE"}

package/esm/src/alg.js

@@ -0,0 +1,97 @@
+import { AeadId } from "@hpke/core";
+import { JoseError } from "./errors.js";
+/**
+ * JOSE HPKE algorithm identifiers from draft-ietf-jose-hpke-encrypt-22.
+ *
+ * Integrated Encryption: "HPKE-0" through "HPKE-7".
+ * Key Encryption: "HPKE-0-KE" through "HPKE-7-KE", except "HPKE-4-KE" and
+ * "HPKE-6-KE", which the draft does not define.
+ */
+export const JoseHpkeAlg = {
+    /** DHKEM(P-256), HKDF-SHA256, AES-128-GCM */
+    HPKE_0: "HPKE-0",
+    /** DHKEM(P-384), HKDF-SHA384, AES-256-GCM */
+    HPKE_1: "HPKE-1",
+    /** DHKEM(P-521), HKDF-SHA512, AES-256-GCM */
+    HPKE_2: "HPKE-2",
+    /** DHKEM(X25519), HKDF-SHA256, AES-128-GCM */
+    HPKE_3: "HPKE-3",
+    /** DHKEM(X25519), HKDF-SHA256, ChaCha20Poly1305 */
+    HPKE_4: "HPKE-4",
+    /** DHKEM(X448), HKDF-SHA512, AES-256-GCM */
+    HPKE_5: "HPKE-5",
+    /** DHKEM(X448), HKDF-SHA512, ChaCha20Poly1305 */
+    HPKE_6: "HPKE-6",
+    /** DHKEM(P-256), HKDF-SHA256, AES-256-GCM */
+    HPKE_7: "HPKE-7",
+    /** Key Encryption: DHKEM(P-256), HKDF-SHA256, AES-128-GCM */
+    HPKE_0_KE: "HPKE-0-KE",
+    /** Key Encryption: DHKEM(P-384), HKDF-SHA384, AES-256-GCM */
+    HPKE_1_KE: "HPKE-1-KE",
+    /** Key Encryption: DHKEM(P-521), HKDF-SHA512, AES-256-GCM */
+    HPKE_2_KE: "HPKE-2-KE",
+    /** Key Encryption: DHKEM(X25519), HKDF-SHA256, AES-128-GCM */
+    HPKE_3_KE: "HPKE-3-KE",
+    /** Key Encryption: DHKEM(X448), HKDF-SHA512, AES-256-GCM */
+    HPKE_5_KE: "HPKE-5-KE",
+    /** Key Encryption: DHKEM(P-256), HKDF-SHA256, AES-256-GCM */
+    HPKE_7_KE: "HPKE-7-KE",
+};
+/** JWE content-encryption algorithm identifiers. */
+export const ContentEncAlg = {
+    /** AES-128-GCM */
+    A128GCM: "A128GCM",
+    /** AES-256-GCM */
+    A256GCM: "A256GCM",
+};
+/**
+ * Map an HPKE AEAD object to its supported JWE content-encryption algorithm.
+ *
+ * @throws {JoseError} if the AEAD has no supported JWE equivalent.
+ */
+export function contentEncAlgFromAead(aead) {
+    let alg;
+    let keySize;
+    switch (aead.id) {
+        case AeadId.Aes128Gcm:
+            alg = ContentEncAlg.A128GCM;
+            keySize = 16;
+            break;
+        case AeadId.Aes256Gcm:
+            alg = ContentEncAlg.A256GCM;
+            keySize = 32;
+            break;
+        default:
+            throw new JoseError(`Unsupported content encryption AEAD: id=0x${aead.id.toString(16).padStart(4, "0")}`);
+    }
+    if (aead.keySize !== keySize || aead.nonceSize !== 12 || aead.tagSize !== 16) {
+        throw new JoseError(`Invalid content encryption AEAD parameters for ${alg}: expected keySize=${keySize}, nonceSize=12, tagSize=16`);
+    }
+    return alg;
+}
+const KEY_ENCRYPTION_ALGS = new Set([
+    "HPKE-0-KE",
+    "HPKE-1-KE",
+    "HPKE-2-KE",
+    "HPKE-3-KE",
+    "HPKE-5-KE",
+    "HPKE-7-KE",
+]);
+const INTEGRATED_ENCRYPTION_ALGS = new Set([
+    "HPKE-0",
+    "HPKE-1",
+    "HPKE-2",
+    "HPKE-3",
+    "HPKE-4",
+    "HPKE-5",
+    "HPKE-6",
+    "HPKE-7",
+]);
+/** Whether the algorithm is for Key Encryption. */
+export function isKeyEncryption(alg) {
+    return KEY_ENCRYPTION_ALGS.has(alg);
+}
+/** Whether the algorithm is for Integrated Encryption. */
+export function isIntegratedEncryption(alg) {
+    return INTEGRATED_ENCRYPTION_ALGS.has(alg);
+}

package/esm/src/encrypt.d.ts

@@ -0,0 +1,83 @@
+import type { AeadInterface, CipherSuite } from "@hpke/core";
+import { type JoseHpkeAlg } from "./alg.js";
+import { type JweFlattenedJson, type JweGeneralJson, type JweJson } from "./serialization.js";
+/** A recipient descriptor for JoseEncrypt.seal(). */
+export interface JoseRecipient {
+    /** The recipient's public key. */
+    recipientPublicKey: CryptoKey;
+    /** Key identifier for the recipient. */
+    kid?: string;
+    /** Extra info embedded in Recipient_structure. */
+    extraInfo?: Uint8Array;
+    /**
+     * Pre-shared key for PSK mode. `id` is the HPKE psk_id; it is carried in the
+     * "psk_id" header parameter as BASE64URL(id).
+     */
+    psk?: {
+        id: Uint8Array;
+        key: Uint8Array;
+    };
+}
+/** Options for JoseEncrypt.seal(). */
+export interface JoseEncryptSealOptions {
+    /** Additional authenticated data (JWE AAD). */
+    aad?: Uint8Array;
+}
+/** Options for JoseEncrypt.open(). */
+export interface JoseEncryptOpenOptions {
+    /** Extra info for Recipient_structure. */
+    extraInfo?: Uint8Array;
+    /** Pre-shared key for PSK mode. `id` is the HPKE psk_id. */
+    psk?: {
+        id: Uint8Array;
+        key: Uint8Array;
+    };
+    /** Key identifier to match against recipients. */
+    kid?: string;
+}
+/**
+ * JWE Key Encryption using HPKE.
+ *
+ * Implements draft-ietf-jose-hpke-encrypt-22 Section 6. seal() produces the
+ * General JSON Serialization; open() accepts all JWE serializations.
+ */
+export interface JoseEncrypt {
+    /** The underlying HPKE CipherSuite. */
+    readonly suite: CipherSuite;
+    /** Generate a KEM key pair. */
+    generateKemKeyPair(): Promise<CryptoKeyPair>;
+    /**
+     * Encrypt plaintext into a JWE JSON Serialization structure.
+     */
+    seal(recipients: JoseRecipient[], plaintext: Uint8Array, options?: JoseEncryptSealOptions): Promise<JweJson>;
+    /**
+     * Decrypt a JWE in the Compact, Flattened JSON or General JSON Serialization.
+     * Header parameters are read from the union of the protected, shared
+     * unprotected and per-recipient headers.
+     */
+    open(recipientKey: CryptoKeyPair | CryptoKey, jwe: string | JweFlattenedJson | JweGeneralJson, options?: JoseEncryptOpenOptions): Promise<Uint8Array>;
+    /**
+     * Import a public key from a JWK.
+     */
+    importPublicJwk(jwk: JsonWebKey): Promise<CryptoKey>;
+    /**
+     * Import a private key from a JWK.
+     */
+    importPrivateJwk(jwk: JsonWebKey): Promise<CryptoKey>;
+}
+/** @internal */
+export declare class JoseEncryptImpl implements JoseEncrypt {
+    private _suite;
+    private _alg;
+    private _contentEncAlg;
+    private _contentAead;
+    constructor(suite: CipherSuite, alg: JoseHpkeAlg, contentAead: AeadInterface);
+    get suite(): CipherSuite;
+    generateKemKeyPair(): Promise<CryptoKeyPair>;
+    seal(recipients: JoseRecipient[], plaintext: Uint8Array, options?: JoseEncryptSealOptions): Promise<JweJson>;
+    open(recipientKey: CryptoKeyPair | CryptoKey, jwe: string | JweFlattenedJson | JweGeneralJson, options?: JoseEncryptOpenOptions): Promise<Uint8Array>;
+    private _wrapCek;
+    importPublicJwk(jwk: JsonWebKey): Promise<CryptoKey>;
+    importPrivateJwk(jwk: JsonWebKey): Promise<CryptoKey>;
+}
+//# sourceMappingURL=encrypt.d.ts.map

package/esm/src/encrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../../src/src/encrypt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,UAAU,CAAC;AAOlB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,OAAO,EAGb,MAAM,oBAAoB,CAAC;AAM5B,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,kBAAkB,EAAE,SAAS,CAAC;IAC9B,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC;CAC3C;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,4DAA4D;IAC5D,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC;IAC1C,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,+BAA+B;IAC/B,kBAAkB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7C;;OAEG;IACH,IAAI,CACF,UAAU,EAAE,aAAa,EAAE,EAC3B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CACF,YAAY,EAAE,aAAa,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,cAAc,EAC/C,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;OAEG;IACH,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAErD;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACvD;AAED,gBAAgB;AAChB,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,YAAY,CAAgB;gBAGlC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,aAAa;IAa5B,IAAI,KAAK,IAAI,WAAW,CAEvB;IAEK,kBAAkB,IAAI,OAAO,CAAC,aAAa,CAAC;IAI5C,IAAI,CACR,UAAU,EAAE,aAAa,EAAE,EAC3B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,OAAO,CAAC;IAsEb,IAAI,CACR,YAAY,EAAE,aAAa,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,cAAc,EAC/C,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,UAAU,CAAC;YAwGR,QAAQ;IA0ChB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IASpD,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;CAQ5D"}

package/esm/src/encrypt.js

@@ -0,0 +1,228 @@
+import { contentEncAlgFromAead, isKeyEncryption, } from "./alg.js";
+import { decodeBase64Url, encodeBase64Url } from "./utils.js";
+import { JoseError, withJoseError } from "./errors.js";
+import { extractPrivateKeyBytesFromJwk, extractPublicKeyBytesFromJwk, } from "./jwk.js";
+import { parseJwe, } from "./serialization.js";
+import { buildRecipientStructure } from "./structures.js";
+const EMPTY = new Uint8Array(0);
+const te = new TextEncoder();
+/** @internal */
+export class JoseEncryptImpl {
+    constructor(suite, alg, contentAead) {
+        Object.defineProperty(this, "_suite", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_alg", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_contentEncAlg", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_contentAead", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!isKeyEncryption(alg)) {
+            throw new JoseError(`JoseEncrypt requires a Key Encryption algorithm, got ${alg}`);
+        }
+        this._suite = suite;
+        this._alg = alg;
+        this._contentEncAlg = contentEncAlgFromAead(contentAead);
+        this._contentAead = contentAead;
+    }
+    get suite() {
+        return this._suite;
+    }
+    async generateKemKeyPair() {
+        return await this._suite.kem.generateKeyPair();
+    }
+    async seal(recipients, plaintext, options) {
+        if (recipients.length === 0) {
+            throw new JoseError("At least one recipient is required");
+        }
+        const keySize = this._contentAead.keySize;
+        const nonceSize = this._contentAead.nonceSize;
+        const cek = crypto.getRandomValues(new Uint8Array(keySize));
+        try {
+            return await withJoseError("Encryption failed", async () => {
+                const nonce = crypto.getRandomValues(new Uint8Array(nonceSize));
+                // Build protected header: { "enc": "A128GCM" }
+                const protectedHeaderObj = {
+                    enc: this._contentEncAlg,
+                };
+                const encodedProtectedHeader = encodeBase64Url(te.encode(JSON.stringify(protectedHeaderObj)));
+                // Content AAD = ASCII(EPH) or ASCII(EPH || '.' || BASE64URL(JWE AAD))
+                let contentAad;
+                let jweAad;
+                if (options?.aad && options.aad.length > 0) {
+                    jweAad = encodeBase64Url(options.aad);
+                    contentAad = `${encodedProtectedHeader}.${jweAad}`;
+                }
+                else {
+                    contentAad = encodedProtectedHeader;
+                }
+                const aadBytes = te.encode(contentAad);
+                // Encrypt content with CEK
+                const contentCtx = this._contentAead.createEncryptionContext(cek);
+                const combined = new Uint8Array(await contentCtx.seal(nonce, plaintext, aadBytes));
+                // Split ciphertext and tag
+                const ct = combined.slice(0, combined.length - this._contentAead.tagSize);
+                const tag = combined.slice(combined.length - this._contentAead.tagSize);
+                // Wrap CEK for each recipient
+                const recipientEntries = [];
+                for (const r of recipients) {
+                    const entry = await this._wrapCek(r, cek);
+                    recipientEntries.push(entry);
+                }
+                const result = {
+                    protected: encodedProtectedHeader,
+                    iv: encodeBase64Url(nonce),
+                    ciphertext: encodeBase64Url(ct),
+                    tag: encodeBase64Url(tag),
+                    recipients: recipientEntries,
+                };
+                if (jweAad) {
+                    result.aad = jweAad;
+                }
+                return result;
+            });
+        }
+        finally {
+            // Best effort: crypto contexts may retain their own key copies.
+            cek.fill(0);
+        }
+    }
+    async open(recipientKey, jwe, options) {
+        const extraInfo = options?.extraInfo ?? EMPTY;
+        const parsed = parseJwe(jwe);
+        // Decode IV, ciphertext, tag
+        if (!parsed.iv) {
+            throw new JoseError("Missing IV");
+        }
+        if (!parsed.tag) {
+            throw new JoseError("Missing authentication tag");
+        }
+        const nonce = decodeBase64Url(parsed.iv);
+        const ct = decodeBase64Url(parsed.ciphertext);
+        const tag = decodeBase64Url(parsed.tag);
+        const privateKey = "privateKey" in recipientKey
+            ? recipientKey.privateKey
+            : recipientKey;
+        // Find matching recipient and unwrap CEK
+        let cek = null;
+        for (const { joseHeader, encryptedKey } of parsed.recipients) {
+            // All recipients of a JWE share one content encryption algorithm
+            if (joseHeader.enc !== this._contentEncAlg) {
+                throw new JoseError(`Content encryption algorithm mismatch: expected ${this._contentEncAlg}, got ${joseHeader.enc}`);
+            }
+            // Check algorithm matches
+            if (joseHeader.alg !== this._alg)
+                continue;
+            // Match by kid if specified
+            if (options?.kid && joseHeader.kid !== options.kid)
+                continue;
+            // Get ek (encapsulated key)
+            const rEk = joseHeader.ek;
+            if (!rEk || !encryptedKey)
+                continue;
+            // PSK consistency
+            if (options?.psk) {
+                if (joseHeader.psk_id !== encodeBase64Url(options.psk.id))
+                    continue;
+            }
+            else {
+                if ("psk_id" in joseHeader)
+                    continue;
+            }
+            const encBytes = decodeBase64Url(rEk);
+            const wrappedCek = decodeBase64Url(encryptedKey);
+            // Build HPKE info = Recipient_structure(enc_alg, extra_info)
+            const hpkeInfo = buildRecipientStructure(this._contentEncAlg, extraInfo);
+            try {
+                const recipientParams = {
+                    recipientKey: privateKey,
+                    enc: encBytes,
+                    info: hpkeInfo,
+                };
+                if (options?.psk) {
+                    recipientParams.psk = options.psk;
+                }
+                const ctx = await this._suite.createRecipientContext(recipientParams);
+                cek = new Uint8Array(await ctx.open(wrappedCek, EMPTY));
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (cek === null) {
+            throw new JoseError("No matching recipient found or decryption failed");
+        }
+        try {
+            if (cek.length !== this._contentAead.keySize) {
+                throw new JoseError(`Invalid CEK length: expected ${this._contentAead.keySize}, got ${cek.length}`);
+            }
+            return await withJoseError("Content decryption failed", async () => {
+                // Combine ciphertext and tag for AES-GCM
+                const combined = new Uint8Array(ct.length + tag.length);
+                combined.set(ct);
+                combined.set(tag, ct.length);
+                const contentCtx = this._contentAead.createEncryptionContext(cek);
+                return new Uint8Array(await contentCtx.open(nonce, combined, parsed.additionalData));
+            });
+        }
+        finally {
+            // Best effort: crypto contexts may retain their own key copies.
+            cek.fill(0);
+        }
+    }
+    async _wrapCek(recipient, cek) {
+        const extraInfo = recipient.extraInfo ?? EMPTY;
+        // Build HPKE info = Recipient_structure(enc_alg, extra_info)
+        const hpkeInfo = buildRecipientStructure(this._contentEncAlg, extraInfo);
+        const senderParams = {
+            recipientPublicKey: recipient.recipientPublicKey,
+            info: hpkeInfo,
+        };
+        if (recipient.psk) {
+            senderParams.psk = recipient.psk;
+        }
+        const ctx = await this._suite.createSenderContext(senderParams);
+        const encBytes = new Uint8Array(ctx.enc);
+        const wrappedCek = new Uint8Array(await ctx.seal(cek, EMPTY));
+        // Per-recipient unprotected header
+        const rHeader = {
+            alg: this._alg,
+            ek: encodeBase64Url(encBytes),
+        };
+        if (recipient.kid) {
+            rHeader.kid = recipient.kid;
+        }
+        if (recipient.psk) {
+            rHeader.psk_id = encodeBase64Url(recipient.psk.id);
+        }
+        return {
+            header: rHeader,
+            encrypted_key: encodeBase64Url(wrappedCek),
+        };
+    }
+    async importPublicJwk(jwk) {
+        const rawBytes = extractPublicKeyBytesFromJwk(jwk, this._alg);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, true);
+    }
+    async importPrivateJwk(jwk) {
+        const rawBytes = extractPrivateKeyBytesFromJwk(jwk, this._alg);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, false);
+    }
+}