@kokuin/token 0.3.0 → 0.5.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,14 +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';
-/** @internal */
+import type { DIDString } from './types.js';
+/**
+ * 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): string;
-/** @internal */
+export declare function getDID(codec: Uint8Array, publicKey: Uint8Array): DIDString;
+/**
+ * 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;
 };
@@ -21,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 [
@@ -45,9 +56,18 @@ 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) {
+/**
+ * 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

@@ -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;
 };
@@ -20,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;
 };
@@ -32,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;
 /**
@@ -83,14 +105,13 @@ export type ResolvedKey = {
     publicKey: Uint8Array;
 };
 export type MultiKeyIdentity = {
-    id: string;
-    longForm: string;
+    id: DIDString;
+    longForm: DIDString;
     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>;
 };
 /**

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') {
@@ -256,7 +280,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.
@@ -289,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,
@@ -305,7 +323,6 @@ function buildIdentity(id, longForm, doc, keys) {
         publicKey: primarySig.publicKey,
         privateKey: primarySig.privateKey,
         signToken,
-        decrypt,
         agreeKey
     };
 }