@kokuin/token 0.1.0

package/lib/identity.js

@@ -0,0 +1,344 @@
+import { ed25519, x25519 } from '@noble/curves/ed25519.js';
+import { b64uFromJSON, fromUTF, toB64U } from '@sozai/codec';
+import { AttributeKeys, createTracer, SpanNames, withSpan } from '@sozai/otel';
+import { CODECS, getDID, normalizeDID } from './did.js';
+import { decryptToken } from './jwe.js';
+import { encodeMultibase } from './multibase.js';
+import { encodePeer4, isPeer4 } from './peer4.js';
+import { concatBytes } from './utils.js';
+const tracer = createTracer('token');
+export function isSigningIdentity(identity) {
+    return 'publicKey' in identity && 'signToken' in identity && typeof identity.signToken === 'function';
+}
+export function isDecryptingIdentity(identity) {
+    return 'decrypt' in identity && typeof identity.decrypt === 'function' && 'agreeKey' in identity && typeof identity.agreeKey === 'function';
+}
+export function isFullIdentity(identity) {
+    return isSigningIdentity(identity) && isDecryptingIdentity(identity);
+}
+export function isOwnIdentity(identity) {
+    return isFullIdentity(identity) && 'privateKey' in identity;
+}
+/**
+ * Create a signing identity from an Ed25519 private key.
+ */ export function createSigningIdentity(privateKey) {
+    const publicKey = ed25519.getPublicKey(privateKey);
+    const id = getDID(CODECS.EdDSA, publicKey);
+    async function signToken(payload, options = {}) {
+        return withSpan(tracer, SpanNames.TOKEN_SIGN, {
+            attributes: {
+                [AttributeKeys.AUTH_DID]: id,
+                [AttributeKeys.AUTH_ALGORITHM]: 'EdDSA'
+            }
+        }, async ()=>{
+            if (payload.iss != null && payload.iss !== id) {
+                throw new Error('Invalid payload: issuer does not match signer');
+            }
+            const fullHeader = {
+                ...options.header ?? {},
+                typ: 'JWT',
+                alg: 'EdDSA'
+            };
+            const fullPayload = {
+                ...payload,
+                iss: id
+            };
+            const data = `${b64uFromJSON(fullHeader)}.${b64uFromJSON(fullPayload)}`;
+            return {
+                header: fullHeader,
+                payload: fullPayload,
+                signature: toB64U(ed25519.sign(fromUTF(data), privateKey)),
+                data
+            };
+        });
+    }
+    return {
+        id,
+        publicKey,
+        signToken
+    };
+}
+/**
+ * Create a decrypting identity from an Ed25519 private key.
+ * Uses X25519 key derivation for ECDH key agreement.
+ */ export function createDecryptingIdentity(privateKey) {
+    const publicKey = ed25519.getPublicKey(privateKey);
+    const id = getDID(CODECS.EdDSA, publicKey);
+    const x25519Private = ed25519.utils.toMontgomerySecret(privateKey);
+    async function decrypt(jwe) {
+        return decryptToken({
+            id,
+            decrypt,
+            agreeKey
+        }, jwe);
+    }
+    async function agreeKey(ephemeralPublicKey) {
+        return x25519.getSharedSecret(x25519Private, ephemeralPublicKey);
+    }
+    return {
+        id,
+        decrypt,
+        agreeKey
+    };
+}
+/**
+ * Create a full identity (signing + decrypting) from an Ed25519 private key.
+ */ export function createFullIdentity(privateKey) {
+    const signing = createSigningIdentity(privateKey);
+    const decrypting = createDecryptingIdentity(privateKey);
+    return {
+        ...signing,
+        ...decrypting
+    };
+}
+/**
+ * Generate a random identity with a new Ed25519 private key.
+ */ export function randomIdentity() {
+    const privateKey = ed25519.utils.randomSecretKey();
+    return {
+        ...createFullIdentity(privateKey),
+        privateKey
+    };
+}
+const CODEC_ED25519_PUB = new Uint8Array([
+    0xed,
+    0x01
+]);
+const CODEC_X25519_PUB = new Uint8Array([
+    0xec,
+    0x01
+]);
+function codecFor(alg) {
+    switch(alg){
+        case 'EdDSA':
+            return CODEC_ED25519_PUB;
+        case 'X25519':
+            return CODEC_X25519_PUB;
+    }
+}
+function publicKeyMultibase(alg, publicKey) {
+    return encodeMultibase(concatBytes(codecFor(alg), publicKey));
+}
+function generateKeyPair(alg, providedPrivate) {
+    switch(alg){
+        case 'EdDSA':
+            {
+                const priv = providedPrivate ?? ed25519.utils.randomSecretKey();
+                return {
+                    privateKey: priv,
+                    publicKey: ed25519.getPublicKey(priv)
+                };
+            }
+        case 'X25519':
+            {
+                const priv = providedPrivate ?? x25519.utils.randomSecretKey();
+                return {
+                    privateKey: priv,
+                    publicKey: x25519.getPublicKey(priv)
+                };
+            }
+    }
+}
+function isClassical(spec) {
+    return spec.alg === 'EdDSA' || spec.alg === 'X25519';
+}
+function chooseMethod(input) {
+    if (input.didMethod != null) {
+        if (input.didMethod === 'key') {
+            if (input.keys.length !== 1) {
+                throw new Error('IdentityError.InvalidMethod: did:key requires exactly one key');
+            }
+            if (!isClassical(input.keys[0])) {
+                throw new Error('IdentityError.InvalidMethod: did:key requires a classical algorithm');
+            }
+            if (input.keys[0].purpose !== 'sig') {
+                throw new Error('IdentityError.InvalidMethod: did:key requires a signing key');
+            }
+        }
+        return input.didMethod;
+    }
+    if (input.keys.length === 1 && isClassical(input.keys[0]) && input.keys[0].purpose === 'sig') {
+        return 'key';
+    }
+    return 'peer:4';
+}
+function resolveKeys(input) {
+    return input.keys.map((spec, i)=>{
+        const { privateKey, publicKey } = generateKeyPair(spec.alg, spec.privateKey);
+        return {
+            fragment: `#key-${i}`,
+            alg: spec.alg,
+            purpose: spec.purpose,
+            privateKey,
+            publicKey
+        };
+    });
+}
+function buildDoc(keys) {
+    const verificationMethod = keys.map((k)=>({
+            id: k.fragment,
+            type: 'Multikey',
+            publicKeyMultibase: publicKeyMultibase(k.alg, k.publicKey)
+        }));
+    const authentication = keys.filter((k)=>k.purpose === 'sig').map((k)=>k.fragment);
+    const keyAgreement = keys.filter((k)=>k.purpose === 'kem').map((k)=>k.fragment);
+    const doc = {
+        '@context': [
+            'https://www.w3.org/ns/did/v1'
+        ],
+        verificationMethod
+    };
+    if (authentication.length > 0) doc.authentication = authentication;
+    if (keyAgreement.length > 0) doc.keyAgreement = keyAgreement;
+    return doc;
+}
+function pickSigningKey(keys, kid) {
+    if (kid != null) {
+        const found = keys.find((k)=>k.fragment === kid);
+        if (found == null) throw new Error(`KidNotFound: ${kid}`);
+        if (found.purpose !== 'sig') throw new Error(`Kid is not a signing key: ${kid}`);
+        return found;
+    }
+    const first = keys.find((k)=>k.purpose === 'sig');
+    if (first == null) throw new Error('No signing key in identity');
+    return first;
+}
+function signWith(key, data) {
+    switch(key.alg){
+        case 'EdDSA':
+            return ed25519.sign(data, key.privateKey);
+        case 'X25519':
+            throw new Error('X25519 cannot sign');
+    }
+}
+function pickKemKey(keys, kid) {
+    if (kid != null) {
+        const found = keys.find((k)=>k.fragment === kid);
+        if (found == null) throw new Error(`KidNotFound: ${kid}`);
+        if (found.purpose !== 'kem' || found.alg !== 'X25519') {
+            throw new Error(`Kid is not a KEM X25519 key: ${kid}`);
+        }
+        return found;
+    }
+    const first = keys.find((k)=>k.purpose === 'kem' && k.alg === 'X25519');
+    if (first == null) throw new Error('No KEM key in identity');
+    return first;
+}
+function buildIdentity(id, longForm, doc, keys) {
+    const primarySig = keys.find((k)=>k.purpose === 'sig');
+    if (primarySig == null) {
+        throw new Error('createIdentity requires at least one signing key');
+    }
+    const sentTo = new Set();
+    const isPeer = isPeer4(id);
+    function pickIss(payload, embedLongForm) {
+        if (!isPeer) return id;
+        if (embedLongForm === true) return longForm;
+        if (embedLongForm === false) return id;
+        const aud = payload.aud;
+        if (typeof aud !== 'string') return id;
+        const normalizedAud = normalizeDID(aud);
+        if (sentTo.has(normalizedAud)) return id;
+        // Concurrent sign() calls with the same new aud may both emit long-form; recipient cache writes are idempotent so this is acceptable.
+        sentTo.add(normalizedAud);
+        return longForm;
+    }
+    async function signToken(payload, options = {}) {
+        const key = pickSigningKey(keys, options.kid);
+        const iss = pickIss(payload, options.embedLongForm);
+        const header = {
+            ...options.header ?? {},
+            typ: 'JWT',
+            alg: 'EdDSA',
+            ...isPeer ? {
+                kid: key.fragment
+            } : {}
+        };
+        const fullPayload = {
+            ...payload,
+            iss
+        };
+        const data = `${b64uFromJSON(header)}.${b64uFromJSON(fullPayload)}`;
+        return {
+            header: header,
+            payload: fullPayload,
+            signature: toB64U(signWith(key, fromUTF(data))),
+            data
+        };
+    }
+    async function agreeKey(ephemeralPublicKey, kid) {
+        const key = pickKemKey(keys, kid);
+        return x25519.getSharedSecret(key.privateKey, ephemeralPublicKey);
+    }
+    async function decrypt(jwe) {
+        pickKemKey(keys);
+        return decryptToken({
+            id,
+            decrypt,
+            agreeKey
+        }, jwe);
+    }
+    return {
+        id,
+        longForm,
+        doc,
+        keys,
+        publicKey: primarySig.publicKey,
+        privateKey: primarySig.privateKey,
+        signToken,
+        decrypt,
+        agreeKey
+    };
+}
+/**
+ * Build a multi-key identity from one or more key specs.
+ *
+ * DID method selection:
+ * - Single classical (`EdDSA` / `X25519`) signing key with no override → `did:key`.
+ * - Anything else (multiple keys, KEM-only, any non-classical algorithm) → `did:peer:4`.
+ * - Caller may force a method via `input.didMethod`. Invalid combinations throw
+ *   `IdentityError.InvalidMethod` (e.g. forcing `did:key` with multiple keys).
+ *
+ * Key resolution:
+ * - Each `IdentityKeySpec.privateKey` is honored when present (deterministic), otherwise
+ *   a fresh random key is generated. See {@link IdentityKeySpec.privateKey}.
+ * - At least one signing key (`purpose: 'sig'`) is required; the first becomes the
+ *   identity's primary signing key and seeds `publicKey` / `privateKey` on the result.
+ *
+ * For `did:peer:4`, the returned `id` is the short form (hash of the doc) and is
+ * deterministic with respect to the resolved keys — providing the same `privateKey`
+ * bytes across runs yields the same short form. `longForm` carries the full doc and
+ * is what peers exchange for first contact (see `signToken({ embedLongForm })`).
+ *
+ * @throws `Error` when `input.keys` is empty or no `sig` key is provided.
+ * @throws `IdentityError.InvalidMethod` when `didMethod` cannot satisfy the key set.
+ */ export async function createIdentity(input) {
+    if (input.keys.length === 0) {
+        throw new Error('createIdentity requires at least one key');
+    }
+    const method = chooseMethod(input);
+    const keys = resolveKeys(input);
+    if (method === 'key') {
+        const [k] = keys;
+        const id = getDID(CODECS.EdDSA, k.publicKey);
+        const doc = {
+            '@context': [
+                'https://www.w3.org/ns/did/v1'
+            ],
+            verificationMethod: [
+                {
+                    id: '#key-0',
+                    type: 'Multikey',
+                    publicKeyMultibase: publicKeyMultibase(k.alg, k.publicKey)
+                }
+            ],
+            authentication: [
+                '#key-0'
+            ]
+        };
+        return buildIdentity(id, id, doc, keys);
+    }
+    const doc = buildDoc(keys);
+    const { longForm, shortForm } = encodePeer4(doc);
+    return buildIdentity(shortForm, longForm, doc, keys);
+}

