@kokuin/token 0.1.0

package/lib/schemas.d.ts

@@ -0,0 +1,161 @@
+import { type FromSchema } from '@sozai/schema';
+/** @internal */
+export declare const SUPPORTED_ALGORITHMS: readonly ["EdDSA", "ES256"];
+/** @internal */
+export declare const signatureAlgorithmSchema: {
+    readonly type: "string";
+    readonly enum: readonly ["EdDSA", "ES256"];
+};
+/** @internal */
+export type SignatureAlgorithm = FromSchema<typeof signatureAlgorithmSchema>;
+/** @internal */
+export declare const validateAlgorithm: import("@sozai/schema").Validator<"EdDSA" | "ES256">;
+/** @internal */
+export declare const signedHeaderSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly typ: {
+            readonly type: "string";
+            readonly const: "JWT";
+        };
+        readonly alg: {
+            readonly type: "string";
+            readonly enum: readonly ["EdDSA", "ES256"];
+        };
+        readonly kid: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["typ", "alg"];
+    readonly additionalProperties: true;
+};
+/** @internal */
+export type SignedHeader = FromSchema<typeof signedHeaderSchema>;
+/** @internal */
+export declare const validateSignedHeader: import("@sozai/schema").Validator<{
+    [x: string]: unknown;
+    kid?: string | undefined;
+    alg: "EdDSA" | "ES256";
+    typ: "JWT";
+}>;
+/** @internal */
+export declare const unsignedHeaderSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly typ: {
+            readonly type: "string";
+            readonly const: "JWT";
+        };
+        readonly alg: {
+            readonly type: "string";
+            readonly const: "none";
+        };
+    };
+    readonly required: readonly ["typ", "alg"];
+    readonly additionalProperties: true;
+};
+/** @internal */
+export type UnsignedHeader = FromSchema<typeof unsignedHeaderSchema>;
+/** @internal */
+export declare const validateUnsignedHeader: import("@sozai/schema").Validator<{
+    [x: string]: unknown;
+    alg: "none";
+    typ: "JWT";
+}>;
+/** @internal */
+export declare const supportedHeaderSchema: {
+    readonly anyOf: readonly [{
+        readonly type: "object";
+        readonly properties: {
+            readonly typ: {
+                readonly type: "string";
+                readonly const: "JWT";
+            };
+            readonly alg: {
+                readonly type: "string";
+                readonly enum: readonly ["EdDSA", "ES256"];
+            };
+            readonly kid: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["typ", "alg"];
+        readonly additionalProperties: true;
+    }, {
+        readonly type: "object";
+        readonly properties: {
+            readonly typ: {
+                readonly type: "string";
+                readonly const: "JWT";
+            };
+            readonly alg: {
+                readonly type: "string";
+                readonly const: "none";
+            };
+        };
+        readonly required: readonly ["typ", "alg"];
+        readonly additionalProperties: true;
+    }];
+};
+/** @internal */
+export type SupportedHeader = FromSchema<typeof supportedHeaderSchema>;
+/** @internal */
+export declare const capabilitySchema: {
+    readonly anyOf: readonly [{
+        readonly type: "string";
+    }, {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+        };
+    }];
+};
+/** @internal */
+export declare const signedPayloadSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly iss: {
+            readonly type: "string";
+        };
+        readonly sub: {
+            readonly type: "string";
+        };
+        readonly aud: {
+            readonly type: "string";
+        };
+        readonly cap: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            }];
+        };
+        readonly exp: {
+            readonly type: "number";
+        };
+        readonly nbf: {
+            readonly type: "number";
+        };
+        readonly iat: {
+            readonly type: "number";
+        };
+    };
+    readonly required: readonly ["iss"];
+    readonly additionalProperties: true;
+};
+/** @internal */
+export type SignedPayload = FromSchema<typeof signedPayloadSchema>;
+/** @internal */
+export declare const validateSignedPayload: import("@sozai/schema").Validator<{
+    [x: string]: unknown;
+    sub?: string | undefined;
+    cap?: string | string[] | undefined;
+    aud?: string | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    iss: string;
+}>;

package/lib/schemas.js

@@ -0,0 +1,96 @@
+import { createValidator } from '@sozai/schema';
+/** @internal */ export const SUPPORTED_ALGORITHMS = [
+    'EdDSA',
+    'ES256'
+];
+/** @internal */ export const signatureAlgorithmSchema = {
+    type: 'string',
+    enum: SUPPORTED_ALGORITHMS
+};
+/** @internal */ export const validateAlgorithm = createValidator(signatureAlgorithmSchema);
+/** @internal */ export const signedHeaderSchema = {
+    type: 'object',
+    properties: {
+        typ: {
+            type: 'string',
+            const: 'JWT'
+        },
+        alg: signatureAlgorithmSchema,
+        kid: {
+            type: 'string'
+        }
+    },
+    required: [
+        'typ',
+        'alg'
+    ],
+    additionalProperties: true
+};
+/** @internal */ export const validateSignedHeader = createValidator(signedHeaderSchema);
+/** @internal */ export const unsignedHeaderSchema = {
+    type: 'object',
+    properties: {
+        typ: {
+            type: 'string',
+            const: 'JWT'
+        },
+        alg: {
+            type: 'string',
+            const: 'none'
+        }
+    },
+    required: [
+        'typ',
+        'alg'
+    ],
+    additionalProperties: true
+};
+/** @internal */ export const validateUnsignedHeader = createValidator(unsignedHeaderSchema);
+/** @internal */ export const supportedHeaderSchema = {
+    anyOf: [
+        signedHeaderSchema,
+        unsignedHeaderSchema
+    ]
+};
+/** @internal */ export const capabilitySchema = {
+    anyOf: [
+        {
+            type: 'string'
+        },
+        {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        }
+    ]
+};
+/** @internal */ export const signedPayloadSchema = {
+    type: 'object',
+    properties: {
+        iss: {
+            type: 'string'
+        },
+        sub: {
+            type: 'string'
+        },
+        aud: {
+            type: 'string'
+        },
+        cap: capabilitySchema,
+        exp: {
+            type: 'number'
+        },
+        nbf: {
+            type: 'number'
+        },
+        iat: {
+            type: 'number'
+        }
+    },
+    required: [
+        'iss'
+    ],
+    additionalProperties: true
+};
+/** @internal */ export const validateSignedPayload = createValidator(signedPayloadSchema);

package/lib/signer.d.ts

@@ -0,0 +1,6 @@
+import { fromB64, toB64 } from '@sozai/codec';
+export { fromB64 as decodePrivateKey, toB64 as encodePrivateKey };
+/**
+ * Generate a random private key.
+ */
+export declare const randomPrivateKey: (seed?: import("@noble/curves/utils.js").TArg<Uint8Array>) => import("@noble/curves/utils.js").TRet<Uint8Array>;

package/lib/signer.js

@@ -0,0 +1,6 @@
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { fromB64, toB64 } from '@sozai/codec';
+export { fromB64 as decodePrivateKey, toB64 as encodePrivateKey };
+/**
+ * Generate a random private key.
+ */ export const randomPrivateKey = ed25519.utils.randomSecretKey;

package/lib/time.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Get the current time in seconds since Unix epoch.
+ */
+export declare function now(): number;
+/**
+ * Options for time-based token validation.
+ */
+export type TimeValidationOptions = {
+    /** Current time in seconds. Defaults to now(). */
+    atTime?: number;
+    /** Clock skew tolerance in seconds. Defaults to 0. */
+    clockTolerance?: number;
+};
+/**
+ * Payload with optional time-based claims.
+ */
+export type TimeClaimsPayload = {
+    /** Expiration time (seconds since epoch) */
+    exp?: number;
+    /** Not before time (seconds since epoch) */
+    nbf?: number;
+    /** Issued at time (seconds since epoch) */
+    iat?: number;
+};
+/**
+ * Validate time-based claims in a token payload.
+ * @throws Error if token is expired or not yet valid
+ */
+export declare function assertTimeClaimsValid(payload: TimeClaimsPayload, options?: TimeValidationOptions): void;

package/lib/time.js

@@ -0,0 +1,18 @@
+/**
+ * Get the current time in seconds since Unix epoch.
+ */ export function now() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Validate time-based claims in a token payload.
+ * @throws Error if token is expired or not yet valid
+ */ export function assertTimeClaimsValid(payload, options = {}) {
+    const time = options.atTime ?? now();
+    const tolerance = options.clockTolerance ?? 0;
+    if (payload.exp != null && payload.exp + tolerance < time) {
+        throw new Error('Token expired');
+    }
+    if (payload.nbf != null && payload.nbf - tolerance > time) {
+        throw new Error('Token not yet valid');
+    }
+}

package/lib/token.d.ts

@@ -0,0 +1,53 @@
+import type { DIDCache, DIDResolver } from './cache.js';
+import type { SigningIdentity } from './identity.js';
+import { type SignedPayload } from './schemas.js';
+import { type TimeValidationOptions } from './time.js';
+import type { SignedToken, Token, UnsignedToken, VerifiedToken } from './types.js';
+import { type Verifiers } from './verifier.js';
+export type VerifyTokenOptions = TimeValidationOptions & {
+    verifiers?: Verifiers;
+    resolver?: DIDResolver;
+    cache?: DIDCache;
+};
+export type VerifySignedPayloadInput<Payload extends Record<string, unknown> = Record<string, unknown>> = {
+    signature: Uint8Array;
+    payload: Payload;
+    header: {
+        alg?: string;
+        kid?: string;
+    };
+    data: Uint8Array | string;
+    verifiers?: Verifiers;
+    resolver?: DIDResolver;
+    cache?: DIDCache;
+};
+/**
+ * Verify the signature of a signed payload and return the public key of the issuer.
+ */
+export declare function verifySignedPayload<Payload extends Record<string, unknown> = Record<string, unknown>>(input: VerifySignedPayloadInput<Payload>): Promise<Uint8Array>;
+/**
+ * Check if a token is signed.
+ */
+export declare function isSignedToken<Payload extends SignedPayload = SignedPayload>(token: unknown): token is SignedToken<Payload>;
+/**
+ * Check if a token is unsigned.
+ */
+export declare function isUnsignedToken<Payload extends Record<string, unknown>>(token: Token<Payload>): 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.
+ */
+export declare function isVerifiedToken<Payload extends SignedPayload>(token: unknown): token is VerifiedToken<Payload>;
+/**
+ * Create an unsigned token object.
+ */
+export declare function createUnsignedToken<Payload extends Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>>(payload: Payload, header?: Header): UnsignedToken<Payload, Header>;
+/**
+ * Sign a token object if not already signed.
+ */
+export declare function signToken<Payload extends Record<string, unknown>, Header extends Record<string, unknown>>(signer: SigningIdentity, token: Token<Payload, Header>): Promise<SignedToken<Payload, Header>>;
+/**
+ * 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>>;

package/lib/token.js

@@ -0,0 +1,181 @@
+import { b64uFromJSON, b64uToJSON, canonicalStringify, fromB64U, fromUTF } from '@sozai/codec';
+import { AttributeKeys, createTracer, SpanNames, withSpan } from '@sozai/otel';
+import { assertType, isType } from '@sozai/schema';
+import { resolveIssuerWithDoc } from './did.js';
+import { validateAlgorithm, validateSignedHeader, validateSignedPayload, validateUnsignedHeader } from './schemas.js';
+import { assertTimeClaimsValid } from './time.js';
+import { getVerifier } from './verifier.js';
+const tokenTracer = createTracer('token');
+// Tokens whose signature was verified in this process. Deserialized JSON can carry a
+// `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();
+/**
+ * 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;
+    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 verify = getVerifier(alg, verifiers);
+    const message = typeof data === 'string' ? fromUTF(data) : data;
+    const verified = await verify(signature, message, publicKey);
+    if (!verified) {
+        throw new Error('Invalid signature');
+    }
+    if (cache != null && peer4Doc != null) {
+        await cache.set(peer4Doc.shortForm, peer4Doc.doc);
+    }
+    return publicKey;
+}
+/**
+ * Check if a token is signed.
+ */ export function isSignedToken(token) {
+    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) {
+    return isType(validateUnsignedHeader, token.header);
+}
+/**
+ * Check if a token was verified by `verifyToken` in this process.
+ * A `verifiedPublicKey` property on a deserialized token is never trusted.
+ */ export function isVerifiedToken(token) {
+    return isSignedToken(token) && token.verifiedPublicKey != null && verifiedTokens.has(token);
+}
+/**
+ * Create an unsigned token object.
+ */ export function createUnsignedToken(payload, header) {
+    return {
+        header: {
+            ...header ?? {},
+            typ: 'JWT',
+            alg: 'none'
+        },
+        payload
+    };
+}
+/**
+ * Sign a token object if not already signed.
+ */ export async function signToken(signer, token) {
+    return isSignedToken(token) ? token : await signer.signToken(token.payload, {
+        header: token.header
+    });
+}
+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
+        }
+    }
+    throw new Error('Invalid token: data does not match header and payload');
+}
+async function verifyTokenInner(token, options = {}) {
+    const { verifiers, resolver, cache, ...timeOptions } = options;
+    if (typeof token !== 'string') {
+        if (isUnsignedToken(token)) {
+            return token;
+        }
+        if (isVerifiedToken(token)) {
+            assertTimeClaimsValid(token.payload, timeOptions);
+            return token;
+        }
+        if (isSignedToken(token)) {
+            const data = getVerifiableData(token);
+            const verifiedPublicKey = await verifySignedPayload({
+                signature: fromB64U(token.signature),
+                payload: token.payload,
+                header: token.header,
+                data,
+                verifiers,
+                resolver,
+                cache
+            });
+            assertTimeClaimsValid(token.payload, timeOptions);
+            const result = {
+                ...token,
+                data,
+                verifiedPublicKey
+            };
+            verifiedTokens.add(result);
+            return result;
+        }
+        throw new Error('Unsupported token');
+    }
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        throw new Error('Invalid token format: expected 3 parts separated by dots');
+    }
+    const [encodedHeader, encodedPayload, signature] = parts;
+    const header = b64uToJSON(encodedHeader);
+    if (header.typ !== 'JWT') {
+        throw new Error('Invalid token header type');
+    }
+    if (header.alg === 'none') {
+        return {
+            header,
+            payload: b64uToJSON(encodedPayload)
+        };
+    }
+    if (isType(validateAlgorithm, header.alg)) {
+        if (signature == null) {
+            throw new Error('Missing signature for token with signed header');
+        }
+        const payload = b64uToJSON(encodedPayload);
+        const data = `${encodedHeader}.${encodedPayload}`;
+        const verifiedPublicKey = await verifySignedPayload({
+            signature: fromB64U(signature),
+            payload,
+            header: header,
+            data,
+            verifiers,
+            resolver,
+            cache
+        });
+        assertTimeClaimsValid(payload, timeOptions);
+        const result = {
+            data,
+            header,
+            payload,
+            signature,
+            verifiedPublicKey
+        };
+        verifiedTokens.add(result);
+        return result;
+    }
+    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)=>{
+        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);
+        }
+        return result;
+    });
+}

