@hpke/jose 0.0.0-stage → 0.1.0

package/esm/src/jwk.js

@@ -0,0 +1,77 @@
+import { decodeBase64Url } from "./utils.js";
+import { JoseError } from "./errors.js";
+/** Expected JWK key type and curve for a given JOSE HPKE algorithm. */
+export function getExpectedJwkParams(alg) {
+    switch (alg) {
+        case "HPKE-0":
+        case "HPKE-0-KE":
+        case "HPKE-7":
+        case "HPKE-7-KE":
+            return { kty: "EC", crv: "P-256" };
+        case "HPKE-1":
+        case "HPKE-1-KE":
+            return { kty: "EC", crv: "P-384" };
+        case "HPKE-2":
+        case "HPKE-2-KE":
+            return { kty: "EC", crv: "P-521" };
+        case "HPKE-3":
+        case "HPKE-3-KE":
+        case "HPKE-4":
+            return { kty: "OKP", crv: "X25519" };
+        case "HPKE-5":
+        case "HPKE-5-KE":
+        case "HPKE-6":
+            return { kty: "OKP", crv: "X448" };
+        default:
+            throw new JoseError(`Unknown algorithm: ${alg}`);
+    }
+}
+/**
+ * Extract raw public key bytes from a JWK.
+ * For EC keys: uncompressed point (0x04 || x || y).
+ * For OKP keys: raw x coordinate bytes.
+ */
+export function extractPublicKeyBytesFromJwk(jwk, alg) {
+    const expected = getExpectedJwkParams(alg);
+    if (jwk.kty !== expected.kty) {
+        throw new JoseError(`JWK kty mismatch: expected ${expected.kty}, got ${jwk.kty}`);
+    }
+    if (jwk.crv !== expected.crv) {
+        throw new JoseError(`JWK crv mismatch: expected ${expected.crv}, got ${jwk.crv}`);
+    }
+    if (!jwk.x) {
+        throw new JoseError("JWK missing x parameter");
+    }
+    if (expected.kty === "EC") {
+        if (!jwk.y) {
+            throw new JoseError("JWK missing y parameter for EC key");
+        }
+        const x = decodeBase64Url(jwk.x);
+        const y = decodeBase64Url(jwk.y);
+        // Uncompressed point: 0x04 || x || y
+        const raw = new Uint8Array(1 + x.length + y.length);
+        raw[0] = 0x04;
+        raw.set(x, 1);
+        raw.set(y, 1 + x.length);
+        return raw;
+    }
+    // OKP: raw x bytes
+    return decodeBase64Url(jwk.x);
+}
+/**
+ * Extract raw private key bytes from a JWK.
+ * Returns the d parameter bytes.
+ */
+export function extractPrivateKeyBytesFromJwk(jwk, alg) {
+    const expected = getExpectedJwkParams(alg);
+    if (jwk.kty !== expected.kty) {
+        throw new JoseError(`JWK kty mismatch: expected ${expected.kty}, got ${jwk.kty}`);
+    }
+    if (jwk.crv !== expected.crv) {
+        throw new JoseError(`JWK crv mismatch: expected ${expected.crv}, got ${jwk.crv}`);
+    }
+    if (!jwk.d) {
+        throw new JoseError("JWK missing d parameter (private key)");
+    }
+    return decodeBase64Url(jwk.d);
+}

package/esm/src/serialization.d.ts

