@hpke/cose 0.0.0-stage → 0.0.1

package/esm/src/encrypt.js

@@ -0,0 +1,317 @@
+import { encode, encodeTagged } from "./cbor/encoder.js";
+import { decode } from "./cbor/decoder.js";
+import { contentKeySize, contentNonceSize, isKeyEncryption, } from "./alg.js";
+import { CoseError } from "./errors.js";
+import { extractPrivateKeyBytes, extractPublicKeyBytes } from "./coseKey.js";
+import { buildEncStructureEncrypt, buildRecipientStructure, HeaderLabel, } from "./structures.js";
+const EMPTY = new Uint8Array(0);
+function uint8ArrayEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** @internal */
+export class CoseEncryptImpl {
+    /**
+     * @param suite The HPKE CipherSuite to use for key wrapping.
+     * @param alg A COSE HPKE algorithm identifier for Key Encryption (46-53).
+     * @param contentAlg The content encryption algorithm (A128GCM=1, A256GCM=3, or CHACHA20POLY1305=24).
+     * @param contentCrypto Content encryption implementation for Layer 0.
+     */
+    constructor(suite, alg, contentAlg, contentCrypto) {
+        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, "_contentAlg", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_contentCrypto", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!isKeyEncryption(alg)) {
+            throw new CoseError(`CoseEncrypt requires a Key Encryption algorithm (46-53), got ${alg}`);
+        }
+        this._suite = suite;
+        this._alg = alg;
+        this._contentAlg = contentAlg;
+        this._contentCrypto = contentCrypto;
+    }
+    /** The underlying HPKE CipherSuite. */
+    get suite() {
+        return this._suite;
+    }
+    /**
+     * Generate a KEM key pair.
+     */
+    async generateKemKeyPair() {
+        return await this._suite.kem.generateKeyPair();
+    }
+    /**
+     * Encrypt plaintext into a CBOR-encoded COSE_Encrypt structure.
+     *
+     * @param recipients One or more recipient descriptors.
+     * @param plaintext The data to encrypt.
+     * @param options Optional seal parameters.
+     * @returns CBOR-encoded COSE_Encrypt.
+     */
+    async seal(recipients, plaintext, options) {
+        const inner = await this._sealInner(recipients, plaintext, options);
+        const coseEncrypt = [
+            inner.protectedHeader,
+            inner.unprotectedMap,
+            inner.ciphertext,
+            inner.recipientEntries,
+        ];
+        if (options?.tagged) {
+            return encodeTagged(96, coseEncrypt);
+        }
+        return encode(coseEncrypt);
+    }
+    async sealDetached(recipients, plaintext, options) {
+        const inner = await this._sealInner(recipients, plaintext, options);
+        const coseEncrypt = [
+            inner.protectedHeader,
+            inner.unprotectedMap,
+            null,
+            inner.recipientEntries,
+        ];
+        const message = options?.tagged
+            ? encodeTagged(96, coseEncrypt)
+            : encode(coseEncrypt);
+        return { message, payload: inner.ciphertext };
+    }
+    async _sealInner(recipients, plaintext, options) {
+        if (recipients.length === 0) {
+            throw new CoseError("At least one recipient is required");
+        }
+        const extAad = options?.externalAad ?? EMPTY;
+        const keySize = contentKeySize(this._contentAlg);
+        const nonceSize = contentNonceSize(this._contentAlg);
+        const cek = crypto.getRandomValues(new Uint8Array(keySize));
+        const nonce = crypto.getRandomValues(new Uint8Array(nonceSize));
+        const protectedMap = new Map();
+        protectedMap.set(HeaderLabel.ALG, this._contentAlg);
+        const protectedHeader = encode(protectedMap);
+        const unprotectedMap = new Map();
+        unprotectedMap.set(HeaderLabel.IV, nonce);
+        const aad = buildEncStructureEncrypt(protectedHeader, extAad);
+        const ciphertext = await this._contentEncrypt(cek, nonce, plaintext, aad);
+        const recipientEntries = [];
+        for (const r of recipients) {
+            const entry = await this._wrapCek(r, cek);
+            recipientEntries.push(entry);
+        }
+        return { protectedHeader, unprotectedMap, ciphertext, recipientEntries };
+    }
+    /**
+     * Decrypt a CBOR-encoded COSE_Encrypt structure.
+     *
+     * @param recipientKey The recipient's key pair or private key.
+     * @param data CBOR-encoded COSE_Encrypt.
+     * @param options Optional parameters.
+     * @returns Decrypted plaintext.
+     */
+    async open(recipientKey, data, options) {
+        const extAad = options?.externalAad ?? EMPTY;
+        const extraInfo = options?.extraInfo ?? EMPTY;
+        const hpkeAad = options?.aad ?? EMPTY;
+        const decoded = decode(data);
+        if (!Array.isArray(decoded) || decoded.length !== 4) {
+            throw new CoseError("Invalid COSE_Encrypt structure");
+        }
+        const protectedHeader = decoded[0];
+        const unprotectedHeader = decoded[1];
+        const rawCiphertext = decoded[2];
+        const recipientsList = decoded[3];
+        if (!(protectedHeader instanceof Uint8Array)) {
+            throw new CoseError("Invalid protected header");
+        }
+        // Support detached payload: if ciphertext in structure is null,
+        // use detachedPayload from options.
+        let ciphertext;
+        if (rawCiphertext === null) {
+            if (!options?.detachedPayload) {
+                throw new CoseError("Ciphertext is null (detached) but no detachedPayload provided");
+            }
+            ciphertext = options.detachedPayload;
+        }
+        else if (rawCiphertext instanceof Uint8Array) {
+            ciphertext = rawCiphertext;
+        }
+        else {
+            throw new CoseError("Invalid ciphertext");
+        }
+        if (!Array.isArray(recipientsList)) {
+            throw new CoseError("Invalid recipients array");
+        }
+        // Parse Layer 0 protected header
+        const headerMap = decode(protectedHeader);
+        if (!(headerMap instanceof Map)) {
+            throw new CoseError("Protected header is not a map");
+        }
+        // If alg is present, verify it matches. If absent, proceed with
+        // the instance's configured content algorithm (Postel's principle).
+        const algValue = headerMap.get(HeaderLabel.ALG);
+        if (algValue !== undefined && algValue !== this._contentAlg) {
+            throw new CoseError(`Content algorithm mismatch: expected ${this._contentAlg}, got ${algValue}`);
+        }
+        // Read IV from unprotected header
+        if (!(unprotectedHeader instanceof Map)) {
+            throw new CoseError("Invalid unprotected header");
+        }
+        const nonce = unprotectedHeader.get(HeaderLabel.IV);
+        if (!(nonce instanceof Uint8Array)) {
+            throw new CoseError("Missing or invalid IV in unprotected header");
+        }
+        const privateKey = "privateKey" in recipientKey
+            ? recipientKey.privateKey
+            : recipientKey;
+        // Find matching recipient and unwrap CEK
+        let cek = null;
+        for (const entry of recipientsList) {
+            if (!Array.isArray(entry) || entry.length !== 3)
+                continue;
+            const rProtected = entry[0];
+            const rUnprotected = entry[1];
+            const rCiphertext = entry[2];
+            if (!(rProtected instanceof Uint8Array))
+                continue;
+            if (!(rCiphertext instanceof Uint8Array))
+                continue;
+            const rHeader = decode(rProtected);
+            if (!(rHeader instanceof Map))
+                continue;
+            // If alg is present in recipient header, verify it matches.
+            // If absent, try this recipient (Postel's principle).
+            const rAlg = rHeader.get(HeaderLabel.ALG);
+            if (rAlg !== undefined && rAlg !== this._alg)
+                continue;
+            // Match by kid if specified
+            if (options?.kid) {
+                const rKid = rHeader.get(HeaderLabel.KID);
+                if (!(rKid instanceof Uint8Array))
+                    continue;
+                if (!uint8ArrayEqual(rKid, options.kid))
+                    continue;
+            }
+            // ek is in the unprotected header
+            if (!(rUnprotected instanceof Map))
+                continue;
+            const rEnc = rUnprotected.get(HeaderLabel.EK);
+            if (!(rEnc instanceof Uint8Array))
+                continue;
+            // Validate psk_id / mode consistency (draft-ietf-cose-hpke §5)
+            // psk_id MUST be in the recipient protected header per spec.
+            if (options?.psk) {
+                const storedPskId = rHeader.get(HeaderLabel.PSK_ID);
+                if (!(storedPskId instanceof Uint8Array))
+                    continue;
+                if (!uint8ArrayEqual(storedPskId, options.psk.id))
+                    continue;
+            }
+            else {
+                // In base mode, psk_id MUST NOT be present
+                if (rHeader.has(HeaderLabel.PSK_ID)) {
+                    continue;
+                }
+            }
+            // Build HPKE info = Recipient_structure(contentAlg, protected, extraInfo)
+            const hpkeInfo = buildRecipientStructure(this._contentAlg, rProtected, extraInfo);
+            try {
+                // Build recipient context params
+                const recipientParams = {
+                    recipientKey: privateKey,
+                    enc: rEnc,
+                    info: hpkeInfo,
+                };
+                if (options?.psk) {
+                    recipientParams.psk = {
+                        id: options.psk.id,
+                        key: options.psk.key,
+                    };
+                }
+                const ctx = await this._suite.createRecipientContext(recipientParams);
+                cek = new Uint8Array(await ctx.open(rCiphertext, hpkeAad));
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (cek === null) {
+            throw new CoseError("No matching recipient found or decryption failed");
+        }
+        // Decrypt content with CEK
+        const contentAad = buildEncStructureEncrypt(protectedHeader, extAad);
+        return await this._contentDecrypt(cek, nonce, ciphertext, contentAad);
+    }
+    async _contentEncrypt(cek, nonce, plaintext, aad) {
+        return await this._contentCrypto.seal(cek, nonce, plaintext, aad);
+    }
+    async _contentDecrypt(cek, nonce, ciphertext, aad) {
+        return await this._contentCrypto.open(cek, nonce, ciphertext, aad);
+    }
+    async _wrapCek(recipient, cek) {
+        const extraInfo = recipient.extraInfo ?? EMPTY;
+        const hpkeAad = recipient.aad ?? EMPTY;
+        // Recipient protected header: { alg, [kid], [psk_id] }
+        const rProtectedMap = new Map();
+        rProtectedMap.set(HeaderLabel.ALG, this._alg);
+        if (recipient.kid) {
+            rProtectedMap.set(HeaderLabel.KID, recipient.kid);
+        }
+        if (recipient.psk) {
+            rProtectedMap.set(HeaderLabel.PSK_ID, recipient.psk.id);
+        }
+        const rProtectedHeader = encode(rProtectedMap);
+        // HPKE info = Recipient_structure(contentAlg, protected, extraInfo)
+        const hpkeInfo = buildRecipientStructure(this._contentAlg, rProtectedHeader, extraInfo);
+        // Build sender context params
+        const senderParams = {
+            recipientPublicKey: recipient.recipientPublicKey,
+            info: hpkeInfo,
+        };
+        if (recipient.psk) {
+            senderParams.psk = {
+                id: recipient.psk.id,
+                key: recipient.psk.key,
+            };
+        }
+        // Create sender context with the info
+        const ctx = await this._suite.createSenderContext(senderParams);
+        const encBytes = new Uint8Array(ctx.enc);
+        const wrappedCek = new Uint8Array(await ctx.seal(cek, hpkeAad));
+        // Recipient unprotected header: { ek: enc }
+        const rUnprotectedMap = new Map();
+        rUnprotectedMap.set(HeaderLabel.EK, encBytes);
+        // COSE_recipient = [protected, unprotected, ciphertext]
+        return [rProtectedHeader, rUnprotectedMap, wrappedCek];
+    }
+    async importPublicCoseKey(coseKeyBytes) {
+        const rawBytes = extractPublicKeyBytes(coseKeyBytes);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, true);
+    }
+    async importPrivateCoseKey(coseKeyBytes) {
+        const rawBytes = extractPrivateKeyBytes(coseKeyBytes);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, false);
+    }
+}

