@kokuin/token 0.1.0 → 0.2.0

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) {

package/lib/identity.js

@@ -1,6 +1,7 @@
+import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
 import { ed25519, x25519 } from '@noble/curves/ed25519.js';
 import { b64uFromJSON, fromUTF, toB64U } from '@sozai/codec';
-import { AttributeKeys, createTracer, SpanNames, withSpan } from '@sozai/otel';
+import { withSpan } from '@sozai/otel';
 import { CODECS, getDID, normalizeDID } from './did.js';
 import { decryptToken } from './jwe.js';
 import { encodeMultibase } from './multibase.js';
@@ -25,10 +26,10 @@ export function isOwnIdentity(identity) {
     const publicKey = ed25519.getPublicKey(privateKey);
     const id = getDID(CODECS.EdDSA, publicKey);
     async function signToken(payload, options = {}) {
-        return withSpan(tracer, SpanNames.TOKEN_SIGN, {
+        return withSpan(tracer, KokuinSpanNames.TOKEN_SIGN, {
             attributes: {
-                [AttributeKeys.AUTH_DID]: id,
-                [AttributeKeys.AUTH_ALGORITHM]: 'EdDSA'
+                [KokuinAttributeKeys.AUTH_DID]: id,
+                [KokuinAttributeKeys.AUTH_ALGORITHM]: 'EdDSA'
             }
         }, async ()=>{
             if (payload.iss != null && payload.iss !== id) {

package/lib/jwe.js

@@ -235,7 +235,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/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

@@ -1,5 +1,6 @@
+import { createTracer, KokuinAttributeKeys, KokuinSpanNames } from '@kokuin/otel';
 import { b64uFromJSON, b64uToJSON, canonicalStringify, fromB64U, fromUTF } from '@sozai/codec';
-import { AttributeKeys, createTracer, SpanNames, withSpan } from '@sozai/otel';
+import { withSpan } from '@sozai/otel';
 import { assertType, isType } from '@sozai/schema';
 import { resolveIssuerWithDoc } from './did.js';
 import { validateAlgorithm, validateSignedHeader, validateSignedPayload, validateUnsignedHeader } from './schemas.js';
@@ -10,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) {
@@ -37,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);
 }
 /**
@@ -92,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)) {
@@ -113,6 +148,7 @@ async function verifyTokenInner(token, options = {}) {
                 cache
             });
             assertTimeClaimsValid(token.payload, timeOptions);
+            assertAudienceValid(token.payload, audience);
             const result = {
                 ...token,
                 data,
@@ -133,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)) {
@@ -154,6 +194,7 @@ async function verifyTokenInner(token, options = {}) {
             cache
         });
         assertTimeClaimsValid(payload, timeOptions);
+        assertAudienceValid(payload, audience);
         const result = {
             data,
             header,
@@ -166,15 +207,12 @@ 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 = {}) {
-    return withSpan(tokenTracer, SpanNames.TOKEN_VERIFY, {}, async (span)=>{
+export async function verifyToken(token, options = {}) {
+    return withSpan(tokenTracer, KokuinSpanNames.TOKEN_VERIFY, {}, async (span)=>{
         const result = await verifyTokenInner(token, options);
         if (isSignedToken(result)) {
-            span.setAttribute(AttributeKeys.AUTH_DID, result.payload.iss);
-            span.setAttribute(AttributeKeys.AUTH_ALGORITHM, result.header.alg);
+            span.setAttribute(KokuinAttributeKeys.AUTH_DID, result.payload.iss);
+            span.setAttribute(KokuinAttributeKeys.AUTH_ALGORITHM, result.header.alg);
         }
         return result;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/token",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "JWT signing and verification",
   "keywords": [
@@ -26,15 +26,18 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.1.0",
-    "@sozai/schema": "^0.1.0",
-    "@sozai/otel": "^0.1.0",
     "@noble/ciphers": "^2.1.1",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.0",
-    "@scure/base": "^2.2.0"
+    "@scure/base": "^2.2.0",
+    "@sozai/codec": "^0.2.0",
+    "@sozai/otel": "^0.2.0",
+    "@sozai/schema": "^0.1.1",
+    "@kokuin/otel": "^0.1.0"
   },
   "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "@opentelemetry/sdk-trace-node": "^2.9.0",
     "uint8arrays": "^6.1.1"
   },
   "scripts": {