@kokuin/token 0.5.0 → 0.6.0

package/lib/did.d.ts

@@ -1,5 +1,5 @@
 import type { DIDResolver } from './cache.js';
-import { type MethodRegistry } from './method.js';
+import { type MethodRegistry, type ResolvedSigningKey } from './method.js';
 import type { DIDDoc } from './peer4.js';
 import type { SignatureAlgorithm } from './schemas.js';
 import type { DIDString } from './types.js';
@@ -142,3 +142,13 @@ export declare function normalizeDID(did: string): string;
  * 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;
+/**
+ * The signing keys a DID carries in its identifier, or `null` when it carries none. `did:key` is its
+ * key; a `did:peer:4` long form embeds the document, so its `authentication` keys (signing is what
+ * a pin or a membership is for) are readable from the string. Anything network-backed -- a
+ * short-form `did:peer:4`, `did:kokuin:` -- answers `null` rather than looking up.
+ *
+ * Throws on an identifier that claims to carry a key and does not; the caller treats that as no
+ * match.
+ */
+export declare function signingKeysOf(did: string): Array<ResolvedSigningKey> | null;

package/lib/did.js

@@ -282,11 +282,11 @@ function hasKeyPrefix(did) {
 }
 function resolveKidOrAuth(doc, kid) {
     if (kid == null) {
-        const auth = doc.authentication;
-        if (auth == null || auth.length === 0) {
+        const firstAuth = doc.authentication?.[0];
+        if (firstAuth == null) {
             throw new Error('resolveIssuer: did:peer:4 token missing kid and doc has no authentication entries');
         }
-        return resolveKidFromDoc(doc, auth[0]);
+        return resolveKidFromDoc(doc, firstAuth);
     }
     // 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
@@ -365,3 +365,47 @@ function resolveKidFromDoc(doc, kid) {
     }
     return null;
 }
+/** As long as `resolveKidFromDoc` allows: base58 decoding is O(n^2). */ const MAX_KEY_ENCODED = 64;
+/**
+ * The signing keys a DID carries in its identifier, or `null` when it carries none. `did:key` is its
+ * key; a `did:peer:4` long form embeds the document, so its `authentication` keys (signing is what
+ * a pin or a membership is for) are readable from the string. Anything network-backed -- a
+ * short-form `did:peer:4`, `did:kokuin:` -- answers `null` rather than looking up.
+ *
+ * Throws on an identifier that claims to carry a key and does not; the caller treats that as no
+ * match.
+ */ export function signingKeysOf(did) {
+    if (did.startsWith('did:key:')) {
+        const [alg, publicKey] = getSignatureInfo(did);
+        return [
+            {
+                alg,
+                publicKey
+            }
+        ];
+    }
+    if (!isPeer4(did) || did === getPeer4ShortForm(did)) {
+        return null;
+    }
+    const { doc } = decodePeer4(did);
+    const keys = [];
+    for (const id of doc.authentication ?? []){
+        const method = doc.verificationMethod.find((entry)=>entry.id === id);
+        if (method == null || method.publicKeyMultibase.length > MAX_KEY_ENCODED) {
+            continue;
+        }
+        let info = null;
+        try {
+            info = getAlgorithmAndPublicKey(decodeMultibase(method.publicKeyMultibase));
+        } catch  {
+            continue;
+        }
+        if (info != null) {
+            keys.push({
+                alg: info[0],
+                publicKey: info[1]
+            });
+        }
+    }
+    return keys;
+}

package/lib/identity.js

@@ -169,19 +169,21 @@ function isClassical(spec) {
 function chooseMethod(input) {
     if (input.didMethod != null) {
         if (input.didMethod === 'key') {
-            if (input.keys.length !== 1) {
+            const [firstKey, ...rest] = input.keys;
+            if (firstKey === undefined || rest.length > 0) {
                 throw new Error('IdentityError.InvalidMethod: did:key requires exactly one key');
             }
-            if (!isClassical(input.keys[0])) {
+            if (!isClassical(firstKey)) {
                 throw new Error('IdentityError.InvalidMethod: did:key requires a classical algorithm');
             }
-            if (input.keys[0].purpose !== 'sig') {
+            if (firstKey.purpose !== 'sig') {
                 throw new Error('IdentityError.InvalidMethod: did:key requires a signing key');
             }
         }
         return input.didMethod;
     }
-    if (input.keys.length === 1 && isClassical(input.keys[0]) && input.keys[0].purpose === 'sig') {
+    const [firstKey, ...rest] = input.keys;
+    if (firstKey !== undefined && rest.length === 0 && isClassical(firstKey) && firstKey.purpose === 'sig') {
         return 'key';
     }
     return 'peer:4';
@@ -356,6 +358,9 @@ function buildIdentity(id, longForm, doc, keys) {
     const keys = resolveKeys(input);
     if (method === 'key') {
         const [k] = keys;
+        if (k === undefined) {
+            throw new Error('createIdentity requires at least one key');
+        }
         const id = getDID(CODECS.EdDSA, k.publicKey);
         const doc = {
             '@context': [

package/lib/index.d.ts

@@ -10,10 +10,10 @@
  * @module token
  */
 export { type CreateInMemoryDIDCacheOptions, createInMemoryDIDCache, type DIDCache, type DIDResolver, } from './cache.js';
-export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerMode, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, UnresolvableIssuerError, } from './did.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, type ResolveIssuerHeader, type ResolveIssuerMode, type ResolveIssuerWithDocResult, resolveIssuer, resolveIssuerWithDoc, signingKeysOf, 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 { type AgreementAlgorithm, type DIDMethodResolver, findMethodResolver, type MemberQuery, type MethodRegistry, type ResolvedAgreementKey, type ResolvedMember, 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 { capabilitySchema, type SignatureAlgorithm, type SignedHeader, type SignedPayload, type SupportedHeader, signedHeaderSchema, signedPayloadSchema, supportedHeaderSchema, type UnsignedHeader, unsignedHeaderSchema, validateAlgorithm, validateSignedHeader, validateSignedPayload, validateUnsignedHeader, } from './schemas.js';
@@ -21,5 +21,5 @@ export { decodePrivateKey, encodePrivateKey, randomPrivateKey, } from './signer.
 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 { concatBytes, stringifyToken } from './utils.js';
+export { concatBytes, decodeSignedToken, stringifyToken } from './utils.js';
 export { getVerifier, type Verifier, type Verifiers, } from './verifier.js';

package/lib/index.js

@@ -9,7 +9,7 @@
  *
  * @module token
  */ export { createInMemoryDIDCache } from './cache.js';
-export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, resolveIssuer, resolveIssuerWithDoc, UnresolvableIssuerError } from './did.js';
+export { CODECS, getAgreementKey, getAlgorithmAndPublicKey, getDID, getSignatureInfo, IssuerKeyNotFoundError, isIssuerKeyNotFoundError, isUnresolvableIssuerError, normalizeDID, resolveIssuer, resolveIssuerWithDoc, signingKeysOf, 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';
@@ -18,5 +18,5 @@ export { capabilitySchema, signedHeaderSchema, signedPayloadSchema, supportedHea
 export { decodePrivateKey, encodePrivateKey, randomPrivateKey } from './signer.js';
 export { assertTimeClaimsValid, now } from './time.js';
 export { createUnsignedToken, isSignedToken, isUnsignedToken, isVerifiedToken, signToken, verifyToken } from './token.js';
-export { concatBytes, stringifyToken } from './utils.js';
+export { concatBytes, decodeSignedToken, stringifyToken } from './utils.js';
 export { getVerifier } from './verifier.js';

package/lib/method.d.ts

@@ -5,6 +5,17 @@ export type ResolvedSigningKey = {
     alg: SignatureAlgorithm;
     publicKey: Uint8Array;
 };
+/** The member of a subject's management tier being asked about: its DID, `add` digest and generation. */
+export type MemberQuery = {
+    did: string;
+    add: string;
+    gen: number;
+};
+/** The signing key a subject's log pins for a member, and when that membership lapses (unix seconds). */
+export type ResolvedMember = {
+    key: ResolvedSigningKey;
+    lease: number;
+};
 export type AgreementAlgorithm = 'X25519';
 /** A key agreement key a DID method resolved for a recipient. */
 export type ResolvedAgreementKey = {
@@ -64,6 +75,17 @@ export type DIDMethodResolver = {
      * break every implementation for a member most methods have no answer for.
      */
     resolveDenySet?(did: string): Promise<ReadonlySet<string>>;
+    /**
+     * The key and lease the subject's log holds for one **member** of its management tier, answered for
+     * **now**. A grant issued by a member rather than by the subject's own key is valid only while that
+     * membership is live, so the verifier asks the log rather than trusting the grant's claims.
+     *
+     * Optional, and its **absence fails closed**: a method that cannot answer refuses every
+     * member-issued grant rather than falling back to {@link resolve}, which names the subject's own
+     * keys and would answer a different question. A member that is unknown, removed or lapsed must
+     * reject, never resolve.
+     */
+    resolveMember?(subject: string, member: MemberQuery): Promise<ResolvedMember>;
 };
 export type MethodRegistry = ReadonlyArray<DIDMethodResolver>;
 /** Total: a malformed DID yields `undefined` rather than throwing. */

package/lib/token.js

@@ -125,12 +125,12 @@ function matchesVerifiableData(token, data) {
     if (data === `${b64uFromJSON(token.header)}.${b64uFromJSON(token.payload)}`) {
         return true;
     }
-    const parts = data.split('.');
-    if (parts.length !== 2) {
+    const [headerPart, payloadPart, extra] = data.split('.');
+    if (headerPart === undefined || payloadPart === undefined || extra !== undefined) {
         return false;
     }
     try {
-        return canonicalStringify(b64uToJSON(parts[0])) === canonicalStringify(token.header) && canonicalStringify(b64uToJSON(parts[1])) === canonicalStringify(token.payload);
+        return canonicalStringify(b64uToJSON(headerPart)) === canonicalStringify(token.header) && canonicalStringify(b64uToJSON(payloadPart)) === canonicalStringify(token.payload);
     } catch  {
         // invalid base64url or JSON in data
         return false;
@@ -210,6 +210,9 @@ async function verifyTokenInner(token, options = {}) {
         throw new Error('Invalid token format: expected 3 parts separated by dots');
     }
     const [encodedHeader, encodedPayload, signature] = parts;
+    if (encodedHeader === undefined || encodedPayload === undefined) {
+        throw new Error('Invalid token format: expected 3 parts separated by dots');
+    }
     const header = b64uToJSON(encodedHeader);
     if (header.typ !== 'JWT') {
         throw new Error('Invalid token header type');

package/lib/utils.d.ts

@@ -1,6 +1,10 @@
-import type { Token } from './types.js';
+import type { SignedToken, Token } from './types.js';
 export declare function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array;
 /**
  * Convert a Token object to its JWT string representation.
  */
 export declare function stringifyToken(token: Token): string;
+/**
+ * Parse a signed token string without verifying it. `data` keeps the original signed segments.
+ */
+export declare function decodeSignedToken<Payload extends Record<string, unknown> = Record<string, unknown>>(token: string): SignedToken<Payload>;

package/lib/utils.js

@@ -1,4 +1,4 @@
-import { b64uFromJSON } from '@sozai/codec';
+import { b64uFromJSON, b64uToJSON } from '@sozai/codec';
 export function concatBytes(a, b) {
     const out = new Uint8Array(a.length + b.length);
     out.set(a, 0);
@@ -17,3 +17,17 @@ export function concatBytes(a, b) {
     }
     return parts.join('.');
 }
+/**
+ * Parse a signed token string without verifying it. `data` keeps the original signed segments.
+ */ export function decodeSignedToken(token) {
+    const [header, payload, signature, ...rest] = token.split('.');
+    if (!header || !payload || !signature || rest.length > 0) {
+        throw new Error('Invalid token format: expected 3 parts separated by dots');
+    }
+    return {
+        data: `${header}.${payload}`,
+        header: b64uToJSON(header),
+        payload: b64uToJSON(payload),
+        signature
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokuin/token",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "JWT signing and verification",
   "keywords": [
     "json",
@@ -26,17 +26,17 @@
     "lib/*"
   ],
   "dependencies": {
-    "@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"
+    "@kokuin/otel": "^0.3.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@scure/base": "^2.4.0",
+    "@sozai/codec": "^0.4.3",
+    "@sozai/otel": "^0.3.4",
+    "@sozai/schema": "^0.1.6"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "^2.10.0",
-    "@opentelemetry/sdk-trace-node": "^2.10.0",
+    "@opentelemetry/api": "^1.10.0",
+    "@opentelemetry/sdk-trace": "^3.0.0",
     "uint8arrays": "^6.1.1"
   },
   "publishConfig": {
@@ -44,9 +44,9 @@
   },
   "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:clean": "del-cli lib",
+    "build:js": "del-cli 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
     "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
     "test:unit": "vitest run"