@kokuin/token 0.2.0 → 0.4.0

package/lib/cache.js

@@ -1,4 +1,4 @@
-import { encodePeer4, isPeer4 } from './peer4.js';
+import { assertDocWithinMaxSize, 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
@@ -25,6 +25,13 @@ const DEFAULT_MAX_ENTRIES = 10_000;
             if (!isPeer4(shortForm)) {
                 return Promise.reject(new Error('DIDCache: short form must be a did:peer:4 identifier'));
             }
+            // The doc originated from a resolver. Bound it before the encode below, which is linear in
+            // its size — the same guard the resolver path applies.
+            try {
+                assertDocWithinMaxSize(doc);
+            } catch (err) {
+                return Promise.reject(err);
+            }
             const expected = encodePeer4(doc).shortForm;
             if (expected !== shortForm) {
                 return Promise.reject(new Error('DIDCache: short form/doc hash mismatch'));

package/lib/did.d.ts

@@ -1,12 +1,13 @@
 import type { DIDResolver } from './cache.js';
 import type { DIDDoc } from './peer4.js';
 import type { SignatureAlgorithm } from './schemas.js';
+import type { DIDString } from './types.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;
+export declare function getDID(codec: Uint8Array, publicKey: Uint8Array): DIDString;
 /** @internal */
 export declare function getSignatureInfo(did: string): [SignatureAlgorithm, Uint8Array];
 export type ResolveIssuerHeader = {
@@ -37,3 +38,12 @@ export declare function resolveIssuer(iss: string, header?: ResolveIssuerHeader,
  * All other DID methods pass through unchanged.
  */
 export declare function normalizeDID(did: string): string;
+/**
+ * The X25519 public key a DID document publishes for key agreement, or `null` when it
+ * publishes none.
+ *
+ * Unlike a `did:key` EdDSA identity — whose agreement key is *derived* from its signing key
+ * via the birational map — a peer:4 identity carries an independent agreement key in its doc.
+ * A sender MUST use the published key: the derived one is a different key and will not decrypt.
+ */
+export declare function getAgreementKey(doc: DIDDoc): Uint8Array | null;

package/lib/did.js

@@ -45,7 +45,7 @@ function isCodecMatch(codec, bytes) {
         bytes[i] = v;
     });
     bytes.set(publicKey, codec.length);
-    return PREFIX + base58.encode(bytes);
+    return `${PREFIX}${base58.encode(bytes)}`;
 }
 /** @internal */ export function getSignatureInfo(did) {
     if (!did.startsWith(PREFIX)) {
@@ -166,3 +166,45 @@ function resolveKidFromDoc(doc, kid) {
  */ export function normalizeDID(did) {
     return isPeer4(did) ? getPeer4ShortForm(did) : did;
 }
+/** Multicodec prefix for an X25519 public key, as published in a peer:4 doc. */ const CODEC_X25519_PUB = new Uint8Array([
+    0xec,
+    0x01
+]);
+/**
+ * The X25519 public key a DID document publishes for key agreement, or `null` when it
+ * publishes none.
+ *
+ * Unlike a `did:key` EdDSA identity — whose agreement key is *derived* from its signing key
+ * via the birational map — a peer:4 identity carries an independent agreement key in its doc.
+ * A sender MUST use the published key: the derived one is a different key and will not decrypt.
+ */ export function getAgreementKey(doc) {
+    const fragments = doc.keyAgreement;
+    if (fragments == null) {
+        return null;
+    }
+    for (const fragment of fragments){
+        const method = doc.verificationMethod.find((verificationMethod)=>verificationMethod.id === fragment);
+        if (method == null) {
+            continue;
+        }
+        // Bound before decoding — base58.decode is O(n^2) — same as resolveKidFromDoc().
+        if (method.publicKeyMultibase.length > MAX_DID_KEY_ENCODED) {
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = decodeMultibase(method.publicKeyMultibase);
+        } catch  {
+            continue;
+        }
+        if (!isCodecMatch(CODEC_X25519_PUB, bytes)) {
+            continue;
+        }
+        const publicKey = bytes.slice(CODEC_X25519_PUB.length);
+        if (publicKey.length !== 32) {
+            continue;
+        }
+        return publicKey;
+    }
+    return null;
+}

package/lib/identity.d.ts

@@ -1,7 +1,7 @@
 import { type DIDDoc } from './peer4.js';
-import type { SignedToken } from './types.js';
+import type { DIDString, SignedToken } from './types.js';
 export type Identity = {
-    readonly id: string;
+    readonly id: DIDString;
 };
 export type SignTokenOptions = {
     /** Extra header fields merged into the signed JWS header. */
@@ -9,10 +9,13 @@ export type SignTokenOptions = {
     /** 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.
+     * Override the 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.
+     * - undefined (default): long form on the first token to a given `payload.aud`, short form
+     *   thereafter; and always long form when the payload names no single string audience, since
+     *   there is then no audience to key first contact on and the recipient may hold no cached
+     *   document for this DID.
      */
     embedLongForm?: boolean;
 };
@@ -83,8 +86,8 @@ export type ResolvedKey = {
     publicKey: Uint8Array;
 };
 export type MultiKeyIdentity = {
-    id: string;
-    longForm: string;
+    id: DIDString;
+    longForm: DIDString;
     doc: DIDDoc;
     keys: Array<ResolvedKey>;
     publicKey: Uint8Array;

package/lib/identity.js

@@ -212,18 +212,37 @@ function signWith(key, data) {
             throw new Error('X25519 cannot sign');
     }
 }
-function pickKemKey(keys, kid) {
+/**
+ * The X25519 private scalar this identity agrees with, for `kid` or by default.
+ *
+ * A peer:4 identity uses its published `keyAgreement` key. A `did:key` EdDSA identity has no
+ * published agreement key — a sender derives one from its signing key via the birational map —
+ * so it must derive the matching secret the same way, exactly as `createDecryptingIdentity` does.
+ */ function pickAgreementSecret(keys, isPeer, kid) {
     if (kid != null) {
-        const found = keys.find((k)=>k.fragment === kid);
+        // No birational fallback here, unlike the no-kid branch below: a kid names one specific
+        // key, so falling back to a *different*, derived key would silently agree with the wrong
+        // secret. This means a did:key identity's agreeKey(epk, '#key-0') throws where
+        // agreeKey(epk) succeeds — a known asymmetry, currently unreachable: decryptToken (jwe.ts)
+        // never passes a kid, and DecryptingIdentity#agreeKey has no kid parameter at all.
+        const found = keys.find((key)=>key.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;
+        return found.privateKey;
     }
-    const first = keys.find((k)=>k.purpose === 'kem' && k.alg === 'X25519');
-    if (first == null) throw new Error('No KEM key in identity');
-    return first;
+    const kem = keys.find((key)=>key.purpose === 'kem' && key.alg === 'X25519');
+    if (kem != null) {
+        return kem.privateKey;
+    }
+    if (!isPeer) {
+        const sig = keys.find((key)=>key.purpose === 'sig' && key.alg === 'EdDSA');
+        if (sig != null) {
+            return ed25519.utils.toMontgomerySecret(sig.privateKey);
+        }
+    }
+    throw new Error('No KEM key in identity');
 }
 function buildIdentity(id, longForm, doc, keys) {
     const primarySig = keys.find((k)=>k.purpose === 'sig');
@@ -237,7 +256,9 @@ function buildIdentity(id, longForm, doc, keys) {
         if (embedLongForm === true) return longForm;
         if (embedLongForm === false) return id;
         const aud = payload.aud;
-        if (typeof aud !== 'string') return id;
+        // No single named audience: there is nothing to key first-contact on, and the recipient may
+        // never have seen this doc. Embed the long form so the token resolves standalone.
+        if (typeof aud !== 'string') return longForm;
         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.
@@ -268,11 +289,10 @@ function buildIdentity(id, longForm, doc, keys) {
         };
     }
     async function agreeKey(ephemeralPublicKey, kid) {
-        const key = pickKemKey(keys, kid);
-        return x25519.getSharedSecret(key.privateKey, ephemeralPublicKey);
+        return x25519.getSharedSecret(pickAgreementSecret(keys, isPeer, kid), ephemeralPublicKey);
     }
     async function decrypt(jwe) {
-        pickKemKey(keys);
+        pickAgreementSecret(keys, isPeer); // fail fast when this identity cannot agree at all
         return decryptToken({
             id,
             decrypt,

package/lib/index.d.ts

@@ -10,11 +10,11 @@
  * @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 { CODECS, getAgreementKey, 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 type { ConcatKDFParams, EncryptOptions, EnvelopeMode, JWEHeader, SharedSecretResult, TokenEncrypter, UnwrapOptions, UnwrappedEnvelope, WrapOptions, } from './jwe.js';
+export { concatKDF, createTokenEncrypter, decryptToken, deriveSharedSecret, encryptToken, unwrapEnvelope, wrapEnvelope, } from './jwe.js';
+export type { KeyEntry, KeyStore, MutableKeyEntry } 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';
@@ -23,5 +23,5 @@ export { decodePrivateKey, encodePrivateKey, randomPrivateKey, } from './signer.
 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 { concatBytes, stringifyToken } from './utils.js';
 export { getVerifier, type Verifier, type Verifiers, } from './verifier.js';

package/lib/index.js

@@ -9,9 +9,9 @@
  *
  * @module token
  */ export { createInMemoryDIDCache } from './cache.js';
-export { CODECS, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, resolveIssuer, resolveIssuerWithDoc } from './did.js';
+export { CODECS, getAgreementKey, 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 { concatKDF, createTokenEncrypter, decryptToken, deriveSharedSecret, 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';
@@ -19,5 +19,5 @@ export { capabilitySchema, signedHeaderSchema, signedPayloadSchema, supportedHea
 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 { concatBytes, stringifyToken } from './utils.js';
 export { getVerifier } from './verifier.js';

package/lib/jwe.d.ts

@@ -25,11 +25,50 @@ export type TokenEncrypter = {
 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 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 declare function deriveSharedSecret(recipient: string): SharedSecretResult;
 /**
  * Create a token encrypter for a recipient identified by X25519 public key or DID string.
  */

package/lib/jwe.js

@@ -3,7 +3,8 @@ 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 { 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) {
@@ -52,12 +53,15 @@ function lengthPrefixed(data) {
     }
     return sha256(hashInput).slice(0, keyLength / 8);
 }
-function encryptWithX25519(recipientPublicKey, plaintext) {
-    // Generate ephemeral X25519 key pair
+function agreeWithKey(recipientPublicKey) {
     const ephemeralPrivateKey = x25519.utils.randomSecretKey();
-    const ephemeralPublicKey = x25519.getPublicKey(ephemeralPrivateKey);
-    // Compute shared secret via ECDH
-    const sharedSecret = x25519.getSharedSecret(ephemeralPrivateKey, recipientPublicKey);
+    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,
@@ -104,6 +108,23 @@ function resolveX25519Key(recipient) {
             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 {
@@ -113,6 +134,37 @@ function resolveX25519Key(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}`);

package/lib/keystore.d.ts

@@ -1,10 +1,71 @@
+/**
+ * A single key slot in a {@link KeyStore}, identified by `keyID`.
+ *
+ * This is the **read/provide** facet — the floor every backend can honor, including ones
+ * that derive keys rather than store them (HD) or never expose key material at all.
+ * A backend that can also write and delete implements {@link MutableKeyEntry}.
+ *
+ * ## Invariants
+ *
+ * Enforced by `keyStoreConformanceCases`. A backend that cannot satisfy these does not
+ * implement this type — it exposes a different surface instead.
+ *
+ * 1. **keyID round-trips.** `store.entry(x).keyID === x`, always.
+ * 2. **Absent means `null`.** {@link getAsync} resolves `null` when no key exists. Never
+ *    `undefined`, never a throw. A *derived* backend may never return `null` at all —
+ *    it can always produce a key — and that is contract-legal.
+ * 3. **{@link provideAsync} is idempotent under concurrency.** Two concurrent calls on one
+ *    keyID resolve to the *same* key. Never two keys; never a key that is generated,
+ *    returned to a caller, and then overwritten by a racer.
+ */
 export type KeyEntry<PrivateKeyType> = {
+    /** The keyID this entry was created for. Identical to the string passed to `entry()`. */
     readonly keyID: string;
+    /** The stored key, or `null` when none exists. Never `undefined`; never throws for absence. */
     getAsync(): Promise<PrivateKeyType | null>;
-    setAsync(privateKey: PrivateKeyType): Promise<void>;
+    /**
+     * The stored key, generating and persisting one if absent.
+     *
+     * Idempotent under concurrency: racing callers converge on a single key. Backends that
+     * share storage across processes need a cross-process lock to hold this (see `lockPath`
+     * on `NodeKeyStore` / `ElectronKeyStore`); an in-process promise chain is not enough.
+     */
     provideAsync(): Promise<PrivateKeyType>;
+};
+/**
+ * A {@link KeyEntry} on a backend that can also **write and delete** key material.
+ *
+ * HD and ledger backends deliberately do NOT implement this: an HD key is derived (there is
+ * nothing to set, and removing it does not stop it being derivable), and a ledger key never
+ * leaves the device. Previously they "conformed" by throwing from `setAsync` and silently
+ * no-op'ing `removeAsync` — the type now says what the substrate can do, so there is nothing
+ * to throw from.
+ */
+export type MutableKeyEntry<PrivateKeyType> = KeyEntry<PrivateKeyType> & {
+    /** Persist `privateKey` under this entry's keyID, replacing any existing key. */
+    setAsync(privateKey: PrivateKeyType): Promise<void>;
+    /** Delete this entry's key. Idempotent — removing an absent key resolves, it does not throw. */
     removeAsync(): Promise<void>;
 };
+/**
+ * A keyed collection of {@link KeyEntry}s.
+ *
+ * Parameterized by entry type, so a writable backend is `KeyStore<T, MutableKeyEntry<T>>`
+ * and a derived one is `KeyStore<T, KeyEntry<T>>`. No separate mutable store type is needed.
+ *
+ * Most consumers should NOT be generic over this — they should be generic over
+ * `IdentityProvider`, which is what "give me an identity for this keyID" actually needs.
+ * `KeyStore` is the *storage* contract, useful to backend authors and to the conformance
+ * suite. A backend whose key never leaves the device (ledger) implements `IdentityProvider`
+ * and neither storage type; that is the contract working, not a gap.
+ */
 export type KeyStore<PrivateKeyType, EntryType extends KeyEntry<PrivateKeyType> = KeyEntry<PrivateKeyType>> = {
+    /**
+     * The entry for `keyID`.
+     *
+     * Must be **cached**: `store.entry(x) === store.entry(x)`. Entries carry per-entry
+     * concurrency state (the `provideAsync` lock), so handing out a fresh entry per call
+     * silently defeats it.
+     */
     entry(keyID: string): EntryType;
 };

package/lib/keystore.js

@@ -1 +1,31 @@
-export { };
+/**
+ * A single key slot in a {@link KeyStore}, identified by `keyID`.
+ *
+ * This is the **read/provide** facet — the floor every backend can honor, including ones
+ * that derive keys rather than store them (HD) or never expose key material at all.
+ * A backend that can also write and delete implements {@link MutableKeyEntry}.
+ *
+ * ## Invariants
+ *
+ * Enforced by `keyStoreConformanceCases`. A backend that cannot satisfy these does not
+ * implement this type — it exposes a different surface instead.
+ *
+ * 1. **keyID round-trips.** `store.entry(x).keyID === x`, always.
+ * 2. **Absent means `null`.** {@link getAsync} resolves `null` when no key exists. Never
+ *    `undefined`, never a throw. A *derived* backend may never return `null` at all —
+ *    it can always produce a key — and that is contract-legal.
+ * 3. **{@link provideAsync} is idempotent under concurrency.** Two concurrent calls on one
+ *    keyID resolve to the *same* key. Never two keys; never a key that is generated,
+ *    returned to a caller, and then overwritten by a racer.
+ */ /**
+ * A keyed collection of {@link KeyEntry}s.
+ *
+ * Parameterized by entry type, so a writable backend is `KeyStore<T, MutableKeyEntry<T>>`
+ * and a derived one is `KeyStore<T, KeyEntry<T>>`. No separate mutable store type is needed.
+ *
+ * Most consumers should NOT be generic over this — they should be generic over
+ * `IdentityProvider`, which is what "give me an identity for this keyID" actually needs.
+ * `KeyStore` is the *storage* contract, useful to backend authors and to the conformance
+ * suite. A backend whose key never leaves the device (ledger) implements `IdentityProvider`
+ * and neither storage type; that is the contract working, not a gap.
+ */ export { };

package/lib/peer4.d.ts

@@ -1,4 +1,5 @@
 import { type FromSchema } from '@sozai/schema';
+import type { DIDString } from './types.js';
 /** @internal */
 export declare const verificationMethodSchema: {
     readonly type: "object";
@@ -87,6 +88,10 @@ export type DecodePeer4Options = {
 /**
  * Throw if a DID document's canonical serialization exceeds `maxSize` bytes.
  * Used to bound a resolver-returned doc before it reaches the O(n^2) base58 encode.
+ *
+ * The entry-count check runs first and is O(1): `canonicalStringify` below is linear in the
+ * document, so an attacker-supplied `verificationMethod` array with millions of entries would
+ * otherwise cost linear time before it could be measured and rejected.
  */
 export declare function assertDocWithinMaxSize(doc: DIDDoc, maxSize?: number): void;
 /**
@@ -111,7 +116,7 @@ export declare function decodePeer4(longForm: string, options?: DecodePeer4Optio
  * Returns both the long form (self-contained, doc embedded) and short form (hash only).
  */
 export declare function encodePeer4(doc: DIDDoc): {
-    longForm: string;
-    shortForm: string;
+    longForm: DIDString;
+    shortForm: DIDString;
     doc: DIDDoc;
 };

package/lib/peer4.js

@@ -79,6 +79,10 @@ const JSON_MULTICODEC = new Uint8Array([
     0x04
 ]);
 const DEFAULT_MAX_DOC_SIZE = 4 * 1024;
+// The smallest legal verificationMethod entry — {"id":"","type":"","publicKeyMultibase":""} at 43
+// bytes plus an array separator — serializes to 44. Undercounting here only widens the cap, so the
+// O(1) guard below can never reject a doc the full byte measure would have accepted.
+const MIN_VERIFICATION_METHOD_BYTES = 40;
 // base58 expands bytes to characters by log(256) / log(58).
 const BASE58_EXPANSION = 1.3658;
 // A SHA-256 multihash is 34 bytes: 47 base58 characters plus the multibase 'z'.
@@ -86,7 +90,15 @@ const MAX_HASH_ENCODED = 64;
 /**
  * Throw if a DID document's canonical serialization exceeds `maxSize` bytes.
  * Used to bound a resolver-returned doc before it reaches the O(n^2) base58 encode.
+ *
+ * The entry-count check runs first and is O(1): `canonicalStringify` below is linear in the
+ * document, so an attacker-supplied `verificationMethod` array with millions of entries would
+ * otherwise cost linear time before it could be measured and rejected.
  */ export function assertDocWithinMaxSize(doc, maxSize = DEFAULT_MAX_DOC_SIZE) {
+    const maxEntries = Math.ceil(maxSize / MIN_VERIFICATION_METHOD_BYTES);
+    if (Array.isArray(doc.verificationMethod) && doc.verificationMethod.length > maxEntries) {
+        throw new Error(`did:peer:4 resolver doc has too many verification methods: ${doc.verificationMethod.length} > ${maxEntries}`);
+    }
     const size = fromUTF(canonicalStringify(doc)).length;
     if (size > maxSize) {
         throw new Error(`did:peer:4 resolver doc too large: ${size} > ${maxSize}`);

package/lib/rotation.d.ts

@@ -1,15 +1,16 @@
 import type { MultiKeyIdentity } from './identity.js';
-import type { SignedToken } from './types.js';
+import type { DIDString, SignedToken } from './types.js';
 export type RotationPayload = {
     type: 'did-rotation';
-    iss?: string;
-    to: string;
-    toLongForm: string;
+    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 whose `iss` is the old DID.
+ * 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,6 +1,7 @@
 /**
  * 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.
+ * 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({

package/lib/token.d.ts

@@ -2,7 +2,7 @@ import type { DIDCache, DIDResolver } from './cache.js';
 import type { SigningIdentity } from './identity.js';
 import { type SignedPayload } from './schemas.js';
 import { type TimeValidationOptions } from './time.js';
-import type { SignedToken, Token, UnsignedToken, VerifiedToken } from './types.js';
+import type { DIDString, SignedToken, Token, UnsignedToken, VerifiedToken } from './types.js';
 import { type Verifiers } from './verifier.js';
 export type VerifyTokenOptions = TimeValidationOptions & {
     verifiers?: Verifiers;
@@ -16,7 +16,7 @@ export type VerifyTokenOptions = TimeValidationOptions & {
      * capability's `aud` is the delegation next-hop rather than a service audience. An empty
      * array accepts no audience (every token is rejected).
      */
-    audience?: string | Array<string>;
+    audience?: DIDString | Array<DIDString>;
     /**
      * Accept unsigned (`alg:none`) tokens. Defaults to `false`.
      *

package/lib/token.js

@@ -11,6 +11,12 @@ const tokenTracer = createTracer('token');
 // `verifiedPublicKey` property but can never be a member of this set, so verification
 // is only ever skipped for objects produced by `verifyToken` itself.
 const verifiedTokens = new WeakSet();
+// The `data` string each verified token's signature was checked against, keyed off the object
+// rather than read back from it. `token.data` is a mutable property of that same object, so
+// comparing a recomputed header/payload against it is vacuous: code that mutates the payload can
+// re-derive `data` from the mutation and stay self-consistent. This map is not reachable from the
+// token, so the value captured at verification time is the one the re-bind compares against.
+const verifiedTokenData = new WeakMap();
 function assertAudienceValid(payload, audience) {
     if (audience == null) {
         return;
@@ -101,27 +107,43 @@ function assertUnsignedAllowed(allowUnsigned) {
         header: token.header
     });
 }
+// Whether `data` is a serialization of the token's current header and payload. It may use a
+// different JSON serialization of the same values; accept it only if it decodes to exactly those,
+// so the signed bytes can never be decoupled from the payload used for authorization.
+function matchesVerifiableData(token, data) {
+    if (data === `${b64uFromJSON(token.header)}.${b64uFromJSON(token.payload)}`) {
+        return true;
+    }
+    const parts = data.split('.');
+    if (parts.length !== 2) {
+        return false;
+    }
+    try {
+        return canonicalStringify(b64uToJSON(parts[0])) === canonicalStringify(token.header) && canonicalStringify(b64uToJSON(parts[1])) === canonicalStringify(token.payload);
+    } catch  {
+        // invalid base64url or JSON in data
+        return false;
+    }
+}
 function getVerifiableData(token) {
-    const recomputed = `${b64uFromJSON(token.header)}.${b64uFromJSON(token.payload)}`;
     const data = token.data;
-    if (data == null || data === recomputed) {
-        return recomputed;
-    }
-    // `data` may use a different JSON serialization of the same header and payload.
-    // Accept it only if it decodes to exactly the same values, so the signed bytes
-    // can never be decoupled from the payload used for authorization.
-    const parts = typeof data === 'string' ? data.split('.') : [];
-    if (parts.length === 2) {
-        try {
-            if (canonicalStringify(b64uToJSON(parts[0])) === canonicalStringify(token.header) && canonicalStringify(b64uToJSON(parts[1])) === canonicalStringify(token.payload)) {
-                return data;
-            }
-        } catch  {
-        // invalid base64url or JSON in data: fall through to the error below
-        }
+    if (data == null) {
+        return `${b64uFromJSON(token.header)}.${b64uFromJSON(token.payload)}`;
+    }
+    if (typeof data === 'string' && matchesVerifiableData(token, data)) {
+        return data;
     }
     throw new Error('Invalid token: data does not match header and payload');
 }
+// Re-bind an already-verified token to the bytes its signature was checked against. The `data`
+// comes from `verifiedTokenData`, never from the token, so a caller that mutates the payload
+// cannot make the check pass by re-deriving `token.data` alongside it.
+function assertVerifiedDataUnchanged(token) {
+    const data = verifiedTokenData.get(token);
+    if (data == null || !matchesVerifiableData(token, data)) {
+        throw new Error('Invalid token: data does not match header and payload');
+    }
+}
 async function verifyTokenInner(token, options = {}) {
     const { verifiers, resolver, cache, audience, allowUnsigned = false, ...timeOptions } = options;
     if (typeof token !== 'string') {
@@ -132,6 +154,10 @@ async function verifyTokenInner(token, options = {}) {
             return token;
         }
         if (isVerifiedToken(token)) {
+            // The signature was checked when this object entered `verifiedTokens`, but its payload may
+            // have been mutated in place since. Re-bind it to the signed bytes — cheap next to a
+            // signature verification, and enough to reject tampering.
+            assertVerifiedDataUnchanged(token);
             assertTimeClaimsValid(token.payload, timeOptions);
             assertAudienceValid(token.payload, audience);
             return token;
@@ -155,6 +181,7 @@ async function verifyTokenInner(token, options = {}) {
                 verifiedPublicKey
             };
             verifiedTokens.add(result);
+            verifiedTokenData.set(result, data);
             return result;
         }
         throw new Error('Unsupported token');
@@ -203,6 +230,7 @@ async function verifyTokenInner(token, options = {}) {
             verifiedPublicKey
         };
         verifiedTokens.add(result);
+        verifiedTokenData.set(result, data);
         return result;
     }
     throw new Error('Unsupported signature algorithm');

package/lib/types.d.ts

@@ -1,4 +1,5 @@
 import type { SignedHeader, SignedPayload, UnsignedHeader } from './schemas.js';
+export type DIDString = `did:${string}:${string}`;
 export type SignedToken<Payload extends Record<string, unknown> = Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>> = {
     data: string;
     header: SignedHeader & Header;

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@kokuin/token",
-  "version": "0.2.0",
-  "license": "MIT",
+  "version": "0.4.0",
   "description": "JWT signing and verification",
   "keywords": [
     "json",
@@ -15,38 +14,42 @@
     "url": "https://github.com/TairuFramework/kokuin",
     "directory": "packages/token"
   },
+  "license": "MIT",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*"
   ],
-  "sideEffects": false,
   "dependencies": {
     "@noble/ciphers": "^2.1.1",
-    "@noble/curves": "^2.0.1",
-    "@noble/hashes": "^2.0.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
     "@scure/base": "^2.2.0",
-    "@sozai/codec": "^0.2.0",
-    "@sozai/otel": "^0.2.0",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/otel": "^0.3.2",
     "@sozai/schema": "^0.1.1",
-    "@kokuin/otel": "^0.1.0"
+    "@kokuin/otel": "^0.3.0"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/sdk-trace-node": "^2.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
     "uint8arrays": "^6.1.1"
   },
+  "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",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }