@kokuin/token 0.4.0 → 0.5.0

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/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,5 +1,6 @@
 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 { DIDString, SignedToken, Token, UnsignedToken, VerifiedToken } from './types.js';
@@ -8,6 +9,13 @@ 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
@@ -17,6 +25,18 @@ export type VerifyTokenOptions = TimeValidationOptions & {
      * array accepts no audience (every token is rejected).
      */
     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

@@ -17,6 +17,11 @@ const verifiedTokens = new WeakSet();
 // 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;
@@ -44,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);
@@ -145,7 +156,7 @@ function assertVerifiedDataUnchanged(token) {
     }
 }
 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);
@@ -153,7 +164,10 @@ 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.
@@ -171,7 +185,9 @@ async function verifyTokenInner(token, options = {}) {
                 data,
                 verifiers,
                 resolver,
-                cache
+                cache,
+                methods,
+                historic
             });
             assertTimeClaimsValid(token.payload, timeOptions);
             assertAudienceValid(token.payload, audience);
@@ -182,6 +198,9 @@ async function verifyTokenInner(token, options = {}) {
             };
             verifiedTokens.add(result);
             verifiedTokenData.set(result, data);
+            if (historic === true) {
+                historicallyVerifiedTokens.add(result);
+            }
             return result;
         }
         throw new Error('Unsupported token');
@@ -218,7 +237,9 @@ async function verifyTokenInner(token, options = {}) {
             data,
             verifiers,
             resolver,
-            cache
+            cache,
+            methods,
+            historic
         });
         assertTimeClaimsValid(payload, timeOptions);
         assertAudienceValid(payload, audience);
@@ -231,6 +252,9 @@ async function verifyTokenInner(token, options = {}) {
         };
         verifiedTokens.add(result);
         verifiedTokenData.set(result, data);
+        if (historic === true) {
+            historicallyVerifiedTokens.add(result);
+        }
         return result;
     }
     throw new Error('Unsupported signature algorithm');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/token",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "JWT signing and verification",
   "keywords": [
     "json",
@@ -26,10 +26,9 @@
     "lib/*"
   ],
   "dependencies": {
-    "@noble/ciphers": "^2.1.1",
     "@noble/curves": "^2.3.0",
     "@noble/hashes": "^2.3.0",
-    "@scure/base": "^2.2.0",
+    "@scure/base": "^2.3.0",
     "@sozai/codec": "^0.4.0",
     "@sozai/otel": "^0.3.2",
     "@sozai/schema": "^0.1.1",

package/lib/jwe.d.ts

@@ -1,106 +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';
-};
-export type SharedSecretResult = {
-    /**
-     * The raw X25519 ECDH output. **Not** uniformly random — run it through a KDF with your own
-     * domain separation before using it as a key.
-     */
-    sharedSecret: Uint8Array;
-    /**
-     * Send this to the recipient. They recover the same `sharedSecret` bytes with
-     * `identity.agreeKey(ephemeralPublicKey)`.
-     */
-    ephemeralPublicKey: Uint8Array;
-};
-/**
- * Concat KDF per RFC 7518 Section 4.6.2.
- * Single SHA-256 iteration (sufficient for 256-bit keys).
- */
-export declare function concatKDF(params: ConcatKDFParams): Uint8Array;
-/**
- * Perform X25519 key agreement with a recipient DID, without building a JWE.
- *
- * Resolves the recipient's agreement key by the same rule `createTokenEncrypter` uses — a
- * did:peer:4 identity's published `keyAgreement` key, or an EdDSA `did:key`'s birationally
- * derived one — generates a single-use ephemeral key pair, and returns the ECDH output.
- * The ephemeral private key never leaves this function.
- *
- * The recipient recovers the identical bytes with `identity.agreeKey(ephemeralPublicKey)` —
- * called with no `kid`; the sender always resolves the first published `keyAgreement` key, and
- * on a multi-KEM identity a different `kid` silently recovers different bytes.
- *
- * The agreement is anonymous — it authenticates nothing about the sender, only that the secret
- * is recoverable by the recipient. Bind `ephemeralPublicKey` and the recipient DID into your
- * KDF's info/context.
- *
- * ```ts
- * const { sharedSecret, ephemeralPublicKey } = deriveSharedSecret(recipientDID)
- * // ship ephemeralPublicKey alongside whatever the secret protects
- * ```
- *
- * The result is a raw ECDH output, not a key: run it through a KDF before use.
- *
- * @param recipient a `did:key` EdDSA DID, or a `did:peer:4` **long form**. A peer:4 short form
- *   throws — the document that carries the agreement key lives only in the long form.
- */
-export declare function deriveSharedSecret(recipient: string): SharedSecretResult;
-/**
- * Create a token encrypter for a recipient identified by X25519 public key or DID string.
- */
-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>;