@sdxc/jwt 0.0.0-pre.1

package/dist/jwt.js

@@ -0,0 +1,322 @@
+/**
+ * A JWT payload as an object with typed accessors, meant to be subclassed.
+ *
+ * A decoded token is a bag of `unknown`, and reading claims straight off it spreads
+ * the same string literals and the same type checks across every call site. `JWT`
+ * gives each kind of token a class instead: the registered claims arrive as getters,
+ * an application adds its own on top through `this.parser`, and signing, verifying,
+ * and decoding all produce an instance of that class.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toSeconds } from "@sdxc/duration";
+import * as jose from "jose";
+import { ObjectParser } from "./lib/parser.js";
+/** Milliseconds in a second, for converting between epoch claims and `Date`. */
+const MS_PER_SECOND = 1000;
+/** Claims that may be written as a length of time from now. */
+const RELATIVE_CLAIMS = ["exp", "iat", "nbf"];
+/**
+ * Resolves any claim written as a length of time into the instant it names.
+ * A duration is measured from now, so `exp: "1h"` is an hour from now, and a
+ * number stays seconds since the epoch; the claim set copies only when needed.
+ *
+ * @param payload - The claims as written.
+ * @returns The claims with every time claim as seconds since the epoch.
+ */
+function resolveRelativeClaims(payload) {
+    let relative = RELATIVE_CLAIMS.filter((claim) => typeof payload[claim] === "string");
+    if (relative.length === 0)
+        return payload;
+    let resolved = { ...payload };
+    let now = Math.floor(Date.now() / MS_PER_SECOND);
+    for (let claim of relative)
+        resolved[claim] = now + toSeconds(payload[claim]);
+    return resolved;
+}
+/**
+ * A JWT payload, with the registered claims exposed as typed accessors.
+ *
+ * Subclass it to add accessors for claims beyond the registered set; an
+ * instance proxies to `payload`, so an accessor-less claim still reads by name.
+ *
+ * @example
+ * class IdToken extends JWT {
+ * 	override get subject() {
+ * 		return this.parser.string("sub"); // required here, so `string` not `string | null`
+ * 	}
+ *
+ * 	get email() {
+ * 		return this.parser.string("email");
+ * 	}
+ * }
+ */
+export class JWT {
+    /** The raw claim set, readable whole for callers that want the payload itself. */
+    payload;
+    /** Type-checked reads over `payload`, for the accessors a subclass defines. */
+    parser;
+    /**
+     * Wraps a claim set in a proxy: a claim with no accessor still reads through
+     * to the payload, and assigning an unknown property lands there too, so a
+     * missing claim answers `null` and callers can test for it directly.
+     *
+     * @param payload - The claims, defaulting to an empty set so a token can be built
+     *   up through the setters.
+     * @example
+     * let jwt = new JWT({ sub: "user-123" });
+     * jwt.subject; // "user-123"
+     */
+    constructor(payload = {}) {
+        this.payload = resolveRelativeClaims(payload);
+        this.parser = new ObjectParser(this.payload);
+        return new Proxy(this, {
+            get(self, prop) {
+                if (prop in self)
+                    return Reflect.get(self, prop);
+                if (typeof prop === "string" && self.parser.has(prop))
+                    return self.parser.get(prop);
+                return null;
+            },
+            set(self, prop, value) {
+                if (prop in self)
+                    return Reflect.set(self, prop, value);
+                if (typeof prop === "string") {
+                    self.payload[prop] = value;
+                    return true;
+                }
+                return Reflect.set(self, prop, value);
+            },
+        });
+    }
+    /**
+     * The `aud` claim: who the token is for.
+     *
+     * @returns One audience, several, or `null` when the claim is absent or malformed.
+     */
+    get audience() {
+        if (!this.parser.has("aud"))
+            return null;
+        let value = this.parser.get("aud");
+        if (typeof value === "string")
+            return value;
+        if (Array.isArray(value))
+            return value;
+        return null;
+    }
+    /** @param value - The audience to set, or `null` to drop the claim. */
+    set audience(value) {
+        this.payload.aud = value ?? undefined;
+    }
+    /**
+     * The `exp` claim, as stored.
+     *
+     * @returns The raw claim value, or `null` when the token does not expire.
+     */
+    get expirationTime() {
+        if (this.parser.has("exp"))
+            return this.parser.number("exp");
+        return null;
+    }
+    /** @param value - The expiration to set, or `null` to drop the claim. */
+    set expirationTime(value) {
+        this.payload.exp = value ?? undefined;
+    }
+    /**
+     * How many seconds are left before the token expires.
+     *
+     * Counted in the seconds RFC 7519 stores `exp` in, so the number is a length of
+     * time and goes negative once the token is past its expiry.
+     *
+     * @returns The seconds until `exp`, or `null` when the claim is absent.
+     */
+    get expiresIn() {
+        if (this.expirationTime === null)
+            return null;
+        return this.expirationTime - Math.floor(Date.now() / MS_PER_SECOND);
+    }
+    /**
+     * The expiration as a `Date`.
+     *
+     * @returns The expiry, or `null` when the token does not expire.
+     */
+    get expiresAt() {
+        if (this.expirationTime === null)
+            return null;
+        return new Date(this.expirationTime * MS_PER_SECOND);
+    }
+    /**
+     * Whether the token is past its expiry, by this class's reading of `exp`.
+     *
+     * A convenience for display and for cache decisions. `JWT.verify` is what enforces
+     * `exp`, against the units the RFC defines.
+     *
+     * @returns `false` for a token with no `exp`, since nothing says it has expired.
+     */
+    get expired() {
+        if (this.expiresIn === null)
+            return false;
+        return this.expiresIn <= 0;
+    }
+    /**
+     * The `iat` claim: when the token was issued.
+     *
+     * @returns The issuance time, or `null` when the claim is absent.
+     */
+    get issuedAt() {
+        if (this.parser.has("iat"))
+            return new Date(this.parser.number("iat"));
+        return null;
+    }
+    /** @param value - The issuance time to set, or `null` to drop the claim. */
+    set issuedAt(value) {
+        this.payload.iat = value ? Math.floor(value.getTime() / MS_PER_SECOND) : undefined;
+    }
+    /**
+     * The `iss` claim: who issued the token.
+     *
+     * @returns The issuer, or `null` when the claim is absent.
+     */
+    get issuer() {
+        if (this.parser.has("iss"))
+            return this.parser.string("iss");
+        return null;
+    }
+    /** @param value - The issuer to set, or `null` to drop the claim. */
+    set issuer(value) {
+        this.payload.iss = value ?? undefined;
+    }
+    /**
+     * The `jti` claim: the token's unique identifier.
+     *
+     * @returns The identifier, or `null` when the claim is absent.
+     */
+    get id() {
+        if (this.parser.has("jti"))
+            return this.parser.string("jti");
+        return null;
+    }
+    /** @param value - The identifier to set, or `null` to drop the claim. */
+    set id(value) {
+        this.payload.jti = value ?? undefined;
+    }
+    /**
+     * The `nbf` claim: when the token starts being valid.
+     *
+     * @returns The start of validity, or `null` when the claim is absent.
+     */
+    get notBefore() {
+        if (this.parser.has("nbf"))
+            return new Date(this.parser.number("nbf"));
+        return null;
+    }
+    /** @param value - The start of validity to set, or `null` to drop the claim. */
+    set notBefore(value) {
+        this.payload.nbf = value ? Math.floor(value.getTime() / MS_PER_SECOND) : undefined;
+    }
+    /**
+     * The `sub` claim: who the token is about.
+     *
+     * @returns The subject, or `null` when the claim is absent.
+     */
+    get subject() {
+        if (this.parser.has("sub"))
+            return this.parser.string("sub");
+        return null;
+    }
+    /** @param value - The subject to set, or `null` to drop the claim. */
+    set subject(value) {
+        this.payload.sub = value ?? undefined;
+    }
+    /**
+     * Signs this token.
+     *
+     * @param algorithm - Algorithm to sign with; also selects the key.
+     * @param jwks - Candidate keys, newest first.
+     * @returns The compact-serialized token.
+     * @example
+     * let signed = await token.sign(JWK.Algorithm.ES256, await JWK.signingKeys(storage));
+     */
+    sign(algorithm, jwks) {
+        return JWT.sign(this, algorithm, jwks);
+    }
+    /**
+     * The claims a subclass exposes, as a plain object.
+     *
+     * Reads the getters declared directly on the instance's own prototype, so what
+     * comes out is the subclass's view of the token: the claims it models.
+     *
+     * @returns Each own getter's name mapped to its value.
+     */
+    toJSON() {
+        let descriptors = Object.getOwnPropertyDescriptors(Object.getPrototypeOf(this));
+        let keys = Object.keys(descriptors).filter((key) => typeof descriptors[key]?.get === "function");
+        return keys.reduce((acc, key) => {
+            acc[key] = this[key];
+            return acc;
+        }, {});
+    }
+    /**
+     * Signs a token with the first key matching the algorithm.
+     *
+     * The keys arrive newest first, so the newest signs while older ones stay
+     * published to verify what they already signed, keyed by the `kid` header.
+     *
+     * @param jwt - The token to sign.
+     * @param algorithm - Algorithm to sign with; also selects the key.
+     * @param jwks - Candidate keys, newest first.
+     * @returns The compact-serialized token.
+     * @throws When no key in the set was generated for that algorithm.
+     */
+    static sign(jwt, algorithm, jwks) {
+        let key = jwks.find((candidate) => candidate.alg === algorithm);
+        if (!key)
+            throw new Error(`No key available to sign JWT with algorithm ${algorithm}`);
+        return new jose.SignJWT(jwt.payload)
+            .setProtectedHeader({ alg: algorithm, typ: "JWT", kid: key.id })
+            .sign(key.private);
+    }
+    /**
+     * Verifies a token and returns it as an instance of the class this was called on.
+     *
+     * The key is picked by the token's `kid`, letting a retired key keep verifying
+     * what it already signed through a rotation; `algorithms` pins accepted ones.
+     *
+     * @param token - The compact-serialized token.
+     * @param jwks - The keys themselves, or a resolver from `JWK.importLocal` /
+     *   `JWK.importRemote`. Keys given directly are wrapped into a local key set so
+     *   they go through the same per-token `kid` selection a resolver would apply.
+     * @param options - Expected issuer, audience, algorithms, clock tolerance, and so on.
+     * @returns The verified token.
+     * @throws When the set offers no key for the token, or when a check on it fails.
+     * @example
+     * let idToken = await IdToken.verify(raw, keys, {
+     * 	issuer,
+     * 	audience: clientId,
+     * 	algorithms: [JWK.Algorithm.ES256],
+     * });
+     */
+    static async verify(token, jwks, options) {
+        if (Array.isArray(jwks) && jwks.length === 0) {
+            throw new Error("No key available to verify JWT");
+        }
+        let key = Array.isArray(jwks)
+            ? jose.createLocalJWKSet({ keys: jwks.map((candidate) => candidate.jwk) })
+            : jwks;
+        let result = await jose.jwtVerify(token, key, options);
+        return new this(result.payload);
+    }
+    /**
+     * Reads a token's claims as the token presents them, prior to verification.
+     *
+     * Use it to decide how to verify a token — reading `iss` to pick a JWKS, for
+     * instance — and let `verify` be what every decision about the request rests on.
+     *
+     * @param token - The compact-serialized token.
+     * @returns The decoded token, as an instance of the class this was called on.
+     */
+    static decode(token) {
+        return new this(jose.decodeJwt(token));
+    }
+}

