@sdxc/jwt 0.0.0-pre.1

package/dist/jwk.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Key material for the JWTs this monorepo issues and verifies.
+ *
+ * Covers the whole life of a signing key: generating a pair, serializing it so it
+ * survives in a bucket or a database row, importing it back into `CryptoKey` objects,
+ * publishing the public half as a JWKS, and turning someone else's JWKS — local or
+ * remote — into the resolver a token is verified through.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import * as jose from "jose";
+import type { KeyStorage } from "./key-storage.js";
+import * as SignatureAlgorithm from "./algorithm.js";
+/**
+ * Everything about the keys a token is signed with or verified against.
+ *
+ * Modeled as a namespace rather than loose exports because the names only make
+ * sense qualified: `JWK.KeyPair`, `JWK.generateKeyPair`, `JWK.toJSON`.
+ */
+export declare namespace JWK {
+    /**
+     * ES256 is issued here; RS256 verifies tokens from upstream identity
+     * providers; EdDSA derives its nonce from the key and message, keeping the
+     * ECDSA nonce-reuse leak that exposes a private key out of reach.
+     */
+    const Algorithm: typeof SignatureAlgorithm;
+    /** One of the supported signature algorithms. */
+    type Algorithm = (typeof SignatureAlgorithm)[keyof typeof SignatureAlgorithm];
+    /** A key pair imported into a usable form, with the public half in JWK format. */
+    interface KeyPair {
+        /** Identifier published as the `kid`, and written into every token header. */
+        id: string;
+        /** Algorithm the pair was generated for. */
+        alg: Algorithm;
+        /** Public half, used to verify. */
+        public: jose.CryptoKey;
+        /** Private half, used to sign. */
+        private: jose.CryptoKey;
+        /** When the pair was generated, used to prefer the newest key. */
+        created: Date;
+        /** When the pair stopped being usable for signing, if it has. */
+        expired?: Date;
+        /** Public half in JWK form, carrying `kid` and `use`, ready to publish. */
+        jwk: jose.JWK;
+    }
+    /**
+     * A key pair in the form it is stored and transported in.
+     *
+     * PEM strings and a millisecond timestamp, so the whole pair survives
+     * `JSON.stringify` into a bucket or a text column with nothing lost.
+     */
+    interface SerializedKeyPair {
+        /** Identifier that becomes the `kid`. */
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        /** Algorithm the pair was generated for. */
+        alg: Algorithm;
+        /** Public key in SPKI PEM form. */
+        publicKey: string;
+        /** Private key in PKCS#8 PEM form. */
+        privateKey: string;
+        /** Generation time in milliseconds since the epoch. */
+        created: number;
+        /** Expiry, when the pair has been retired from signing. */
+        expired?: Date;
+    }
+    /**
+     * The half of a key pair `JWT.sign` needs.
+     *
+     * A structural subset of `KeyPair`, so a full pair is accepted wherever this is
+     * expected, and a caller holding only a private key already has enough to sign.
+     */
+    interface SigningKey {
+        /** Identifier written into the token header as `kid`. */
+        id: string;
+        /** Algorithm the key was generated for, matched against the requested one. */
+        alg: string;
+        /** The private half. */
+        private: jose.CryptoKey;
+    }
+    /**
+     * The half of a key pair `JWT.verify` needs when the keys are already in hand.
+     *
+     * A single `jwk` field carries both the key material and the `kid` a token's
+     * header is matched against — everything selecting a key from a set takes.
+     */
+    interface VerificationKey {
+        jwk: jose.JWK;
+    }
+    /**
+     * Answers with the key a given token's header calls for.
+     *
+     * What `importLocal` and `importRemote` hand back: the key set is only consulted
+     * once there is a token to consult it about.
+     */
+    type KeyResolver = jose.JWTVerifyGetKey;
+    /** Where `JWT.verify` can find a token's key: the keys themselves, or a resolver. */
+    type VerificationKeys = KeyResolver | VerificationKey[];
+    /** Request headers, timeouts, and cache windows a remote key set can be given. */
+    type RemoteOptions = jose.RemoteJWKSetOptions;
+    /**
+     * Generates a new key pair in serialized form.
+     *
+     * Generated extractable, so the pair survives being written to storage and
+     * every isolate can import it to verify tokens any other isolate signed.
+     *
+     * @param alg - Algorithm to generate for.
+     * @returns The pair as PEM strings, ready to store.
+     * @example
+     * let serialized = await JWK.generateKeyPair(JWK.Algorithm.ES256);
+     * await db.create(table, { id: serialized.id, private_key: serialized.privateKey });
+     */
+    function generateKeyPair(alg: Algorithm): Promise<SerializedKeyPair>;
+    /**
+     * Imports a stored key pair back into usable `CryptoKey` objects.
+     *
+     * The public half imports extractable, ready to re-export as a JWK; the
+     * private half imports non-extractable, keeping it confined to the runtime.
+     *
+     * @param value - A pair previously produced by `generateKeyPair`.
+     * @returns The pair with both halves imported and the public JWK attached.
+     * @example
+     * let keyPair = await JWK.importKeyPair({ id, alg, publicKey, privateKey, created });
+     */
+    function importKeyPair(value: SerializedKeyPair): Promise<KeyPair>;
+    /**
+     * Loads the signing keys out of storage, generating one on first use.
+     *
+     * Every stored key comes back newest first; finding none usable mints an ES256
+     * key and re-reads storage, so every isolate converges on the same result.
+     *
+     * @param storage - Where key files live.
+     * @returns The usable key pairs, newest first.
+     * @example
+     * let keys = await JWK.signingKeys(storage);
+     * let jwks = JWK.toJSON(keys);
+     */
+    function signingKeys(storage: KeyStorage): Promise<KeyPair[]>;
+    /**
+     * Resolves a token's key by matching its header's `kid`, key type, curve,
+     * algorithm, and use against the set; anything but exactly one match is an
+     * error. Kept async so callers await it the same way as `importRemote`.
+     *
+     * @param jwks - The key set, as served by a JWKS endpoint.
+     * @returns A resolver that answers with the key a given token names.
+     * @example
+     * let keys = await JWK.importLocal(jwks);
+     * let token = await IdToken.verify(raw, keys, { issuer, audience, algorithms });
+     */
+    function importLocal(jwks: jose.JSONWebKeySet): Promise<KeyResolver>;
+    /**
+     * Points a resolver at a JWKS endpoint, fetched on first use and re-fetched
+     * at most once per cooldown window when a token names an unseen `kid` —
+     * carrying a relying party across a key rotation between deploys.
+     *
+     * @param url - The JWKS endpoint.
+     * @param options - Request headers, timeouts, and cache windows.
+     * @returns A resolver that answers with the key a given token names.
+     * @example
+     * let keys = JWK.importRemote(new URL(jwksUrl));
+     */
+    function importRemote(url: URL, options?: RemoteOptions): Promise<KeyResolver>;
+    /**
+     * Renders key pairs as the JSON a `/.well-known/jwks.json` endpoint serves.
+     *
+     * Each entry keeps only the public parameters its key type publishes here,
+     * plus `kid` and `alg`, keeping unvetted private material out of the set.
+     *
+     * @param keys - The key pairs to publish.
+     * @returns The JWKS document.
+     * @throws When a pair's key type has no published shape on record.
+     * @example
+     * return Response.json(JWK.toJSON(await JWK.signingKeys(storage)));
+     */
+    function toJSON(keys: KeyPair[]): jose.JSONWebKeySet;
+}

package/dist/jwk.js

@@ -0,0 +1,210 @@
+/**
+ * Key material for the JWTs this monorepo issues and verifies.
+ *
+ * Covers the whole life of a signing key: generating a pair, serializing it so it
+ * survives in a bucket or a database row, importing it back into `CryptoKey` objects,
+ * publishing the public half as a JWKS, and turning someone else's JWKS — local or
+ * remote — into the resolver a token is verified through.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import * as jose from "jose";
+import * as SignatureAlgorithm from "./algorithm.js";
+/**
+ * Prefix every stored signing key is written under.
+ *
+ * Listing by prefix is the only index this package has over the bucket, so the
+ * prefix is what separates key files from anything else sharing the bucket.
+ */
+const SIGNING_KEY_PREFIX = "signing:key";
+/**
+ * Page size used while walking the stored keys, well under the 1000-item cap
+ * an object store typically enforces, so a page is rarely followed by a second.
+ */
+const SCAN_PAGE_SIZE = 100;
+/**
+ * The public parameters a JWKS entry carries, one key type at a time.
+ * Rebuilding an entry only from the fields listed here keeps private components
+ * — `d`, and an RSA key's `p`, `q`, `dp`, `dq`, `qi` — out of a published set.
+ */
+const PUBLISHED_JWK_FIELDS = {
+    EC: ({ crv, x, y }) => ({ crv, x, y }),
+    OKP: ({ crv, x }) => ({ crv, x }),
+    RSA: ({ e, n }) => ({ e, n }),
+};
+/**
+ * Everything about the keys a token is signed with or verified against.
+ *
+ * Modeled as a namespace rather than loose exports because the names only make
+ * sense qualified: `JWK.KeyPair`, `JWK.generateKeyPair`, `JWK.toJSON`.
+ */
+export var JWK;
+(function (JWK) {
+    /**
+     * ES256 is issued here; RS256 verifies tokens from upstream identity
+     * providers; EdDSA derives its nonce from the key and message, keeping the
+     * ECDSA nonce-reuse leak that exposes a private key out of reach.
+     */
+    JWK.Algorithm = SignatureAlgorithm;
+    /**
+     * Generates a new key pair in serialized form.
+     *
+     * Generated extractable, so the pair survives being written to storage and
+     * every isolate can import it to verify tokens any other isolate signed.
+     *
+     * @param alg - Algorithm to generate for.
+     * @returns The pair as PEM strings, ready to store.
+     * @example
+     * let serialized = await JWK.generateKeyPair(JWK.Algorithm.ES256);
+     * await db.create(table, { id: serialized.id, private_key: serialized.privateKey });
+     */
+    async function generateKeyPair(alg) {
+        let key = await jose.generateKeyPair(alg, { extractable: true });
+        return {
+            id: crypto.randomUUID(),
+            publicKey: await jose.exportSPKI(key.publicKey),
+            privateKey: await jose.exportPKCS8(key.privateKey),
+            created: Date.now(),
+            alg,
+        };
+    }
+    JWK.generateKeyPair = generateKeyPair;
+    /**
+     * Imports a stored key pair back into usable `CryptoKey` objects.
+     *
+     * The public half imports extractable, ready to re-export as a JWK; the
+     * private half imports non-extractable, keeping it confined to the runtime.
+     *
+     * @param value - A pair previously produced by `generateKeyPair`.
+     * @returns The pair with both halves imported and the public JWK attached.
+     * @example
+     * let keyPair = await JWK.importKeyPair({ id, alg, publicKey, privateKey, created });
+     */
+    async function importKeyPair(value) {
+        let publicKey = await jose.importSPKI(value.publicKey, value.alg, { extractable: true });
+        let privateKey = await jose.importPKCS8(value.privateKey, value.alg);
+        let jwk = await jose.exportJWK(publicKey);
+        jwk.kid = value.id;
+        jwk.use = "sig";
+        return {
+            id: value.id,
+            alg: value.alg,
+            created: new Date(value.created),
+            expired: value.expired,
+            public: publicKey,
+            private: privateKey,
+            jwk,
+        };
+    }
+    JWK.importKeyPair = importKeyPair;
+    /**
+     * Loads the signing keys out of storage, generating one on first use.
+     *
+     * Every stored key comes back newest first; finding none usable mints an ES256
+     * key and re-reads storage, so every isolate converges on the same result.
+     *
+     * @param storage - Where key files live.
+     * @returns The usable key pairs, newest first.
+     * @example
+     * let keys = await JWK.signingKeys(storage);
+     * let jwks = JWK.toJSON(keys);
+     */
+    async function signingKeys(storage) {
+        let results = [];
+        for await (let entry of scan(storage, SIGNING_KEY_PREFIX)) {
+            let file = await storage.get(entry.key);
+            if (!file)
+                continue;
+            results.push(await importKeyPair(JSON.parse(await file.text())));
+        }
+        results.sort((a, b) => b.created.getTime() - a.created.getTime());
+        if (results.some((item) => !item.expired))
+            return results;
+        await storeKeyPair(storage, SIGNING_KEY_PREFIX, await generateKeyPair(JWK.Algorithm.ES256));
+        return await signingKeys(storage);
+    }
+    JWK.signingKeys = signingKeys;
+    /**
+     * Resolves a token's key by matching its header's `kid`, key type, curve,
+     * algorithm, and use against the set; anything but exactly one match is an
+     * error. Kept async so callers await it the same way as `importRemote`.
+     *
+     * @param jwks - The key set, as served by a JWKS endpoint.
+     * @returns A resolver that answers with the key a given token names.
+     * @example
+     * let keys = await JWK.importLocal(jwks);
+     * let token = await IdToken.verify(raw, keys, { issuer, audience, algorithms });
+     */
+    // biome-ignore lint/suspicious/useAwait: symmetry with `importRemote`, see above.
+    async function importLocal(jwks) {
+        return jose.createLocalJWKSet(jwks);
+    }
+    JWK.importLocal = importLocal;
+    /**
+     * Points a resolver at a JWKS endpoint, fetched on first use and re-fetched
+     * at most once per cooldown window when a token names an unseen `kid` —
+     * carrying a relying party across a key rotation between deploys.
+     *
+     * @param url - The JWKS endpoint.
+     * @param options - Request headers, timeouts, and cache windows.
+     * @returns A resolver that answers with the key a given token names.
+     * @example
+     * let keys = JWK.importRemote(new URL(jwksUrl));
+     */
+    // biome-ignore lint/suspicious/useAwait: async for the reason given on `importLocal`.
+    async function importRemote(url, options) {
+        return jose.createRemoteJWKSet(url, options);
+    }
+    JWK.importRemote = importRemote;
+    /**
+     * Renders key pairs as the JSON a `/.well-known/jwks.json` endpoint serves.
+     *
+     * Each entry keeps only the public parameters its key type publishes here,
+     * plus `kid` and `alg`, keeping unvetted private material out of the set.
+     *
+     * @param keys - The key pairs to publish.
+     * @returns The JWKS document.
+     * @throws When a pair's key type has no published shape on record.
+     * @example
+     * return Response.json(JWK.toJSON(await JWK.signingKeys(storage)));
+     */
+    function toJSON(keys) {
+        return {
+            keys: keys.map(({ alg, id, jwk }) => {
+                let publish = jwk.kty ? PUBLISHED_JWK_FIELDS[jwk.kty] : undefined;
+                if (!publish)
+                    throw new Error(`Cannot publish a key of type ${String(jwk.kty)}`);
+                return { ...publish(jwk), kty: jwk.kty, kid: id, alg };
+            }),
+        };
+    }
+    JWK.toJSON = toJSON;
+    /**
+     * Walks every stored key under a prefix, page by page.
+     *
+     * Every page's entries are yielded, including the first, so the earliest key
+     * file stays included, and any returned cursor is followed to the next page.
+     *
+     * @param storage - Where key files live.
+     * @param prefix - Key prefix to walk.
+     * @yields Every listed entry, in the order the store returns them.
+     */
+    async function* scan(storage, prefix) {
+        let cursor;
+        do {
+            let result = await storage.list({ prefix, cursor, limit: SCAN_PAGE_SIZE });
+            yield* result.files;
+            cursor = result.cursor;
+        } while (cursor);
+    }
+    /**
+     * @param storage - Where key files live.
+     * @param prefix - Key prefix to write under.
+     * @param serialized - The pair to store.
+     */
+    async function storeKeyPair(storage, prefix, serialized) {
+        let file = new File([JSON.stringify(serialized)], "jwks.json", { type: "application/json" });
+        await storage.set(`${prefix}:${serialized.id}`, file);
+    }
+})(JWK || (JWK = {}));

package/dist/jwt.d.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 type { DurationString } from "@sdxc/duration";
+import * as jose from "jose";
+import type { JWK } from "./jwk.js";
+import { ObjectParser } from "./lib/parser.js";
+/**
+ * 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 declare class JWT implements jose.JWTPayload {
+    /** The raw claim set, readable whole for callers that want the payload itself. */
+    readonly payload: JWT.Payload;
+    /** Type-checked reads over `payload`, for the accessors a subclass defines. */
+    protected parser: ObjectParser;
+    /**
+     * Any claim, by name, for the ones no accessor covers.
+     *
+     * Required to satisfy `jose.JWTPayload`, and it is what the proxy below fills in.
+     */
+    [propName: string]: unknown;
+    /**
+     * 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?: JWT.PayloadInput);
+    /**
+     * The `aud` claim: who the token is for.
+     *
+     * @returns One audience, several, or `null` when the claim is absent or malformed.
+     */
+    get audience(): string | string[] | null;
+    /** @param value - The audience to set, or `null` to drop the claim. */
+    set audience(value: string | string[] | null);
+    /**
+     * The `exp` claim, as stored.
+     *
+     * @returns The raw claim value, or `null` when the token does not expire.
+     */
+    get expirationTime(): number | null;
+    /** @param value - The expiration to set, or `null` to drop the claim. */
+    set expirationTime(value: number | null);
+    /**
+     * 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(): number | null;
+    /**
+     * The expiration as a `Date`.
+     *
+     * @returns The expiry, or `null` when the token does not expire.
+     */
+    get expiresAt(): Date | null;
+    /**
+     * 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(): boolean;
+    /**
+     * The `iat` claim: when the token was issued.
+     *
+     * @returns The issuance time, or `null` when the claim is absent.
+     */
+    get issuedAt(): Date | null;
+    /** @param value - The issuance time to set, or `null` to drop the claim. */
+    set issuedAt(value: Date | null);
+    /**
+     * The `iss` claim: who issued the token.
+     *
+     * @returns The issuer, or `null` when the claim is absent.
+     */
+    get issuer(): string | null;
+    /** @param value - The issuer to set, or `null` to drop the claim. */
+    set issuer(value: string | null);
+    /**
+     * The `jti` claim: the token's unique identifier.
+     *
+     * @returns The identifier, or `null` when the claim is absent.
+     */
+    get id(): string | null;
+    /** @param value - The identifier to set, or `null` to drop the claim. */
+    set id(value: string | null);
+    /**
+     * The `nbf` claim: when the token starts being valid.
+     *
+     * @returns The start of validity, or `null` when the claim is absent.
+     */
+    get notBefore(): Date | null;
+    /** @param value - The start of validity to set, or `null` to drop the claim. */
+    set notBefore(value: Date | null);
+    /**
+     * The `sub` claim: who the token is about.
+     *
+     * @returns The subject, or `null` when the claim is absent.
+     */
+    get subject(): string | null;
+    /** @param value - The subject to set, or `null` to drop the claim. */
+    set subject(value: string | null);
+    /**
+     * 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: JWK.Algorithm, jwks: JWK.SigningKey[]): Promise<string>;
+    /**
+     * 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(): Record<string, unknown>;
+    /**
+     * 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: JWT, algorithm: JWK.Algorithm, jwks: JWK.SigningKey[]): Promise<string>;
+    /**
+     * 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 verify<M extends JWT>(this: new (payload: JWT.Payload) => M, token: string, jwks: JWK.VerificationKeys, options?: JWT.VerifyOptions): Promise<M>;
+    /**
+     * 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<M extends JWT>(this: new (payload: JWT.Payload) => M, token: string): M;
+}
+export declare namespace JWT {
+    /** A JWT claim set, with every time claim as the seconds since the epoch. */
+    type Payload = jose.JWTPayload;
+    /**
+     * A claim set as it may be written, where a time claim can be a length of time.
+     *
+     * `exp: "1h"` is an hour from the moment the token is built; a number stays
+     * seconds since the epoch. Either way, `payload` holds the resolved seconds.
+     */
+    type PayloadInput = Omit<Payload, "exp" | "iat" | "nbf"> & {
+        exp?: number | DurationString;
+        iat?: number | DurationString;
+        nbf?: number | DurationString;
+    };
+    /** The checks `JWT.verify` can be asked to run beyond the signature. */
+    type VerifyOptions = jose.JWTVerifyOptions;
+}