package/esm/src/encrypt0.d.ts

@@ -0,0 +1,91 @@
+import type { CipherSuite } from "@hpke/core";
+import { type CoseHpkeAlg } from "./alg.js";
+/** Options for CoseEncrypt0 seal/open operations. */
+export interface CoseEncrypt0Options {
+    /** External AAD included in the Enc_structure. */
+    externalAad?: Uint8Array;
+    /** HPKE info parameter. */
+    info?: Uint8Array;
+    /** Pre-shared key for PSK mode. */
+    psk?: {
+        id: Uint8Array;
+        key: Uint8Array;
+    };
+    /** Key identifier to include in the protected header (bstr per RFC 9052). */
+    kid?: Uint8Array;
+    /** If true, output is wrapped in CBOR Tag 16 (COSE_Encrypt0). */
+    tagged?: boolean;
+    /**
+     * Detached ciphertext for open(). When provided, the ciphertext field
+     * in the COSE structure (which should be null) is replaced by this value.
+     */
+    detachedPayload?: Uint8Array;
+}
+/** Result of a detached seal operation. */
+export interface CoseEncrypt0DetachedResult {
+    /** CBOR-encoded COSE_Encrypt0 with null ciphertext. */
+    message: Uint8Array;
+    /** The ciphertext transported separately. */
+    payload: Uint8Array;
+}
+/**
+ * COSE_Encrypt0 (Integrated Encryption) using HPKE.
+ *
+ * Implements draft-ietf-cose-hpke-27 Section 3.2 (HPKE Integrated Encryption Mode).
+ */
+export interface CoseEncrypt0 {
+    /** The underlying HPKE CipherSuite. */
+    readonly suite: CipherSuite;
+    /**
+     * Encrypt a plaintext into a CBOR-encoded COSE_Encrypt0 structure.
+     */
+    seal(recipientPublicKey: CryptoKey, plaintext: Uint8Array, options?: CoseEncrypt0Options): Promise<Uint8Array>;
+    /**
+     * Encrypt a plaintext into a detached COSE_Encrypt0 structure.
+     * The ciphertext field is null; the actual payload is returned separately.
+     */
+    sealDetached(recipientPublicKey: CryptoKey, plaintext: Uint8Array, options?: CoseEncrypt0Options): Promise<CoseEncrypt0DetachedResult>;
+    /**
+     * Decrypt a CBOR-encoded COSE_Encrypt0 structure.
+     * For detached payloads, pass the ciphertext via options.detachedPayload.
+     */
+    open(recipientKey: CryptoKeyPair | CryptoKey, data: Uint8Array, options?: CoseEncrypt0Options): Promise<Uint8Array>;
+    /**
+     * Import a public key from a CBOR-encoded COSE_Key.
+     * Validates kty, crv, and key length.
+     */
+    importPublicCoseKey(coseKeyBytes: Uint8Array): Promise<CryptoKey>;
+    /**
+     * Import a private key from a CBOR-encoded COSE_Key.
+     * Validates kty, crv, and key length.
+     */
+    importPrivateCoseKey(coseKeyBytes: Uint8Array): Promise<CryptoKey>;
+}
+/** @internal */
+export declare class CoseEncrypt0Impl implements CoseEncrypt0 {
+    private _alg;
+    private _suite;
+    /**
+     * @param suite The HPKE CipherSuite to use.
+     * @param alg A COSE HPKE algorithm identifier for Integrated Encryption (35-45).
+     * @throws {CoseError} if alg is not an Integrated Encryption algorithm.
+     */
+    constructor(suite: CipherSuite, alg: CoseHpkeAlg);
+    /** The underlying HPKE CipherSuite. */
+    get suite(): CipherSuite;
+    seal(recipientPublicKey: CryptoKey, plaintext: Uint8Array, options?: CoseEncrypt0Options): Promise<Uint8Array>;
+    sealDetached(recipientPublicKey: CryptoKey, plaintext: Uint8Array, options?: CoseEncrypt0Options): Promise<CoseEncrypt0DetachedResult>;
+    private _sealInner;
+    /**
+     * Decrypt a CBOR-encoded COSE_Encrypt0 structure.
+     *
+     * @param recipientKey The recipient's key pair or CryptoKey (private).
+     * @param data CBOR-encoded COSE_Encrypt0.
+     * @param options Optional external AAD, HPKE info, and PSK.
+     * @returns Decrypted plaintext.
+     */
+    open(recipientKey: CryptoKeyPair | CryptoKey, data: Uint8Array, options?: CoseEncrypt0Options): Promise<Uint8Array>;
+    importPublicCoseKey(coseKeyBytes: Uint8Array): Promise<CryptoKey>;
+    importPrivateCoseKey(coseKeyBytes: Uint8Array): Promise<CryptoKey>;
+}
+//# sourceMappingURL=encrypt0.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt0.d.ts","sourceRoot":"","sources":["../../src/src/encrypt0.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,OAAO,EAAE,KAAK,WAAW,EAA0B,MAAM,UAAU,CAAC;AAepE,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,mCAAmC;IACnC,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC;IAC1C,6EAA6E;IAC7E,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,UAAU,CAAC;CAC9B;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,OAAO,EAAE,UAAU,CAAC;IACpB,6CAA6C;IAC7C,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;OAEG;IACH,IAAI,CACF,kBAAkB,EAAE,SAAS,EAC7B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;OAGG;IACH,YAAY,CACV,kBAAkB,EAAE,SAAS,EAC7B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CACF,YAAY,EAAE,aAAa,GAAG,SAAS,EACvC,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;OAGG;IACH,mBAAmB,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAElE;;;OAGG;IACH,oBAAoB,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACpE;AAED,gBAAgB;AAChB,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,MAAM,CAAc;IAE5B;;;;OAIG;gBACS,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW;IAUhD,uCAAuC;IACvC,IAAI,KAAK,IAAI,WAAW,CAEvB;IAEK,IAAI,CACR,kBAAkB,EAAE,SAAS,EAC7B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC;IAchB,YAAY,CAChB,kBAAkB,EAAE,SAAS,EAC7B,SAAS,EAAE,UAAU,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,0BAA0B,CAAC;YAcxB,UAAU;IA6CxB;;;;;;;OAOG;IACG,IAAI,CACR,YAAY,EAAE,aAAa,GAAG,SAAS,EACvC,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,UAAU,CAAC;IAyGhB,mBAAmB,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IASjE,oBAAoB,CAAC,YAAY,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;CAQzE"}