package/dist/key-storage.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The storage contract `JWK.signingKeys` needs, and nothing more.
+ *
+ * Signing keys have to outlive the isolate that generated them and be readable by
+ * every isolate that issues tokens, so they live in a bucket rather than in memory.
+ * This declares only the three operations that requires — read one, write one, page
+ * through them — so any object store can back it without this package taking on a
+ * dependency on a particular storage client.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Paging and filtering options for a {@link KeyStorage} listing. */
+export interface KeyStorageListOptions {
+    /** Opaque continuation token from a previous listing. */
+    cursor?: string;
+    /** Maximum number of entries to return in this page. */
+    limit?: number;
+    /** Only return entries whose key starts with this string. */
+    prefix?: string;
+}
+/** One page of a {@link KeyStorage} listing. */
+export interface KeyStorageListResult {
+    /** Continuation token, absent once the listing is exhausted. */
+    cursor?: string;
+    /** The entries in this page, keys only. */
+    files: {
+        key: string;
+    }[];
+}
+/**
+ * A key/value store of `File` objects, narrowed to what signing-key rotation uses.
+ *
+ * A key, once written, stays kept, so every token it signed stays
+ * verifiable; methods may be sync or a promise, fitting tests and production.
+ */
+export interface KeyStorage {
+    /**
+     * Reads the file stored under a key.
+     *
+     * @param key - The storage key to read.
+     * @returns The file, or `null` when nothing is stored under that key.
+     */
+    get(key: string): File | null | Promise<File | null>;
+    /**
+     * Pages through the stored keys.
+     *
+     * @param options - Prefix, page size, and continuation token.
+     * @returns One page of entries, plus a cursor when more remain.
+     */
+    list(options?: KeyStorageListOptions): KeyStorageListResult | Promise<KeyStorageListResult>;
+    /**
+     * Writes a file under a key, replacing anything already there.
+     *
+     * @param key - The storage key to write to.
+     * @param file - The file to store.
+     */
+    set(key: string, file: File): void | Promise<void>;
+}

