@kokuin/jwe 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# @kokuin/jwe
+
+## Installation
+
+```sh
+npm install @kokuin/jwe
+```

package/lib/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * JWE encryption for kokuin tokens.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/jwe
+ * ```
+ *
+ * @module jwe
+ */
+import { type KeyAgreementIdentity, type MethodRegistry, type SigningIdentity, type Verifiers } from '@kokuin/token';
+export type ConcatKDFParams = {
+    sharedSecret: Uint8Array;
+    keyLength: number;
+    algorithmID: string;
+    partyUInfo: Uint8Array;
+    partyVInfo: Uint8Array;
+};
+export type JWEHeader = {
+    alg: string;
+    enc: string;
+    epk: {
+        kty: string;
+        crv: string;
+        x: string;
+    };
+    apu?: string;
+    apv?: string;
+};
+export type TokenEncrypter = {
+    recipientID?: string;
+    encrypt(plaintext: Uint8Array): Promise<string>;
+};
+export type EncryptOptions = {
+    algorithm: 'X25519';
+};
+export type SharedSecretResult = {
+    /**
+     * The raw X25519 ECDH output. **Not** uniformly random — run it through a KDF with your own
+     * domain separation before using it as a key.
+     */
+    sharedSecret: Uint8Array;
+    /**
+     * Send this to the recipient. They recover the same `sharedSecret` bytes with
+     * `identity.agreeKey(ephemeralPublicKey)`.
+     */
+    ephemeralPublicKey: Uint8Array;
+};
+/**
+ * Concat KDF per RFC 7518 Section 4.6.2.
+ * Single SHA-256 iteration (sufficient for 256-bit keys).
+ */
+export declare function concatKDF(params: ConcatKDFParams): Uint8Array;
+/**
+ * Perform X25519 key agreement with a recipient DID, without building a JWE. Resolves the agreement
+ * key by the same rule `createTokenEncrypter` uses (a did:peer:4's published `keyAgreement` key, or a
+ * `did:key`'s birationally derived one), generates a single-use ephemeral pair, and returns the ECDH
+ * output; the ephemeral private key never leaves this function.
+ *
+ * The recipient recovers the identical bytes with `identity.agreeKey(ephemeralPublicKey)` and no
+ * `kid` — the sender always resolves the *first* published `keyAgreement` key, so a different `kid`
+ * on a multi-KEM identity silently recovers different bytes.
+ *
+ * Anonymous — it authenticates nothing about the sender, only that the recipient can recover the
+ * secret. Bind `ephemeralPublicKey` and the recipient DID into your KDF's info/context. The result is
+ * a raw ECDH output, not a key: run it through a KDF.
+ *
+ * ```ts
+ * const { sharedSecret, ephemeralPublicKey } = deriveSharedSecret(recipientDID)
+ * // ship ephemeralPublicKey alongside whatever the secret protects
+ * ```
+ *
+ * @param recipient a `did:key` EdDSA DID, or a `did:peer:4` **long form** — a short form throws, its
+ *   agreement key living only in the long form.
+ */
+export declare function deriveSharedSecret(recipient: string): SharedSecretResult;
+/**
+ * Create a token encrypter for a recipient identified by X25519 public key or DID string.
+ */
+export declare function createTokenEncrypter(recipient: Uint8Array, options: EncryptOptions): TokenEncrypter;
+export declare function createTokenEncrypter(recipient: string): TokenEncrypter;
+export type ResolveRecipientOptions = {
+    methods: MethodRegistry;
+};
+/**
+ * Async sibling of {@link deriveSharedSecret} for recipients whose agreement key must be reached
+ * through a registered `DIDMethodResolver` (e.g. `did:kokuin:`), in addition to the
+ * self-contained DIDs `deriveSharedSecret` already handles.
+ *
+ * @param recipient a DID string. Self-contained DIDs (`did:key`, `did:peer:4` long form) resolve
+ *   the same way `deriveSharedSecret` does; any other DID is looked up in `options.methods`.
+ */
+export declare function deriveSharedSecretAsync(recipient: string, options: ResolveRecipientOptions): Promise<SharedSecretResult>;
+/**
+ * Async sibling of {@link createTokenEncrypter} for recipients whose agreement key must be
+ * reached through a registered `DIDMethodResolver` (e.g. `did:kokuin:`), in addition to the
+ * self-contained DIDs `createTokenEncrypter` already handles.
+ */
+export declare function createTokenEncrypterAsync(recipient: string, options: ResolveRecipientOptions): Promise<TokenEncrypter>;
+/**
+ * Encrypt plaintext to JWE compact serialization using the given encrypter.
+ */
+export declare function encryptToken(encrypter: TokenEncrypter, plaintext: Uint8Array): Promise<string>;
+/**
+ * Decrypt a JWE compact serialization string.
+ */
+export declare function decryptToken(decrypter: KeyAgreementIdentity, jwe: string): Promise<Uint8Array>;
+export type EnvelopeMode = 'plain' | 'jws' | 'jws-in-jwe' | 'jwe-in-jws';
+export type UnwrappedEnvelope = {
+    payload: Record<string, unknown>;
+    mode: EnvelopeMode;
+};
+export type WrapOptions = {
+    signer?: SigningIdentity;
+    encrypter?: TokenEncrypter;
+    header?: Record<string, unknown>;
+};
+export type UnwrapOptions = {
+    decrypter?: KeyAgreementIdentity;
+    verifiers?: Verifiers;
+};
+/**
+ * Wrap a payload into a token string according to the specified envelope mode.
+ */
+export declare function wrapEnvelope(mode: EnvelopeMode, payload: Record<string, unknown>, options: WrapOptions): Promise<string>;
+/**
+ * Unwrap a token string, auto-detecting the envelope mode from its structure.
+ */
+export declare function unwrapEnvelope(message: string, options: UnwrapOptions): Promise<UnwrappedEnvelope>;

package/lib/index.js

@@ -0,0 +1,399 @@
+/**
+ * JWE encryption for kokuin tokens.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/jwe
+ * ```
+ *
+ * @module jwe
+ */ import { createUnsignedToken, decodePeer4, findMethodResolver, getAgreementKey, getPeer4ShortForm, getSignatureInfo, isPeer4, isUnsignedToken, stringifyToken, verifyToken } from '@kokuin/token';
+import { gcm } from '@noble/ciphers/aes.js';
+import { randomBytes } from '@noble/ciphers/utils.js';
+import { ed25519, x25519 } from '@noble/curves/ed25519.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { b64uFromJSON, b64uToJSON, fromB64U, toB64U } from '@sozai/codec';
+function uint32BE(value) {
+    const buf = new Uint8Array(4);
+    const view = new DataView(buf.buffer);
+    view.setUint32(0, value, false);
+    return buf;
+}
+function lengthPrefixed(data) {
+    const prefix = uint32BE(data.length);
+    const result = new Uint8Array(4 + data.length);
+    result.set(prefix);
+    result.set(data, 4);
+    return result;
+}
+/**
+ * Concat KDF per RFC 7518 Section 4.6.2.
+ * Single SHA-256 iteration (sufficient for 256-bit keys).
+ */ export function concatKDF(params) {
+    const { sharedSecret, keyLength, algorithmID, partyUInfo, partyVInfo } = params;
+    const encoder = new TextEncoder();
+    const algID = lengthPrefixed(encoder.encode(algorithmID));
+    const apu = lengthPrefixed(partyUInfo);
+    const apv = lengthPrefixed(partyVInfo);
+    const keyDataLen = uint32BE(keyLength);
+    // round = 1 (single iteration for 256-bit key)
+    const round = uint32BE(1);
+    // Hash(round || sharedSecret || algID || apu || apv || keyDataLen)
+    const parts = [
+        round,
+        sharedSecret,
+        algID,
+        apu,
+        apv,
+        keyDataLen
+    ];
+    let totalLength = 0;
+    for (const part of parts){
+        totalLength += part.length;
+    }
+    const hashInput = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const part of parts){
+        hashInput.set(part, offset);
+        offset += part.length;
+    }
+    return sha256(hashInput).slice(0, keyLength / 8);
+}
+function agreeWithKey(recipientPublicKey) {
+    const ephemeralPrivateKey = x25519.utils.randomSecretKey();
+    return {
+        ephemeralPublicKey: x25519.getPublicKey(ephemeralPrivateKey),
+        sharedSecret: x25519.getSharedSecret(ephemeralPrivateKey, recipientPublicKey)
+    };
+}
+function encryptWithX25519(recipientPublicKey, plaintext) {
+    const { sharedSecret, ephemeralPublicKey } = agreeWithKey(recipientPublicKey);
+    // Derive content encryption key via Concat KDF
+    const cek = concatKDF({
+        sharedSecret,
+        keyLength: 256,
+        algorithmID: 'A256GCM',
+        partyUInfo: new Uint8Array(0),
+        partyVInfo: new Uint8Array(0)
+    });
+    // Generate random 96-bit IV for AES-GCM
+    const iv = randomBytes(12);
+    // Build protected header
+    const protectedHeader = {
+        alg: 'ECDH-ES',
+        enc: 'A256GCM',
+        epk: {
+            kty: 'OKP',
+            crv: 'X25519',
+            x: toB64U(ephemeralPublicKey)
+        }
+    };
+    // Encode protected header
+    const encodedHeader = b64uFromJSON(protectedHeader);
+    // AAD is the ASCII bytes of the encoded header (per RFC 7516 Section 5.1 step 14)
+    const aad = new TextEncoder().encode(encodedHeader);
+    // Encrypt with AES-256-GCM (tag is appended to ciphertext)
+    const cipher = gcm(cek, iv, aad);
+    const ciphertextWithTag = cipher.encrypt(plaintext);
+    // Split ciphertext and tag (GCM tag is last 16 bytes)
+    const ciphertext = ciphertextWithTag.slice(0, ciphertextWithTag.length - 16);
+    const tag = ciphertextWithTag.slice(ciphertextWithTag.length - 16);
+    // JWE Compact Serialization: header.encryptedKey.iv.ciphertext.tag
+    // For ECDH-ES direct, encrypted key is empty
+    return [
+        encodedHeader,
+        '',
+        toB64U(iv),
+        toB64U(ciphertext),
+        toB64U(tag)
+    ].join('.');
+}
+function resolveX25519Key(recipient) {
+    if (typeof recipient !== 'string') {
+        return {
+            key: recipient
+        };
+    }
+    if (isPeer4(recipient)) {
+        const shortForm = getPeer4ShortForm(recipient);
+        if (recipient === shortForm) {
+            // The doc lives in the long form. Resolving a short form needs a DIDResolver, which
+            // this sync constructor cannot await — so say so, rather than failing as a bad DID.
+            throw new Error(`Cannot encrypt to a did:peer:4 short form: ${shortForm}. Pass the long form, which carries the document.`);
+        }
+        const { doc } = decodePeer4(recipient);
+        const key = getAgreementKey(doc);
+        if (key == null) {
+            throw new Error(`Recipient publishes no X25519 keyAgreement key: ${shortForm}`);
+        }
+        return {
+            key,
+            id: shortForm
+        };
+    }
+    const [algorithm, publicKey] = getSignatureInfo(recipient);
+    if (algorithm === 'EdDSA') {
+        return {
+            key: ed25519.utils.toMontgomery(publicKey),
+            id: recipient
+        };
+    }
+    throw new Error(`Unsupported DID algorithm for encryption: ${algorithm}`);
+}
+/**
+ * Perform X25519 key agreement with a recipient DID, without building a JWE. Resolves the agreement
+ * key by the same rule `createTokenEncrypter` uses (a did:peer:4's published `keyAgreement` key, or a
+ * `did:key`'s birationally derived one), generates a single-use ephemeral pair, and returns the ECDH
+ * output; the ephemeral private key never leaves this function.
+ *
+ * The recipient recovers the identical bytes with `identity.agreeKey(ephemeralPublicKey)` and no
+ * `kid` — the sender always resolves the *first* published `keyAgreement` key, so a different `kid`
+ * on a multi-KEM identity silently recovers different bytes.
+ *
+ * Anonymous — it authenticates nothing about the sender, only that the recipient can recover the
+ * secret. Bind `ephemeralPublicKey` and the recipient DID into your KDF's info/context. The result is
+ * a raw ECDH output, not a key: run it through a KDF.
+ *
+ * ```ts
+ * const { sharedSecret, ephemeralPublicKey } = deriveSharedSecret(recipientDID)
+ * // ship ephemeralPublicKey alongside whatever the secret protects
+ * ```
+ *
+ * @param recipient a `did:key` EdDSA DID, or a `did:peer:4` **long form** — a short form throws, its
+ *   agreement key living only in the long form.
+ */ export function deriveSharedSecret(recipient) {
+    if (typeof recipient !== 'string') {
+        throw new Error('deriveSharedSecret requires a DID string');
+    }
+    return agreeWithKey(resolveX25519Key(recipient).key);
+}
+export function createTokenEncrypter(recipient, options) {
+    if (typeof recipient !== 'string' && options?.algorithm !== 'X25519') {
+        throw new Error(`Unsupported algorithm: ${options?.algorithm}`);
+    }
+    const { key, id } = typeof recipient === 'string' ? resolveX25519Key(recipient) : resolveX25519Key(recipient);
+    return {
+        recipientID: id,
+        async encrypt (plaintext) {
+            return encryptWithX25519(key, plaintext);
+        }
+    };
+}
+/** Algorithms this package can encrypt with, strongest first. */ const AGREEMENT_PREFERENCE = [
+    'X25519'
+];
+/**
+ * Pick the strongest supported algorithm out of a resolver's key agreement set.
+ *
+ * Three distinguishable failures, so a caller can tell what to do about each: nothing registered
+ * for the method, a resolver that never grew key agreement, and a resolver whose keys are all
+ * algorithms this package does not (yet) implement.
+ */ async function resolveViaMethodResolver(recipient, resolver) {
+    if (resolver.resolveAgreementKey == null) {
+        throw new Error(`Cannot encrypt: ${resolver.method} does not support key agreement`);
+    }
+    const keys = await resolver.resolveAgreementKey(recipient);
+    for (const alg of AGREEMENT_PREFERENCE){
+        const match = keys.find((key)=>key.alg === alg);
+        if (match != null) {
+            return {
+                key: match.publicKey,
+                id: recipient
+            };
+        }
+    }
+    throw new Error(`Cannot encrypt to ${recipient}: no supported key agreement algorithm in [${keys.map((key)=>key.alg).join(', ')}]`);
+}
+/**
+ * `did:key` and `did:peer:4` carry their own key material and never go through a registered
+ * `DIDMethodResolver` — a cheap shape check, not an attempt-and-catch, so it never has to
+ * interpret (or swallow) an error the sync path raised.
+ */ function isSelfContainedRecipient(recipient) {
+    // Mirrors isPeer4's own prefix check without relying on its `value is string` predicate, which
+    // narrows a value already known to be a string to `never` on the negated branch.
+    return recipient.startsWith('did:peer:4z') || recipient.startsWith('did:key:');
+}
+/**
+ * Resolve a recipient's X25519 agreement key, reaching for a registered `DIDMethodResolver`
+ * only when the DID needs one.
+ *
+ * A resolver match is decided first and always wins. Failing that, `did:key` / `did:peer:4`
+ * fall to the sync path, whose own diagnostics (a did:peer:4 short form, an unsupported
+ * signature algorithm) propagate untouched — never caught here and rewritten as "no resolver".
+ * Anything else with no resolver registered gets that "no resolver" error, since the sync path
+ * has no way to resolve it either and would otherwise fail with an unrelated parse error.
+ */ async function resolveRecipientKey(recipient, options) {
+    const resolver = findMethodResolver(options.methods, recipient);
+    if (resolver != null) {
+        return resolveViaMethodResolver(recipient, resolver);
+    }
+    if (isSelfContainedRecipient(recipient)) {
+        return resolveX25519Key(recipient);
+    }
+    const method = recipient.split(':').slice(0, 2).join(':');
+    throw new Error(`Cannot encrypt: no resolver registered for ${method}`);
+}
+/**
+ * Async sibling of {@link deriveSharedSecret} for recipients whose agreement key must be reached
+ * through a registered `DIDMethodResolver` (e.g. `did:kokuin:`), in addition to the
+ * self-contained DIDs `deriveSharedSecret` already handles.
+ *
+ * @param recipient a DID string. Self-contained DIDs (`did:key`, `did:peer:4` long form) resolve
+ *   the same way `deriveSharedSecret` does; any other DID is looked up in `options.methods`.
+ */ export async function deriveSharedSecretAsync(recipient, options) {
+    if (typeof recipient !== 'string') {
+        throw new Error('deriveSharedSecretAsync requires a DID string');
+    }
+    const { key } = await resolveRecipientKey(recipient, options);
+    return agreeWithKey(key);
+}
+/**
+ * Async sibling of {@link createTokenEncrypter} for recipients whose agreement key must be
+ * reached through a registered `DIDMethodResolver` (e.g. `did:kokuin:`), in addition to the
+ * self-contained DIDs `createTokenEncrypter` already handles.
+ */ export async function createTokenEncrypterAsync(recipient, options) {
+    const { key, id } = await resolveRecipientKey(recipient, options);
+    return {
+        recipientID: id,
+        async encrypt (plaintext) {
+            return encryptWithX25519(key, plaintext);
+        }
+    };
+}
+/**
+ * Encrypt plaintext to JWE compact serialization using the given encrypter.
+ */ export async function encryptToken(encrypter, plaintext) {
+    return encrypter.encrypt(plaintext);
+}
+/**
+ * Decrypt a JWE compact serialization string.
+ */ export async function decryptToken(decrypter, jwe) {
+    const parts = jwe.split('.');
+    if (parts.length !== 5) {
+        throw new Error(`Invalid JWE format: expected 5 parts, got ${parts.length}`);
+    }
+    const [encodedHeader, _encryptedKey, encodedIV, encodedCiphertext, encodedTag] = parts;
+    // Parse protected header
+    const header = b64uToJSON(encodedHeader);
+    if (header.alg !== 'ECDH-ES') {
+        throw new Error(`Unsupported JWE algorithm: ${header.alg}`);
+    }
+    if (header.enc !== 'A256GCM') {
+        throw new Error(`Unsupported JWE encryption: ${header.enc}`);
+    }
+    // Extract ephemeral public key from header
+    const ephemeralPublicKey = fromB64U(header.epk.x);
+    // Compute shared secret via ECDH key agreement
+    const sharedSecret = await decrypter.agreeKey(ephemeralPublicKey);
+    // Derive content encryption key
+    const cek = concatKDF({
+        sharedSecret,
+        keyLength: 256,
+        algorithmID: 'A256GCM',
+        partyUInfo: header.apu != null ? fromB64U(header.apu) : new Uint8Array(0),
+        partyVInfo: header.apv != null ? fromB64U(header.apv) : new Uint8Array(0)
+    });
+    // Decode components
+    const iv = fromB64U(encodedIV);
+    const ciphertext = fromB64U(encodedCiphertext);
+    const tag = fromB64U(encodedTag);
+    // Reconstruct ciphertext+tag (GCM expects them concatenated)
+    const ciphertextWithTag = new Uint8Array(ciphertext.length + tag.length);
+    ciphertextWithTag.set(ciphertext);
+    ciphertextWithTag.set(tag, ciphertext.length);
+    // AAD is the ASCII bytes of the encoded header
+    const aad = new TextEncoder().encode(encodedHeader);
+    // Decrypt with AES-256-GCM
+    const cipher = gcm(cek, iv, aad);
+    return cipher.decrypt(ciphertextWithTag);
+}
+/**
+ * Wrap a payload into a token string according to the specified envelope mode.
+ */ export async function wrapEnvelope(mode, payload, options) {
+    switch(mode){
+        case 'plain':
+            {
+                const token = createUnsignedToken(payload, options.header);
+                // Append empty signature segment for RFC 7519 unsecured JWT format (header.payload.)
+                return `${stringifyToken(token)}.`;
+            }
+        case 'jws':
+            {
+                if (options.signer == null) throw new Error('Signer required for jws mode');
+                const token = await options.signer.signToken(payload, {
+                    header: options.header
+                });
+                return stringifyToken(token);
+            }
+        case 'jws-in-jwe':
+            {
+                if (options.signer == null) throw new Error('Signer required for jws-in-jwe mode');
+                if (options.encrypter == null) throw new Error('Encrypter required for jws-in-jwe mode');
+                const signed = await options.signer.signToken(payload, {
+                    header: options.header
+                });
+                const jwsString = stringifyToken(signed);
+                return encryptToken(options.encrypter, new TextEncoder().encode(jwsString));
+            }
+        case 'jwe-in-jws':
+            {
+                if (options.signer == null) throw new Error('Signer required for jwe-in-jws mode');
+                if (options.encrypter == null) throw new Error('Encrypter required for jwe-in-jws mode');
+                const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+                const jwe = await encryptToken(options.encrypter, plaintext);
+                const signed = await options.signer.signToken({
+                    jwe
+                }, {
+                    header: options.header
+                });
+                return stringifyToken(signed);
+            }
+    }
+}
+/**
+ * Unwrap a token string, auto-detecting the envelope mode from its structure.
+ */ export async function unwrapEnvelope(message, options) {
+    const parts = message.split('.');
+    if (parts.length === 5) {
+        // JWE outer → jws-in-jwe mode
+        if (options.decrypter == null) throw new Error('Decrypter required for JWE message');
+        const decrypted = await decryptToken(options.decrypter, message);
+        const jwsString = new TextDecoder().decode(decrypted);
+        const token = await verifyToken(jwsString, {
+            verifiers: options.verifiers
+        });
+        return {
+            payload: token.payload,
+            mode: 'jws-in-jwe'
+        };
+    }
+    if (parts.length === 3) {
+        // JWT: could be plain, jws, or jwe-in-jws
+        const token = await verifyToken(message, {
+            verifiers: options.verifiers,
+            allowUnsigned: true
+        });
+        if (isUnsignedToken(token)) {
+            return {
+                payload: token.payload,
+                mode: 'plain'
+            };
+        }
+        // Check if payload contains a JWE (jwe-in-jws)
+        if ('jwe' in token.payload && typeof token.payload.jwe === 'string') {
+            if (options.decrypter == null) throw new Error('Decrypter required for jwe-in-jws message');
+            const decrypted = await decryptToken(options.decrypter, token.payload.jwe);
+            const innerPayload = JSON.parse(new TextDecoder().decode(decrypted));
+            return {
+                payload: innerPayload,
+                mode: 'jwe-in-jws'
+            };
+        }
+        return {
+            payload: token.payload,
+            mode: 'jws'
+        };
+    }
+    throw new Error(`Invalid envelope format: expected 3 or 5 dot-separated parts, got ${parts.length}`);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kokuin/jwe",
+  "version": "0.1.0",
+  "description": "JWE encryption for kokuin tokens",
+  "keywords": [
+    "json",
+    "web",
+    "encryption",
+    "jwe"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kokuin",
+    "directory": "packages/jwe"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@noble/ciphers": "^2.3.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@sozai/codec": "^0.4.0",
+    "@kokuin/token": "^0.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
+}