@@ -0,0 +1,61 @@
+/** A recipient entry of a JWE General JSON Serialization, as accepted by open(). */
+export interface JweGeneralRecipientJson {
+    header?: Record<string, unknown>;
+    encrypted_key?: string;
+}
+/** JWE General JSON Serialization, as accepted by open(). */
+export interface JweGeneralJson {
+    protected: string;
+    unprotected?: Record<string, unknown>;
+    iv?: string;
+    aad?: string;
+    ciphertext: string;
+    tag?: string;
+    recipients: JweGeneralRecipientJson[];
+}
+/** JWE Flattened JSON Serialization, as accepted by open(). */
+export interface JweFlattenedJson {
+    protected: string;
+    unprotected?: Record<string, unknown>;
+    header?: Record<string, unknown>;
+    encrypted_key?: string;
+    iv?: string;
+    aad?: string;
+    ciphertext: string;
+    tag?: string;
+}
+/** A recipient entry of the JWE produced by JoseEncrypt.seal(). */
+export interface JweRecipientJson extends JweGeneralRecipientJson {
+    header: Record<string, unknown>;
+    encrypted_key: string;
+}
+/** The JWE General JSON Serialization produced by JoseEncrypt.seal(). */
+export interface JweJson extends JweGeneralJson {
+    iv: string;
+    tag: string;
+    recipients: JweRecipientJson[];
+}
+/** @internal */
+export interface ParsedRecipient {
+    /** The union of the protected, shared and per-recipient headers. */
+    joseHeader: Record<string, unknown>;
+    encryptedKey: string;
+}
+/** @internal */
+export interface ParsedJwe {
+    protectedHeader: Record<string, unknown>;
+    /** The Additional Authenticated Data encryption parameter. */
+    additionalData: Uint8Array;
+    iv: string;
+    ciphertext: string;
+    tag: string;
+    recipients: ParsedRecipient[];
+}
+/**
+ * Parse a JWE in any serialization into the values used by the message
+ * decryption process of draft-ietf-jose-hpke-encrypt-22 Section 7.2.
+ *
+ * @internal
+ */
+export declare function parseJwe(jwe: string | JweFlattenedJson | JweGeneralJson): ParsedJwe;
+//# sourceMappingURL=serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/src/serialization.ts"],"names":[],"mappings":"AAKA,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAiB,SAAQ,uBAAuB;IAC/D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,yEAAyE;AACzE,MAAM,WAAW,OAAQ,SAAQ,cAAc;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,gBAAgB;AAChB,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,8DAA8D;IAC9D,cAAc,EAAE,UAAU,CAAC;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAgHD;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,cAAc,GAC9C,SAAS,CAEX"}

package/esm/src/serialization.js

@@ -0,0 +1,107 @@
+import { decodeBase64Url } from "./utils.js";
+import { JoseError } from "./errors.js";
+const te = new TextEncoder();
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseProtectedHeader(encoded) {
+    let header;
+    try {
+        header = JSON.parse(new TextDecoder().decode(decodeBase64Url(encoded)));
+    }
+    catch {
+        throw new JoseError("Invalid protected header");
+    }
+    if (!isJsonObject(header)) {
+        throw new JoseError("Invalid protected header");
+    }
+    return header;
+}
+/** Build the JOSE Header, rejecting names that occur in more than one part. */
+function buildJoseHeader(...parts) {
+    // No prototype: "__proto__" in a header must stay an ordinary name.
+    const joseHeader = Object.create(null);
+    for (const part of parts) {
+        if (part === undefined)
+            continue;
+        if (!isJsonObject(part)) {
+            throw new JoseError("Invalid JOSE Header");
+        }
+        for (const [name, value] of Object.entries(part)) {
+            if (Object.prototype.hasOwnProperty.call(joseHeader, name)) {
+                throw new JoseError(`Duplicate Header Parameter: ${name}`);
+            }
+            joseHeader[name] = value;
+        }
+    }
+    return joseHeader;
+}
+function parseCompact(jwe) {
+    const parts = jwe.split(".");
+    if (parts.length !== 5) {
+        throw new JoseError("Invalid JWE Compact Serialization");
+    }
+    const [encodedHeader, encryptedKey, iv, ciphertext, tag] = parts;
+    if (!encodedHeader || !encryptedKey) {
+        throw new JoseError("Invalid JWE Compact Serialization");
+    }
+    const protectedHeader = parseProtectedHeader(encodedHeader);
+    return {
+        protectedHeader,
+        additionalData: te.encode(encodedHeader),
+        iv,
+        ciphertext,
+        tag,
+        recipients: [{
+                joseHeader: buildJoseHeader(protectedHeader),
+                encryptedKey,
+            }],
+    };
+}
+function parseJson(jwe) {
+    if (!jwe.protected) {
+        throw new JoseError("Missing protected header");
+    }
+    const protectedHeader = parseProtectedHeader(jwe.protected);
+    let recipients;
+    if ("recipients" in jwe) {
+        if (!Array.isArray(jwe.recipients)) {
+            throw new JoseError("Missing or invalid recipients array");
+        }
+        if ("header" in jwe || "encrypted_key" in jwe) {
+            throw new JoseError("recipients must not be used with header or encrypted_key");
+        }
+        recipients = jwe.recipients;
+    }
+    else {
+        recipients = [{ header: jwe.header, encrypted_key: jwe.encrypted_key }];
+    }
+    if (typeof jwe.ciphertext !== "string") {
+        throw new JoseError("Missing ciphertext");
+    }
+    return {
+        protectedHeader,
+        additionalData: te.encode(jwe.aad !== undefined ? `${jwe.protected}.${jwe.aad}` : jwe.protected),
+        iv: jwe.iv ?? "",
+        ciphertext: jwe.ciphertext,
+        tag: jwe.tag ?? "",
+        recipients: recipients.map((entry) => {
+            if (!isJsonObject(entry)) {
+                throw new JoseError("Invalid recipient");
+            }
+            return {
+                joseHeader: buildJoseHeader(protectedHeader, jwe.unprotected, entry.header),
+                encryptedKey: entry.encrypted_key ?? "",
+            };
+        }),
+    };
+}
+/**
+ * Parse a JWE in any serialization into the values used by the message
+ * decryption process of draft-ietf-jose-hpke-encrypt-22 Section 7.2.
+ *
+ * @internal
+ */
+export function parseJwe(jwe) {
+    return typeof jwe === "string" ? parseCompact(jwe) : parseJson(jwe);
+}

