@gjermundgaraba/clankerauth-sdk 0.25.0 → 0.26.0

package/README.md

@@ -70,14 +70,26 @@ import { Effect } from "effect";
 import { FetchHttpClient } from "effect/http";
 import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
 
-const makeVerifier = Verifier.make({
-  issuer: "https://clankerauth.internal/api/auth",
-  resource: "https://notes.internal/",
-  requiredScopes: ["notes:read"],
-}).pipe(Effect.provide(FetchHttpClient.layer));
-// Acquire once, then use verifier.verifyToken(token).
+// Once, at module scope: what every verification has read.
+const store = Verifier.store();
+
+// Per request, in the request that verifies.
+const verify = (token: string) =>
+  Verifier.make({
+    issuer: "https://clankerauth.internal/api/auth",
+    resource: "https://notes.internal/",
+    store,
+    requiredScopes: ["notes:read"],
+  }).pipe(
+    Effect.flatMap((verifier) => verifier.verifyToken(token)),
+    Effect.provide(FetchHttpClient.layer),
+  );
 ```
 
+The store holds what verifiers have read, decoded and checked: each issuer's JWKS keys, and each resource's verified key list with when it was read and when it expires. It holds values only, never an Effect, a fiber, a Promise, a `Response` or a timer, so it may live as long as the process. A verifier holds nothing but its options, the store and the HTTP client. On a hit it verifies locally; on a miss, or once what it holds has expired, it reads the issuer in the verification that missed and writes the result back. Concurrent misses each read, and none waits on another's: a verification that misses before any read has finished reads for itself. Steady traffic costs one or two extra issuer reads per refresh; a burst arriving at an empty or expired store reads once per verification in it.
+
+That split is what Cloudflare Workers requires. A Worker's I/O belongs to the request that started it: a request cannot resume work another request started, and a continuation whose request has ended is dropped ([I/O on behalf of a different request](https://developers.cloudflare.com/workers/observability/errors/#cannot-perform-io-on-behalf-of-a-different-request), [cross-request promise resolution](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#handle-cross-request-promise-resolution-correctly)). Data may live in global scope; in-flight work may not. So keep the store at module scope, as data, and acquire the verifier in each request. On Node a verifier acquired once is just as correct, since it owns no running work either.
+
 ## One resource per application
 
 Register **one** resource in the clankerauth dashboard, identified by the application's public origin root, written with its trailing slash: `https://notes.internal/`. That one resource covers `/api`, `/mcp` and any socket, with one RFC 9728 document at `/.well-known/oauth-protected-resource` and one `forward_auth` block in the proxy.
