@kokuin/token 0.3.0 → 0.5.0

package/lib/index.d.ts

@@ -10,18 +10,16 @@
  * @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, TokenEncrypter, UnwrapOptions, UnwrappedEnvelope, WrapOptions, } from './jwe.js';
-export { concatKDF, createTokenEncrypter, decryptToken, 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';
 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,15 +9,14 @@
  *
  * @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, 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';
 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/method.d.ts

@@ -0,0 +1,70 @@
+import type { ResolveIssuerHeader } from './did.js';
+import type { SignatureAlgorithm } from './schemas.js';
+/** The signing key a DID method resolved for a given issuer and header. */
+export type ResolvedSigningKey = {
+    alg: SignatureAlgorithm;
+    publicKey: Uint8Array;
+};
+export type AgreementAlgorithm = 'X25519';
+/** A key agreement key a DID method resolved for a recipient. */
+export type ResolvedAgreementKey = {
+    alg: AgreementAlgorithm;
+    publicKey: Uint8Array;
+};
+/**
+ * A DID method this package can resolve `iss` through without importing its implementation.
+ *
+ * Methods whose document is a projection of an event log — `did:kokuin:` — cannot be resolved
+ * from the identifier alone and cannot be linked from here without a dependency cycle:
+ * `@kokuin/controller` depends on this package for signing. Injecting the resolver keeps the
+ * dependency one-way.
+ */
+export type DIDMethodResolver = {
+    /** The method segment, without `did:` and without the trailing colon. E.g. `kokuin`. */
+    method: string;
+    /**
+     * The key this subject signs with **now** — its head keys, nothing rotated away. The safe default:
+     * authenticating a live signer asks whether *this* party can sign today, so a retired key must not
+     * answer yes. {@link resolveHistoric} is the other question.
+     */
+    resolve(did: string, header: ResolveIssuerHeader): Promise<ResolvedSigningKey>;
+    /**
+     * The key this subject signed with **at some point in the past**, for verifying an artefact it has
+     * already issued — the explicit opt-in half of the split. It accepts a key the subject may have
+     * rotated away *because it was compromised*, so the answer is "did once hold", never "holds". Use it
+     * only for past-minted material that must survive routine key hygiene (a capability, a revocation
+     * record, an archived grant), never to authenticate a live signer.
+     *
+     * A method whose key set never changes may alias it to {@link resolve}. Optional, so a resolver
+     * written before this member typechecks, but its **absence fails closed**: `resolveIssuerWithDoc`
+     * refuses rather than falling back to {@link resolve}, which would answer a different question. A
+     * method that can retire keys must implement it — including a *wrapper* around one that does.
+     */
+    resolveHistoric?(did: string, header: ResolveIssuerHeader): Promise<ResolvedSigningKey>;
+    /**
+     * Resolve the recipient's key agreement key set, in the method's order. Every entry with its
+     * algorithm rather than one chosen key: the set is an OR set, and selection belongs to the
+     * encrypting package. Optional: a method with no key agreement omits it.
+     */
+    resolveAgreementKey?(did: string): Promise<Array<ResolvedAgreementKey>>;
+    /**
+     * What this subject has revoked: no capability whose `aud` is in the set is valid. Entries are DIDs,
+     * but a wider vocabulary may add others — `did:kokuin:` also denies its own signing keys, spelled
+     * `#<key>` — so a reader must **match, never enumerate**. A DID and a key fragment cannot collide.
+     *
+     * Answer for **now**, not any position a token names: a capability's claims are backdatable, so an
+     * anchored check would let the holder pick a moment before it was revoked. A subject that cannot be
+     * resolved must reject, never answer the empty set (which reads as "nobody revoked").
+     *
+     * Optional, but unlike `resolveAgreementKey` its absence **disables enforcement** for every subject
+     * of this method, silently and in the passing direction. So a method with no revocation concept
+     * omits it, and **a method that can revoke must implement it — including a *wrapper*** (one
+     * forwarding only `resolve` type-checks and turns every denial into a pass). It rides this registry
+     * so a caller who wired resolution cannot separately forget enforcement; requiring it here would
+     * break every implementation for a member most methods have no answer for.
+     */
+    resolveDenySet?(did: string): Promise<ReadonlySet<string>>;
+};
+export type MethodRegistry = ReadonlyArray<DIDMethodResolver>;
+/** Total: a malformed DID yields `undefined` rather than throwing. */
+export declare function findMethodResolver(registry: MethodRegistry, did: string): DIDMethodResolver | undefined;

package/lib/method.js

@@ -0,0 +1,8 @@
+/** Total: a malformed DID yields `undefined` rather than throwing. */ export function findMethodResolver(registry, did) {
+    const parts = did.split(':');
+    if (parts.length < 3 || parts[0] !== 'did') {
+        return undefined;
+    }
+    const method = parts[1];
+    return registry.find((entry)=>entry.method === method);
+}

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/schemas.d.ts

@@ -10,7 +10,13 @@ export declare const signatureAlgorithmSchema: {
 export type SignatureAlgorithm = FromSchema<typeof signatureAlgorithmSchema>;
 /** @internal */
 export declare const validateAlgorithm: import("@sozai/schema").Validator<"EdDSA" | "ES256">;
-/** @internal */
+/**
+ * The header of a signed token.
+ *
+ * Supported rather than internal: `@enkaku/protocol` composes its own message schemas out of this,
+ * `unsignedHeaderSchema` and `signedPayloadSchema` — a protocol built on kokuin tokens has to
+ * describe them in its own wire schema, and it cannot do that from a type alone.
+ */
 export declare const signedHeaderSchema: {
     readonly type: "object";
     readonly properties: {
@@ -38,7 +44,9 @@ export declare const validateSignedHeader: import("@sozai/schema").Validator<{
     alg: "EdDSA" | "ES256";
     typ: "JWT";
 }>;
-/** @internal */
+/**
+ * The header of an unsigned token. See {@link signedHeaderSchema} for why this is supported.
+ */
 export declare const unsignedHeaderSchema: {
     readonly type: "object";
     readonly properties: {
@@ -110,7 +118,12 @@ export declare const capabilitySchema: {
         };
     }];
 };
-/** @internal */
+/**
+ * The registered claims a signed token carries. `additionalProperties` is open, so a consumer
+ * spreads `properties` into its own object schema and concatenates `required`.
+ *
+ * Supported rather than internal — see {@link signedHeaderSchema}.
+ */
 export declare const signedPayloadSchema: {
     readonly type: "object";
     readonly properties: {
@@ -146,7 +159,12 @@ export declare const signedPayloadSchema: {
     readonly required: readonly ["iss"];
     readonly additionalProperties: true;
 };
-/** @internal */
+/**
+ * The registered claims of a signed token, inferred from {@link signedPayloadSchema}.
+ *
+ * Supported rather than internal, and the most widely used of these: it is what a consumer
+ * intersects its own payload type with to describe a token it issues or verifies.
+ */
 export type SignedPayload = FromSchema<typeof signedPayloadSchema>;
 /** @internal */
 export declare const validateSignedPayload: import("@sozai/schema").Validator<{

package/lib/schemas.js

@@ -8,7 +8,13 @@ import { createValidator } from '@sozai/schema';
     enum: SUPPORTED_ALGORITHMS
 };
 /** @internal */ export const validateAlgorithm = createValidator(signatureAlgorithmSchema);
-/** @internal */ export const signedHeaderSchema = {
+/**
+ * The header of a signed token.
+ *
+ * Supported rather than internal: `@enkaku/protocol` composes its own message schemas out of this,
+ * `unsignedHeaderSchema` and `signedPayloadSchema` — a protocol built on kokuin tokens has to
+ * describe them in its own wire schema, and it cannot do that from a type alone.
+ */ export const signedHeaderSchema = {
     type: 'object',
     properties: {
         typ: {
@@ -27,7 +33,9 @@ import { createValidator } from '@sozai/schema';
     additionalProperties: true
 };
 /** @internal */ export const validateSignedHeader = createValidator(signedHeaderSchema);
-/** @internal */ export const unsignedHeaderSchema = {
+/**
+ * The header of an unsigned token. See {@link signedHeaderSchema} for why this is supported.
+ */ export const unsignedHeaderSchema = {
     type: 'object',
     properties: {
         typ: {
@@ -65,7 +73,12 @@ import { createValidator } from '@sozai/schema';
         }
     ]
 };
-/** @internal */ export const signedPayloadSchema = {
+/**
+ * The registered claims a signed token carries. `additionalProperties` is open, so a consumer
+ * spreads `properties` into its own object schema and concatenates `required`.
+ *
+ * Supported rather than internal — see {@link signedHeaderSchema}.
+ */ export const signedPayloadSchema = {
     type: 'object',
     properties: {
         iss: {

package/lib/token.d.ts

@@ -1,13 +1,21 @@
 import type { DIDCache, DIDResolver } from './cache.js';
 import type { SigningIdentity } from './identity.js';
+import type { MethodRegistry } from './method.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;
     resolver?: DIDResolver;
     cache?: DIDCache;
+    /**
+     * DID methods that need external resolution to verify an issuer. `did:key` and `did:peer:4` need no
+     * entry (they carry their key in the identifier or document); a method whose key set is a projection
+     * of state held elsewhere — `did:kokuin:` — cannot be verified without one, and fails with `Unknown
+     * DID` when no registry is passed.
+     */
+    methods?: MethodRegistry;
     /**
      * Expected audience(s) for the token. When set, verification rejects a token whose `aud`
      * claim is not among the given value(s), and rejects unsigned / `alg:none` tokens outright
@@ -16,7 +24,19 @@ 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>;
+    /**
+     * Verify against a key the issuer has already rotated away, as well as its current ones. Defaults
+     * to `false` — the safe question: the signature must be from a key the issuer holds **now**, so a
+     * rotated-away (leaked) key mints nothing. Opting in asks whether the issuer held the key **at some
+     * point**, which a past-issued capability or revocation record needs to survive routine key hygiene.
+     *
+     * Set it only for a past-issued token that is not itself proof a live party holds a key. Not a
+     * compatibility switch: it is the difference between "a compromised key mints nothing" and "mints
+     * anything until the profile resets". A resolver with no `resolveHistoric` rejects with
+     * `UnresolvableIssuerError` rather than answering the current-key question.
+     */
+    historic?: boolean;
     /**
      * Accept unsigned (`alg:none`) tokens. Defaults to `false`.
      *
@@ -38,6 +58,9 @@ export type VerifySignedPayloadInput<Payload extends Record<string, unknown> = R
     verifiers?: Verifiers;
     resolver?: DIDResolver;
     cache?: DIDCache;
+    methods?: MethodRegistry;
+    /** See `VerifyTokenOptions.historic`. Defaults to `false` — the issuer's current keys only. */
+    historic?: boolean;
 };
 /**
  * Verify the signature of a signed payload and return the public key of the issuer.

package/lib/token.js

@@ -11,6 +11,17 @@ 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();
+// Tokens verified with `historic: true` — against a key the issuer has since rotated away.
+// Membership blocks the fast path: a later `verifyToken` without `historic` asks the stricter
+// question, and answering it from a weaker check is fail-open, so it re-verifies (which may pass).
+// The reverse needs nothing — a strict answer already implies the loose one.
+const historicallyVerifiedTokens = new WeakSet();
 function assertAudienceValid(payload, audience) {
     if (audience == null) {
         return;
@@ -38,16 +49,22 @@ function assertUnsignedAllowed(allowUnsigned) {
 /**
  * Verify the signature of a signed payload and return the public key of the issuer.
  */ export async function verifySignedPayload(input) {
-    const { signature, payload, header, data, verifiers, resolver, cache } = input;
+    const { signature, payload, header, data, verifiers, resolver, cache, methods, historic } = input;
     assertType(validateSignedPayload, payload);
     const effectiveResolver = cache == null ? resolver : async (did)=>{
         const cached = await cache.get(did);
         if (cached != null) return cached;
         return resolver != null ? resolver(did) : undefined;
     };
-    const { alg, publicKey, peer4Doc } = await resolveIssuerWithDoc(payload.iss, {
-        kid: header.kid
-    }, effectiveResolver);
+    const { alg, publicKey, peer4Doc } = await resolveIssuerWithDoc({
+        iss: payload.iss,
+        header: {
+            kid: header.kid
+        },
+        resolver: effectiveResolver,
+        methods,
+        historic
+    });
     const verify = getVerifier(alg, verifiers);
     const message = typeof data === 'string' ? fromUTF(data) : data;
     const verified = await verify(signature, message, publicKey);
@@ -101,29 +118,45 @@ 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;
+    const { verifiers, resolver, cache, methods, audience, allowUnsigned = false, historic, ...timeOptions } = options;
     if (typeof token !== 'string') {
         if (isUnsignedToken(token)) {
             assertSignedForAudience(audience);
@@ -131,7 +164,14 @@ async function verifyTokenInner(token, options = {}) {
             assertTimeClaimsValid(token.payload, timeOptions);
             return token;
         }
-        if (isVerifiedToken(token)) {
+        // The `historic` arm is what keeps the fast path from weakening the check: a token verified
+        // against a rotated-away key must not satisfy a later caller who asked for the issuer's current
+        // keys. It falls through to the full verification below rather than being rejected.
+        if (isVerifiedToken(token) && !(historic !== true && historicallyVerifiedTokens.has(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;
@@ -145,7 +185,9 @@ async function verifyTokenInner(token, options = {}) {
                 data,
                 verifiers,
                 resolver,
-                cache
+                cache,
+                methods,
+                historic
             });
             assertTimeClaimsValid(token.payload, timeOptions);
             assertAudienceValid(token.payload, audience);
@@ -155,6 +197,10 @@ async function verifyTokenInner(token, options = {}) {
                 verifiedPublicKey
             };
             verifiedTokens.add(result);
+            verifiedTokenData.set(result, data);
+            if (historic === true) {
+                historicallyVerifiedTokens.add(result);
+            }
             return result;
         }
         throw new Error('Unsupported token');
@@ -191,7 +237,9 @@ async function verifyTokenInner(token, options = {}) {
             data,
             verifiers,
             resolver,
-            cache
+            cache,
+            methods,
+            historic
         });
         assertTimeClaimsValid(payload, timeOptions);
         assertAudienceValid(payload, audience);
@@ -203,6 +251,10 @@ async function verifyTokenInner(token, options = {}) {
             verifiedPublicKey
         };
         verifiedTokens.add(result);
+        verifiedTokenData.set(result, data);
+        if (historic === true) {
+            historicallyVerifiedTokens.add(result);
+        }
         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.3.0",
-  "license": "MIT",
+  "version": "0.5.0",
   "description": "JWT signing and verification",
   "keywords": [
     "json",
@@ -15,38 +14,41 @@
     "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",
-    "@scure/base": "^2.2.0",
-    "@sozai/codec": "^0.2.0",
-    "@sozai/otel": "^0.3.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@scure/base": "^2.3.0",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/otel": "^0.3.2",
     "@sozai/schema": "^0.1.1",
     "@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"
   }
 }

package/lib/jwe.d.ts

@@ -1,67 +0,0 @@
-import type { DecryptingIdentity, SigningIdentity } from './identity.js';
-import type { Verifiers } from './verifier.js';
-export type ConcatKDFParams = {
-    sharedSecret: Uint8Array;
-    keyLength: number;
-    algorithmID: string;
-    partyUInfo: Uint8Array;
-    partyVInfo: Uint8Array;
-};
-export type JWEHeader = {
-    alg: string;
-    enc: string;
-    epk: {
-        kty: string;
-        crv: string;
-        x: string;
-    };
-    apu?: string;
-    apv?: string;
-};
-export type TokenEncrypter = {
-    recipientID?: string;
-    encrypt(plaintext: Uint8Array): Promise<string>;
-};
-export type EncryptOptions = {
-    algorithm: 'X25519';
-};
-/**
- * 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;
-/**
- * Create a token encrypter for a recipient identified by X25519 public key or DID string.
- */
-export declare function createTokenEncrypter(recipient: Uint8Array, options: EncryptOptions): TokenEncrypter;
-export declare function createTokenEncrypter(recipient: string): TokenEncrypter;
-/**
- * Encrypt plaintext to JWE compact serialization using the given encrypter.
- */
-export declare function encryptToken(encrypter: TokenEncrypter, plaintext: Uint8Array): Promise<string>;
-/**
- * Decrypt a JWE compact serialization string.
- */
-export declare function decryptToken(decrypter: DecryptingIdentity, jwe: string): Promise<Uint8Array>;
-export type EnvelopeMode = 'plain' | 'jws' | 'jws-in-jwe' | 'jwe-in-jws';
-export type UnwrappedEnvelope = {
-    payload: Record<string, unknown>;
-    mode: EnvelopeMode;
-};
-export type WrapOptions = {
-    signer?: SigningIdentity;
-    encrypter?: TokenEncrypter;
-    header?: Record<string, unknown>;
-};
-export type UnwrapOptions = {
-    decrypter?: DecryptingIdentity;
-    verifiers?: Verifiers;
-};
-/**
- * Wrap a payload into a token string according to the specified envelope mode.
- */
-export declare function wrapEnvelope(mode: EnvelopeMode, payload: Record<string, unknown>, options: WrapOptions): Promise<string>;
-/**
- * Unwrap a token string, auto-detecting the envelope mode from its structure.
- */
-export declare function unwrapEnvelope(message: string, options: UnwrapOptions): Promise<UnwrappedEnvelope>;