@kokuin/token 0.4.0 → 0.5.0

package/lib/jwe.js

@@ -1,315 +0,0 @@
-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';
-import { getAgreementKey, getSignatureInfo } from './did.js';
-import { decodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
-import { createUnsignedToken, isUnsignedToken, verifyToken } from './token.js';
-import { stringifyToken } from './utils.js';
-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 recipient's agreement key by the same rule `createTokenEncrypter` uses — a
- * did:peer:4 identity's published `keyAgreement` key, or an EdDSA `did:key`'s birationally
- * derived one — generates a single-use ephemeral key pair, and returns the ECDH output.
- * The ephemeral private key never leaves this function.
- *
- * The recipient recovers the identical bytes with `identity.agreeKey(ephemeralPublicKey)` —
- * called with no `kid`; the sender always resolves the first published `keyAgreement` key, and
- * on a multi-KEM identity a different `kid` silently recovers different bytes.
- *
- * The agreement is anonymous — it authenticates nothing about the sender, only that the secret
- * is recoverable by the recipient. Bind `ephemeralPublicKey` and the recipient DID into your
- * KDF's info/context.
- *
- * ```ts
- * const { sharedSecret, ephemeralPublicKey } = deriveSharedSecret(recipientDID)
- * // ship ephemeralPublicKey alongside whatever the secret protects
- * ```
- *
- * The result is a raw ECDH output, not a key: run it through a KDF before use.
- *
- * @param recipient a `did:key` EdDSA DID, or a `did:peer:4` **long form**. A peer:4 short form
- *   throws — the document that carries the agreement key lives 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 } = resolveX25519Key(recipient);
-    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/lib/rotation.d.ts

@@ -1,16 +0,0 @@
-import type { MultiKeyIdentity } from './identity.js';
-import type { DIDString, SignedToken } from './types.js';
-export type RotationPayload = {
-    type: 'did-rotation';
-    iss?: DIDString;
-    to: DIDString;
-    toLongForm: DIDString;
-    issuedAt: number;
-};
-/**
- * Sign a rotation assertion linking an old identity to a new one.
- * The assertion is a regular signed token issued by the old identity: its `iss` is that identity's
- * DID, in long form for a `did:peer:4` signer since the payload names no audience.
- * Verifiers walking a rotation chain can use this to link related identities.
- */
-export declare function createRotationAssertion(oldIdentity: MultiKeyIdentity, newIdentity: MultiKeyIdentity, issuedAt?: number): Promise<SignedToken<RotationPayload>>;

package/lib/rotation.js

@@ -1,13 +0,0 @@
-/**
- * Sign a rotation assertion linking an old identity to a new one.
- * The assertion is a regular signed token issued by the old identity: its `iss` is that identity's
- * DID, in long form for a `did:peer:4` signer since the payload names no audience.
- * Verifiers walking a rotation chain can use this to link related identities.
- */ export async function createRotationAssertion(oldIdentity, newIdentity, issuedAt = Math.floor(Date.now() / 1000)) {
-    return oldIdentity.signToken({
-        type: 'did-rotation',
-        to: newIdentity.id,
-        toLongForm: newIdentity.longForm,
-        issuedAt
-    });
-}