package/lib/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JWT signing and verification.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/token
+ * ```
+ *
+ * @module token
+ */
+export { type CreateInMemoryDIDCacheOptions, createInMemoryDIDCache, type DIDCache, type DIDResolver, } from './cache.js';
+export { CODECS, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, } from './did.js';
+export { type CreateIdentityInput, createDecryptingIdentity, createFullIdentity, createIdentity, createSigningIdentity, type DecryptingIdentity, type FullIdentity, type Identity, type IdentityKeySpec, type IdentityProvider, isDecryptingIdentity, isFullIdentity, isOwnIdentity, isSigningIdentity, type KeyAlg, type KeyPurpose, type MultiKeyIdentity, type OwnIdentity, type ResolvedKey, randomIdentity, type SigningIdentity, type SignTokenOptions, } from './identity.js';
+export type { ConcatKDFParams, EncryptOptions, EnvelopeMode, JWEHeader, TokenEncrypter, UnwrapOptions, UnwrappedEnvelope, WrapOptions, } from './jwe.js';
+export { concatKDF, createTokenEncrypter, decryptToken, encryptToken, unwrapEnvelope, wrapEnvelope, } from './jwe.js';
+export type { KeyEntry, KeyStore } from './keystore.js';
+export { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash, } from './multibase.js';
+export { type DecodePeer4Options, type DIDDoc, decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4, type VerificationMethod, validateDIDDoc, } from './peer4.js';
+export { createRotationAssertion, type RotationPayload, } from './rotation.js';
+export { capabilitySchema, type SignatureAlgorithm, type SignedHeader, type SignedPayload, type SupportedHeader, signedHeaderSchema, signedPayloadSchema, supportedHeaderSchema, type UnsignedHeader, unsignedHeaderSchema, validateAlgorithm, validateSignedHeader, validateSignedPayload, validateUnsignedHeader, } from './schemas.js';
+export { decodePrivateKey, encodePrivateKey, randomPrivateKey, } from './signer.js';
+export { assertTimeClaimsValid, now, type TimeClaimsPayload, type TimeValidationOptions, } from './time.js';
+export { createUnsignedToken, isSignedToken, isUnsignedToken, isVerifiedToken, signToken, type VerifyTokenOptions, verifyToken, } from './token.js';
+export type * from './types.js';
+export { stringifyToken } from './utils.js';
+export { getVerifier, type Verifier, type Verifiers, } from './verifier.js';

package/lib/index.js

@@ -0,0 +1,23 @@
+/**
+ * JWT signing and verification.
+ *
+ * ## Installation
+ *
+ * ```sh
+ * npm install @kokuin/token
+ * ```
+ *
+ * @module token
+ */ export { createInMemoryDIDCache } from './cache.js';
+export { CODECS, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, resolveIssuer, resolveIssuerWithDoc } from './did.js';
+export { createDecryptingIdentity, createFullIdentity, createIdentity, createSigningIdentity, isDecryptingIdentity, isFullIdentity, isOwnIdentity, isSigningIdentity, randomIdentity } from './identity.js';
+export { concatKDF, createTokenEncrypter, decryptToken, encryptToken, unwrapEnvelope, wrapEnvelope } from './jwe.js';
+export { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash } from './multibase.js';
+export { decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4, validateDIDDoc } from './peer4.js';
+export { createRotationAssertion } from './rotation.js';
+export { capabilitySchema, signedHeaderSchema, signedPayloadSchema, supportedHeaderSchema, unsignedHeaderSchema, validateAlgorithm, validateSignedHeader, validateSignedPayload, validateUnsignedHeader } from './schemas.js';
+export { decodePrivateKey, encodePrivateKey, randomPrivateKey } from './signer.js';
+export { assertTimeClaimsValid, now } from './time.js';
+export { createUnsignedToken, isSignedToken, isUnsignedToken, isVerifiedToken, signToken, verifyToken } from './token.js';
+export { stringifyToken } from './utils.js';
+export { getVerifier } from './verifier.js';

package/lib/jwe.d.ts

@@ -0,0 +1,67 @@
+import type { DecryptingIdentity, SigningIdentity } from './identity.js';
+import type { Verifiers } from './verifier.js';
+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';
+};
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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: DecryptingIdentity, 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?: DecryptingIdentity;
+    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>;