package/lib/types.d.ts

@@ -0,0 +1,17 @@
+import type { SignedHeader, SignedPayload, UnsignedHeader } from './schemas.js';
+export type SignedToken<Payload extends Record<string, unknown> = Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>> = {
+    data: string;
+    header: SignedHeader & Header;
+    payload: SignedPayload & Payload;
+    signature: string;
+};
+export type UnsignedToken<Payload extends Record<string, unknown> = Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>> = {
+    data?: string;
+    header: UnsignedHeader & Header;
+    payload: Payload;
+    signature?: undefined;
+};
+export type VerifiedToken<Payload extends Record<string, unknown> = Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>> = SignedToken<Payload, Header> & {
+    verifiedPublicKey: Uint8Array;
+};
+export type Token<Payload extends Record<string, unknown> = Record<string, unknown>, Header extends Record<string, unknown> = Record<string, unknown>> = UnsignedToken<Payload, Header> | SignedToken<Payload, Header> | VerifiedToken<Payload, Header>;

package/lib/types.js

@@ -0,0 +1 @@
+export { };

package/lib/utils.d.ts

@@ -0,0 +1,6 @@
+import type { 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;

package/lib/utils.js

@@ -0,0 +1,19 @@
+import { b64uFromJSON } from '@sozai/codec';
+export function concatBytes(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+/**
+ * Convert a Token object to its JWT string representation.
+ */ export function stringifyToken(token) {
+    const parts = [
+        b64uFromJSON(token.header),
+        b64uFromJSON(token.payload)
+    ];
+    if (token.signature != null) {
+        parts.push(token.signature);
+    }
+    return parts.join('.');
+}

package/lib/verifier.d.ts

@@ -0,0 +1,9 @@
+import type { SignatureAlgorithm } from './schemas.js';
+/** @internal */
+export type Verifier = (signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array) => boolean | Promise<boolean>;
+/** @internal */
+export type Verifiers = Partial<Record<SignatureAlgorithm, Verifier>>;
+/** @internal */
+export declare const defaultVerifiers: Verifiers;
+/** @internal */
+export declare function getVerifier(algorithm: SignatureAlgorithm, verifiers?: Verifiers): Verifier;

package/lib/verifier.js

@@ -0,0 +1,19 @@
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { p256 } from '@noble/curves/nist.js';
+/** @internal */ export const defaultVerifiers = {
+    ES256: (signature, message, publicKey)=>{
+        return p256.verify(signature, message, publicKey, {
+            lowS: true
+        });
+    },
+    EdDSA: (signature, message, publicKey)=>{
+        return ed25519.verify(signature, message, publicKey);
+    }
+};
+/** @internal */ export function getVerifier(algorithm, verifiers = {}) {
+    const verifier = verifiers[algorithm] ?? defaultVerifiers[algorithm];
+    if (verifier == null) {
+        throw new Error('Unsupported signature algorithm');
+    }
+    return verifier;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kokuin/token",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "JWT signing and verification",
+  "keywords": [
+    "json",
+    "web",
+    "token",
+    "jwt",
+    "signature"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kokuin",
+    "directory": "packages/token"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "uint8arrays": "^6.1.1"
+  },
+  "scripts": {
+    "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:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run",
+    "test": "pnpm run test:types && pnpm run test:unit"
+  }
+}