@kokuin/token 0.2.0 → 0.3.0

package/lib/did.d.ts

@@ -37,3 +37,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

@@ -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.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');
@@ -268,11 +287,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 { 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';

package/lib/index.js

@@ -9,7 +9,7 @@
  *
  * @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 { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash } from './multibase.js';

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) {
@@ -104,6 +105,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 {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/token",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "JWT signing and verification",
   "keywords": [
@@ -31,9 +31,9 @@
     "@noble/hashes": "^2.0.0",
     "@scure/base": "^2.2.0",
     "@sozai/codec": "^0.2.0",
-    "@sozai/otel": "^0.2.0",
+    "@sozai/otel": "^0.3.0",
     "@sozai/schema": "^0.1.1",
-    "@kokuin/otel": "^0.1.0"
+    "@kokuin/otel": "^0.3.0"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.9.0",