@kokuin/token 0.1.0

package/README.md

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

package/lib/cache.d.ts

@@ -0,0 +1,23 @@
+import { type DIDDoc } from './peer4.js';
+/**
+ * Resolves a DID string to a DID document.
+ * Implementations may be sync or async, returning undefined when the DID is unknown.
+ */
+export type DIDResolver = (did: string) => DIDDoc | undefined | Promise<DIDDoc | undefined>;
+/**
+ * Content-addressed store for did:peer:4 documents, keyed by the short-form DID.
+ * `set` MUST verify that the short form matches the hash of the canonical doc before storing.
+ */
+export type DIDCache = {
+    get(shortForm: string): DIDDoc | undefined | Promise<DIDDoc | undefined>;
+    set(shortForm: string, doc: DIDDoc): void | Promise<void>;
+};
+export type CreateInMemoryDIDCacheOptions = {
+    /** Maximum number of cached entries. Oldest evicted first. Default 10_000. */
+    maxEntries?: number;
+};
+/**
+ * Build an in-memory DID cache. The returned cache verifies short-form/doc binding on every set
+ * and evicts least-recently-used entries when maxEntries is exceeded.
+ */
+export declare function createInMemoryDIDCache(options?: CreateInMemoryDIDCacheOptions): DIDCache;

package/lib/cache.js

@@ -0,0 +1,41 @@
+import { encodePeer4, isPeer4 } from './peer4.js';
+const DEFAULT_MAX_ENTRIES = 10_000;
+/**
+ * Build an in-memory DID cache. The returned cache verifies short-form/doc binding on every set
+ * and evicts least-recently-used entries when maxEntries is exceeded.
+ */ export function createInMemoryDIDCache(options = {}) {
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (maxEntries < 1) {
+        throw new Error('DIDCache: maxEntries must be at least 1');
+    }
+    const docs = new Map();
+    function touch(shortForm, doc) {
+        docs.delete(shortForm);
+        docs.set(shortForm, doc);
+    }
+    return {
+        get (shortForm) {
+            const doc = docs.get(shortForm);
+            if (doc != null) {
+                touch(shortForm, doc);
+            }
+            return doc;
+        },
+        set (shortForm, doc) {
+            if (!isPeer4(shortForm)) {
+                return Promise.reject(new Error('DIDCache: short form must be a did:peer:4 identifier'));
+            }
+            const expected = encodePeer4(doc).shortForm;
+            if (expected !== shortForm) {
+                return Promise.reject(new Error('DIDCache: short form/doc hash mismatch'));
+            }
+            touch(shortForm, doc);
+            while(docs.size > maxEntries){
+                const oldest = docs.keys().next().value;
+                if (oldest == null) break;
+                docs.delete(oldest);
+            }
+            return Promise.resolve();
+        }
+    };
+}

package/lib/did.d.ts

@@ -0,0 +1,39 @@
+import type { DIDResolver } from './cache.js';
+import type { DIDDoc } from './peer4.js';
+import type { SignatureAlgorithm } from './schemas.js';
+/** @internal */
+export declare const CODECS: Record<SignatureAlgorithm, Uint8Array>;
+/** @internal */
+export declare function getAlgorithmAndPublicKey(bytes: Uint8Array): [SignatureAlgorithm, Uint8Array] | null;
+/** @internal */
+export declare function getDID(codec: Uint8Array, publicKey: Uint8Array): string;
+/** @internal */
+export declare function getSignatureInfo(did: string): [SignatureAlgorithm, Uint8Array];
+export type ResolveIssuerHeader = {
+    kid?: string;
+};
+export type ResolveIssuerWithDocResult = {
+    alg: SignatureAlgorithm;
+    publicKey: Uint8Array;
+    /** Present when iss was a peer:4 long form or resolver returned a doc — caller may use to populate a cache. */
+    peer4Doc?: {
+        shortForm: string;
+        doc: DIDDoc;
+    };
+};
+/**
+ * Resolve a token issuer (did:key or did:peer:4) and return alg + public key,
+ * plus the decoded peer:4 doc when one was obtained inline or via the resolver.
+ * Callers writing to a DID cache should write `peer4Doc` only after signature verification.
+ */
+export declare function resolveIssuerWithDoc(iss: string, header?: ResolveIssuerHeader, resolver?: DIDResolver): Promise<ResolveIssuerWithDocResult>;
+/**
+ * Resolve a token issuer to [alg, publicKey]. Backward-compatible wrapper around resolveIssuerWithDoc.
+ */
+export declare function resolveIssuer(iss: string, header?: ResolveIssuerHeader, resolver?: DIDResolver): Promise<[SignatureAlgorithm, Uint8Array]>;
+/**
+ * Fold a DID to its canonical form for equality comparison.
+ * For did:peer:4, returns the short form regardless of whether input is long or short.
+ * All other DID methods pass through unchanged.
+ */
+export declare function normalizeDID(did: string): string;