package/dist/key-storage.js

@@ -0,0 +1,12 @@
+/**
+ * The storage contract `JWK.signingKeys` needs, and nothing more.
+ *
+ * Signing keys have to outlive the isolate that generated them and be readable by
+ * every isolate that issues tokens, so they live in a bucket rather than in memory.
+ * This declares only the three operations that requires — read one, write one, page
+ * through them — so any object store can back it without this package taking on a
+ * dependency on a particular storage client.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/dist/lib/parser.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Type-checked reads over a decoded JWT claim set.
+ *
+ * A JWT payload arrives as `unknown`-shaped JSON, so every claim a token class
+ * exposes has to be both looked up and type-checked before it can be returned.
+ * This module is the one place that does it, and the errors it raises name the
+ * claim and the type mismatch so a malformed token is diagnosable from the log
+ * line alone.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Base class for every failure this parser raises.
+ *
+ * A single base lets a caller distinguish malformed claims from a genuine bug
+ * with one `instanceof` check; subclasses still tell missing from mistyped.
+ */
+export declare class ParserError extends Error {
+    name: string;
+}
+/** Raised when a claim a token class requires is absent from the payload. */
+export declare class MissingKeyError extends ParserError {
+    name: string;
+    /**
+     * Builds the error for an absent claim.
+     *
+     * @param key - Name of the claim that was not present.
+     */
+    constructor(key: string);
+}
+/** Raised when a claim is present but holds a value of the wrong JSON type. */
+export declare class InvalidTypeError extends ParserError {
+    name: string;
+    /**
+     * Builds the error for a claim of an unexpected type.
+     *
+     * @param key - Name of the claim that was read.
+     * @param expected - Type the caller asked for.
+     * @param actual - Type the payload actually carried.
+     */
+    constructor(key: string, expected: string, actual: string);
+}
+/**
+ * Reads values out of a plain object, checking the type of each one.
+ *
+ * Throws on a mismatch, so a `JWT` subclass's getters can return the claim's
+ * own type directly.
+ *
+ * @example
+ * get email(): string {
+ * 	return this.parser.string("email");
+ * }
+ */
+export declare class ObjectParser {
+    #private;
+    /**
+     * Wraps an object for type-checked reads.
+     *
+     * @param value - The decoded payload to read from.
+     * @throws {InvalidTypeError} When the value is not a non-null object.
+     */
+    constructor(value: unknown);
+    /**
+     * Reports whether a key is present, including when it holds `null`.
+     *
+     * This is the guard an optional claim needs, since every typed read below throws
+     * on a key that is not there.
+     *
+     * @param key - Claim name to look for.
+     * @returns Whether the key exists on the object.
+     * @example
+     * if (this.parser.has("nonce")) return this.parser.string("nonce");
+     */
+    has(key: string): boolean;
+    /**
+     * Reads a key exactly as stored, leaving the type check to the caller.
+     *
+     * @param key - Claim name to read.
+     * @returns The raw value, which the typed readers narrow.
+     * @throws {MissingKeyError} When the key is not present.
+     */
+    get(key: string): unknown;
+    /**
+     * Reads a key as a string.
+     *
+     * @param key - Claim name to read.
+     * @returns The string value.
+     * @throws {MissingKeyError} When the key is not present.
+     * @throws {InvalidTypeError} When the value is not a string.
+     * @example
+     * this.parser.string("sub"); // "user-123"
+     */
+    string(key: string): string;
+    /**
+     * Reads a key as a number.
+     *
+     * Time claims (`exp`, `iat`, `nbf`) are numbers in seconds, so this is what the
+     * date-shaped accessors are built on.
+     *
+     * @param key - Claim name to read.
+     * @returns The number value.
+     * @throws {MissingKeyError} When the key is not present.
+     * @throws {InvalidTypeError} When the value is not a number.
+     */
+    number(key: string): number;
+    /**
+     * Reads a key as a boolean.
+     *
+     * Strict: only an actual boolean passes, so a stringly-typed `email_verified`
+     * claim from an identity provider surfaces as a type error.
+     *
+     * @param key - Claim name to read.
+     * @returns The boolean value.
+     * @throws {MissingKeyError} When the key is not present.
+     * @throws {InvalidTypeError} When the value is not a boolean.
+     */
+    boolean(key: string): boolean;
+    /**
+     * Reads a key as a nested object, wrapped for further type-checked reads.
+     *
+     * @param key - Claim name to read.
+     * @returns A parser over the nested object.
+     * @throws {MissingKeyError} When the key is not present.
+     * @throws {InvalidTypeError} When the value is not a non-null object.
+     * @example
+     * this.parser.object("events").has("http://schemas.openid.net/event/backchannel-logout");
+     */
+    object(key: string): ObjectParser;
+    /**
+     * Returns the wrapped object, so a claim set can be handed on whole.
+     *
+     * @returns The object this parser reads from.
+     */
+    valueOf(): object;
+}