@@ -106,11 +118,12 @@ export const Login = Authentication.make("notes.Login", CurrentPrincipal, {
 export const Http = ActionHttp.make([List, Write, Whoami], { authentication: Login });
 ```
 
-The server declares the resource once, at module level, from that descriptor, every scope it has and the one every credential must carry, `required`, one of `scopes` as the types check. It provides its `layer` and its `provider` once at application construction, never per request. `Resource.make` takes only a descriptor declaring `ProviderUnavailable`: one that does not is a type error there, naming `error: ProviderUnavailable`.
+The server declares the resource once, at module level, from that descriptor, every scope it has and the one every credential must carry, `required`, one of `scopes` as the types check. It provides its `layer` and its `provider` once at application construction. `Resource.make` takes only a descriptor declaring `ProviderUnavailable`: one that does not is a type error there, naming `error: ProviderUnavailable`.
 
 ```ts
 import { Layer } from "effect";
 import { FetchHttpClient } from "effect/http";
+import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
 import { Resource } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
@@ -133,13 +146,14 @@ const routes = Layer.mergeAll(
     NotesResource.layer({
       issuer: "https://clankerauth.internal/api/auth",
       publicUrl: new URL("https://notes.internal"),
+      store: Verifier.store(),
     }),
   ),
   Layer.provide(FetchHttpClient.layer),
 );
 ```
 
-Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the release that matches your Effect. The scopes are the same in every deployment, so they are declared with the resource; `NotesResource.layer` takes what varies by deployment and builds the resource once: its verifier and refusals. `NotesResource.provider` is the descriptor's provider, effect-actions' `Authentication.layer`: it verifies every protected route and tool call before decoding, and publishes discovery itself, public and outside authentication; there is no discovery route to merge. Discovery cache policy belongs to the host. Every response to a request it authenticates carries `Cache-Control: no-store`. Middleware of your own runs as effect-actions runs it: router middleware provided after the provider, or an HTTP layer's `middleware`.
+Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the release that matches your Effect. The scopes are the same in every deployment, so they are declared with the resource; `NotesResource.layer` takes what varies by deployment and builds the resource once: its verifier and refusals. Its `store` is the verifier's, as above. The resource holds no running work, so built once it still reads the issuer only in the request that verifies; an application that builds its layers per request, as a Worker may, passes a store made at module scope, so what was read outlives each request. `NotesResource.provider` is the descriptor's provider, effect-actions' `Authentication.layer`: it verifies every protected route and tool call before decoding, and publishes discovery itself, public and outside authentication; there is no discovery route to merge. Discovery cache policy belongs to the host. Every response to a request it authenticates carries `Cache-Control: no-store`. Middleware of your own runs as effect-actions runs it: router middleware provided after the provider, or an HTTP layer's `middleware`.
 
 A surface whose callers hold API keys and never run an OAuth flow, such as a second listener beside the one that publishes the resource, sets `discovery: false`: it authenticates the same way, publishes nothing, and its challenge is a plain `Bearer`. It is the same registered resource, so it takes the publishing listener's public URL, not its own address: a public machine listener beside a private admin one still passes the admin URL.
 
@@ -147,7 +161,7 @@ Two listeners with different scopes, such as that admin and machine pair, are st
 
 A declared resource is a `Resource.Declared<"notes.Login">`, and what its `layer` builds a `Resource.Built`; its descriptor is a `Resource.Login<"notes.Login">`. `Declared` and `Login` take what the descriptor declares as an optional second parameter, `ProviderUnavailable` alone when left out. `Declared` and `Built` take the resource's scopes as an optional parameter, last, which `make` infers from `scopes`: an annotation that leaves it out accepts any scope string. The entry point also exports each type a resource's declarations mention under a flat name (`DeclaredResource`, `BuiltResource`, `ResourceService`, `ResourceDeclaration`, `ResourceOptions`, `Login`, `Admission`, `Refusal`, `Principal`, `Verifier`); `CurrentPrincipal` and its `Caller` are `/session`'s, where declarations name them. So a package that exports its descriptor, its resource or its implementations emits declarations without an annotation.
 
-The supplied `HttpClient` must not retry credential exchanges or follow redirects. The SDK overrides only FetchHttpClient's redirect policy to reject redirects, preserves other caller-provided fetch defaults, and never installs retry middleware.
+The supplied `HttpClient` must not retry credential exchanges or follow redirects. The SDK overrides only FetchHttpClient's redirect policy, to `manual`, and fails a read answered with a redirect (any 3xx) as `ProviderUnavailable`; it preserves other caller-provided fetch defaults and never installs retry middleware. `manual`, not `error`, because Cloudflare Workers rejects `redirect: "error"` before sending ([Request](https://developers.cloudflare.com/workers/runtime-apis/request/#options)).
 
 ## Scope enforcement
 

package/dist/resource.d.ts

@@ -26,6 +26,11 @@ export interface Options {
      * logged once as a warning, since an OAuth client discovering the resource there refuses it.
      */
     readonly publicUrl: URL;
+    /**
+     * What the resource's verifier keeps of what it reads, `Verifier.store()`: made once where
+     * the process starts, so it outlives a layer built per request.
+     */
+    readonly store: Verifier.Store;
     /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
     readonly apiKeys?: boolean;
     /**

package/dist/resource.js

@@ -56,6 +56,7 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
     const unbounded = yield* Verifier.make({
         issuer: options.issuer,
         resource: identifier,
+        store: options.store,
         requiredScopes: [required],
         apiKeys: options.apiKeys,
     });

package/dist/transport.d.ts

@@ -1,4 +1,8 @@
 import { Effect } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { ProviderUnavailable } from "./errors.ts";
+/**
+ * Send `request` without following a redirect: a redirect fails the read. `manual`, since
+ * Cloudflare Workers rejects `redirect: "error"` before sending.
+ */
 export declare const execute: (client: HttpClient.HttpClient, request: HttpClientRequest.HttpClientRequest) => Effect.Effect<import("effect/http/HttpClientResponse").HttpClientResponse, ProviderUnavailable, import("effect/Scope").Scope>;

package/dist/transport.js

@@ -1,9 +1,16 @@
 import { Context, Effect } from "effect";
 import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
 import { ProviderUnavailable } from "./errors.js";
+/**
+ * Send `request` without following a redirect: a redirect fails the read. `manual`, since
+ * Cloudflare Workers rejects `redirect: "error"` before sending.
+ */
 export const execute = (client, request) => Effect.contextWith((context) => HttpClient.withScope(client)
     .execute(request)
     .pipe(Effect.provideService(FetchHttpClient.RequestInit, {
     ...Context.getOrUndefined(context, FetchHttpClient.RequestInit),
-    redirect: "error",
-}), Effect.mapError((cause) => new ProviderUnavailable({ operation: "http.request", cause }))));
+    redirect: "manual",
+}), Effect.mapError((cause) => new ProviderUnavailable({ operation: "http.request", cause })), Effect.filterOrFail((response) => response.status < 300 || response.status >= 400, (response) => new ProviderUnavailable({
+    operation: "http.redirect",
+    cause: { status: response.status },
+}))));

package/dist/verify.d.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import type { JWK } from "jose";
 import { HttpClient } from "effect/http";
 import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.ts";
 import type { AuthenticationError } from "./errors.ts";
@@ -28,6 +29,8 @@ export interface Principal {
 export interface Options {
     readonly issuer: string;
     readonly resource: string;
+    /** Where this verifier keeps what it reads and finds what was read before: see `Store`. */
+    readonly store: Store;
     readonly requiredScopes?: readonly string[];
     /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
     readonly apiKeys?: boolean;
@@ -35,8 +38,51 @@ export interface Options {
 export interface Verifier {
     readonly verifyToken: (token: string) => Effect.Effect<Principal, AuthenticationError>;
 }
+/** One verified key list: the entries it holds and how long they may decide. */
+export interface Keys {
+    /** Epoch milliseconds, by this host's clock: when the list was read. */
+    readonly readAt: number;
+    /** Epoch milliseconds: the end of the issuer's outage window for this list. */
+    readonly expiresAt: number;
+    readonly entries: ReadonlyMap<string, string>;
+}
+/**
+ * The last JWKS document read from an issuer: its keys, which signing keys are resolved
+ * from, or the operation that failed. Either answers until its lifetime or cooldown ends.
+ */
+export type SettledJwks = {
+    readonly readAt: number;
+    readonly keys: readonly JWK[];
+} | {
+    readonly readAt: number;
+    readonly failure: string;
+};
+/** The last key list read for one resource of an issuer, and the last one that verified. */
+export interface SettledKeyList {
+    /** Epoch milliseconds: when the last read ended, which holds off the next for the cooldown. */
+    readonly readAt: number;
+    /** The operation the last read failed at; `undefined` when it succeeded. */
+    readonly failure: string | undefined;
+    /** The last list that verified, which decides through an outage until it expires. */
+    readonly held: Keys | undefined;
+}
+/**
+ * What verifiers have read and decoded, for every verifier given it: JWKS documents by
+ * issuer, key lists by issuer and resource. It holds values only, never an Effect, fiber,
+ * Promise, Response or timer, so it may live as long as the process, at module scope on a
+ * runtime whose I/O belongs to one request, such as Cloudflare Workers. Every read runs in
+ * the verification that misses, and writes its result back; concurrent misses each read.
+ */
+export interface Store {
+    readonly jwks: Map<string, SettledJwks>;
+    readonly keyLists: Map<string, SettledKeyList>;
+}
+/** An empty store: `const store = Verifier.store()`, once, where the process starts. */
+export declare const store: () => Store;
 /**
- * Acquire once per resource; transport is selected by the application, not the SDK.
+ * A verifier over `options.store`; transport is selected by the application, not the SDK.
+ * It holds nothing but its options, the store and the HTTP client, so acquiring one per
+ * request costs nothing: every read it makes runs in the verification that needs it.
  * Verification runs to completion: a deadline is the request edge's policy, which
  * `Resource` applies, so an in-process caller can await a provider call it cannot cancel.
  * The one exception is a key list read, which gives up after three seconds.

package/dist/verify.js

@@ -1,4 +1,4 @@
-import { Clock, Duration, Effect, Exit, Ref, Result, Schema } from "effect";
+import { Clock, Duration, Effect, Result, Schema } from "effect";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
 import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized, } from "./errors.js";
@@ -26,9 +26,11 @@ const Claims = Schema.Struct({
 /** The list document as the issuer's `keyList` action answers it. */
 const KeyListResponse = Schema.Struct({ list: Schema.String });
 const KeyListClaims = KeyList.Claims.pipe(Schema.fieldsAssign({ exp: Schema.Finite }));
+/** An empty store: `const store = Verifier.store()`, once, where the process starts. */
+export const store = () => ({ jwks: new Map(), keyLists: new Map() });
 const unauthorized = (cause) => new Unauthorized({ cause });
 /** How long a JWKS document answers verification before it is read again. */
-const documentLifetime = "1 minute";
+const documentLifetime = Duration.minutes(1);
 /**
  * How long a read holds off the next one: a failed read of either document, and any read
  * of the key list, so a key the held list does not name reaches the issuer at most this often.
@@ -40,13 +42,16 @@ const cooldown = Duration.seconds(5);
  */
 const listReadTimeout = "3 seconds";
 /**
- * Acquire once per resource; transport is selected by the application, not the SDK.
+ * A verifier over `options.store`; transport is selected by the application, not the SDK.
+ * It holds nothing but its options, the store and the HTTP client, so acquiring one per
+ * request costs nothing: every read it makes runs in the verification that needs it.
  * Verification runs to completion: a deadline is the request edge's policy, which
  * `Resource` applies, so an in-process caller can await a provider call it cannot cancel.
  * The one exception is a key list read, which gives up after three seconds.
  */
 export const make = Effect.fn("Verifier.make")(function* (options) {
     const client = yield* HttpClient.HttpClient;
+    const listed = JSON.stringify([options.issuer, options.resource]);
     const endpoints = yield* Effect.try({
         try: () => ({
             jwks: new URL(`${options.issuer}/jwks`).href,
@@ -62,15 +67,33 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 cause: { status: response.status },
             });
         const jwks = yield* HttpClientResponse.schemaBodyJson(Jwks)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "jwks.decode", cause })));
-        return createLocalJWKSet({
-            keys: jwks.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key),
-        });
+        return jwks.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key);
     }, Effect.scoped);
-    const keys = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : cooldown);
+    /** The keys read within their lifetime, a failed read's failure within its cooldown, or a read now. */
+    const keys = Effect.gen(function* () {
+        const settled = options.store.jwks.get(options.issuer);
+        const now = yield* Clock.currentTimeMillis;
+        if (settled !== undefined) {
+            const answers = "keys" in settled ? documentLifetime : cooldown;
+            if (now - settled.readAt < Duration.toMillis(answers))
+                return "keys" in settled
+                    ? settled.keys
+                    : yield* new ProviderUnavailable({ operation: settled.failure });
+        }
+        const read = yield* Effect.result(document());
+        const readAt = yield* Clock.currentTimeMillis;
+        // why: a failure never replaces an outcome that ended after it began; a success always writes.
+        if (Result.isSuccess(read) ||
+            (options.store.jwks.get(options.issuer)?.readAt ?? -Infinity) < now)
+            options.store.jwks.set(options.issuer, Result.isSuccess(read)
+                ? { readAt, keys: read.success }
+                : { readAt, failure: read.failure.operation });
+        return Result.isSuccess(read) ? read.success : yield* read.failure;
+    });
     const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
-        const resolve = yield* keys;
+        const jwks = { keys: [...(yield* keys)] };
         return yield* Effect.tryPromise({
-            try: () => resolve({ alg: "EdDSA", kid }),
+            try: () => createLocalJWKSet(jwks)({ alg: "EdDSA", kid }),
             catch: unauthorized,
         });
     });
@@ -132,20 +155,43 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             entries: new Map(claims.keys.map((entry) => [entry.id, entry.sealed])),
         };
     }, Effect.scoped);
-    const failing = yield* Ref.make(false);
-    const readList = yield* Effect.cachedWithTTL(listDocument().pipe(Effect.timeoutOrElse({
-        duration: listReadTimeout,
-        orElse: () => Effect.fail(new ProviderUnavailable({ operation: "key-list.timeout" })),
-    }), Effect.tapError(({ operation }) => Effect.flatMap(Ref.getAndSet(failing, true), (was) => was
-        ? Effect.void
-        : Effect.logWarning("clankerauth key list reads are failing; a held list decides until it expires", { operation }))), Effect.tap(() => Effect.flatMap(Ref.getAndSet(failing, false), (was) => was ? Effect.logInfo("clankerauth key list reads have recovered") : Effect.void))), cooldown);
-    const held = yield* Ref.make(undefined);
+    /**
+     * Read the key list, unless a read ended within the cooldown: then that read's outcome
+     * stands. A list that verified is always written back; a failure is not, over a read that
+     * ended after it began. A failure is logged once until a read succeeds again.
+     */
+    const readList = Effect.gen(function* () {
+        const settled = options.store.keyLists.get(listed);
+        const startedAt = yield* Clock.currentTimeMillis;
+        if (settled !== undefined && startedAt - settled.readAt < Duration.toMillis(cooldown))
+            return settled.failure === undefined
+                ? undefined
+                : yield* new ProviderUnavailable({ operation: settled.failure });
+        const read = yield* Effect.result(listDocument().pipe(Effect.timeoutOrElse({
+            duration: listReadTimeout,
+            orElse: () => Effect.fail(new ProviderUnavailable({ operation: "key-list.timeout" })),
+        })));
+        const readAt = yield* Clock.currentTimeMillis;
+        const before = options.store.keyLists.get(listed);
+        const failing = before?.failure !== undefined;
+        if (Result.isSuccess(read)) {
+            options.store.keyLists.set(listed, { readAt, failure: undefined, held: read.success });
+            if (failing)
+                yield* Effect.logInfo("clankerauth key list reads have recovered");
+            return undefined;
+        }
+        if ((before?.readAt ?? -Infinity) >= startedAt)
+            return yield* read.failure;
+        const { operation } = read.failure;
+        options.store.keyLists.set(listed, { readAt, failure: operation, held: before?.held });
+        if (!failing)
+            yield* Effect.logWarning("clankerauth key list reads are failing; a held list decides until it expires", { operation });
+        return yield* read.failure;
+    });
     /** The list read now, or within the cooldown, or else the held one, while inside its window. */
     const latest = Effect.gen(function* () {
         const fetched = yield* Effect.result(readList);
-        if (Result.isSuccess(fetched))
-            yield* Ref.set(held, fetched.success);
-        const list = yield* Ref.get(held);
+        const list = options.store.keyLists.get(listed)?.held;
         if (list !== undefined && list.expiresAt > (yield* Clock.currentTimeMillis))
             return list;
         return yield* Result.isFailure(fetched)
@@ -158,7 +204,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             catch: unauthorized,
         });
         const now = yield* Clock.currentTimeMillis;
-        const current = yield* Ref.get(held);
+        const current = options.store.keyLists.get(listed)?.held;
         const list = current !== undefined &&
             now - current.readAt < Duration.toMillis(keyListRefresh) &&
             current.expiresAt > now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {