@kokuin/token 0.1.1 → 0.3.0

package/lib/did.d.ts

@@ -37,3 +37,12 @@ export declare function resolveIssuer(iss: string, header?: ResolveIssuerHeader,
  * All other DID methods pass through unchanged.
  */
 export declare function normalizeDID(did: string): string;
+/**
+ * The X25519 public key a DID document publishes for key agreement, or `null` when it
+ * publishes none.
+ *
+ * Unlike a `did:key` EdDSA identity — whose agreement key is *derived* from its signing key
+ * via the birational map — a peer:4 identity carries an independent agreement key in its doc.
+ * A sender MUST use the published key: the derived one is a different key and will not decrypt.
+ */
+export declare function getAgreementKey(doc: DIDDoc): Uint8Array | null;

package/lib/did.js

@@ -1,6 +1,6 @@
 import { base58 } from '@scure/base';
 import { decodeMultibase } from './multibase.js';
-import { decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
+import { assertDocWithinMaxSize, decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
 /** @internal */ export const CODECS = {
     ES256: new Uint8Array([
         128,
@@ -16,6 +16,9 @@ const EXPECTED_KEY_SIZES = {
     ES256: 33
 };
 const PREFIX = 'did:key:z';
+// ES256 is the largest supported did:key payload: a 2-byte codec plus a 33-byte key
+// encodes to 48 base58 characters. Bound before decoding — base58.decode is O(n^2).
+const MAX_DID_KEY_ENCODED = 64;
 function isCodecMatch(codec, bytes) {
     if (bytes.length < codec.length) return false;
     for(let i = 0; i < codec.length; i++){
@@ -48,7 +51,11 @@ function isCodecMatch(codec, bytes) {
     if (!did.startsWith(PREFIX)) {
         throw new Error('Invalid DID format');
     }
-    const bytes = base58.decode(did.slice(PREFIX.length));
+    const encoded = did.slice(PREFIX.length);
+    if (encoded.length > MAX_DID_KEY_ENCODED) {
+        throw new Error('Invalid DID format: key too large');
+    }
+    const bytes = base58.decode(encoded);
     const info = getAlgorithmAndPublicKey(bytes);
     if (info == null) {
         throw new Error('Unsupported DID signature codec');
@@ -86,6 +93,7 @@ function isCodecMatch(codec, bytes) {
         if (doc == null) {
             throw new Error(`Unknown DID: ${shortForm}`);
         }
+        assertDocWithinMaxSize(doc);
         const expected = encodePeer4(doc).shortForm;
         if (expected !== shortForm) {
             throw new Error('DIDResolver: short form/doc hash mismatch');
@@ -123,6 +131,17 @@ function resolveKidOrAuth(doc, kid) {
         }
         return resolveKidFromDoc(doc, auth[0]);
     }
+    // A kid must reference a method the subject authorized for `authentication`. Without this
+    // check a key listed only under `assertionMethod` (or any other relationship) could sign
+    // tokens. `KidNotFound` still takes precedence so a genuinely absent kid is reported as such.
+    const method = doc.verificationMethod.find((m)=>m.id === kid);
+    if (method == null) {
+        throw new Error(`KidNotFound: ${kid}`);
+    }
+    const auth = doc.authentication;
+    if (auth == null || !auth.includes(kid)) {
+        throw new Error(`resolveIssuer: kid ${kid} is not an authentication method`);
+    }
     return resolveKidFromDoc(doc, kid);
 }
 function resolveKidFromDoc(doc, kid) {
@@ -130,6 +149,9 @@ function resolveKidFromDoc(doc, kid) {
     if (method == null) {
         throw new Error(`KidNotFound: ${kid}`);
     }
+    if (method.publicKeyMultibase.length > MAX_DID_KEY_ENCODED) {
+        throw new Error('Invalid verification method: key too large');
+    }
     const bytes = decodeMultibase(method.publicKeyMultibase);
     const info = getAlgorithmAndPublicKey(bytes);
     if (info == null) {
@@ -144,3 +166,45 @@ function resolveKidFromDoc(doc, kid) {
  */ export function normalizeDID(did) {
     return isPeer4(did) ? getPeer4ShortForm(did) : did;
 }
+/** Multicodec prefix for an X25519 public key, as published in a peer:4 doc. */ const CODEC_X25519_PUB = new Uint8Array([
+    0xec,
+    0x01
+]);
+/**
+ * The X25519 public key a DID document publishes for key agreement, or `null` when it
+ * publishes none.
+ *
+ * Unlike a `did:key` EdDSA identity — whose agreement key is *derived* from its signing key
+ * via the birational map — a peer:4 identity carries an independent agreement key in its doc.
+ * A sender MUST use the published key: the derived one is a different key and will not decrypt.
+ */ export function getAgreementKey(doc) {
+    const fragments = doc.keyAgreement;
+    if (fragments == null) {
+        return null;
+    }
+    for (const fragment of fragments){
+        const method = doc.verificationMethod.find((verificationMethod)=>verificationMethod.id === fragment);
+        if (method == null) {
+            continue;
+        }
+        // Bound before decoding — base58.decode is O(n^2) — same as resolveKidFromDoc().
+        if (method.publicKeyMultibase.length > MAX_DID_KEY_ENCODED) {
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = decodeMultibase(method.publicKeyMultibase);
+        } catch  {
+            continue;
+        }
+        if (!isCodecMatch(CODEC_X25519_PUB, bytes)) {
+            continue;
+        }
+        const publicKey = bytes.slice(CODEC_X25519_PUB.length);
+        if (publicKey.length !== 32) {
+            continue;
+        }
+        return publicKey;
+    }
+    return null;
+}

package/lib/identity.js

@@ -212,18 +212,37 @@ function signWith(key, data) {
             throw new Error('X25519 cannot sign');
     }
 }
-function pickKemKey(keys, kid) {
+/**
+ * The X25519 private scalar this identity agrees with, for `kid` or by default.
+ *
+ * A peer:4 identity uses its published `keyAgreement` key. A `did:key` EdDSA identity has no
+ * published agreement key — a sender derives one from its signing key via the birational map —
+ * so it must derive the matching secret the same way, exactly as `createDecryptingIdentity` does.
+ */ function pickAgreementSecret(keys, isPeer, kid) {
     if (kid != null) {
-        const found = keys.find((k)=>k.fragment === kid);
+        // No birational fallback here, unlike the no-kid branch below: a kid names one specific
+        // key, so falling back to a *different*, derived key would silently agree with the wrong
+        // secret. This means a did:key identity's agreeKey(epk, '#key-0') throws where
+        // agreeKey(epk) succeeds — a known asymmetry, currently unreachable: decryptToken (jwe.ts)
+        // never passes a kid, and DecryptingIdentity#agreeKey has no kid parameter at all.
+        const found = keys.find((key)=>key.fragment === kid);
         if (found == null) throw new Error(`KidNotFound: ${kid}`);
         if (found.purpose !== 'kem' || found.alg !== 'X25519') {
             throw new Error(`Kid is not a KEM X25519 key: ${kid}`);
         }
-        return found;
+        return found.privateKey;
     }
-    const first = keys.find((k)=>k.purpose === 'kem' && k.alg === 'X25519');
-    if (first == null) throw new Error('No KEM key in identity');
-    return first;
+    const kem = keys.find((key)=>key.purpose === 'kem' && key.alg === 'X25519');
+    if (kem != null) {
+        return kem.privateKey;
+    }
+    if (!isPeer) {
+        const sig = keys.find((key)=>key.purpose === 'sig' && key.alg === 'EdDSA');
+        if (sig != null) {
+            return ed25519.utils.toMontgomerySecret(sig.privateKey);
+        }
+    }
+    throw new Error('No KEM key in identity');
 }
 function buildIdentity(id, longForm, doc, keys) {
     const primarySig = keys.find((k)=>k.purpose === 'sig');
@@ -268,11 +287,10 @@ function buildIdentity(id, longForm, doc, keys) {
         };
     }
     async function agreeKey(ephemeralPublicKey, kid) {
-        const key = pickKemKey(keys, kid);
-        return x25519.getSharedSecret(key.privateKey, ephemeralPublicKey);
+        return x25519.getSharedSecret(pickAgreementSecret(keys, isPeer, kid), ephemeralPublicKey);
     }
     async function decrypt(jwe) {
-        pickKemKey(keys);
+        pickAgreementSecret(keys, isPeer); // fail fast when this identity cannot agree at all
         return decryptToken({
             id,
             decrypt,

package/lib/index.d.ts

@@ -10,11 +10,11 @@
  * @module token
  */
 export { type CreateInMemoryDIDCacheOptions, createInMemoryDIDCache, type DIDCache, type DIDResolver, } from './cache.js';
-export { CODECS, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, } from './did.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, } from './did.js';
 export { type CreateIdentityInput, createDecryptingIdentity, createFullIdentity, createIdentity, createSigningIdentity, type DecryptingIdentity, type FullIdentity, type Identity, type IdentityKeySpec, type IdentityProvider, isDecryptingIdentity, isFullIdentity, isOwnIdentity, isSigningIdentity, type KeyAlg, type KeyPurpose, type MultiKeyIdentity, type OwnIdentity, type ResolvedKey, randomIdentity, type SigningIdentity, type SignTokenOptions, } from './identity.js';
 export type { ConcatKDFParams, EncryptOptions, EnvelopeMode, JWEHeader, TokenEncrypter, UnwrapOptions, UnwrappedEnvelope, WrapOptions, } from './jwe.js';
 export { concatKDF, createTokenEncrypter, decryptToken, encryptToken, unwrapEnvelope, wrapEnvelope, } from './jwe.js';
-export type { KeyEntry, KeyStore } from './keystore.js';
+export type { KeyEntry, KeyStore, MutableKeyEntry } from './keystore.js';
 export { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash, } from './multibase.js';
 export { type DecodePeer4Options, type DIDDoc, decodePeer4, encodePeer4, getPeer4ShortForm, isPeer4, type VerificationMethod, validateDIDDoc, } from './peer4.js';
 export { createRotationAssertion, type RotationPayload, } from './rotation.js';

package/lib/index.js

@@ -9,7 +9,7 @@
  *
  * @module token
  */ export { createInMemoryDIDCache } from './cache.js';
-export { CODECS, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, resolveIssuer, resolveIssuerWithDoc } from './did.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, normalizeDID, resolveIssuer, resolveIssuerWithDoc } from './did.js';
 export { createDecryptingIdentity, createFullIdentity, createIdentity, createSigningIdentity, isDecryptingIdentity, isFullIdentity, isOwnIdentity, isSigningIdentity, randomIdentity } from './identity.js';
 export { concatKDF, createTokenEncrypter, decryptToken, encryptToken, unwrapEnvelope, wrapEnvelope } from './jwe.js';
 export { decodeMultibase, encodeMultibase, multihashSHA256, verifyMultihash } from './multibase.js';

package/lib/jwe.js

@@ -3,7 +3,8 @@ import { randomBytes } from '@noble/ciphers/utils.js';
 import { ed25519, x25519 } from '@noble/curves/ed25519.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { b64uFromJSON, b64uToJSON, fromB64U, toB64U } from '@sozai/codec';
-import { getSignatureInfo } from './did.js';
+import { getAgreementKey, getSignatureInfo } from './did.js';
+import { decodePeer4, getPeer4ShortForm, isPeer4 } from './peer4.js';
 import { createUnsignedToken, isUnsignedToken, verifyToken } from './token.js';
 import { stringifyToken } from './utils.js';
 function uint32BE(value) {
@@ -104,6 +105,23 @@ function resolveX25519Key(recipient) {
             key: recipient
         };
     }
+    if (isPeer4(recipient)) {
+        const shortForm = getPeer4ShortForm(recipient);
+        if (recipient === shortForm) {
+            // The doc lives in the long form. Resolving a short form needs a DIDResolver, which
+            // this sync constructor cannot await — so say so, rather than failing as a bad DID.
+            throw new Error(`Cannot encrypt to a did:peer:4 short form: ${shortForm}. Pass the long form, which carries the document.`);
+        }
+        const { doc } = decodePeer4(recipient);
+        const key = getAgreementKey(doc);
+        if (key == null) {
+            throw new Error(`Recipient publishes no X25519 keyAgreement key: ${shortForm}`);
+        }
+        return {
+            key,
+            id: shortForm
+        };
+    }
     const [algorithm, publicKey] = getSignatureInfo(recipient);
     if (algorithm === 'EdDSA') {
         return {
@@ -235,7 +253,8 @@ export function createTokenEncrypter(recipient, options) {
     if (parts.length === 3) {
         // JWT: could be plain, jws, or jwe-in-jws
         const token = await verifyToken(message, {
-            verifiers: options.verifiers
+            verifiers: options.verifiers,
+            allowUnsigned: true
         });
         if (isUnsignedToken(token)) {
             return {

package/lib/keystore.d.ts

@@ -1,10 +1,71 @@
+/**
+ * A single key slot in a {@link KeyStore}, identified by `keyID`.
+ *
+ * This is the **read/provide** facet — the floor every backend can honor, including ones
+ * that derive keys rather than store them (HD) or never expose key material at all.
+ * A backend that can also write and delete implements {@link MutableKeyEntry}.
+ *
+ * ## Invariants
+ *
+ * Enforced by `keyStoreConformanceCases`. A backend that cannot satisfy these does not
+ * implement this type — it exposes a different surface instead.
+ *
+ * 1. **keyID round-trips.** `store.entry(x).keyID === x`, always.
+ * 2. **Absent means `null`.** {@link getAsync} resolves `null` when no key exists. Never
+ *    `undefined`, never a throw. A *derived* backend may never return `null` at all —
+ *    it can always produce a key — and that is contract-legal.
+ * 3. **{@link provideAsync} is idempotent under concurrency.** Two concurrent calls on one
+ *    keyID resolve to the *same* key. Never two keys; never a key that is generated,
+ *    returned to a caller, and then overwritten by a racer.
+ */
 export type KeyEntry<PrivateKeyType> = {
+    /** The keyID this entry was created for. Identical to the string passed to `entry()`. */
     readonly keyID: string;
+    /** The stored key, or `null` when none exists. Never `undefined`; never throws for absence. */
     getAsync(): Promise<PrivateKeyType | null>;
-    setAsync(privateKey: PrivateKeyType): Promise<void>;
+    /**
+     * The stored key, generating and persisting one if absent.
+     *
+     * Idempotent under concurrency: racing callers converge on a single key. Backends that
+     * share storage across processes need a cross-process lock to hold this (see `lockPath`
+     * on `NodeKeyStore` / `ElectronKeyStore`); an in-process promise chain is not enough.
+     */
     provideAsync(): Promise<PrivateKeyType>;
+};
+/**
+ * A {@link KeyEntry} on a backend that can also **write and delete** key material.
+ *
+ * HD and ledger backends deliberately do NOT implement this: an HD key is derived (there is
+ * nothing to set, and removing it does not stop it being derivable), and a ledger key never
+ * leaves the device. Previously they "conformed" by throwing from `setAsync` and silently
+ * no-op'ing `removeAsync` — the type now says what the substrate can do, so there is nothing
+ * to throw from.
+ */
+export type MutableKeyEntry<PrivateKeyType> = KeyEntry<PrivateKeyType> & {
+    /** Persist `privateKey` under this entry's keyID, replacing any existing key. */
+    setAsync(privateKey: PrivateKeyType): Promise<void>;
+    /** Delete this entry's key. Idempotent — removing an absent key resolves, it does not throw. */
     removeAsync(): Promise<void>;
 };
+/**
+ * A keyed collection of {@link KeyEntry}s.
+ *
+ * Parameterized by entry type, so a writable backend is `KeyStore<T, MutableKeyEntry<T>>`
+ * and a derived one is `KeyStore<T, KeyEntry<T>>`. No separate mutable store type is needed.
+ *
+ * Most consumers should NOT be generic over this — they should be generic over
+ * `IdentityProvider`, which is what "give me an identity for this keyID" actually needs.
+ * `KeyStore` is the *storage* contract, useful to backend authors and to the conformance
+ * suite. A backend whose key never leaves the device (ledger) implements `IdentityProvider`
+ * and neither storage type; that is the contract working, not a gap.
+ */
 export type KeyStore<PrivateKeyType, EntryType extends KeyEntry<PrivateKeyType> = KeyEntry<PrivateKeyType>> = {
+    /**
+     * The entry for `keyID`.
+     *
+     * Must be **cached**: `store.entry(x) === store.entry(x)`. Entries carry per-entry
+     * concurrency state (the `provideAsync` lock), so handing out a fresh entry per call
+     * silently defeats it.
+     */
     entry(keyID: string): EntryType;
 };

package/lib/keystore.js

@@ -1 +1,31 @@
-export { };
+/**
+ * A single key slot in a {@link KeyStore}, identified by `keyID`.
+ *
+ * This is the **read/provide** facet — the floor every backend can honor, including ones
+ * that derive keys rather than store them (HD) or never expose key material at all.
+ * A backend that can also write and delete implements {@link MutableKeyEntry}.
+ *
+ * ## Invariants
+ *
+ * Enforced by `keyStoreConformanceCases`. A backend that cannot satisfy these does not
+ * implement this type — it exposes a different surface instead.
+ *
+ * 1. **keyID round-trips.** `store.entry(x).keyID === x`, always.
+ * 2. **Absent means `null`.** {@link getAsync} resolves `null` when no key exists. Never
+ *    `undefined`, never a throw. A *derived* backend may never return `null` at all —
+ *    it can always produce a key — and that is contract-legal.
+ * 3. **{@link provideAsync} is idempotent under concurrency.** Two concurrent calls on one
+ *    keyID resolve to the *same* key. Never two keys; never a key that is generated,
+ *    returned to a caller, and then overwritten by a racer.
+ */ /**
+ * A keyed collection of {@link KeyEntry}s.
+ *
+ * Parameterized by entry type, so a writable backend is `KeyStore<T, MutableKeyEntry<T>>`
+ * and a derived one is `KeyStore<T, KeyEntry<T>>`. No separate mutable store type is needed.
+ *
+ * Most consumers should NOT be generic over this — they should be generic over
+ * `IdentityProvider`, which is what "give me an identity for this keyID" actually needs.
+ * `KeyStore` is the *storage* contract, useful to backend authors and to the conformance
+ * suite. A backend whose key never leaves the device (ledger) implements `IdentityProvider`
+ * and neither storage type; that is the contract working, not a gap.
+ */ export { };

package/lib/peer4.d.ts

@@ -81,9 +81,14 @@ export type DIDDoc = FromSchema<typeof didDocSchema>;
  */
 export declare function validateDIDDoc(value: unknown): value is DIDDoc;
 export type DecodePeer4Options = {
-    /** Maximum allowed size of the canonical doc bytes. Default 64 KB. */
+    /** Maximum allowed size of the canonical doc bytes. Default 4 KiB. */
     maxDocSize?: number;
 };
+/**
+ * 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.
+ */
+export declare function assertDocWithinMaxSize(doc: DIDDoc, maxSize?: number): void;
 /**
  * Check whether a value is a did:peer:4 identifier (either form).
  */

package/lib/peer4.js

@@ -78,7 +78,20 @@ const JSON_MULTICODEC = new Uint8Array([
     0x80,
     0x04
 ]);
-const DEFAULT_MAX_DOC_SIZE = 64 * 1024;
+const DEFAULT_MAX_DOC_SIZE = 4 * 1024;
+// 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'.
+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.
+ */ export function assertDocWithinMaxSize(doc, maxSize = DEFAULT_MAX_DOC_SIZE) {
+    const size = fromUTF(canonicalStringify(doc)).length;
+    if (size > maxSize) {
+        throw new Error(`did:peer:4 resolver doc too large: ${size} > ${maxSize}`);
+    }
+}
 /**
  * Check whether a value is a did:peer:4 identifier (either form).
  */ export function isPeer4(value) {
@@ -109,9 +122,14 @@ function startsWithJsonCodec(bytes) {
     }
     const hashEncoded = longForm.slice(PEER4_PREFIX.length, sep);
     const encodedDoc = longForm.slice(sep + 1);
+    // Both segments feed an O(n^2) base58 decode, so bound them before decoding.
+    if (hashEncoded.length > MAX_HASH_ENCODED) {
+        throw new Error('did:peer:4 hash too large');
+    }
     const maxSize = options.maxDocSize ?? DEFAULT_MAX_DOC_SIZE;
-    if (encodedDoc.length > maxSize * 2) {
-        throw new Error(`did:peer:4 encoded doc too large: ${encodedDoc.length} > ${maxSize * 2}`);
+    const maxEncoded = Math.ceil((maxSize + JSON_MULTICODEC.length) * BASE58_EXPANSION) + 8;
+    if (encodedDoc.length > maxEncoded) {
+        throw new Error(`did:peer:4 encoded doc too large: ${encodedDoc.length} > ${maxEncoded}`);
     }
     const hashBytes = decodeMultibase(hashEncoded);
     if (!verifyMultihash(hashBytes, fromUTF(encodedDoc))) {

package/lib/token.d.ts

@@ -8,6 +8,24 @@ export type VerifyTokenOptions = TimeValidationOptions & {
     verifiers?: Verifiers;
     resolver?: DIDResolver;
     cache?: DIDCache;
+    /**
+     * 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
+     * (they carry no proof of their claims). Intended for the invocation/leaf token directed at
+     * a service — it must NOT be forwarded into capability-chain verification, where a
+     * 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>;
+    /**
+     * Accept unsigned (`alg:none`) tokens. Defaults to `false`.
+     *
+     * An unsigned token carries no proof of its claims: its payload is entirely
+     * attacker-chosen. With the default, `verifyToken` rejects them and its return type is
+     * `VerifiedToken`, so a caller cannot reach an unverified payload by accident. Only opt
+     * in when the payload is not used for authorization.
+     */
+    allowUnsigned?: boolean;
 };
 export type VerifySignedPayloadInput<Payload extends Record<string, unknown> = Record<string, unknown>> = {
     signature: Uint8Array;
@@ -32,7 +50,7 @@ export declare function isSignedToken<Payload extends SignedPayload = SignedPayl
 /**
  * Check if a token is unsigned.
  */
-export declare function isUnsignedToken<Payload extends Record<string, unknown>>(token: Token<Payload>): token is UnsignedToken<Payload>;
+export declare function isUnsignedToken<Payload extends Record<string, unknown>>(token: unknown): token is UnsignedToken<Payload>;
 /**
  * Check if a token was verified by `verifyToken` in this process.
  * A `verifiedPublicKey` property on a deserialized token is never trusted.
@@ -50,4 +68,10 @@ export declare function signToken<Payload extends Record<string, unknown>, Heade
  * Verify a token is either unsigned or signed with a valid signature.
  * Also validates time-based claims (exp, nbf) if present.
  */
-export declare function verifyToken<Payload extends Record<string, unknown> = Record<string, unknown>>(token: Token<Payload> | string, options?: VerifyTokenOptions): Promise<Token<Payload>>;
+export declare function verifyToken<Payload extends Record<string, unknown> = Record<string, unknown>>(token: Token<Payload> | string, options?: VerifyTokenOptions & {
+    allowUnsigned?: false;
+}): Promise<VerifiedToken<Payload>>;
+export declare function verifyToken<Payload extends Record<string, unknown> = Record<string, unknown>>(token: Token<Payload> | string, options: VerifyTokenOptions & {
+    allowUnsigned: true;
+}): Promise<Token<Payload>>;
+export declare function verifyToken<Payload extends Record<string, unknown> = Record<string, unknown>>(token: Token<Payload> | string, options: VerifyTokenOptions): Promise<Token<Payload>>;

package/lib/token.js

@@ -11,6 +11,30 @@ 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();
+function assertAudienceValid(payload, audience) {
+    if (audience == null) {
+        return;
+    }
+    const aud = payload.aud;
+    const allowed = Array.isArray(audience) ? audience : [
+        audience
+    ];
+    if (typeof aud !== 'string' || !allowed.includes(aud)) {
+        throw new Error(`Invalid token: audience ${typeof aud === 'string' ? `"${aud}"` : 'missing'} not accepted`);
+    }
+}
+// An unsigned / `alg:none` token carries no proof of its claims, so it cannot satisfy an
+// audience requirement. Reject it rather than silently skipping the check.
+function assertSignedForAudience(audience) {
+    if (audience != null) {
+        throw new Error('Invalid token: audience validation requires a signed token');
+    }
+}
+function assertUnsignedAllowed(allowUnsigned) {
+    if (!allowUnsigned) {
+        throw new Error('Invalid token: unsigned tokens rejected, pass allowUnsigned to accept');
+    }
+}
 /**
  * Verify the signature of a signed payload and return the public key of the issuer.
  */ export async function verifySignedPayload(input) {
@@ -38,12 +62,18 @@ const verifiedTokens = new WeakSet();
 /**
  * Check if a token is signed.
  */ export function isSignedToken(token) {
+    if (typeof token !== 'object' || token === null) {
+        return false;
+    }
     const t = token;
     return isType(validateSignedHeader, t.header) && isType(validateSignedPayload, t.payload) && t.signature != null;
 }
 /**
  * Check if a token is unsigned.
  */ export function isUnsignedToken(token) {
+    if (typeof token !== 'object' || token === null) {
+        return false;
+    }
     return isType(validateUnsignedHeader, token.header);
 }
 /**
@@ -93,13 +123,17 @@ function getVerifiableData(token) {
     throw new Error('Invalid token: data does not match header and payload');
 }
 async function verifyTokenInner(token, options = {}) {
-    const { verifiers, resolver, cache, ...timeOptions } = options;
+    const { verifiers, resolver, cache, audience, allowUnsigned = false, ...timeOptions } = options;
     if (typeof token !== 'string') {
         if (isUnsignedToken(token)) {
+            assertSignedForAudience(audience);
+            assertUnsignedAllowed(allowUnsigned);
+            assertTimeClaimsValid(token.payload, timeOptions);
             return token;
         }
         if (isVerifiedToken(token)) {
             assertTimeClaimsValid(token.payload, timeOptions);
+            assertAudienceValid(token.payload, audience);
             return token;
         }
         if (isSignedToken(token)) {
@@ -114,6 +148,7 @@ async function verifyTokenInner(token, options = {}) {
                 cache
             });
             assertTimeClaimsValid(token.payload, timeOptions);
+            assertAudienceValid(token.payload, audience);
             const result = {
                 ...token,
                 data,
@@ -134,9 +169,13 @@ async function verifyTokenInner(token, options = {}) {
         throw new Error('Invalid token header type');
     }
     if (header.alg === 'none') {
+        assertSignedForAudience(audience);
+        assertUnsignedAllowed(allowUnsigned);
+        const payload = b64uToJSON(encodedPayload);
+        assertTimeClaimsValid(payload, timeOptions);
         return {
             header,
-            payload: b64uToJSON(encodedPayload)
+            payload
         };
     }
     if (isType(validateAlgorithm, header.alg)) {
@@ -155,6 +194,7 @@ async function verifyTokenInner(token, options = {}) {
             cache
         });
         assertTimeClaimsValid(payload, timeOptions);
+        assertAudienceValid(payload, audience);
         const result = {
             data,
             header,
@@ -167,10 +207,7 @@ async function verifyTokenInner(token, options = {}) {
     }
     throw new Error('Unsupported signature algorithm');
 }
-/**
- * Verify a token is either unsigned or signed with a valid signature.
- * Also validates time-based claims (exp, nbf) if present.
- */ export async function verifyToken(token, options = {}) {
+export async function verifyToken(token, options = {}) {
     return withSpan(tokenTracer, KokuinSpanNames.TOKEN_VERIFY, {}, async (span)=>{
         const result = await verifyTokenInner(token, options);
         if (isSignedToken(result)) {

package/package.json

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