@saurbit/oauth2-jwt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saurbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @saurbit/oauth2-jwt
+
+JWT utilities and JWKS authority for [`@saurbit/oauth2`](https://jsr.io/@saurbit/oauth2). Wraps
+[jose](https://github.com/panva/jose) to provide ready-made implementations of the JWT-related
+interfaces required by `@saurbit/oauth2`.
+
+## Installation
+
+**Node.js / Bun**
+
+```sh
+npm install @saurbit/oauth2-jwt
+# or
+yarn add @saurbit/oauth2-jwt
+# or
+pnpm add @saurbit/oauth2-jwt
+# or
+bun add @saurbit/oauth2-jwt
+```
+
+**Deno / JSR**
+
+```sh
+deno add jsr:@saurbit/oauth2-jwt
+```
+
+## JWT Utilities
+
+`@saurbit/oauth2-jwt` provides three ready-made functions that satisfy the `JwtVerify`, `JwtDecode`,
+and `JwkVerify` interfaces expected by `@saurbit/oauth2`.
+
+### `verifyJwt` and `decodeJwt`
+
+Used by the `ClientSecretJwt` and `PrivateKeyJwt` client authentication methods.
+
+**`ClientSecretJwt`**
+
+```ts
+import { ClientSecretJwt } from "@saurbit/oauth2";
+import { decodeJwt, verifyJwt } from "@saurbit/oauth2-jwt";
+
+const clientSecretJwt = new ClientSecretJwt(decodeJwt, verifyJwt);
+```
+
+**`PrivateKeyJwt`**
+
+```ts
+import { PrivateKeyJwt } from "@saurbit/oauth2";
+import { decodeJwt, verifyJwt } from "@saurbit/oauth2-jwt";
+
+const privateKeyJwt = new PrivateKeyJwt(decodeJwt, verifyJwt);
+```
+
+### `verifyJwk`
+
+Used by `DPoPTokenType` for Demonstration of Proof-of-Possession token validation.
+
+```ts
+import { createInMemoryReplayStore, DPoPTokenType } from "@saurbit/oauth2";
+import { verifyJwk } from "@saurbit/oauth2-jwt";
+
+const dpop = new DPoPTokenType(verifyJwk, createInMemoryReplayStore());
+```
+
+## JWKS Authority
+
+`JoseJwksAuthority` manages RS256 signing key pairs, signs and verifies JWTs, and returns the JWKS
+endpoint payload. Keys are stored in a `JwksKeyStore` and generated automatically on first use.
+
+### Setup
+
+```ts
+import { createInMemoryKeyStore, JoseJwksAuthority } from "@saurbit/oauth2-jwt";
+
+const store = createInMemoryKeyStore();
+const authority = new JoseJwksAuthority(store, 8.64e+6); // public keys valid for 100 days
+```
+
+### Sign a JWT
+
+```ts
+const { token } = await authority.sign({
+  sub: "user-123",
+  iss: "https://auth.example.com",
+  aud: "my-client",
+  iat: Math.floor(Date.now() / 1000),
+  exp: Math.floor(Date.now() / 1000) + 3600,
+  jti: crypto.randomUUID(),
+});
+```
+
+### Verify a JWT
+
+```ts
+const payload = await authority.verify(token);
+console.log(payload.sub); // "user-123"
+```
+
+### JWKS endpoint
+
+`getJwksEndpointResponse()` returns the set of current public keys in JWKS format, ready to be
+served at a well-known endpoint (e.g. `/.well-known/jwks.json`).
+
+```ts
+// Example with Hono
+app.get("/jwks", async (c) => {
+  return c.json(await authority.getJwksEndpointResponse());
+});
+```
+
+The response has the shape `{ keys: RawKey[] }` and is safe to return directly as JSON.
+
+## Key Rotation
+
+`JwksRotator` manages scheduled key rotation. It compares the current time against the last rotation
+timestamp and generates a new key pair only when the configured interval has elapsed.
+
+Call `checkAndRotateKeys()` at service startup and/or on a recurring schedule (e.g. every hour). If
+a rotation is due a new key pair is generated; otherwise the call is a no-op. During rotation the
+previous public key remains available in the JWKS until its TTL expires, so in-flight tokens
+continue to verify correctly.
+
+### Setup
+
+```ts
+import { createInMemoryKeyStore, JoseJwksAuthority, JwksRotator } from "@saurbit/oauth2-jwt";
+
+const store = createInMemoryKeyStore();
+const authority = new JoseJwksAuthority(store, 8.64e+6); // 100 days key TTL
+
+const rotator = new JwksRotator({
+  keyGenerator: authority,
+  rotatorKeyStore: store,
+  rotationIntervalMs: 7.884e9, // 91 days
+});
+```
+
+### Usage
+
+```ts
+// At startup
+await rotator.checkAndRotateKeys();
+
+// Or on a recurring schedule
+setInterval(async () => {
+  await rotator.checkAndRotateKeys();
+}, 60 * 60 * 1000); // every hour
+```
+
+## License
+
+[MIT](./LICENSE)

package/esm/jose_jwks_authority.d.ts

@@ -0,0 +1,90 @@
+import { JWTPayload } from "jose";
+import { JwksKeyStore, JwtAuthority, RawKey, RSA } from "./types.js";
+/**
+ * JWT authority backed by [jose](https://github.com/panva/jose).
+ *
+ * Manages RS256 signing key pairs, signs and verifies JWTs, and returns the
+ * JWKS endpoint payload. Keys are stored in a {@link JwksKeyStore} and are
+ * generated automatically on first use.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryKeyStore, JoseJwksAuthority } from "@saurbit/oauth2-jwt";
+ *
+ * const store = createInMemoryKeyStore();
+ * const authority = new JoseJwksAuthority(store, 86400); // keys valid for 24 h
+ *
+ * const { token } = await authority.sign({ sub: "user-123", exp: Math.floor(Date.now() / 1000) + 3600 });
+ * const payload = await authority.verify(token);
+ * ```
+ */
+export declare class JoseJwksAuthority implements JwtAuthority {
+    #private;
+    /**
+     * @param store The key store used to manage JWKS keys.
+     * @param ttl Time-to-live for the keys in seconds.
+     */
+    constructor(store: JwksKeyStore, ttl?: number);
+    /**
+     * Retrieves the current set of public keys from the key store.
+     * @returns An object containing the array of public keys.
+     */
+    getPublicKeys(): Promise<{
+        keys: RawKey[];
+    }>;
+    /**
+     * Get current kid for observability/debugging
+     */
+    getCurrentKid(): Promise<string | undefined>;
+    /**
+     * Helps implement the JWKS endpoint by returning the current set of public keys in the expected format.
+     * @returns The current set of public keys in the JWKS format.
+     */
+    getJwksEndpointResponse(): Promise<{
+        keys: RawKey[];
+    }>;
+    /**
+     * Retrieves the public key corresponding to the given "kid" from the JWKS.
+     * @param kid The key ID of the desired public key.
+     * @returns The RSA public key if found, otherwise undefined.
+     */
+    getPublicKey(kid: string): Promise<RSA | undefined>;
+    /**
+     * Generates a new RSA key pair, stores it in the key store with the appropriate metadata
+     * (kid, alg, use), and ensures that the public key is available for JWKS exposure.
+     */
+    generateKeyPair(): Promise<void>;
+    /**
+     * Signs the given payload as a JWT using the current private key.
+     * The "kid" of the signing key is included in the JWT header to allow verifiers
+     * to select the correct public key from the JWKS for verification.
+     * This method ensures that the JWT is signed with a valid key and that
+     * the corresponding public key is available in the JWKS for future verification.
+     * @param payload The payload to be signed as a JWT.
+     * @returns An object containing the signed JWT and the key ID used for signing.
+     */
+    sign(payload: JWTPayload): Promise<{
+        token: string;
+        kid: string;
+    }>;
+    /**
+     * Verifies the given JWT using the appropriate public key from the JWKS based on the "kid" in the JWT header.
+     * It performs additional checks to ensure the integrity and expected structure of the JWT,
+     * such as validating the algorithm and ensuring no unexpected JWK is present in the header.
+     * @param token
+     * @returns
+     */
+    verify<P extends JWTPayload = JWTPayload>(token: string): Promise<P>;
+    /**
+     * Signs multiple payloads with the same private key, returning an array of tokens and their corresponding kids.
+     * This is useful for batch operations where multiple JWTs need to be issued at once,
+     * ensuring they all use the same key and can be verified against the same public key in the JWKS.
+     * @param payloads The array of payloads to be signed as JWTs.
+     * @returns An array of objects containing the signed JWTs and their corresponding key IDs.
+     */
+    signMany(payloads: JWTPayload[]): Promise<{
+        token: string;
+        kid: string;
+    }[]>;
+}
+//# sourceMappingURL=jose_jwks_authority.d.ts.map

package/esm/jose_jwks_authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jose_jwks_authority.d.ts","sourceRoot":"","sources":["../src/jose_jwks_authority.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,UAAU,EAGX,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AA0BrE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAkB,YAAW,YAAY;;IAOpD;;;OAGG;gBACS,KAAK,EAAE,YAAY,EAAE,GAAG,GAAE,MAAc;IAsCpD;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IASlD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAKlD;;;OAGG;IACH,uBAAuB,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAItD;;;;OAIG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IAQzD;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC;;;;;;;;OAQG;IACG,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBxE;;;;;;OAMG;IACG,MAAM,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA+B1E;;;;;;OAMG;IACG,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAyBlF"}

package/esm/jose_jwks_authority.js

@@ -0,0 +1,214 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _JoseJwksAuthority_instances, _JoseJwksAuthority_store, _JoseJwksAuthority_ttl, _JoseJwksAuthority_generateAndStoreKeyPair, _JoseJwksAuthority_getPrivateKey;
+import { exportJWK, generateKeyPair, importJWK, jwtVerify, SignJWT, } from "jose";
+function base64UrlToString(b64url) {
+    // Fast path for Node/Bun
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(b64url, "base64url").toString();
+    }
+    // Convert Base64URL → standard Base64
+    const base64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+    // Add padding if missing
+    const padded = base64.padEnd(base64.length + (4 - (base64.length % 4)) % 4, "=");
+    // Decode
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * JWT authority backed by [jose](https://github.com/panva/jose).
+ *
+ * Manages RS256 signing key pairs, signs and verifies JWTs, and returns the
+ * JWKS endpoint payload. Keys are stored in a {@link JwksKeyStore} and are
+ * generated automatically on first use.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryKeyStore, JoseJwksAuthority } from "@saurbit/oauth2-jwt";
+ *
+ * const store = createInMemoryKeyStore();
+ * const authority = new JoseJwksAuthority(store, 86400); // keys valid for 24 h
+ *
+ * const { token } = await authority.sign({ sub: "user-123", exp: Math.floor(Date.now() / 1000) + 3600 });
+ * const payload = await authority.verify(token);
+ * ```
+ */
+export class JoseJwksAuthority {
+    /**
+     * @param store The key store used to manage JWKS keys.
+     * @param ttl Time-to-live for the keys in seconds.
+     */
+    constructor(store, ttl = 36000) {
+        _JoseJwksAuthority_instances.add(this);
+        _JoseJwksAuthority_store.set(this, void 0);
+        /**
+         * seconds
+         */
+        _JoseJwksAuthority_ttl.set(this, void 0);
+        __classPrivateFieldSet(this, _JoseJwksAuthority_store, store, "f");
+        __classPrivateFieldSet(this, _JoseJwksAuthority_ttl, ttl, "f");
+    }
+    /**
+     * Retrieves the current set of public keys from the key store.
+     * @returns An object containing the array of public keys.
+     */
+    async getPublicKeys() {
+        const publicJwks = await __classPrivateFieldGet(this, _JoseJwksAuthority_store, "f").getPublicKeys();
+        const json = { keys: publicJwks };
+        if (json && "keys" in json && Array.isArray(json.keys)) {
+            json.keys = [...json.keys].reverse();
+        }
+        return json;
+    }
+    /**
+     * Get current kid for observability/debugging
+     */
+    async getCurrentKid() {
+        const key = await __classPrivateFieldGet(this, _JoseJwksAuthority_instances, "m", _JoseJwksAuthority_getPrivateKey).call(this);
+        return key?.kid;
+    }
+    /**
+     * Helps implement the JWKS endpoint by returning the current set of public keys in the expected format.
+     * @returns The current set of public keys in the JWKS format.
+     */
+    getJwksEndpointResponse() {
+        return this.getPublicKeys();
+    }
+    /**
+     * Retrieves the public key corresponding to the given "kid" from the JWKS.
+     * @param kid The key ID of the desired public key.
+     * @returns The RSA public key if found, otherwise undefined.
+     */
+    async getPublicKey(kid) {
+        const keyStore = await this.getPublicKeys();
+        const key = keyStore.keys.find((k) => k.kid === kid);
+        if (!key)
+            return undefined;
+        if (key.kty !== "RSA")
+            return undefined;
+        return key;
+    }
+    /**
+     * Generates a new RSA key pair, stores it in the key store with the appropriate metadata
+     * (kid, alg, use), and ensures that the public key is available for JWKS exposure.
+     */
+    async generateKeyPair() {
+        await __classPrivateFieldGet(this, _JoseJwksAuthority_instances, "m", _JoseJwksAuthority_generateAndStoreKeyPair).call(this);
+    }
+    /**
+     * Signs the given payload as a JWT using the current private key.
+     * The "kid" of the signing key is included in the JWT header to allow verifiers
+     * to select the correct public key from the JWKS for verification.
+     * This method ensures that the JWT is signed with a valid key and that
+     * the corresponding public key is available in the JWKS for future verification.
+     * @param payload The payload to be signed as a JWT.
+     * @returns An object containing the signed JWT and the key ID used for signing.
+     */
+    async sign(payload) {
+        const key = await __classPrivateFieldGet(this, _JoseJwksAuthority_instances, "m", _JoseJwksAuthority_getPrivateKey).call(this);
+        if (key.kty !== "RSA") {
+            throw new Error("Invalid key type, expected RSA");
+        }
+        if (!key.kid) {
+            throw new Error('Key is missing "kid" property');
+        }
+        const privateKey = await importJWK(key, "RS256");
+        const token = await new SignJWT(payload)
+            .setProtectedHeader({ typ: "jwt", alg: "RS256", kid: key.kid })
+            .sign(privateKey);
+        return { token, kid: key.kid };
+    }
+    /**
+     * Verifies the given JWT using the appropriate public key from the JWKS based on the "kid" in the JWT header.
+     * It performs additional checks to ensure the integrity and expected structure of the JWT,
+     * such as validating the algorithm and ensuring no unexpected JWK is present in the header.
+     * @param token
+     * @returns
+     */
+    async verify(token) {
+        const [header] = token.split(".");
+        if (!header)
+            throw new Error("Invalid JWT format");
+        const parsedHeader = JSON.parse(base64UrlToString(header));
+        const kid = parsedHeader.kid;
+        if (!kid || typeof kid !== "string")
+            throw new Error('Invalid or missing "kid" in JWT header');
+        const key = await this.getPublicKey(kid);
+        if (!key)
+            throw new Error(`Key with kid "${kid}" not found`);
+        const { payload, protectedHeader } = await jwtVerify(token, key);
+        if (protectedHeader.alg !== "RS256") {
+            throw new Error(`Unexpected algorithm: ${protectedHeader.alg}`);
+        }
+        // additional checks hardening security
+        if ("jwk" in protectedHeader) {
+            throw new Error("Unexpected JWK in header - potential forgery attempt");
+        }
+        if (protectedHeader.typ && protectedHeader.typ.toLowerCase() !== "jwt") {
+            throw new Error(`Unexpected typ: ${protectedHeader.typ}`);
+        }
+        return payload;
+    }
+    /**
+     * Signs multiple payloads with the same private key, returning an array of tokens and their corresponding kids.
+     * This is useful for batch operations where multiple JWTs need to be issued at once,
+     * ensuring they all use the same key and can be verified against the same public key in the JWKS.
+     * @param payloads The array of payloads to be signed as JWTs.
+     * @returns An array of objects containing the signed JWTs and their corresponding key IDs.
+     */
+    async signMany(payloads) {
+        const key = await __classPrivateFieldGet(this, _JoseJwksAuthority_instances, "m", _JoseJwksAuthority_getPrivateKey).call(this);
+        if (key.kty !== "RSA") {
+            throw new Error("Invalid key type, expected RSA");
+        }
+        if (!key.kid) {
+            throw new Error('Key is missing "kid" property');
+        }
+        const privateKey = await importJWK(key, "RS256");
+        const result = [];
+        for (const payload of payloads) {
+            const token = await new SignJWT(payload)
+                .setProtectedHeader({ typ: "jwt", alg: "RS256", kid: key.kid })
+                .sign(privateKey);
+            result.push({ token, kid: key.kid });
+        }
+        return result;
+    }
+}
+_JoseJwksAuthority_store = new WeakMap(), _JoseJwksAuthority_ttl = new WeakMap(), _JoseJwksAuthority_instances = new WeakSet(), _JoseJwksAuthority_generateAndStoreKeyPair = async function _JoseJwksAuthority_generateAndStoreKeyPair() {
+    const { publicKey, privateKey } = await generateKeyPair("RS256", {
+        modulusLength: 2048,
+        extractable: true,
+    });
+    // Convert to JWK format and add necessary properties
+    const privateJwk = await exportJWK(privateKey);
+    const publicJwk = await exportJWK(publicKey);
+    const kid = crypto.randomUUID();
+    privateJwk.kid = kid;
+    privateJwk.alg = "RS256";
+    privateJwk.use = "sig";
+    publicJwk.kid = kid;
+    publicJwk.alg = "RS256";
+    publicJwk.use = "sig";
+    await __classPrivateFieldGet(this, _JoseJwksAuthority_store, "f").storeKeyPair(kid, privateJwk, publicJwk, __classPrivateFieldGet(this, _JoseJwksAuthority_ttl, "f"));
+    return { privateJwk, publicJwk };
+}, _JoseJwksAuthority_getPrivateKey = async function _JoseJwksAuthority_getPrivateKey() {
+    const storedPrivateJwk = await __classPrivateFieldGet(this, _JoseJwksAuthority_store, "f").getPrivateKey();
+    if (storedPrivateJwk) {
+        return storedPrivateJwk;
+    }
+    else {
+        const { privateJwk } = await __classPrivateFieldGet(this, _JoseJwksAuthority_instances, "m", _JoseJwksAuthority_generateAndStoreKeyPair).call(this);
+        return privateJwk;
+    }
+};

package/esm/jwks_key_store.d.ts

@@ -0,0 +1,53 @@
+import type { JwksKeyStore, JwksRotationTimestampStore } from "./types.js";
+/**
+ * In-memory implementation of {@link JwksKeyStore} and {@link JwksRotationTimestampStore}.
+ *
+ * Suitable for single-process deployments and testing. State is not shared
+ * across processes and is lost on restart.
+ *
+ * Use {@link createInMemoryKeyStore} as a convenience factory.
+ */
+export declare class InMemoryKeyStore implements JwksKeyStore, JwksRotationTimestampStore {
+    private privateKey?;
+    private publicKeys;
+    private lastRotation;
+    /**
+     * Stores the current signing key pair. The private key replaces the existing one;
+     * the public key is appended to the list with a computed expiry based on `ttl`.
+     * @param _kid - The key ID (unused by this implementation).
+     * @param privateKey - The private key object to store as the active signing key.
+     * @param publicKey - The public key object to expose in the JWKS.
+     * @param ttl - Time-to-live in seconds for the public key.
+     */
+    storeKeyPair(_kid: string, privateKey: object, publicKey: object, ttl: number): Promise<void>;
+    /**
+     * Retrieves the current private signing key.
+     * @returns The private key object, or `undefined` if no key has been stored yet.
+     */
+    getPrivateKey(): Promise<object | undefined>;
+    /**
+     * Retrieves all public keys that have not yet expired.
+     * Expired keys are automatically pruned from the in-memory list on each call.
+     * @returns An array of non-expired public key objects.
+     */
+    getPublicKeys(): Promise<object[]>;
+    /**
+     * Retrieves the Unix timestamp (in milliseconds) of the last key rotation.
+     * @returns The timestamp of the last rotation, or `0` if no rotation has occurred.
+     */
+    getLastRotationTimestamp(): Promise<number>;
+    /**
+     * Stores the Unix timestamp (in milliseconds) of the most recent key rotation.
+     * @param msDate - The timestamp to persist.
+     */
+    setLastRotationTimestamp(msDate: number): Promise<void>;
+}
+/**
+ * Creates a new {@link InMemoryKeyStore} instance.
+ *
+ * Convenience factory for use with {@link JoseJwksAuthority} and {@link JwksRotator}.
+ *
+ * @returns A fresh in-memory key store with no keys stored.
+ */
+export declare function createInMemoryKeyStore(): InMemoryKeyStore;
+//# sourceMappingURL=jwks_key_store.d.ts.map

package/esm/jwks_key_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks_key_store.d.ts","sourceRoot":"","sources":["../src/jwks_key_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,YAAY,EAAE,0BAA0B;IAC/E,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,YAAY,CAAa;IAEjC;;;;;;;OAOG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAIlD;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMxC;;;OAGG;IACG,wBAAwB,IAAI,OAAO,CAAC,MAAM,CAAC;IAIjD;;;OAGG;IACG,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD"}

package/esm/jwks_key_store.js

@@ -0,0 +1,86 @@
+/**
+ * In-memory implementation of {@link JwksKeyStore} and {@link JwksRotationTimestampStore}.
+ *
+ * Suitable for single-process deployments and testing. State is not shared
+ * across processes and is lost on restart.
+ *
+ * Use {@link createInMemoryKeyStore} as a convenience factory.
+ */
+export class InMemoryKeyStore {
+    constructor() {
+        Object.defineProperty(this, "privateKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "publicKeys", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "lastRotation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    /**
+     * Stores the current signing key pair. The private key replaces the existing one;
+     * the public key is appended to the list with a computed expiry based on `ttl`.
+     * @param _kid - The key ID (unused by this implementation).
+     * @param privateKey - The private key object to store as the active signing key.
+     * @param publicKey - The public key object to expose in the JWKS.
+     * @param ttl - Time-to-live in seconds for the public key.
+     */
+    async storeKeyPair(_kid, privateKey, publicKey, ttl) {
+        this.privateKey = privateKey;
+        const exp = Date.now() + ttl * 1000;
+        this.publicKeys.push({ key: publicKey, exp });
+        return await Promise.resolve();
+    }
+    /**
+     * Retrieves the current private signing key.
+     * @returns The private key object, or `undefined` if no key has been stored yet.
+     */
+    async getPrivateKey() {
+        return await Promise.resolve(this.privateKey);
+    }
+    /**
+     * Retrieves all public keys that have not yet expired.
+     * Expired keys are automatically pruned from the in-memory list on each call.
+     * @returns An array of non-expired public key objects.
+     */
+    async getPublicKeys() {
+        const now = Date.now();
+        this.publicKeys = this.publicKeys.filter((k) => k.exp > now);
+        return await Promise.resolve(this.publicKeys.map((k) => k.key));
+    }
+    /**
+     * Retrieves the Unix timestamp (in milliseconds) of the last key rotation.
+     * @returns The timestamp of the last rotation, or `0` if no rotation has occurred.
+     */
+    async getLastRotationTimestamp() {
+        return await Promise.resolve(this.lastRotation);
+    }
+    /**
+     * Stores the Unix timestamp (in milliseconds) of the most recent key rotation.
+     * @param msDate - The timestamp to persist.
+     */
+    async setLastRotationTimestamp(msDate) {
+        this.lastRotation = msDate;
+        return await Promise.resolve();
+    }
+}
+/**
+ * Creates a new {@link InMemoryKeyStore} instance.
+ *
+ * Convenience factory for use with {@link JoseJwksAuthority} and {@link JwksRotator}.
+ *
+ * @returns A fresh in-memory key store with no keys stored.
+ */
+export function createInMemoryKeyStore() {
+    return new InMemoryKeyStore();
+}

package/esm/jwks_rotator.d.ts

@@ -0,0 +1,36 @@
+import { JwksRotationTimestampStore, KeyGenerator } from "./types.js";
+/**
+ * Configuration options for {@link JwksRotator}.
+ */
+export interface JwksRotatorOptions {
+    /** The key generator used to produce new signing key pairs during rotation. */
+    keyGenerator: KeyGenerator;
+    /** The store used to read and persist the last rotation timestamp. */
+    rotatorKeyStore: JwksRotationTimestampStore;
+    /** How often (in milliseconds) new keys should be generated. For example, `7.884e9` for 91 days. */
+    rotationIntervalMs: number;
+}
+/**
+ * Manages automatic JWKS key rotation based on a configurable interval.
+ *
+ * Call {@link JwksRotator.checkAndRotateKeys} at service startup and/or on a
+ * recurring schedule (e.g. every hour) to ensure that signing keys are rotated
+ * before they expire. During rotation the previous public key remains available
+ * in the JWKS until its TTL expires, so in-flight tokens continue to verify correctly.
+ */
+export declare class JwksRotator {
+    private readonly keyGenerator;
+    private readonly rotatorKeyStore;
+    private readonly rotationIntervalMs;
+    /**
+     * @param options - Rotation configuration: key generator, timestamp store, and interval.
+     */
+    constructor({ keyGenerator, rotationIntervalMs, rotatorKeyStore }: JwksRotatorOptions);
+    /**
+     * Checks if rotation is due, and performs rotation if necessary.
+     * Should be called at service startup or on a schedule (e.g. every hour).
+     */
+    checkAndRotateKeys(): Promise<void>;
+    private rotateKeys;
+}
+//# sourceMappingURL=jwks_rotator.d.ts.map

package/esm/jwks_rotator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks_rotator.d.ts","sourceRoot":"","sources":["../src/jwks_rotator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,YAAY,EAAE,YAAY,CAAC;IAC3B,sEAAsE;IACtE,eAAe,EAAE,0BAA0B,CAAC;IAC5C,oGAAoG;IACpG,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAE5C;;OAEG;gBACS,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,EAAE,kBAAkB;IAMrF;;;OAGG;IACU,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;YAYlC,UAAU;CAGzB"}