package/esm/src/structures.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build the HPKE info parameter for Key Encryption recipients
+ * using the JOSE Recipient_structure.
+ *
+ * Recipient_structure = ASCII("JOSE-HPKE rcpt") ||
+ *                       BYTE(255) ||
+ *                       ASCII(content_encryption_alg) ||
+ *                       BYTE(255) ||
+ *                       recipient_extra_info
+ *
+ * See draft-ietf-jose-hpke-encrypt-22 Section 6.1.
+ */
+export declare function buildRecipientStructure(contentEncAlg: string, recipientExtraInfo?: Uint8Array): Uint8Array;
+//# sourceMappingURL=structures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"structures.d.ts","sourceRoot":"","sources":["../../src/src/structures.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,kBAAkB,GAAE,UAAkB,GACrC,UAAU,CAoBZ"}

package/esm/src/structures.js

@@ -0,0 +1,31 @@
+const EMPTY = new Uint8Array(0);
+const SEPARATOR = new Uint8Array([0xFF]);
+/**
+ * Build the HPKE info parameter for Key Encryption recipients
+ * using the JOSE Recipient_structure.
+ *
+ * Recipient_structure = ASCII("JOSE-HPKE rcpt") ||
+ *                       BYTE(255) ||
+ *                       ASCII(content_encryption_alg) ||
+ *                       BYTE(255) ||
+ *                       recipient_extra_info
+ *
+ * See draft-ietf-jose-hpke-encrypt-22 Section 6.1.
+ */
+export function buildRecipientStructure(contentEncAlg, recipientExtraInfo = EMPTY) {
+    const te = new TextEncoder();
+    const context = te.encode("JOSE-HPKE rcpt");
+    const algBytes = te.encode(contentEncAlg);
+    const result = new Uint8Array(context.length + 1 + algBytes.length + 1 + recipientExtraInfo.length);
+    let offset = 0;
+    result.set(context, offset);
+    offset += context.length;
+    result.set(SEPARATOR, offset);
+    offset += 1;
+    result.set(algBytes, offset);
+    offset += algBytes.length;
+    result.set(SEPARATOR, offset);
+    offset += 1;
+    result.set(recipientExtraInfo, offset);
+    return result;
+}

package/esm/src/utils.d.ts

@@ -0,0 +1,5 @@
+/** Encode a Uint8Array to a base64url string (no padding). */
+export declare function encodeBase64Url(data: Uint8Array): string;
+/** Decode a base64url string to a Uint8Array. */
+export declare function decodeBase64Url(str: string): Uint8Array;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/src/utils.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CASxD;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAWvD"}

package/esm/src/utils.js

@@ -0,0 +1,26 @@
+/** Encode a Uint8Array to a base64url string (no padding). */
+export function encodeBase64Url(data) {
+    let binary = "";
+    for (let i = 0; i < data.length; i++) {
+        binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** Decode a base64url string to a Uint8Array. */
+export function decodeBase64Url(str) {
+    let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = base64.length % 4;
+    if (pad === 2)
+        base64 += "==";
+    else if (pad === 3)
+        base64 += "=";
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@hpke/jose",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "JOSE-HPKE (draft-ietf-jose-hpke-encrypt) encryption for JWE Integrated and Key Encryption",
+  "keywords": [
+    "hpke",
+    "jose",
+    "jwe",
+    "rfc9180",
+    "encryption",
+    "security"
+  ],
+  "author": "Ajitomi Daisuke",
+  "homepage": "https://github.com/dajiaji/hpke-js/tree/main/packages/jose#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dajiaji/hpke-js.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dajiaji/hpke-js/issues"
+  },
+  "main": "./esm/mod.js",
+  "module": "./esm/mod.js",
+  "types": "./esm/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "types": "./esm/mod.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/dajiaji"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@hpke/chacha20poly1305": "^1.8.1",
+    "@hpke/core": "^1.10.1",
+    "@hpke/dhkem-x448": "^1.8.1"
+  },
+  "_generatedBy": "dnt@dev"
+}