package/lib/did.js

@@ -0,0 +1,146 @@
+import { base58 } from '@scure/base';
+import { decodeMultibase } from './multibase.js';
+import { decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
+/** @internal */ export const CODECS = {
+    ES256: new Uint8Array([
+        128,
+        36
+    ]),
+    EdDSA: new Uint8Array([
+        0xed,
+        0x01
+    ])
+};
+const EXPECTED_KEY_SIZES = {
+    EdDSA: 32,
+    ES256: 33
+};
+const PREFIX = 'did:key:z';
+function isCodecMatch(codec, bytes) {
+    if (bytes.length < codec.length) return false;
+    for(let i = 0; i < codec.length; i++){
+        if (bytes[i] !== codec[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/** @internal */ export function getAlgorithmAndPublicKey(bytes) {
+    for (const [alg, codec] of Object.entries(CODECS)){
+        if (isCodecMatch(codec, bytes)) {
+            return [
+                alg,
+                bytes.slice(codec.length)
+            ];
+        }
+    }
+    return null;
+}
+/** @internal */ export function getDID(codec, publicKey) {
+    const bytes = new Uint8Array(codec.length + publicKey.length);
+    codec.forEach((v, i)=>{
+        bytes[i] = v;
+    });
+    bytes.set(publicKey, codec.length);
+    return PREFIX + base58.encode(bytes);
+}
+/** @internal */ export function getSignatureInfo(did) {
+    if (!did.startsWith(PREFIX)) {
+        throw new Error('Invalid DID format');
+    }
+    const bytes = base58.decode(did.slice(PREFIX.length));
+    const info = getAlgorithmAndPublicKey(bytes);
+    if (info == null) {
+        throw new Error('Unsupported DID signature codec');
+    }
+    const [alg, publicKey] = info;
+    const expectedSize = EXPECTED_KEY_SIZES[alg];
+    if (expectedSize != null && publicKey.length !== expectedSize) {
+        throw new Error('Invalid public key size');
+    }
+    return info;
+}
+/**
+ * Resolve a token issuer (did:key or did:peer:4) and return alg + public key,
+ * plus the decoded peer:4 doc when one was obtained inline or via the resolver.
+ * Callers writing to a DID cache should write `peer4Doc` only after signature verification.
+ */ export async function resolveIssuerWithDoc(iss, header = {}, resolver) {
+    if (isPeer4(iss)) {
+        const shortForm = getPeer4ShortForm(iss);
+        if (iss !== shortForm) {
+            const { doc } = decodePeer4(iss);
+            const [alg, publicKey] = resolveKidOrAuth(doc, header.kid);
+            return {
+                alg,
+                publicKey,
+                peer4Doc: {
+                    shortForm,
+                    doc
+                }
+            };
+        }
+        if (resolver == null) {
+            throw new Error(`Unknown DID: ${shortForm}`);
+        }
+        const doc = await resolver(shortForm);
+        if (doc == null) {
+            throw new Error(`Unknown DID: ${shortForm}`);
+        }
+        const expected = encodePeer4(doc).shortForm;
+        if (expected !== shortForm) {
+            throw new Error('DIDResolver: short form/doc hash mismatch');
+        }
+        const [alg, publicKey] = resolveKidOrAuth(doc, header.kid);
+        return {
+            alg,
+            publicKey,
+            peer4Doc: {
+                shortForm,
+                doc
+            }
+        };
+    }
+    const [alg, publicKey] = getSignatureInfo(iss);
+    return {
+        alg,
+        publicKey
+    };
+}
+/**
+ * Resolve a token issuer to [alg, publicKey]. Backward-compatible wrapper around resolveIssuerWithDoc.
+ */ export async function resolveIssuer(iss, header = {}, resolver) {
+    const { alg, publicKey } = await resolveIssuerWithDoc(iss, header, resolver);
+    return [
+        alg,
+        publicKey
+    ];
+}
+function resolveKidOrAuth(doc, kid) {
+    if (kid == null) {
+        const auth = doc.authentication;
+        if (auth == null || auth.length === 0) {
+            throw new Error('resolveIssuer: did:peer:4 token missing kid and doc has no authentication entries');
+        }
+        return resolveKidFromDoc(doc, auth[0]);
+    }
+    return resolveKidFromDoc(doc, kid);
+}
+function resolveKidFromDoc(doc, kid) {
+    const method = doc.verificationMethod.find((m)=>m.id === kid);
+    if (method == null) {
+        throw new Error(`KidNotFound: ${kid}`);
+    }
+    const bytes = decodeMultibase(method.publicKeyMultibase);
+    const info = getAlgorithmAndPublicKey(bytes);
+    if (info == null) {
+        throw new Error('Unsupported verification method codec');
+    }
+    return info;
+}
+/**
+ * Fold a DID to its canonical form for equality comparison.
+ * For did:peer:4, returns the short form regardless of whether input is long or short.
+ * All other DID methods pass through unchanged.
+ */ export function normalizeDID(did) {
+    return isPeer4(did) ? getPeer4ShortForm(did) : did;
+}

package/lib/identity.d.ts

@@ -0,0 +1,119 @@
+import { type DIDDoc } from './peer4.js';
+import type { SignedToken } from './types.js';
+export type Identity = {
+    readonly id: string;
+};
+export type SignTokenOptions = {
+    /** Extra header fields merged into the signed JWS header. */
+    header?: Record<string, unknown>;
+    /** Pick a non-primary signing key by fragment (e.g. "#key-1"). */
+    kid?: string;
+    /**
+     * Override the first-per-aud long-form policy for did:peer:4 identities.
+     * - true: always use long form (no-op for did:key, where longForm === id).
+     * - false: always use short form.
+     * - undefined (default): use long form on first token to a given payload.aud, short form thereafter.
+     */
+    embedLongForm?: boolean;
+};
+export type SigningIdentity = Identity & {
+    publicKey: Uint8Array;
+    signToken: <Payload extends Record<string, unknown> = Record<string, unknown>>(payload: Payload, options?: SignTokenOptions) => Promise<SignedToken<Payload>>;
+};
+export type DecryptingIdentity = Identity & {
+    decrypt(jwe: string): Promise<Uint8Array>;
+    agreeKey(ephemeralPublicKey: Uint8Array): Promise<Uint8Array>;
+};
+export type FullIdentity = SigningIdentity & DecryptingIdentity;
+export type OwnIdentity = FullIdentity & {
+    privateKey: Uint8Array;
+};
+export type IdentityProvider<T extends SigningIdentity = SigningIdentity> = {
+    provideIdentity(keyID: string): Promise<T>;
+};
+export declare function isSigningIdentity(identity: Identity): identity is SigningIdentity;
+export declare function isDecryptingIdentity(identity: Identity): identity is DecryptingIdentity;
+export declare function isFullIdentity(identity: Identity): identity is FullIdentity;
+export declare function isOwnIdentity(identity: Identity): identity is OwnIdentity;
+/**
+ * Create a signing identity from an Ed25519 private key.
+ */
+export declare function createSigningIdentity(privateKey: Uint8Array): SigningIdentity;
+/**
+ * Create a decrypting identity from an Ed25519 private key.
+ * Uses X25519 key derivation for ECDH key agreement.
+ */
+export declare function createDecryptingIdentity(privateKey: Uint8Array): DecryptingIdentity;
+/**
+ * Create a full identity (signing + decrypting) from an Ed25519 private key.
+ */
+export declare function createFullIdentity(privateKey: Uint8Array): FullIdentity;
+/**
+ * Generate a random identity with a new Ed25519 private key.
+ */
+export declare function randomIdentity(): OwnIdentity;
+export type KeyPurpose = 'sig' | 'kem';
+export type KeyAlg = 'EdDSA' | 'X25519';
+export type IdentityKeySpec = {
+    purpose: KeyPurpose;
+    alg: KeyAlg;
+    /**
+     * Optional caller-supplied private key bytes.
+     *
+     * - When provided, the key pair is derived deterministically from these bytes.
+     *   For a single-key spec on `did:peer:4`, this means the resulting short form
+     *   is also deterministic — useful for reproducible identities (tests, seed-based
+     *   recovery, restoring an identity from a stored secret).
+     * - When omitted, a fresh random key is generated via the algorithm's
+     *   `randomSecretKey()` utility (Ed25519 or X25519).
+     *
+     * The caller owns the lifecycle of the supplied bytes.
+     */
+    privateKey?: Uint8Array;
+};
+export type CreateIdentityInput = {
+    keys: Array<IdentityKeySpec>;
+    didMethod?: 'key' | 'peer:4';
+};
+export type ResolvedKey = {
+    fragment: string;
+    alg: KeyAlg;
+    purpose: KeyPurpose;
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+export type MultiKeyIdentity = {
+    id: string;
+    longForm: string;
+    doc: DIDDoc;
+    keys: Array<ResolvedKey>;
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+    signToken<Payload extends Record<string, unknown> = Record<string, unknown>>(payload: Payload, options?: SignTokenOptions): Promise<SignedToken<Payload>>;
+    decrypt(jwe: string): Promise<Uint8Array>;
+    agreeKey(ephemeralPublicKey: Uint8Array, kid?: string): Promise<Uint8Array>;
+};
+/**
+ * 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 declare function createIdentity(input: CreateIdentityInput): Promise<MultiKeyIdentity>;