package/esm/src/encrypt0.js

@@ -0,0 +1,203 @@
+import { encode, encodeTagged } from "./cbor/encoder.js";
+import { decode } from "./cbor/decoder.js";
+import { isIntegratedEncryption } from "./alg.js";
+import { extractPrivateKeyBytes, extractPublicKeyBytes } from "./coseKey.js";
+import { CoseError } from "./errors.js";
+import { buildEncStructure, HeaderLabel } from "./structures.js";
+const EMPTY = new Uint8Array(0);
+function uint8ArrayEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** @internal */
+export class CoseEncrypt0Impl {
+    /**
+     * @param suite The HPKE CipherSuite to use.
+     * @param alg A COSE HPKE algorithm identifier for Integrated Encryption (35-45).
+     * @throws {CoseError} if alg is not an Integrated Encryption algorithm.
+     */
+    constructor(suite, alg) {
+        Object.defineProperty(this, "_alg", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_suite", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!isIntegratedEncryption(alg)) {
+            throw new CoseError("CoseEncrypt0 requires an Integrated Encryption algorithm (35-45)");
+        }
+        this._alg = alg;
+        this._suite = suite;
+    }
+    /** The underlying HPKE CipherSuite. */
+    get suite() {
+        return this._suite;
+    }
+    async seal(recipientPublicKey, plaintext, options) {
+        const { protectedHeader, unprotectedMap, ciphertext } = await this
+            ._sealInner(recipientPublicKey, plaintext, options);
+        const coseEncrypt0 = [
+            protectedHeader,
+            unprotectedMap,
+            ciphertext,
+        ];
+        if (options?.tagged) {
+            return encodeTagged(16, coseEncrypt0);
+        }
+        return encode(coseEncrypt0);
+    }
+    async sealDetached(recipientPublicKey, plaintext, options) {
+        const { protectedHeader, unprotectedMap, ciphertext } = await this
+            ._sealInner(recipientPublicKey, plaintext, options);
+        const coseEncrypt0 = [
+            protectedHeader,
+            unprotectedMap,
+            null,
+        ];
+        const message = options?.tagged
+            ? encodeTagged(16, coseEncrypt0)
+            : encode(coseEncrypt0);
+        return { message, payload: ciphertext };
+    }
+    async _sealInner(recipientPublicKey, plaintext, options) {
+        const externalAad = options?.externalAad ?? EMPTY;
+        const info = options?.info ?? EMPTY;
+        const senderParams = {
+            recipientPublicKey,
+            info,
+        };
+        if (options?.psk) {
+            senderParams.psk = {
+                id: options.psk.id,
+                key: options.psk.key,
+            };
+        }
+        const ctx = await this._suite.createSenderContext(senderParams);
+        const encBytes = new Uint8Array(ctx.enc);
+        const protectedMap = new Map();
+        protectedMap.set(HeaderLabel.ALG, this._alg);
+        if (options?.kid) {
+            protectedMap.set(HeaderLabel.KID, options.kid);
+        }
+        if (options?.psk) {
+            protectedMap.set(HeaderLabel.PSK_ID, options.psk.id);
+        }
+        const protectedHeader = encode(protectedMap);
+        const unprotectedMap = new Map();
+        unprotectedMap.set(HeaderLabel.EK, encBytes);
+        const aad = buildEncStructure(protectedHeader, externalAad);
+        const ciphertext = new Uint8Array(await ctx.seal(plaintext, aad));
+        return { protectedHeader, unprotectedMap, ciphertext };
+    }
+    /**
+     * Decrypt a CBOR-encoded COSE_Encrypt0 structure.
+     *
+     * @param recipientKey The recipient's key pair or CryptoKey (private).
+     * @param data CBOR-encoded COSE_Encrypt0.
+     * @param options Optional external AAD, HPKE info, and PSK.
+     * @returns Decrypted plaintext.
+     */
+    async open(recipientKey, data, options) {
+        const externalAad = options?.externalAad ?? EMPTY;
+        const info = options?.info ?? EMPTY;
+        const decoded = decode(data);
+        if (!Array.isArray(decoded) || decoded.length !== 3) {
+            throw new CoseError("Invalid COSE_Encrypt0 structure");
+        }
+        const protectedHeader = decoded[0];
+        const unprotectedHeader = decoded[1];
+        const rawCiphertext = decoded[2];
+        if (!(protectedHeader instanceof Uint8Array)) {
+            throw new CoseError("Invalid protected header");
+        }
+        // Support detached payload: if ciphertext in structure is null,
+        // use detachedPayload from options.
+        let ciphertext;
+        if (rawCiphertext === null) {
+            if (!options?.detachedPayload) {
+                throw new CoseError("Ciphertext is null (detached) but no detachedPayload provided");
+            }
+            ciphertext = options.detachedPayload;
+        }
+        else if (rawCiphertext instanceof Uint8Array) {
+            ciphertext = rawCiphertext;
+        }
+        else {
+            throw new CoseError("Invalid ciphertext");
+        }
+        // Parse protected header to extract alg
+        const headerMap = decode(protectedHeader);
+        if (!(headerMap instanceof Map)) {
+            throw new CoseError("Protected header is not a map");
+        }
+        // If alg is present, verify it matches. If absent, proceed with
+        // the instance's configured algorithm (Postel's principle).
+        const algValue = headerMap.get(HeaderLabel.ALG);
+        if (algValue !== undefined && algValue !== this._alg) {
+            throw new CoseError(`Algorithm mismatch: expected ${this._alg}, got ${algValue}`);
+        }
+        // Read ek from unprotected header
+        if (!(unprotectedHeader instanceof Map)) {
+            throw new CoseError("Invalid unprotected header");
+        }
+        const encBytes = unprotectedHeader.get(HeaderLabel.EK);
+        if (!(encBytes instanceof Uint8Array)) {
+            throw new CoseError("Missing or invalid ek in unprotected header");
+        }
+        // Validate psk_id / mode consistency (draft-ietf-cose-hpke §4)
+        // psk_id MUST be in the protected header per spec.
+        if (options?.psk) {
+            const storedPskId = headerMap.get(HeaderLabel.PSK_ID);
+            if (!(storedPskId instanceof Uint8Array)) {
+                throw new CoseError("Missing psk_id in protected header for PSK mode");
+            }
+            if (!uint8ArrayEqual(storedPskId, options.psk.id)) {
+                throw new CoseError("psk_id mismatch");
+            }
+        }
+        else {
+            // In base mode, psk_id MUST NOT be present
+            if (headerMap.has(HeaderLabel.PSK_ID)) {
+                throw new CoseError("psk_id present but PSK mode was not selected");
+            }
+        }
+        // Reconstruct AAD = Enc_structure("Encrypt0", protected, external_aad)
+        const aad = buildEncStructure(protectedHeader, externalAad);
+        const privateKey = "privateKey" in recipientKey
+            ? recipientKey.privateKey
+            : recipientKey;
+        // Build recipient context params
+        const recipientParams = {
+            recipientKey: privateKey,
+            enc: encBytes,
+            info,
+        };
+        if (options?.psk) {
+            recipientParams.psk = {
+                id: options.psk.id,
+                key: options.psk.key,
+            };
+        }
+        const ctx = await this._suite.createRecipientContext(recipientParams);
+        return new Uint8Array(await ctx.open(ciphertext, aad));
+    }
+    async importPublicCoseKey(coseKeyBytes) {
+        const rawBytes = extractPublicKeyBytes(coseKeyBytes);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, true);
+    }
+    async importPrivateCoseKey(coseKeyBytes) {
+        const rawBytes = extractPrivateKeyBytes(coseKeyBytes);
+        return await this._suite.kem.importKey("raw", rawBytes.buffer, false);
+    }
+}

