@kokuin/token 0.1.0

package/lib/jwe.js

@@ -0,0 +1,262 @@
+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 { getSignatureInfo } from './did.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 encryptWithX25519(recipientPublicKey, plaintext) {
+    // Generate ephemeral X25519 key pair
+    const ephemeralPrivateKey = x25519.utils.randomSecretKey();
+    const ephemeralPublicKey = x25519.getPublicKey(ephemeralPrivateKey);
+    // Compute shared secret via ECDH
+    const sharedSecret = x25519.getSharedSecret(ephemeralPrivateKey, 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
+        };
+    }
+    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}`);
+}
+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
+        });
+        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/keystore.d.ts

@@ -0,0 +1,10 @@
+export type KeyEntry<PrivateKeyType> = {
+    readonly keyID: string;
+    getAsync(): Promise<PrivateKeyType | null>;
+    setAsync(privateKey: PrivateKeyType): Promise<void>;
+    provideAsync(): Promise<PrivateKeyType>;
+    removeAsync(): Promise<void>;
+};
+export type KeyStore<PrivateKeyType, EntryType extends KeyEntry<PrivateKeyType> = KeyEntry<PrivateKeyType>> = {
+    entry(keyID: string): EntryType;
+};

package/lib/keystore.js

@@ -0,0 +1 @@
+export { };

package/lib/multibase.d.ts

@@ -0,0 +1,4 @@
+export declare function encodeMultibase(bytes: Uint8Array): string;
+export declare function decodeMultibase(value: string): Uint8Array;
+export declare function multihashSHA256(bytes: Uint8Array): Uint8Array;
+export declare function verifyMultihash(multihash: Uint8Array, bytes: Uint8Array): boolean;

package/lib/multibase.js

@@ -0,0 +1,36 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base58 } from '@scure/base';
+const MULTIBASE_BASE58BTC = 'z';
+const MULTIHASH_SHA256_CODE = 0x12;
+const MULTIHASH_SHA256_LENGTH = 0x20;
+export function encodeMultibase(bytes) {
+    return MULTIBASE_BASE58BTC + base58.encode(bytes);
+}
+export function decodeMultibase(value) {
+    if (value.length === 0) {
+        throw new Error('Invalid multibase encoding: empty string');
+    }
+    const prefix = value[0];
+    if (prefix !== MULTIBASE_BASE58BTC) {
+        throw new Error(`Unsupported multibase prefix: ${prefix}`);
+    }
+    return base58.decode(value.slice(1));
+}
+export function multihashSHA256(bytes) {
+    const digest = sha256(bytes);
+    const out = new Uint8Array(2 + digest.length);
+    out[0] = MULTIHASH_SHA256_CODE;
+    out[1] = MULTIHASH_SHA256_LENGTH;
+    out.set(digest, 2);
+    return out;
+}
+export function verifyMultihash(multihash, bytes) {
+    if (multihash.length !== 2 + MULTIHASH_SHA256_LENGTH) return false;
+    if (multihash[0] !== MULTIHASH_SHA256_CODE) return false;
+    if (multihash[1] !== MULTIHASH_SHA256_LENGTH) return false;
+    const expected = sha256(bytes);
+    for(let i = 0; i < MULTIHASH_SHA256_LENGTH; i++){
+        if (multihash[2 + i] !== expected[i]) return false;
+    }
+    return true;
+}

package/lib/peer4.d.ts

@@ -0,0 +1,112 @@
+import { type FromSchema } from '@sozai/schema';
+/** @internal */
+export declare const verificationMethodSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly type: {
+            readonly type: "string";
+        };
+        readonly publicKeyMultibase: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["id", "type", "publicKeyMultibase"];
+    readonly additionalProperties: true;
+};
+/** @internal */
+export type VerificationMethod = FromSchema<typeof verificationMethodSchema>;
+/** @internal */
+export declare const didDocSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly '@context': {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            }];
+        };
+        readonly verificationMethod: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                    };
+                    readonly publicKeyMultibase: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["id", "type", "publicKeyMultibase"];
+                readonly additionalProperties: true;
+            };
+            readonly minItems: 1;
+        };
+        readonly authentication: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly keyAgreement: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly assertionMethod: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly required: readonly ["verificationMethod"];
+    readonly additionalProperties: true;
+};
+/** @internal */
+export type DIDDoc = FromSchema<typeof didDocSchema>;
+/**
+ * Validate that an unknown value conforms to the DID document schema used inside did:peer:4.
+ */
+export declare function validateDIDDoc(value: unknown): value is DIDDoc;
+export type DecodePeer4Options = {
+    /** Maximum allowed size of the canonical doc bytes. Default 64 KB. */
+    maxDocSize?: number;
+};
+/**
+ * Check whether a value is a did:peer:4 identifier (either form).
+ */
+export declare function isPeer4(value: unknown): value is string;
+/**
+ * Extract the short form from either a short or long did:peer:4 string.
+ */
+export declare function getPeer4ShortForm(did: string): string;
+/**
+ * Decode a did:peer:4 long form into its DID document.
+ * Verifies the embedded hash against the encoded doc; throws on mismatch.
+ */
+export declare function decodePeer4(longForm: string, options?: DecodePeer4Options): {
+    longForm: string;
+    shortForm: string;
+    doc: DIDDoc;
+};
+/**
+ * Encode a DID document as a did:peer:4 identifier.
+ * Returns both the long form (self-contained, doc embedded) and short form (hash only).
+ */
+export declare function encodePeer4(doc: DIDDoc): {
+    longForm: string;
+    shortForm: string;
+    doc: DIDDoc;
+};

package/lib/peer4.js

@@ -0,0 +1,158 @@
+import { canonicalStringify, fromUTF, toUTF } from '@sozai/codec';
+import { createValidator, isType } from '@sozai/schema';
+import { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash } from './multibase.js';
+import { concatBytes } from './utils.js';
+/** @internal */ export const verificationMethodSchema = {
+    type: 'object',
+    properties: {
+        id: {
+            type: 'string'
+        },
+        type: {
+            type: 'string'
+        },
+        publicKeyMultibase: {
+            type: 'string'
+        }
+    },
+    required: [
+        'id',
+        'type',
+        'publicKeyMultibase'
+    ],
+    additionalProperties: true
+};
+/** @internal */ export const didDocSchema = {
+    type: 'object',
+    properties: {
+        '@context': {
+            anyOf: [
+                {
+                    type: 'string'
+                },
+                {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    }
+                }
+            ]
+        },
+        verificationMethod: {
+            type: 'array',
+            items: verificationMethodSchema,
+            minItems: 1
+        },
+        authentication: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        keyAgreement: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        assertionMethod: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        }
+    },
+    required: [
+        'verificationMethod'
+    ],
+    additionalProperties: true
+};
+const didDocValidator = createValidator(didDocSchema);
+/**
+ * Validate that an unknown value conforms to the DID document schema used inside did:peer:4.
+ */ export function validateDIDDoc(value) {
+    return isType(didDocValidator, value);
+}
+const PEER4_PREFIX = 'did:peer:4';
+const JSON_MULTICODEC = new Uint8Array([
+    0x80,
+    0x04
+]);
+const DEFAULT_MAX_DOC_SIZE = 64 * 1024;
+/**
+ * Check whether a value is a did:peer:4 identifier (either form).
+ */ export function isPeer4(value) {
+    return typeof value === 'string' && value.startsWith(`${PEER4_PREFIX}z`);
+}
+/**
+ * Extract the short form from either a short or long did:peer:4 string.
+ */ export function getPeer4ShortForm(did) {
+    if (!isPeer4(did)) {
+        throw new Error('Invalid did:peer:4 identifier');
+    }
+    const sep = did.indexOf(':', PEER4_PREFIX.length);
+    return sep === -1 ? did : did.slice(0, sep);
+}
+function startsWithJsonCodec(bytes) {
+    return bytes.length >= 2 && bytes[0] === JSON_MULTICODEC[0] && bytes[1] === JSON_MULTICODEC[1];
+}
+/**
+ * Decode a did:peer:4 long form into its DID document.
+ * Verifies the embedded hash against the encoded doc; throws on mismatch.
+ */ export function decodePeer4(longForm, options = {}) {
+    if (!isPeer4(longForm)) {
+        throw new Error('Invalid did:peer:4 identifier');
+    }
+    const sep = longForm.indexOf(':', PEER4_PREFIX.length);
+    if (sep === -1) {
+        throw new Error('Expected did:peer:4 long form, got short form');
+    }
+    const hashEncoded = longForm.slice(PEER4_PREFIX.length, sep);
+    const encodedDoc = longForm.slice(sep + 1);
+    const maxSize = options.maxDocSize ?? DEFAULT_MAX_DOC_SIZE;
+    if (encodedDoc.length > maxSize * 2) {
+        throw new Error(`did:peer:4 encoded doc too large: ${encodedDoc.length} > ${maxSize * 2}`);
+    }
+    const hashBytes = decodeMultibase(hashEncoded);
+    if (!verifyMultihash(hashBytes, fromUTF(encodedDoc))) {
+        throw new Error('did:peer:4 hash mismatch');
+    }
+    const taggedDoc = decodeMultibase(encodedDoc);
+    if (!startsWithJsonCodec(taggedDoc)) {
+        throw new Error('did:peer:4 doc missing JSON multicodec prefix');
+    }
+    const docBytes = taggedDoc.slice(JSON_MULTICODEC.length);
+    if (docBytes.length > maxSize) {
+        throw new Error(`did:peer:4 doc too large: ${docBytes.length} > ${maxSize}`);
+    }
+    const doc = JSON.parse(toUTF(docBytes));
+    if (!validateDIDDoc(doc)) {
+        throw new Error('did:peer:4 doc failed schema validation');
+    }
+    const shortForm = `${PEER4_PREFIX}${hashEncoded}`;
+    return {
+        longForm,
+        shortForm,
+        doc
+    };
+}
+/**
+ * Encode a DID document as a did:peer:4 identifier.
+ * Returns both the long form (self-contained, doc embedded) and short form (hash only).
+ */ export function encodePeer4(doc) {
+    if (!validateDIDDoc(doc)) {
+        throw new Error('did:peer:4 doc failed schema validation');
+    }
+    const canonicalDocBytes = fromUTF(canonicalStringify(doc));
+    const taggedDoc = concatBytes(JSON_MULTICODEC, canonicalDocBytes);
+    const encodedDoc = encodeMultibase(taggedDoc);
+    const hashBytes = multihashSHA256(fromUTF(encodedDoc));
+    const hash = encodeMultibase(hashBytes);
+    const shortForm = `${PEER4_PREFIX}${hash}`;
+    const longForm = `${shortForm}:${encodedDoc}`;
+    return {
+        longForm,
+        shortForm,
+        doc
+    };
+}

package/lib/rotation.d.ts

@@ -0,0 +1,15 @@
+import type { MultiKeyIdentity } from './identity.js';
+import type { SignedToken } from './types.js';
+export type RotationPayload = {
+    type: 'did-rotation';
+    iss?: string;
+    to: string;
+    toLongForm: string;
+    issuedAt: number;
+};
+/**
+ * Sign a rotation assertion linking an old identity to a new one.
+ * The assertion is a regular signed token whose `iss` is the old DID.
+ * 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

@@ -0,0 +1,12 @@
+/**
+ * Sign a rotation assertion linking an old identity to a new one.
+ * The assertion is a regular signed token whose `iss` is the old DID.
+ * 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
+    });
+}