@sdxc/jwt 2026.10.2 → 2026.10.9

package/README.md

@@ -10,6 +10,11 @@ npm add @sdxc/jwt
 
 Signing and verification run on [`jose`](https://www.npmjs.com/package/jose), and the duration strings the time claims accept come from [`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration). Both install with the package.
 
+Two entry points:
+
+- `@sdxc/jwt` — `JWT`, the `JWK` namespace, and the `KeyStorage` contract.
+- `@sdxc/jwt/r2` — `createR2KeyStorage`, the `KeyStorage` over a Cloudflare R2 bucket.
+
 ## Usage
 
 ### Describing A Kind Of Token
@@ -235,6 +240,22 @@ interface KeyStorageListResult {
 
 To implement it: `get` answers `null` for a key nothing is stored under; `list` returns the entries whose key starts with `prefix`, at most `limit` of them, resuming from `cursor`, and carries a `cursor` of its own only while further pages remain; `set` replaces whatever is stored under the key. Each method may be synchronous or return a promise, so a plain object satisfies the contract in a test while an object store satisfies it in production. `signingKeys` writes each pair as a JSON `SerializedKeyPair` under the key `signing:key:<id>` and lists with the prefix `signing:key` to find them again, so keep every key ever written and every token it signed stays verifiable.
 
+### `createR2KeyStorage(bucket: R2KeyBucket): KeyStorage`
+
+From `@sdxc/jwt/r2`. Stores key files in a Cloudflare R2 bucket, the place a key outlives every isolate and every Worker issuing tokens for one issuer reads the same set.
+
+```typescript
+import { JWK } from "@sdxc/jwt";
+import { createR2KeyStorage } from "@sdxc/jwt/r2";
+import { env } from "cloudflare:workers";
+
+let keys = await JWK.signingKeys(createR2KeyStorage(env.KEYS));
+```
+
+Each object is written with the file's type as its `Content-Type` and its name and type as custom metadata (`name`, `type`), so `get` hands back the `File` that was stored, its `lastModified` set to the upload time. An object written without that metadata reads back named after its key. `list` carries R2's cursor only while a page is truncated.
+
+`R2KeyBucket` is the part of a bucket binding the storage calls — `get`, `list` and `put` — declared structurally, so an `R2Bucket` satisfies it and importing the module needs no platform types. `R2KeyObject` is what its `get` answers.
+
 ## Rotation, And The Order To Roll It Out In
 
 A rotation adds a key: the issuer writes a new pair into storage, `signingKeys` returns it first, `sign` picks it as the newest, and the retired key stays in the published JWKS so the tokens it signed keep verifying until they expire. That rests on every verifier resolving a key per token by `kid`, which makes the rollout order a deployment constraint:

package/dist/r2-key-storage.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Key storage over a Cloudflare R2 bucket, where signing keys outlive every
+ * isolate and every Worker issuing tokens for one issuer reads the same files.
+ * Each stored object carries the file's name and type, so a key reads back as the `File` written.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { KeyStorage, KeyStorageListOptions } from "./key-storage.js";
+/** The HTTP metadata an object is written and read with. */
+interface R2KeyHTTPMetadata {
+    contentType?: string;
+}
+/** A stored object as a read answers it. */
+export interface R2KeyObject {
+    uploaded: Date;
+    httpMetadata?: R2KeyHTTPMetadata;
+    customMetadata?: Record<string, string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * The parts of an R2 bucket binding the storage uses, declared structurally so
+ * importing this module needs no platform types; an `R2Bucket` satisfies it.
+ */
+export interface R2KeyBucket {
+    get(key: string): Promise<R2KeyObject | null>;
+    list(options?: KeyStorageListOptions): Promise<{
+        objects: {
+            key: string;
+        }[];
+        truncated: boolean;
+        cursor?: string;
+    }>;
+    put(key: string, value: ArrayBuffer, options?: {
+        httpMetadata?: R2KeyHTTPMetadata;
+        customMetadata?: Record<string, string>;
+    }): Promise<unknown>;
+}
+/**
+ * Adapts an R2 bucket binding to the storage `JWK.signingKeys` reads and rotates
+ * keys through. The bucket is passed in, so the caller decides where keys live.
+ *
+ * @param bucket - The R2 bucket binding key files are stored in.
+ * @returns Storage that reads, writes, and pages through key files in that bucket.
+ * @example let keys = await JWK.signingKeys(createR2KeyStorage(env.KEYS));
+ */
+export declare function createR2KeyStorage(bucket: R2KeyBucket): KeyStorage;
+export {};

package/dist/r2-key-storage.js

@@ -0,0 +1,58 @@
+/**
+ * Key storage over a Cloudflare R2 bucket, where signing keys outlive every
+ * isolate and every Worker issuing tokens for one issuer reads the same files.
+ * Each stored object carries the file's name and type, so a key reads back as the `File` written.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Adapts an R2 bucket binding to the storage `JWK.signingKeys` reads and rotates
+ * keys through. The bucket is passed in, so the caller decides where keys live.
+ *
+ * @param bucket - The R2 bucket binding key files are stored in.
+ * @returns Storage that reads, writes, and pages through key files in that bucket.
+ * @example let keys = await JWK.signingKeys(createR2KeyStorage(env.KEYS));
+ */
+export function createR2KeyStorage(bucket) {
+    return {
+        /**
+         * A missing key comes back as null, so an object removed between a listing
+         * and its read reads the same as a key that was never there. The bytes are
+         * read fully into memory, which a key file of a few hundred bytes affords.
+         */
+        async get(key) {
+            let object = await bucket.get(key);
+            if (!object)
+                return null;
+            let metadata = object.customMetadata;
+            return new File([await object.arrayBuffer()], metadata?.name ?? key, {
+                type: object.httpMetadata?.contentType ?? metadata?.type,
+                lastModified: object.uploaded.getTime(),
+            });
+        },
+        /**
+         * Carries R2's cursor only while the page is truncated, so a caller walking
+         * pages until the cursor is gone stops after the last one.
+         */
+        async list(options) {
+            let result = await bucket.list({
+                cursor: options?.cursor,
+                limit: options?.limit,
+                prefix: options?.prefix,
+            });
+            return {
+                files: result.objects.map((object) => ({ key: object.key })),
+                cursor: result.truncated ? result.cursor : undefined,
+            };
+        },
+        /** Replaces whatever is stored under the key, recording the file's name and type. */
+        async set(key, file) {
+            let metadata = { name: file.name, type: file.type };
+            await bucket.put(key, await file.arrayBuffer(), {
+                httpMetadata: { contentType: file.type },
+                customMetadata: metadata,
+            });
+        },
+    };
+}

package/package.json

@@ -1,18 +1,19 @@
 {
 	"name": "@sdxc/jwt",
-	"version": "2026.10.2",
+	"version": "2026.10.9",
 	"description": "JWT payload classes and the keys that sign them",
 	"license": "MIT",
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
-		"./algorithm": "./dist/algorithm.js"
+		"./algorithm": "./dist/algorithm.js",
+		"./r2": "./dist/r2-key-storage.js"
 	},
 	"dependencies": {
-		"@sdxc/duration": "2026.10.2",
+		"@sdxc/duration": "2026.10.6",
 		"jose": "^6.2.10"
 	},
-	"gitHead": "7582e46f150b052ba145945661ac9937f5f26f27",
+	"gitHead": "64fa732ed0a8ca8693a35aeef6345ae5be2534ef",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -20,5 +21,14 @@
 		"type": "git",
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/jwt"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/jwt",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
 	}
 }