package/esm/src/errors.d.ts

@@ -0,0 +1,5 @@
+/** Base error for @hpke/cose operations. */
+export declare class CoseError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/src/errors.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qBAAa,SAAU,SAAQ,KAAK;gBACf,OAAO,EAAE,MAAM;CAInC"}

package/esm/src/errors.js

@@ -0,0 +1,7 @@
+/** Base error for @hpke/cose operations. */
+export class CoseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CoseError";
+    }
+}

package/esm/src/hpke0.d.ts

@@ -0,0 +1,8 @@
+import { type ContentAlg } from "./alg.js";
+import type { CoseEncrypt0 } from "./encrypt0.js";
+import type { CoseEncrypt } from "./encrypt.js";
+/** DHKEM(P-256), HKDF-SHA256, AES-128-GCM — Integrated Encryption. */
+export declare function createHpke0(): CoseEncrypt0;
+/** DHKEM(P-256), HKDF-SHA256, AES-128-GCM — Key Encryption. */
+export declare function createHpke0Ke(contentAlg: ContentAlg): CoseEncrypt;
+//# sourceMappingURL=hpke0.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hpke0.d.ts","sourceRoot":"","sources":["../../src/src/hpke0.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,UAAU,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,sEAAsE;AACtE,wBAAgB,WAAW,IAAI,YAAY,CAO1C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,CAYjE"}

