@gjermundgaraba/clankerauth-sdk 0.25.0 → 0.26.1

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
 
@@ -326,7 +340,7 @@ Tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauthorized`
 
 There is one 403. Only the verifier's own check fails with `InsufficientScope`: a credential that is valid but lacks a scope in `requiredScopes`, a resource's `required`. It names that scope and the credential's `actor`, which decides whether its `Forbidden` steps up. A scope asked for after verification, by `requires(scope)`, `admitted(scope)`, `admit(header, scope)` or `watch(header, scope)`, is refused with effect-actions' `Action.Forbidden` directly, decided by the same rule. A credential that is not this resource's at all — the wrong audience, or an API key with no entry in this resource's key list — is `Unauthorized`, because from the resource's side those are the same thing.
 
-JWTs are checked against issuer, audience, EdDSA signature, token type, required claims, expiry and scopes. Sender-constrained tokens are rejected. One JWKS read answers every verification for a minute, so a key the issuer starts or stops publishing takes effect within that minute; a `kid` the current document does not publish is `Unauthorized` and never triggers a read, so a token with an invented `kid` cannot become provider traffic. A failed read answers `ProviderUnavailable` (503) for five seconds before the next attempt; a read every waiting caller gave up on is dropped, and the next verification reads again. API keys are verified offline, against the resource's key list: one document the issuer signs with its access-token key, holding a sealed entry per key granted on this resource, which only that key can find or open. The list is verified once, when it is read, and one read answers every key it names for a minute, without issuer traffic; so a key disabled, deleted or re-scoped keeps the access it had until the next read, within about a minute. A key the held list does not name may have been created, enabled or granted on this resource since, so the list is read again before the key is refused, unless it was read within the last five seconds: such a key works within seconds, and unknown keys reach the issuer at most once every five seconds. A key's own expiry is checked on every verification, so it applies at once. A failed read, or one that takes longer than three seconds, is no error while the last list is inside its own lifetime, which the issuer sets to 24 hours: keys keep verifying through an outage, JWKS or not, and the issuer is tried again after five seconds. A read every waiting caller gave up on is dropped, and the next key reads again. Past that lifetime, or before any list has been read, a key is `ProviderUnavailable`. Reads that start failing are logged once as a warning, and their recovery once at info level, so an outage the held list hides still shows in the application's logs without a line per retry. The last list read is the one held, whatever its `iat`: HTTPS to the issuer is what keeps an old list from being replayed, and one could only ever be replayed inside its own day. The issuer does not count key use, so rate limiting is the application's. A key is a bearer secret, and one granted on several resources can be replayed by any of them to the others; a resource you trust less gets its own key. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without reading the key list. Admission through a `Resource` has a five-second deadline; the raw `Verifier` has none, so an in-process caller can await a provider call it cannot cancel. The exception is the key list read's own three seconds: shorter than that deadline, so an issuer that stops answering delays a key by at most that long, never fails it while a list is held.
+JWTs are checked against issuer, audience, EdDSA signature, token type, required claims, expiry and scopes. Sender-constrained tokens are rejected. One JWKS read answers every verification for a minute, so a key the issuer starts or stops publishing takes effect within that minute; a `kid` the current document does not publish is `Unauthorized` and never triggers a read, so a token with an invented `kid` cannot become provider traffic. A failed read answers `ProviderUnavailable` (503) for five seconds before the next attempt; a read whose verification is interrupted writes nothing, and the next verification reads again. API keys are verified offline, against the resource's key list: one document the issuer signs with its access-token key, holding a sealed entry per key granted on this resource, which only that key can find or open. The list is verified once, when it is read, and one read answers every key it names for a minute, without issuer traffic; so a key disabled, deleted or re-scoped keeps the access it had until the next read, within about a minute. A key the held list does not name may have been created, enabled or granted on this resource since, so the list is read again before the key is refused, unless it was read within the last five seconds: such a key works within seconds, and unknown keys reach the issuer at most once every five seconds. A key's own expiry is checked on every verification, so it applies at once. A failed read, or one whose list or JWKS fetch takes longer than three seconds, is no error while the last list is inside its own lifetime, which the issuer sets to 24 hours: keys keep verifying through an outage, JWKS or not, and the issuer is tried again after five seconds. A read whose verification is interrupted writes nothing, and the next key reads again. Past that lifetime, or before any list has been read, a key is `ProviderUnavailable`. Reads that start failing are logged once as a warning, and their recovery once at info level, so an outage the held list hides still shows in the application's logs without a line per retry. The last list read is the one held, whatever its `iat`: HTTPS to the issuer is what keeps an old list from being replayed, and one could only ever be replayed inside its own day. The issuer does not count key use, so rate limiting is the application's. A key is a bearer secret, and one granted on several resources can be replayed by any of them to the others; a resource you trust less gets its own key. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without reading the key list. Admission through a `Resource` has a five-second deadline; the raw `Verifier` has none, so an in-process caller can await a provider call it cannot cancel. The exception is the key list read, which gives each of its fetches three seconds: the list, and the JWKS it is verified with when none is held, so a slow first fetch does not cut the second short. An issuer that stops answering therefore delays a key by three seconds and never fails it while a list is held; one that answers the list late and then stalls on the JWKS can take the read past `Resource`'s deadline.
 
 The bundled issuer does not configure automatic signing-key rotation. Immediate-use rotation is supported, but tokens signed by a new key are rejected until the next JWKS read, up to a minute; a key list signed by it is not taken until then either, and the held list keeps deciding. Publish-before-use avoids that window; it is not mandatory. Key lists are re-signed on every read, so issued API keys are unaffected by rotation.
 

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,11 +38,54 @@ 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.
+ * The one exception is a key list read, which gives up on each of its fetches after three seconds.
  */
 export declare const make: (options: Options) => Effect.Effect<{
     verifyToken: (token: string) => Effect.Effect<{

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,27 +26,37 @@ 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.
  */
 const cooldown = Duration.seconds(5);
 /**
- * How long a key list read may take. Under `Resource`'s five-second deadline, so a stalled
- * issuer fails the read, not the request, and a held list still decides.
+ * How long each fetch of a key list read may take: the list, and the JWKS it is verified
+ * with when none is held. Under `Resource`'s five-second deadline, so an issuer that stops
+ * answering fails the read, not the request, and a held list still decides.
  */
-const listReadTimeout = "3 seconds";
+const listReadTimeout = Duration.seconds(3);
+const deadline = (operation) => (effect) => Effect.timeoutOrElse(effect, {
+    duration: listReadTimeout,
+    orElse: () => Effect.fail(new ProviderUnavailable({ operation })),
+});
 /**
- * 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.
+ * The one exception is a key list read, which gives up on each of its fetches 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 +72,35 @@ 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);
-    const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
-        const resolve = yield* keys;
+    /** 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 startedAt = yield* Clock.currentTimeMillis;
+        if (settled !== undefined) {
+            const answers = "keys" in settled ? documentLifetime : cooldown;
+            if (startedAt - 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;
+        if (Result.isSuccess(read)) {
+            options.store.jwks.set(options.issuer, { readAt, keys: read.success });
+            return read.success;
+        }
+        // why: a failure never replaces an outcome that ended after it began.
+        if ((options.store.jwks.get(options.issuer)?.readAt ?? -Infinity) >= startedAt)
+            return yield* read.failure;
+        options.store.jwks.set(options.issuer, { readAt, failure: read.failure.operation });
+        return yield* read.failure;
+    });
+    const signingKey = Effect.fn("Verifier.signingKey")(function* (kid, held) {
+        const jwks = { keys: [...(yield* held)] };
         return yield* Effect.tryPromise({
-            try: () => resolve({ alg: "EdDSA", kid }),
+            try: () => createLocalJWKSet(jwks)({ alg: "EdDSA", kid }),
             catch: unauthorized,
         });
     });
@@ -78,9 +108,9 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
      * A document this issuer signed for this resource: EdDSA under a key it names, with the
      * expected `typ`, issuer and audience, and not expired. Which claims it must carry is
      * its schema's to say. `Unauthorized` means it is not to be trusted; what that amounts
-     * to is the caller's to say.
+     * to is the caller's to say. Its signing keys are `held`'s, the store's JWKS by default.
      */
-    const verifySigned = Effect.fn("Verifier.signed")(function* (jws, typ) {
+    const verifySigned = Effect.fn("Verifier.signed")(function* (jws, typ, held = keys) {
         const header = yield* Effect.try({
             try: () => decodeProtectedHeader(jws),
             catch: unauthorized,
@@ -88,7 +118,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         // why: refused before any JWKS read, so an unauthenticated request causes no issuer traffic.
         if (header.alg !== "EdDSA" || header.kid === undefined)
             return yield* unauthorized();
-        const key = yield* signingKey(header.kid);
+        const key = yield* signingKey(header.kid, held);
         const now = yield* Clock.currentTimeMillis;
         const { payload } = yield* Effect.tryPromise({
             try: () => jwtVerify(jws, key, {
@@ -116,15 +146,19 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     });
     const listDocument = Effect.fn("Verifier.keyList")(function* () {
         const request = HttpClientRequest.post(endpoints.keyList).pipe(HttpClientRequest.bodyJsonUnsafe({ resource: options.resource }));
-        const response = yield* execute(client, request);
-        if (response.status !== 200)
-            return yield* new ProviderUnavailable({
-                operation: "key-list.fetch",
-                cause: { status: response.status },
-            });
-        const { list } = yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
+        const fetched = Effect.gen(function* () {
+            const response = yield* execute(client, request);
+            if (response.status !== 200)
+                return yield* new ProviderUnavailable({
+                    operation: "key-list.fetch",
+                    cause: { status: response.status },
+                });
+            return yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
+        });
+        const { list } = yield* fetched.pipe(deadline("key-list.timeout"));
         const rejected = (cause) => new ProviderUnavailable({ operation: "key-list.verify", cause });
-        const payload = yield* verifySigned(list, KeyList.type).pipe(Effect.catchTag("Unauthorized", (cause) => Effect.fail(rejected(cause))));
+        // why: a JWKS read on its own deadline, so a cold one does not spend the list's.
+        const payload = yield* verifySigned(list, KeyList.type, keys.pipe(deadline("jwks.timeout"))).pipe(Effect.catchTag("Unauthorized", (cause) => Effect.fail(rejected(cause))));
         const claims = yield* Schema.decodeUnknownEffect(KeyListClaims)(payload).pipe(Effect.mapError(rejected));
         return {
             readAt: yield* Clock.currentTimeMillis,
@@ -132,20 +166,40 @@ 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());
+        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 +212,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.1",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {