@kokuin/token 0.4.0 → 0.5.0

package/lib/did.d.ts

@@ -1,15 +1,86 @@
 import type { DIDResolver } from './cache.js';
+import { type MethodRegistry } from './method.js';
 import type { DIDDoc } from './peer4.js';
 import type { SignatureAlgorithm } from './schemas.js';
 import type { DIDString } from './types.js';
-/** @internal */
+/**
+ * Multicodec prefixes per signature algorithm, following the `did:key` convention. Supported, not
+ * internal: `@kokuin/capability` builds the `cnf.kid` confirmation claim from this and
+ * {@link getAlgorithmAndPublicKey}, and `cnf.kid` is a published wire format third parties produce
+ * and read.
+ */
 export declare const CODECS: Record<SignatureAlgorithm, Uint8Array>;
-/** @internal */
+/**
+ * Split multicodec-prefixed key bytes into their algorithm and the raw public key, or `null` when
+ * the prefix names no algorithm this package knows.
+ *
+ * The decoder half of the `cnf.kid` wire format — see {@link CODECS}.
+ */
 export declare function getAlgorithmAndPublicKey(bytes: Uint8Array): [SignatureAlgorithm, Uint8Array] | null;
 /** @internal */
 export declare function getDID(codec: Uint8Array, publicKey: Uint8Array): DIDString;
-/** @internal */
+/**
+ * The signature algorithm and raw public key a `did:key` identifier carries. Throws when the string
+ * is not a `did:key`, its encoded form is implausibly long, or the codec names no supported
+ * algorithm.
+ *
+ * Supported, not internal: `@kumiai/mls` checks an MLS credential's key against the key its DID
+ * names, a comparison only this function makes correctly — the alternative is a second decoder in
+ * another repo whose failure mode is accepting a credential for the wrong key. Any other method
+ * resolves through a `DIDMethodResolver`; this is the self-contained case.
+ */
 export declare function getSignatureInfo(did: string): [SignatureAlgorithm, Uint8Array];
+/**
+ * The issuer could not be resolved to a usable signing key: no method, resolver, or registry entry
+ * turned `iss` into one — including a resolver that has no answer, throws, or answers with something
+ * unusable (an oversized document, or one not hashing to the DID asked for).
+ *
+ * Distinct from every other verification failure on purpose. An invalid signature or a bad `kid`
+ * means the issuer *was* resolved and the token is bad (positive evidence); this means nothing was
+ * learned either way, and a caller treating "could not check" as "checked and fine" fails open.
+ * `@kokuin/capability`'s revocation checker turns on this distinction, so it must be a type, not a
+ * message — text matching is how such a check regresses silently.
+ */
+export declare class UnresolvableIssuerError extends Error {
+    /**
+     * Identifies the error by value, not identity: within this package `instanceof` is exact, but a
+     * duplicated `@kokuin/token` in a consumer's tree would make a cross-copy `instanceof` false (which
+     * fails closed, so this is hardening). Consumers should use `isUnresolvableIssuerError`.
+     */
+    static get brand(): string;
+    /** The brand, readable from an instance — what `isUnresolvableIssuerError` matches on. */
+    get brand(): string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Whether a thrown value means the issuer could not be resolved.
+ *
+ * Prefer this to `instanceof UnresolvableIssuerError` across a package boundary: it matches on the
+ * brand, so it holds even if the thrower and the checker resolved different copies of this package.
+ */
+export declare function isUnresolvableIssuerError(value: unknown): value is UnresolvableIssuerError;
+/**
+ * A DID method resolved the issuer, and the token then named a key that issuer does not have. The
+ * counterpart of {@link UnresolvableIssuerError}: a `DIDMethodResolver` needs a way to say "resolved,
+ * and the token is bad" too, else `resolveIssuerWithDoc` wraps everything a method throws as
+ * unresolvable and an unauthenticated `kid` naming a real DID and an invented key reads as "could not
+ * check" rather than "checked, and bad". Throw it only for that; not knowing the DID at all is
+ * {@link UnresolvableIssuerError}.
+ */
+export declare class IssuerKeyNotFoundError extends Error {
+    /** @see UnresolvableIssuerError.brand — same reasoning, across the same package boundary. */
+    static get brand(): string;
+    /** The brand, readable from an instance — what `isIssuerKeyNotFoundError` matches on. */
+    get brand(): string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Whether a thrown value means the issuer resolved but does not have the key the token named.
+ *
+ * Prefer this to `instanceof IssuerKeyNotFoundError` across a package boundary, for the same
+ * reason as {@link isUnresolvableIssuerError}.
+ */
+export declare function isIssuerKeyNotFoundError(value: unknown): value is IssuerKeyNotFoundError;
 export type ResolveIssuerHeader = {
     kid?: string;
 };
@@ -22,16 +93,40 @@ export type ResolveIssuerWithDocResult = {
         doc: DIDDoc;
     };
 };
+/**
+ * Whether to resolve the issuer's *current* signing key or one it signed with in the past. `false`
+ * (default) asks {@link DIDMethodResolver.resolve} — the safe question, right for a live signer.
+ * `true` asks {@link DIDMethodResolver.resolveHistoric}, an explicit statement that the artefact was
+ * issued in the past and must survive key rotation. A resolver with no `resolveHistoric` **refuses**
+ * rather than falling back to `resolve`, which would be the permissive scan by another name.
+ */
+export type ResolveIssuerMode = {
+    historic?: boolean;
+};
+/** Params for {@link resolveIssuer} / {@link resolveIssuerWithDoc}. */
+export type ResolveIssuerParams = {
+    iss: string;
+    header?: ResolveIssuerHeader;
+    resolver?: DIDResolver;
+    methods?: MethodRegistry;
+    /** See {@link ResolveIssuerMode.historic}. */
+    historic?: boolean;
+};
 /**
  * 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.
+ *
+ * The `historic` param selects which question is asked of a `DIDMethodResolver` — see
+ * {@link ResolveIssuerMode}. It reaches only the method-registry branch: `did:key` carries its key
+ * in the identifier and a `did:peer:4` document is fixed by its own hash, so neither has a past key
+ * set distinct from its present one.
  */
-export declare function resolveIssuerWithDoc(iss: string, header?: ResolveIssuerHeader, resolver?: DIDResolver): Promise<ResolveIssuerWithDocResult>;
+export declare function resolveIssuerWithDoc({ iss, header, resolver, methods, historic, }: ResolveIssuerParams): 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]>;
+export declare function resolveIssuer({ iss, header, resolver, methods, historic, }: ResolveIssuerParams): 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.

package/lib/did.js

@@ -1,7 +1,13 @@
 import { base58 } from '@scure/base';
+import { findMethodResolver } from './method.js';
 import { decodeMultibase } from './multibase.js';
 import { assertDocWithinMaxSize, decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
-/** @internal */ export const CODECS = {
+/**
+ * Multicodec prefixes per signature algorithm, following the `did:key` convention. Supported, not
+ * internal: `@kokuin/capability` builds the `cnf.kid` confirmation claim from this and
+ * {@link getAlgorithmAndPublicKey}, and `cnf.kid` is a published wire format third parties produce
+ * and read.
+ */ export const CODECS = {
     ES256: new Uint8Array([
         128,
         36
@@ -28,7 +34,12 @@ function isCodecMatch(codec, bytes) {
     }
     return true;
 }
-/** @internal */ export function getAlgorithmAndPublicKey(bytes) {
+/**
+ * Split multicodec-prefixed key bytes into their algorithm and the raw public key, or `null` when
+ * the prefix names no algorithm this package knows.
+ *
+ * The decoder half of the `cnf.kid` wire format — see {@link CODECS}.
+ */ export function getAlgorithmAndPublicKey(bytes) {
     for (const [alg, codec] of Object.entries(CODECS)){
         if (isCodecMatch(codec, bytes)) {
             return [
@@ -47,7 +58,16 @@ function isCodecMatch(codec, bytes) {
     bytes.set(publicKey, codec.length);
     return `${PREFIX}${base58.encode(bytes)}`;
 }
-/** @internal */ export function getSignatureInfo(did) {
+/**
+ * The signature algorithm and raw public key a `did:key` identifier carries. Throws when the string
+ * is not a `did:key`, its encoded form is implausibly long, or the codec names no supported
+ * algorithm.
+ *
+ * Supported, not internal: `@kumiai/mls` checks an MLS credential's key against the key its DID
+ * names, a comparison only this function makes correctly — the alternative is a second decoder in
+ * another repo whose failure mode is accepting a credential for the wrong key. Any other method
+ * resolves through a `DIDMethodResolver`; this is the self-contained case.
+ */ export function getSignatureInfo(did) {
     if (!did.startsWith(PREFIX)) {
         throw new Error('Invalid DID format');
     }
@@ -67,11 +87,114 @@ function isCodecMatch(codec, bytes) {
     }
     return info;
 }
+const UNRESOLVABLE_ISSUER_BRAND = '@kokuin/token/UnresolvableIssuerError';
+/**
+ * The issuer could not be resolved to a usable signing key: no method, resolver, or registry entry
+ * turned `iss` into one — including a resolver that has no answer, throws, or answers with something
+ * unusable (an oversized document, or one not hashing to the DID asked for).
+ *
+ * Distinct from every other verification failure on purpose. An invalid signature or a bad `kid`
+ * means the issuer *was* resolved and the token is bad (positive evidence); this means nothing was
+ * learned either way, and a caller treating "could not check" as "checked and fine" fails open.
+ * `@kokuin/capability`'s revocation checker turns on this distinction, so it must be a type, not a
+ * message — text matching is how such a check regresses silently.
+ */ export class UnresolvableIssuerError extends Error {
+    /**
+   * Identifies the error by value, not identity: within this package `instanceof` is exact, but a
+   * duplicated `@kokuin/token` in a consumer's tree would make a cross-copy `instanceof` false (which
+   * fails closed, so this is hardening). Consumers should use `isUnresolvableIssuerError`.
+   */ static get brand() {
+        return UNRESOLVABLE_ISSUER_BRAND;
+    }
+    /** The brand, readable from an instance — what `isUnresolvableIssuerError` matches on. */ get brand() {
+        return UNRESOLVABLE_ISSUER_BRAND;
+    }
+    constructor(message, options){
+        super(message, options);
+        this.name = 'UnresolvableIssuerError';
+    }
+}
+/**
+ * Whether a thrown value means the issuer could not be resolved.
+ *
+ * Prefer this to `instanceof UnresolvableIssuerError` across a package boundary: it matches on the
+ * brand, so it holds even if the thrower and the checker resolved different copies of this package.
+ */ export function isUnresolvableIssuerError(value) {
+    return value instanceof Error && value.brand === UNRESOLVABLE_ISSUER_BRAND;
+}
+const ISSUER_KEY_NOT_FOUND_BRAND = '@kokuin/token/IssuerKeyNotFoundError';
+/**
+ * A DID method resolved the issuer, and the token then named a key that issuer does not have. The
+ * counterpart of {@link UnresolvableIssuerError}: a `DIDMethodResolver` needs a way to say "resolved,
+ * and the token is bad" too, else `resolveIssuerWithDoc` wraps everything a method throws as
+ * unresolvable and an unauthenticated `kid` naming a real DID and an invented key reads as "could not
+ * check" rather than "checked, and bad". Throw it only for that; not knowing the DID at all is
+ * {@link UnresolvableIssuerError}.
+ */ export class IssuerKeyNotFoundError extends Error {
+    /** @see UnresolvableIssuerError.brand — same reasoning, across the same package boundary. */ static get brand() {
+        return ISSUER_KEY_NOT_FOUND_BRAND;
+    }
+    /** The brand, readable from an instance — what `isIssuerKeyNotFoundError` matches on. */ get brand() {
+        return ISSUER_KEY_NOT_FOUND_BRAND;
+    }
+    constructor(message, options){
+        super(message, options);
+        this.name = 'IssuerKeyNotFoundError';
+    }
+}
+/**
+ * Whether a thrown value means the issuer resolved but does not have the key the token named.
+ *
+ * Prefer this to `instanceof IssuerKeyNotFoundError` across a package boundary, for the same
+ * reason as {@link isUnresolvableIssuerError}.
+ */ export function isIssuerKeyNotFoundError(value) {
+    return value instanceof Error && value.brand === ISSUER_KEY_NOT_FOUND_BRAND;
+}
 /**
  * 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) {
+ *
+ * The `historic` param selects which question is asked of a `DIDMethodResolver` — see
+ * {@link ResolveIssuerMode}. It reaches only the method-registry branch: `did:key` carries its key
+ * in the identifier and a `did:peer:4` document is fixed by its own hash, so neither has a past key
+ * set distinct from its present one.
+ */ export async function resolveIssuerWithDoc({ iss, header = {}, resolver, methods, historic = false }) {
+    if (methods != null) {
+        const methodResolver = findMethodResolver(methods, iss);
+        if (methodResolver != null) {
+            // The historic question is answered only by `resolveHistoric`; a resolver without one is not
+            // asked `resolve` instead, which would substitute a different question. `UnresolvableIssuerError`
+            // is right — nothing was learned either way, which a fail-closed caller treats as a denial.
+            if (historic && methodResolver.resolveHistoric == null) {
+                throw new UnresolvableIssuerError(`DID method ${methodResolver.method} cannot resolve historic keys: ${iss}`);
+            }
+            // A method resolver throws its own error strings; re-type them so a method-backed resolution
+            // failure is indistinguishable from the built-in ones below. Message preserved, original kept
+            // as `cause`.
+            let resolved;
+            try {
+                // Called as a method of its own resolver, not detached: an implementation may be a class with
+                // private state.
+                resolved = historic && methodResolver.resolveHistoric != null ? await methodResolver.resolveHistoric(iss, header) : await methodResolver.resolve(iss, header);
+            } catch (cause) {
+                // Except the one failure that is not a failure to resolve: "I have this issuer, it has no such
+                // key" is what the `kid` branches below report for `did:peer:4` (ordinary errors — see
+                // IssuerKeyNotFoundError). Wrapping it would let an unauthenticated header make any issuer read
+                // as unresolvable, which callers fail closed on.
+                if (isIssuerKeyNotFoundError(cause)) {
+                    throw cause;
+                }
+                throw new UnresolvableIssuerError(cause instanceof Error ? cause.message : `Unknown DID: ${iss}`, {
+                    cause
+                });
+            }
+            return {
+                alg: resolved.alg,
+                publicKey: resolved.publicKey
+            };
+        }
+    }
     if (isPeer4(iss)) {
         const shortForm = getPeer4ShortForm(iss);
         if (iss !== shortForm) {
@@ -87,16 +210,36 @@ function isCodecMatch(codec, bytes) {
             };
         }
         if (resolver == null) {
-            throw new Error(`Unknown DID: ${shortForm}`);
+            throw new UnresolvableIssuerError(`Unknown DID: ${shortForm}`);
+        }
+        // Throwing is the normal style for a network-backed resolver, so one that throws must be
+        // indistinguishable from one that returns nothing — else the fail-closed guarantee holds only for
+        // resolvers that signal failure by returning `undefined`.
+        let doc;
+        try {
+            doc = await resolver(shortForm);
+        } catch (cause) {
+            throw new UnresolvableIssuerError(`Unknown DID: ${shortForm}`, {
+                cause
+            });
         }
-        const doc = await resolver(shortForm);
         if (doc == null) {
-            throw new Error(`Unknown DID: ${shortForm}`);
+            throw new UnresolvableIssuerError(`Unknown DID: ${shortForm}`);
+        }
+        // An unusable answer — oversized, or not hashing to the DID asked for — counts as unresolvable,
+        // not an ordinary fault: else a caller failing closed solely on `UnresolvableIssuerError` takes a
+        // broken or lying resolver as "not revoked". No availability cost worth weighing — a resolver
+        // willing to lie about documents already controls resolution completely.
+        try {
+            assertDocWithinMaxSize(doc);
+        } catch (cause) {
+            throw new UnresolvableIssuerError(cause instanceof Error ? cause.message : `Unknown DID: ${shortForm}`, {
+                cause
+            });
         }
-        assertDocWithinMaxSize(doc);
         const expected = encodePeer4(doc).shortForm;
         if (expected !== shortForm) {
-            throw new Error('DIDResolver: short form/doc hash mismatch');
+            throw new UnresolvableIssuerError('DIDResolver: short form/doc hash mismatch');
         }
         const [alg, publicKey] = resolveKidOrAuth(doc, header.kid);
         return {
@@ -108,16 +251,30 @@ function isCodecMatch(codec, bytes) {
             }
         };
     }
+    // `iss` narrows to `never` here (isPeer4's `value is string` collapses the false case), so route
+    // the prefix check through a helper taking an unnarrowed `string`.
+    if (!hasKeyPrefix(iss)) {
+        throw new UnresolvableIssuerError(`Unknown DID: ${iss}`);
+    }
     const [alg, publicKey] = getSignatureInfo(iss);
     return {
         alg,
         publicKey
     };
 }
+function hasKeyPrefix(did) {
+    return did.startsWith(PREFIX);
+}
 /**
  * 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);
+ */ export async function resolveIssuer({ iss, header = {}, resolver, methods, historic = false }) {
+    const { alg, publicKey } = await resolveIssuerWithDoc({
+        iss,
+        header,
+        resolver,
+        methods,
+        historic
+    });
     return [
         alg,
         publicKey

package/lib/identity.d.ts

@@ -23,11 +23,10 @@ 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>;
+export type KeyAgreementIdentity = Identity & {
     agreeKey(ephemeralPublicKey: Uint8Array): Promise<Uint8Array>;
 };
-export type FullIdentity = SigningIdentity & DecryptingIdentity;
+export type FullIdentity = SigningIdentity & KeyAgreementIdentity;
 export type OwnIdentity = FullIdentity & {
     privateKey: Uint8Array;
 };
@@ -35,20 +34,40 @@ 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 isKeyAgreementIdentity(identity: Identity): identity is KeyAgreementIdentity;
 export declare function isFullIdentity(identity: Identity): identity is FullIdentity;
 export declare function isOwnIdentity(identity: Identity): identity is OwnIdentity;
+/**
+ * Create a signing identity for an Ed25519 private key under a caller-supplied DID.
+ *
+ * `createSigningIdentity` derives the DID *from* the key, which only works for `did:key`. A method
+ * whose identifier is not a function of the current key — `did:kokuin:`, where the key rotates under
+ * a fixed inception digest — must supply its own `id`, so `iss` is the method's DID, not the key's
+ * `did:key`. The caller owns the pairing: nothing here checks `id` resolves to `privateKey`'s public
+ * key, and a mismatch produces tokens that verify nowhere.
+ */
+export declare function createSigningIdentityForDID(id: DIDString, privateKey: Uint8Array): SigningIdentity;
 /**
  * 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.
+ * Create a key-agreement identity from an Ed25519 private key.
  * Uses X25519 key derivation for ECDH key agreement.
  */
-export declare function createDecryptingIdentity(privateKey: Uint8Array): DecryptingIdentity;
+export declare function createKeyAgreementIdentity(privateKey: Uint8Array): KeyAgreementIdentity;
+/**
+ * A key-agreement identity for a **raw X25519 private key** under a caller-supplied DID.
+ *
+ * The counterpart of {@link createSigningIdentityForDID} for the agreement half. Two differences from
+ * {@link createKeyAgreementIdentity}: the identifier is supplied (a `did:kokuin:` key rotates under a
+ * fixed inception digest, so `id` cannot be a function of the key), and the input is the X25519 scalar
+ * itself rather than an Ed25519 key to Montgomery-convert — a controller derives an independent
+ * agreement keypair, not the Montgomery form of its signing key.
+ */
+export declare function createKeyAgreementIdentityForDID(id: DIDString, x25519PrivateKey: Uint8Array): KeyAgreementIdentity;
 /**
- * Create a full identity (signing + decrypting) from an Ed25519 private key.
+ * Create a full identity (signing + key agreement) from an Ed25519 private key.
  */
 export declare function createFullIdentity(privateKey: Uint8Array): FullIdentity;
 /**
@@ -93,7 +112,6 @@ export type MultiKeyIdentity = {
     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>;
 };
 /**

package/lib/identity.js

@@ -3,7 +3,6 @@ import { ed25519, x25519 } from '@noble/curves/ed25519.js';
 import { b64uFromJSON, fromUTF, toB64U } from '@sozai/codec';
 import { 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';
@@ -11,20 +10,29 @@ 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 isKeyAgreementIdentity(identity) {
+    return 'agreeKey' in identity && typeof identity.agreeKey === 'function';
 }
 export function isFullIdentity(identity) {
-    return isSigningIdentity(identity) && isDecryptingIdentity(identity);
+    return isSigningIdentity(identity) && isKeyAgreementIdentity(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);
+ * Create a signing identity for an Ed25519 private key under a caller-supplied DID.
+ *
+ * `createSigningIdentity` derives the DID *from* the key, which only works for `did:key`. A method
+ * whose identifier is not a function of the current key — `did:kokuin:`, where the key rotates under
+ * a fixed inception digest — must supply its own `id`, so `iss` is the method's DID, not the key's
+ * `did:key`. The caller owns the pairing: nothing here checks `id` resolves to `privateKey`'s public
+ * key, and a mismatch produces tokens that verify nowhere.
+ */ export function createSigningIdentityForDID(id, privateKey) {
+    return buildSigningIdentity(id, privateKey, ed25519.getPublicKey(privateKey));
+}
+// Shared body. Takes `publicKey` rather than deriving it, so `createSigningIdentity` — which
+// needs the public key anyway to build the `did:key` — derives it once instead of twice.
+function buildSigningIdentity(id, privateKey, publicKey) {
     async function signToken(payload, options = {}) {
         return withSpan(tracer, KokuinSpanNames.TOKEN_SIGN, {
             attributes: {
@@ -60,36 +68,51 @@ export function isOwnIdentity(identity) {
     };
 }
 /**
- * Create a decrypting identity from an Ed25519 private key.
+ * Create a signing identity from an Ed25519 private key.
+ */ export function createSigningIdentity(privateKey) {
+    const publicKey = ed25519.getPublicKey(privateKey);
+    return buildSigningIdentity(getDID(CODECS.EdDSA, publicKey), privateKey, publicKey);
+}
+/**
+ * Create a key-agreement identity from an Ed25519 private key.
  * Uses X25519 key derivation for ECDH key agreement.
- */ export function createDecryptingIdentity(privateKey) {
+ */ export function createKeyAgreementIdentity(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.
+ * A key-agreement identity for a **raw X25519 private key** under a caller-supplied DID.
+ *
+ * The counterpart of {@link createSigningIdentityForDID} for the agreement half. Two differences from
+ * {@link createKeyAgreementIdentity}: the identifier is supplied (a `did:kokuin:` key rotates under a
+ * fixed inception digest, so `id` cannot be a function of the key), and the input is the X25519 scalar
+ * itself rather than an Ed25519 key to Montgomery-convert — a controller derives an independent
+ * agreement keypair, not the Montgomery form of its signing key.
+ */ export function createKeyAgreementIdentityForDID(id, x25519PrivateKey) {
+    async function agreeKey(ephemeralPublicKey) {
+        return x25519.getSharedSecret(x25519PrivateKey, ephemeralPublicKey);
+    }
+    return {
+        id,
+        agreeKey
+    };
+}
+/**
+ * Create a full identity (signing + key agreement) from an Ed25519 private key.
  */ export function createFullIdentity(privateKey) {
     const signing = createSigningIdentity(privateKey);
-    const decrypting = createDecryptingIdentity(privateKey);
+    const keyAgreement = createKeyAgreementIdentity(privateKey);
     return {
         ...signing,
-        ...decrypting
+        ...keyAgreement
     };
 }
 /**
@@ -217,14 +240,15 @@ function signWith(key, data) {
  *
  * 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.
+ * so it must derive the matching secret the same way, exactly as `createKeyAgreementIdentity` does.
  */ function pickAgreementSecret(keys, isPeer, kid) {
     if (kid != null) {
         // 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.
+        // agreeKey(epk) succeeds — a known asymmetry, currently unreachable: decryptToken
+        // (@kokuin/jwe) never passes a kid, and KeyAgreementIdentity#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') {
@@ -291,14 +315,6 @@ function buildIdentity(id, longForm, doc, keys) {
     async function agreeKey(ephemeralPublicKey, kid) {
         return x25519.getSharedSecret(pickAgreementSecret(keys, isPeer, kid), ephemeralPublicKey);
     }
-    async function decrypt(jwe) {
-        pickAgreementSecret(keys, isPeer); // fail fast when this identity cannot agree at all
-        return decryptToken({
-            id,
-            decrypt,
-            agreeKey
-        }, jwe);
-    }
     return {
         id,
         longForm,
@@ -307,7 +323,6 @@ function buildIdentity(id, longForm, doc, keys) {
         publicKey: primarySig.publicKey,
         privateKey: primarySig.privateKey,
         signToken,
-        decrypt,
         agreeKey
     };
 }

package/lib/index.d.ts

@@ -10,14 +10,12 @@
  * @module token
  */
 export { type CreateInMemoryDIDCacheOptions, createInMemoryDIDCache, type DIDCache, type DIDResolver, } from './cache.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, SharedSecretResult, TokenEncrypter, UnwrapOptions, UnwrappedEnvelope, WrapOptions, } from './jwe.js';
-export { concatKDF, createTokenEncrypter, decryptToken, deriveSharedSecret, encryptToken, unwrapEnvelope, wrapEnvelope, } from './jwe.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerMode, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, UnresolvableIssuerError, } from './did.js';
+export { type CreateIdentityInput, createFullIdentity, createIdentity, createKeyAgreementIdentity, createKeyAgreementIdentityForDID, createSigningIdentity, createSigningIdentityForDID, type FullIdentity, type Identity, type IdentityKeySpec, type IdentityProvider, isFullIdentity, isKeyAgreementIdentity, isOwnIdentity, isSigningIdentity, type KeyAgreementIdentity, type KeyAlg, type KeyPurpose, type MultiKeyIdentity, type OwnIdentity, type ResolvedKey, randomIdentity, type SigningIdentity, type SignTokenOptions, } from './identity.js';
 export type { KeyEntry, KeyStore, MutableKeyEntry } from './keystore.js';
+export { type AgreementAlgorithm, type DIDMethodResolver, findMethodResolver, type MethodRegistry, type ResolvedAgreementKey, type ResolvedSigningKey, } from './method.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';

package/lib/index.js

@@ -9,12 +9,11 @@
  *
  * @module token
  */ export { createInMemoryDIDCache } from './cache.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, deriveSharedSecret, encryptToken, unwrapEnvelope, wrapEnvelope } from './jwe.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, resolveIssuer, resolveIssuerWithDoc, UnresolvableIssuerError } from './did.js';
+export { createFullIdentity, createIdentity, createKeyAgreementIdentity, createKeyAgreementIdentityForDID, createSigningIdentity, createSigningIdentityForDID, isFullIdentity, isKeyAgreementIdentity, isOwnIdentity, isSigningIdentity, randomIdentity } from './identity.js';
+export { findMethodResolver } from './method.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';