package/esm/src/hpke0.js

@@ -0,0 +1,23 @@
+import { Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256, } from "@hpke/core";
+import { CoseHpkeAlg } from "./alg.js";
+import { aesGcmContentCrypto } from "./contentAesGcm.js";
+import { CoseEncrypt0Impl } from "./encrypt0.js";
+import { CoseEncryptImpl } from "./encrypt.js";
+/** DHKEM(P-256), HKDF-SHA256, AES-128-GCM — Integrated Encryption. */
+export function createHpke0() {
+    const suite = new CipherSuite({
+        kem: new DhkemP256HkdfSha256(),
+        kdf: new HkdfSha256(),
+        aead: new Aes128Gcm(),
+    });
+    return new CoseEncrypt0Impl(suite, CoseHpkeAlg.HPKE_0);
+}
+/** DHKEM(P-256), HKDF-SHA256, AES-128-GCM — Key Encryption. */
+export function createHpke0Ke(contentAlg) {
+    const suite = new CipherSuite({
+        kem: new DhkemP256HkdfSha256(),
+        kdf: new HkdfSha256(),
+        aead: new Aes128Gcm(),
+    });
+    return new CoseEncryptImpl(suite, CoseHpkeAlg.HPKE_0_KE, contentAlg, aesGcmContentCrypto);
+}

package/esm/src/hpke1.d.ts

@@ -0,0 +1,8 @@
+import { type ContentAlg } from "./alg.js";
+import type { CoseEncrypt0 } from "./encrypt0.js";
+import type { CoseEncrypt } from "./encrypt.js";
+/** DHKEM(P-384), HKDF-SHA384, AES-256-GCM — Integrated Encryption. */
+export declare function createHpke1(): CoseEncrypt0;
+/** DHKEM(P-384), HKDF-SHA384, AES-256-GCM — Key Encryption. */
+export declare function createHpke1Ke(contentAlg: ContentAlg): CoseEncrypt;
+//# sourceMappingURL=hpke1.d.ts.map