@gjermundgaraba/clankerauth-sdk 0.9.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @gjermundgaraba/clankerauth-sdk
 
-Effect-native [clankerauth](https://github.com/gjermundgaraba/clankerauth) verification. Verifies JWT access tokens and API keys, including the tokens a reverse proxy obtains through the issuer's forward auth for browser sessions. Optional **effect-actions** integration provides request-scoped identity, OAuth discovery, scope enforcement and a `session` contract a browser page can import on its own.
+Effect-native [clankerauth](https://github.com/gjermundgaraba/clankerauth) verification. Verifies JWT access tokens and API keys, both offline, including the tokens a reverse proxy obtains through the issuer's forward auth for browser sessions. Optional **effect-actions** integration provides request-scoped identity, OAuth discovery, scope enforcement and a `session` contract a browser page can import on its own.
 
 ## Install
 
@@ -8,16 +8,16 @@ Effect-native [clankerauth](https://github.com/gjermundgaraba/clankerauth) verif
 vp add @gjermundgaraba/clankerauth-sdk
 ```
 
-Install Effect in the application:
+Effect is a peer: the application installs Effect 4, still a release candidate, and the SDK shares that copy.
 
 ```sh
-vp add effect@4.0.0-rc.117
+vp add effect@rc
 ```
 
-The `/session` and `/effect-actions` entry points also need effect-actions 0.7 (the SDK's declarations are built against it):
+The `/session` and `/effect-actions` entry points also need effect-actions, an optional peer. Install this range: the SDK's declarations are built against it, and under `skipLibCheck` they silently degrade to `any` with another.
 
 ```sh
-vp add @gjermundgaraba/effect-actions@0.7.0
+vp add @gjermundgaraba/effect-actions@^0.8.0
 ```
 
 ## Entry points
@@ -28,6 +28,8 @@ vp add @gjermundgaraba/effect-actions@0.7.0
 | `…/clankerauth-sdk/errors`         | no                   | **yes**      | the error schemas and `authenticationErrors`      |
 | `…/clankerauth-sdk/session`        | yes                  | **yes**      | the `session` contract, `Principal`, `signOutUrl` |
 | `…/clankerauth-sdk/effect-actions` | yes                  | no           | `Resource`, `CurrentPrincipal`                    |
+| `…/clankerauth-sdk/key-list`       | no                   | no           | the key list format, for issuers and fakes        |
+| `…/clankerauth-sdk/testing`        | no                   | no           | `startFakeIssuer`, for tests (Node only)          |
 
 The package is free of side effects, so a bundler drops what a page does not use. Errors are **not** re-exported from the root: a shared contract imports them from `/errors`, and nothing about that import pulls token verification into a browser bundle.
 
@@ -37,7 +39,7 @@ Core consumers do not need effect-actions or `skipLibCheck`.
 
 ```ts
 import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
+import { FetchHttpClient } from "effect/http";
 import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
 
 const makeVerifier = Verifier.make({
@@ -58,7 +60,7 @@ Acquire the resource once at application construction, never per request.
 
 ```ts
 import { Effect, Layer } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
+import { FetchHttpClient } from "effect/http";
 import { Resource } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
 import { authenticationErrors } from "@gjermundgaraba/clankerauth-sdk/errors";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
@@ -89,7 +91,7 @@ const routes = Layer.unwrap(
 ).pipe(Layer.provide(FetchHttpClient.layer));
 ```
 
-Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the matching `@effect/platform-node@4.0.0-rc.117` package. Discovery is public; do not wrap it in authentication. Discovery cache policy belongs to the host. Every authentication response carries `Cache-Control: no-store`.
+Serve this layer with Effect's `HttpRouter` and your Node server layer. If using `@effect/platform-node`, install the release that matches your Effect. Discovery is public; do not wrap it in authentication. Discovery cache policy belongs to the host. Every authentication response carries `Cache-Control: no-store`.
 
 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.
 
@@ -122,7 +124,7 @@ const routes = Http.layer([Notes.implement(handlers), notes.session], { before:
 
 A forward-auth browser token carries **every** scope the resource defines, because the issuer mints it for the signed-in owner and not for a program. The write scope therefore gates agents and API keys, not the owner at a keyboard: give a read-only agent or key only `scopes.read` and the same rule refuses its writes.
 
-An action reads identity from `CurrentPrincipal`, which contains `subject`, `scopes`, `actor` — either `{ kind: "client", clientId }` or `{ kind: "key", keyId }` — and `expiresAt`: an access token's verified `exp` in epoch milliseconds, so a host bounding a connection to its credential never decodes the token again. It is `undefined` for an API key, which carries no token lifetime and is re-verified on every request; choose your own bound for those.
+An action reads identity from `CurrentPrincipal`, which contains `subject`, `scopes`, `actor` — either `{ kind: "client", clientId }` or `{ kind: "key", keyId }` — and `expiresAt`: an access token's verified `exp`, or an API key's expiry, in epoch milliseconds, so a host bounding a connection to its credential never decodes it again. It is `undefined` for a key that does not expire. A key can also be revoked before then; `watch`, below, ends a connection at whichever comes first.
 
 A hook refusal is a plain declared error: effect-actions encodes it with the schema's status and adds no headers of its own; `Cache-Control: no-store` comes from `Resource.middleware`, which wraps every route it authenticates. Challenge headers come from admission — `Resource.middleware` and `admit` — which is what a client onboarding through RFC 9728 reads. No current client reads the header on a scope refusal, because an MCP denial is a tool error.
 
@@ -144,7 +146,18 @@ if (!admission.ok) {
 connect(admission.principal);
 ```
 
-The refusal carries each error's own status (401/403/429/503), the RFC 6750 challenge including the no-credential case, `Cache-Control: no-store`, and the error's JSON encoding. `Resource.middleware` is built on the same function at `"read"`, so a router and a socket can never answer differently.
+The refusal carries each error's own status (401/403/503), the RFC 6750 challenge including the no-credential case, `Cache-Control: no-store`, and the error's JSON encoding. `Resource.middleware` is built on the same function at `"read"`, so a router and a socket can never answer differently.
+
+A connection that outlives its admission, such as a WebSocket, is held to the same header value and access level with `watch`. It fails with the first refusal: once an access token expires, or once a refreshed key list no longer grants the key, or no longer grants the write scope. It never succeeds, so race it against the connection:
+
+```ts
+const session = Effect.raceFirst(
+  serve(socket),
+  notes.watch(request.headers.authorization, "write"),
+);
+```
+
+An access token cannot be revoked, so `watch` waits for its expiry and then fails `Unauthorized`, without asking the issuer again; a key is re-checked about once a minute against the list the resource last read, which is itself read about once a minute, so a revoked key ends a watched connection within about two minutes. A key needs the issuer only once that list is past its window.
 
 The resource also exposes `verifier.verify(authorization)` and `verifier.verifyToken(token)` as Effects for callers that render their own responses.
 
@@ -190,15 +203,39 @@ link.href = signOutUrl(principal.issuer, `${location.origin}/`);
 
 `Principal` is `{ subject, issuer, scopes }`. `signOutUrl` points at the issuer's `/forward-auth/logout?rd=…`, which ends the issuer session and every app's forward cookie; it is a plain link. On the server, `resource.session` is the same group already implemented from the verified credential — pass it to the HTTP binding beside your own application, and delete the hand-written `whoami`.
 
+## A fake issuer for tests
+
+`@gjermundgaraba/clankerauth-sdk/testing` is the issuer an application test usually wants: the two endpoints a resource server actually calls, and nothing else. It signs with a real EdDSA key and publishes it as JWKS, so every token and key list still travels the resource server's own verifier — signature, issuer, audience, type, claims, scopes, each key's sealed entry — without starting the whole issuer. It runs on Node.
+
+```ts
+import { startFakeIssuer } from "@gjermundgaraba/clankerauth-sdk/testing";
+
+const auth = await startFakeIssuer({
+  resource: "http://127.0.0.1:8080/",
+  scopes: ["notes:read", "notes:write"],
+});
+
+auth.issuer; // configure the resource server with this
+const token = await auth.sign(); // every claim is overridable: auth.sign({ exp, aud, scope })
+const key = auth.apiKey(); // every configured scope on the configured resource
+const hosts = auth.apiKey({ [hostA]: ["host:write"], [hostB]: ["host:write"] }, expiresAt);
+auth.revoke(key); // gone from the next key list, as the real issuer behaves
+auth.fail(503); // both endpoints answer this instead; auth.fail() restores them
+auth.keyLists(); // how many key lists were served
+await auth.close();
+```
+
+`apiKey` takes permissions as the real issuer does, resource identifier to scopes, so one key can reach several resources. A resource server reads its key list at most once a minute, so a test that revokes a key and expects a refusal verifies with a fresh verifier, or advances its clock past that minute. To test against the whole issuer — sign-in, consent, forward auth — use `@gjermundgaraba/clankerauth-dev`.
+
 ## Errors and observability
 
-Schema-tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauthorized` (401), `InsufficientScope` (403), `RateLimited` (429) and `ProviderUnavailable` (503), collected as `authenticationErrors`. Invalid construction fails with `ConfigurationError`.
+Schema-tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauthorized` (401), `InsufficientScope` (403) and `ProviderUnavailable` (503), collected as `authenticationErrors`. Invalid construction fails with `ConfigurationError`.
 
-There is one 403. A credential that is valid but lacks a scope is `InsufficientScope`; a credential that is not this resource's at all — the wrong audience, or an API key with no grant here, which the issuer answers `403` for — is `Unauthorized`, because from the resource's side those are the same thing.
+There is one 403. A credential that is valid but lacks a scope is `InsufficientScope`; 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 unauthenticated requests cannot become provider traffic. A failed read, or one whose caller gave up, answers `ProviderUnavailable` (503) for five seconds before the next attempt. API keys are checked online on **every request**, so revocation is effective immediately. A resource that accepts only OAuth access tokens sets `apiKeys: false`; key-shaped bearers then fail as `Unauthorized` without contacting the issuer. 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.
+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 unauthenticated requests cannot become provider traffic. A failed read, or one whose caller gave up, answers `ProviderUnavailable` (503) for five seconds before the next attempt. 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 for a minute; so disabling, deleting, re-scoping or expiring a key takes effect within about a minute, and a key the list does not hold is `Unauthorized` without further issuer traffic. A failed read, one that takes longer than three seconds, or one whose caller gave up, 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. 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.
 
-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. Publish-before-use avoids that window; it is not mandatory.
+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.
 
 The SDK Resource adapter owns authentication error encoding and challenge headers; effect-actions supplies request-scoped identity, and its authentication middleware marks every response it answers or wraps `Cache-Control: no-store`; other cache policy is the host's. Defects and interruption are not relabeled as authentication rejection. Named effects supply tracing boundaries; application logging/tracing layers remain caller-owned. No `onFailure` callbacks or hidden runtime.
 

package/dist/errors.d.ts

@@ -16,11 +16,6 @@ export declare class Unauthorized extends Unauthorized_base {
         readonly cause?: unknown;
     });
 }
-declare const RateLimited_base: Schema.Class<RateLimited, Schema.TaggedStruct<"RateLimited", {
-    readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-export declare class RateLimited extends RateLimited_base {
-}
 declare const ProviderUnavailable_base: Schema.Class<ProviderUnavailable, Schema.TaggedStruct<"ProviderUnavailable", {
     readonly operation: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -49,6 +44,6 @@ export declare class ConfigurationError extends ConfigurationError_base {
  * What verification, admission and the authorization hook refuse with — one list, so a
  * surface declares `errors: authenticationErrors` and answers every refusal the same way.
  */
-export declare const authenticationErrors: readonly [typeof Unauthorized, typeof InsufficientScope, typeof RateLimited, typeof ProviderUnavailable];
-export type AuthenticationError = Unauthorized | InsufficientScope | RateLimited | ProviderUnavailable;
+export declare const authenticationErrors: readonly [typeof Unauthorized, typeof InsufficientScope, typeof ProviderUnavailable];
+export type AuthenticationError = InstanceType<(typeof authenticationErrors)[number]>;
 export {};

package/dist/errors.js

@@ -12,8 +12,6 @@ export class Unauthorized extends Schema.TaggedError()("Unauthorized", { message
         Object.defineProperty(this, "cause", { value: options.cause });
     }
 }
-export class RateLimited extends Schema.TaggedError()("RateLimited", { message: Schema.String }, { httpApiStatus: 429 }) {
-}
 export class ProviderUnavailable extends Schema.TaggedError()("ProviderUnavailable", { operation: Schema.String }, { httpApiStatus: 503 }) {
     constructor(options) {
         super({ operation: options.operation });
@@ -32,9 +30,4 @@ export class ConfigurationError extends Schema.TaggedError()("ConfigurationError
  * What verification, admission and the authorization hook refuse with — one list, so a
  * surface declares `errors: authenticationErrors` and answers every refusal the same way.
  */
-export const authenticationErrors = [
-    Unauthorized,
-    InsufficientScope,
-    RateLimited,
-    ProviderUnavailable,
-];
+export const authenticationErrors = [Unauthorized, InsufficientScope, ProviderUnavailable];

package/dist/key-list.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The key list: how an issuer publishes the API keys granted on one resource, so its
+ * resource server verifies them offline without learning who else holds what.
+ *
+ * Each entry is found by, and sealed under, values derived from the key's SHA-256 digest
+ * — what the issuer stores — and the resource identifier. Only a holder of the key can
+ * locate or read its entry. Anyone else still sees how many entries a resource has, when
+ * they come and go, and roughly how large each grant is. A digest cannot be reversed, so
+ * neither the list nor the issuer's store yields a key.
+ *
+ * Sealing is exported for issuers, including fakes in tests; a resource server only opens.
+ */
+import { Schema } from "effect";
+/** The list's JWT `typ`, so neither a list nor an access token can pass for the other. */
+export declare const type = "key-list+jwt";
+/**
+ * How long a list decides, in seconds from its `iat`: for as long as a resource server
+ * cannot read a newer one, it keeps accepting the keys this one grants. So it is also the
+ * longest a revoked key stays usable during an issuer outage.
+ */
+export declare const lifetime: number;
+export declare const Entry: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly sealed: Schema.String;
+}>;
+export type Entry = typeof Entry.Type;
+/** The claims a list carries besides `iss`, `aud`, `iat` and `exp`. */
+export declare const Claims: Schema.Struct<{
+    readonly keys: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly sealed: Schema.String;
+    }>>;
+}>;
+/** What one key may do on the list's resource. */
+export declare const Grant: Schema.Struct<{
+    readonly keyId: Schema.NonEmptyString;
+    readonly ownerId: Schema.NonEmptyString;
+    readonly scopes: Schema.$Array<Schema.NonEmptyString>;
+    /** Epoch milliseconds; `null` for a key that does not expire. */
+    readonly expiresAt: Schema.NullOr<Schema.Finite>;
+}>;
+export type Grant = typeof Grant.Type;
+/** The digest an issuer stores for a key: SHA-256 of the whole key, prefix included. */
+export declare const digest: (key: string) => Promise<Uint8Array<ArrayBuffer>>;
+/** One key's entry on one resource, from the digest the issuer stores. */
+export declare const seal: (keyDigest: Uint8Array<ArrayBuffer>, resource: string, grant: Grant) => Promise<Entry>;
+/**
+ * What a list grants this key on its resource, or `undefined` when the list has no entry
+ * for it. Rejects only for an entry that does not open, which the issuer never writes.
+ */
+export declare const open: (key: string, resource: string, entries: ReadonlyMap<string, string>) => Promise<Grant | undefined>;

package/dist/key-list.js

@@ -0,0 +1,77 @@
+/**
+ * The key list: how an issuer publishes the API keys granted on one resource, so its
+ * resource server verifies them offline without learning who else holds what.
+ *
+ * Each entry is found by, and sealed under, values derived from the key's SHA-256 digest
+ * — what the issuer stores — and the resource identifier. Only a holder of the key can
+ * locate or read its entry. Anyone else still sees how many entries a resource has, when
+ * they come and go, and roughly how large each grant is. A digest cannot be reversed, so
+ * neither the list nor the issuer's store yields a key.
+ *
+ * Sealing is exported for issuers, including fakes in tests; a resource server only opens.
+ */
+import { Schema } from "effect";
+import { base64url } from "jose";
+/** The list's JWT `typ`, so neither a list nor an access token can pass for the other. */
+export const type = "key-list+jwt";
+/**
+ * How long a list decides, in seconds from its `iat`: for as long as a resource server
+ * cannot read a newer one, it keeps accepting the keys this one grants. So it is also the
+ * longest a revoked key stays usable during an issuer outage.
+ */
+export const lifetime = 24 * 60 * 60;
+export const Entry = Schema.Struct({ id: Schema.String, sealed: Schema.String });
+/** The claims a list carries besides `iss`, `aud`, `iat` and `exp`. */
+export const Claims = Schema.Struct({ keys: Schema.Array(Entry) });
+/** What one key may do on the list's resource. */
+export const Grant = Schema.Struct({
+    keyId: Schema.NonEmptyString,
+    ownerId: Schema.NonEmptyString,
+    scopes: Schema.Array(Schema.NonEmptyString),
+    /** Epoch milliseconds; `null` for a key that does not expire. */
+    expiresAt: Schema.NullOr(Schema.Finite),
+});
+const GrantJson = Schema.fromJsonString(Grant);
+const encoder = new TextEncoder();
+/** The digest an issuer stores for a key: SHA-256 of the whole key, prefix included. */
+export const digest = async (key) => new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(key)));
+/** One key's entry ID and sealing key on one resource. */
+const derive = async (keyDigest, resource) => {
+    const material = await crypto.subtle.importKey("raw", keyDigest, "HKDF", false, ["deriveBits"]);
+    const bits = new Uint8Array(await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(),
+        info: encoder.encode(`clankerauth key list\0${resource}`),
+    }, material, 512));
+    return {
+        id: base64url.encode(bits.subarray(0, 32)),
+        key: await crypto.subtle.importKey("raw", bits.subarray(32), "AES-GCM", false, [
+            "encrypt",
+            "decrypt",
+        ]),
+    };
+};
+/** One key's entry on one resource, from the digest the issuer stores. */
+export const seal = async (keyDigest, resource, grant) => {
+    const { id, key } = await derive(keyDigest, resource);
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoder.encode(Schema.encodeSync(GrantJson)(grant)));
+    const sealed = new Uint8Array(iv.length + ciphertext.byteLength);
+    sealed.set(iv);
+    sealed.set(new Uint8Array(ciphertext), iv.length);
+    return { id, sealed: base64url.encode(sealed) };
+};
+/**
+ * What a list grants this key on its resource, or `undefined` when the list has no entry
+ * for it. Rejects only for an entry that does not open, which the issuer never writes.
+ */
+export const open = async (key, resource, entries) => {
+    const derived = await derive(await digest(key), resource);
+    const sealed = entries.get(derived.id);
+    if (sealed === undefined)
+        return undefined;
+    const bytes = new Uint8Array(base64url.decode(sealed));
+    const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv: bytes.subarray(0, 12) }, derived.key, bytes.subarray(12));
+    return Schema.decodeUnknownSync(GrantJson)(new TextDecoder().decode(plaintext));
+};

package/dist/refresh.d.ts

@@ -0,0 +1,7 @@
+import { Duration } from "effect";
+/**
+ * How long a key list answers verification before it is read again: the delay after
+ * which a revoked, disabled, expired or re-scoped key is refused, and how often a watched
+ * connection's key is checked again. Internal: not a package entry point.
+ */
+export declare const keyListRefresh: Duration.Duration;

package/dist/refresh.js

@@ -0,0 +1,7 @@
+import { Duration } from "effect";
+/**
+ * How long a key list answers verification before it is read again: the delay after
+ * which a revoked, disabled, expired or re-scoped key is refused, and how often a watched
+ * connection's key is checked again. Internal: not a package entry point.
+ */
+export const keyListRefresh = Duration.minutes(1);

package/dist/request-policy.d.ts

@@ -1,4 +1,4 @@
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 export interface Options {
     /**
      * The origin browsers reach this app at. The application has already validated it;

package/dist/request-policy.js

@@ -9,7 +9,7 @@
  * and `notes.example:443` are different hosts here, as they are to a browser's cookie.
  */
 import { Effect } from "effect";
-import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 /**
  * The one path answered without either check. A container probe reaches the app on its
  * bind address and carries neither header, and no application has a second such path.

package/dist/resource.d.ts

@@ -1,7 +1,7 @@
 import { Context, Effect, Schema } from "effect";
 import type * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { ConfigurationError, InsufficientScope } from "./errors.ts";
+import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.ts";
 import * as Verifier from "./verify.ts";
 declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@clankerauth/CurrentPrincipal", Verifier.Principal>;
 export declare class CurrentPrincipal extends CurrentPrincipal_base {
@@ -24,7 +24,7 @@ export interface Options {
      */
     readonly publicUrl: URL;
     readonly scopes: Scopes;
-    /** `false` rejects API keys without consulting the issuer; only OAuth access tokens are accepted. */
+    /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
     readonly apiKeys?: boolean;
 }
 /**
@@ -48,11 +48,12 @@ export type Admission = {
 export declare const make: (options: Options) => Effect.Effect<{
     verifier: Verifier.Verifier;
     discovery: {
-        layer: import("effect/Layer").Layer<never, never, import("effect/unstable/http/HttpRouter").HttpRouter>;
+        layer: import("effect/Layer").Layer<never, never, import("effect/http/HttpRouter").HttpRouter>;
         metadataUrl: string;
         challenge: (challenge?: Authentication.BearerChallengeOptions) => string;
     };
     admit: (authorization: string | null | undefined, access: Action.Access) => Effect.Effect<Admission, never, never>;
+    watch: (authorization: string | null | undefined, access: Action.Access) => Effect.Effect<never, InsufficientScope | ProviderUnavailable | Unauthorized, never>;
     authorize: (action: Action.Any) => Effect.Effect<void, InsufficientScope, CurrentPrincipal>;
     session: import("@gjermundgaraba/effect-actions/ActionGroup").Implementation<import("@gjermundgaraba/effect-actions/ActionGroup").Group<"session", readonly [Action.Action<"whoami", Schema.$Record<Schema.String, Schema.Never>, Schema.Struct<{
         readonly subject: Schema.NonEmptyString;
@@ -67,10 +68,10 @@ export declare const make: (options: Options) => Effect.Effect<{
     }, never, never>;
     resource: string;
     issuer: string;
-}, ConfigurationError, import("effect/unstable/http/HttpClient").HttpClient>;
+}, ConfigurationError, import("effect/http/HttpClient").HttpClient>;
 export type Resource = Effect.Success<ReturnType<typeof make>>;
 /** Bearer authentication providing `CurrentPrincipal`, on the same admission `admit` renders. */
-export declare const middleware: (resource: Resource) => import("effect/unstable/http/HttpRouter").Middleware<{
+export declare const middleware: (resource: Resource) => import("effect/http/HttpRouter").Middleware<{
     provides: CurrentPrincipal;
     handles: never;
     error: never;

package/dist/resource.js

@@ -1,7 +1,8 @@
-import { Context, Effect, Result, Schema, SchemaAST } from "effect";
+import { Clock, Context, Duration, Effect, Result, Schema, SchemaAST } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
-import { authenticationErrors, ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
+import { HttpServerRequest, HttpServerResponse } from "effect/http";
+import { authenticationErrors, ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized, } from "./errors.js";
+import { keyListRefresh } from "./refresh.js";
 import { Session } from "./session.js";
 import * as Verifier from "./verify.js";
 const encoders = new Map(authenticationErrors.map((schema) => [
@@ -48,23 +49,23 @@ export const make = Effect.fn("Resource.make")(function* (options) {
         apiKeys: options.apiKeys,
     });
     // A request must not wait on an issuer that does not answer: the transport is
-    // interrupted and the credential refused as unavailable.
+    // interrupted and the credential refused as unavailable. A key list read gives up
+    // sooner, so a held list still decides a key.
     const deadline = (effect) => Effect.timeoutOrElse(effect, {
         duration: "5 seconds",
         orElse: () => Effect.fail(new ProviderUnavailable({ operation: "verify.timeout" })),
     });
+    const verify = (authorization) => deadline(unbounded.verify(authorization));
     const verifier = {
-        verify: (authorization) => deadline(unbounded.verify(authorization)),
+        verify,
         verifyToken: (token) => deadline(unbounded.verifyToken(token)),
     };
     const challengeValue = (error, missing) => discovery.challenge({ error, scope: missing ?? options.scopes.read });
     /**
      * The one header besides the content type that a refusal carries: an RFC 6750
-     * challenge naming only the missing scope, or an RFC 6585 retry hint.
+     * challenge naming only the missing scope.
      */
     const refusalHeader = (error, credential) => {
-        if (error instanceof RateLimited)
-            return ["retry-after", "60"];
         if (error instanceof InsufficientScope)
             return ["www-authenticate", challengeValue("insufficient_scope", error.scope)];
         // RFC 6750 §3.1: a request that carried no credentials gets no error code.
@@ -89,21 +90,42 @@ export const make = Effect.fn("Resource.make")(function* (options) {
     const missingScope = (principal) => options.scopes.write !== undefined && !principal.scopes.includes(options.scopes.write)
         ? options.scopes.write
         : undefined;
+    /** The principal an Authorization header value has for `access`, or its refusal. */
+    const principalFor = Effect.fn("Resource.principal")(function* (authorization, access) {
+        const principal = yield* verify(authorization);
+        const missing = access === "write" ? missingScope(principal) : undefined;
+        if (missing !== undefined)
+            return yield* new InsufficientScope({ scope: missing });
+        return principal;
+    });
     /**
      * Verify one Authorization header value outside an Effect router: a Node `upgrade`
      * handler, a socket, a per-request endpoint. `access` is the same declaration an
      * action carries, so `"write"` demands the write scope before a socket is established.
      */
     const admit = Effect.fn("Resource.admit")(function* (authorization, access) {
-        const verified = yield* Effect.result(verifier.verify(authorization));
+        const verified = yield* Effect.result(principalFor(authorization, access));
         if (Result.isFailure(verified))
             return yield* refuse(verified.failure, authorization);
-        const principal = verified.success;
-        const missing = access === "write" ? missingScope(principal) : undefined;
-        if (missing !== undefined)
-            return yield* refuse(new InsufficientScope({ scope: missing }), authorization);
-        return { ok: true, principal };
+        return { ok: true, principal: verified.success };
     });
+    /**
+     * Hold what `admit` let in, such as a socket, to the same header value and `access`:
+     * fails with the first refusal, once a token expires or a key is revoked, expires or
+     * loses the scope. Never succeeds; race it against the connection.
+     */
+    const watch = (authorization, access) => Effect.forever(Effect.gen(function* () {
+        const principal = yield* principalFor(authorization, access);
+        const now = yield* Clock.currentTimeMillis;
+        const remaining = Math.max(0, (principal.expiresAt ?? Infinity) - now);
+        // A key is checked again against each refreshed list, until it expires.
+        if (principal.actor.kind === "key")
+            return yield* Effect.sleep(Math.min(remaining, Duration.toMillis(keyListRefresh)));
+        // An access token cannot be revoked and never becomes valid again, so its expiry is
+        // all that ends it: no second JWKS read that an issuer outage could fail.
+        yield* Effect.sleep(remaining);
+        return yield* new Unauthorized({ message: "Authentication required" });
+    }));
     /**
      * The effect-actions pre-handler hook, bound once per surface. A read needs nothing
      * beyond what verification already required; a write needs the configured write scope.
@@ -129,6 +151,7 @@ export const make = Effect.fn("Resource.make")(function* (options) {
         verifier,
         discovery,
         admit,
+        watch,
         authorize,
         session,
         resource: identifier,

package/dist/testing.d.ts

@@ -0,0 +1,46 @@
+/** Claims set on a signed token. Each one overrides this issuer's default. */
+export interface TokenClaims {
+    readonly iss?: string;
+    readonly sub?: string;
+    readonly aud?: string | Array<string>;
+    readonly iat?: number;
+    /** Epoch seconds. Default: five minutes from now. */
+    readonly exp?: number;
+    /** Space-separated, as the wire carries it. */
+    readonly scope?: string;
+    readonly client_id?: string;
+    /** Proof of possession, for checking that a sender-constrained token is refused. */
+    readonly cnf?: {
+        readonly jkt: string;
+    };
+}
+export interface FakeIssuerOptions {
+    /** The resource identifier tokens are minted for: an application's public origin root. */
+    readonly resource: string;
+    /** The scopes a signed token, and a key minted without permissions, carry. */
+    readonly scopes: readonly string[];
+    /** Who every credential belongs to. Default `"owner"`. */
+    readonly subject?: string;
+}
+/** Resource identifier to the scopes a key has there, as the real issuer takes them. */
+export type Permissions = Readonly<Record<string, readonly string[]>>;
+export interface FakeIssuer {
+    /** What a resource server is configured with: `http://127.0.0.1:<port>/api/auth`. */
+    readonly issuer: string;
+    /** Sign an access token this issuer's JWKS verifies. */
+    readonly sign: (claims?: TokenClaims, typ?: string) => Promise<string>;
+    /**
+     * Mint an API key, listed in each granted resource's key list from its next read.
+     * Default permissions: every configured scope on the configured resource. `expiresAt`
+     * is when the key stops verifying; default never. Key IDs are `key-1`, `key-2`, ….
+     */
+    readonly apiKey: (permissions?: Permissions, expiresAt?: Date) => string;
+    /** Leave a minted key out of every key list from now on, as the real issuer does. */
+    readonly revoke: (key: string) => void;
+    /** Answer both endpoints with this status instead of serving them; omit to restore. */
+    readonly fail: (status?: number) => void;
+    /** Key lists served, so a test can see when a resource server reads its next one. */
+    readonly keyLists: () => number;
+    readonly close: () => Promise<void>;
+}
+export declare const startFakeIssuer: (options: FakeIssuerOptions) => Promise<FakeIssuer>;

package/dist/testing.js

@@ -0,0 +1,108 @@
+/**
+ * A signing fake issuer for tests: the two endpoints a resource server actually calls,
+ * and nothing else. Use it where a real issuer would make a test slow or awkward — a
+ * token that must expire in two seconds, a key granted on someone else's resource, an
+ * outage — and `@gjermundgaraba/clankerauth-dev` where the protocol itself is under test.
+ *
+ * It signs with a real EdDSA key and publishes it as JWKS, so every token and key list
+ * still travels the resource server's own verifier: signature, issuer, audience, type,
+ * claims, scopes, and each key's sealed entry. Node only.
+ */
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { Option, Schema } from "effect";
+import { exportJWK, generateKeyPair, SignJWT } from "jose";
+import * as KeyList from "./key-list.js";
+const ListRequest = Schema.fromJsonString(Schema.Struct({ resource: Schema.String }));
+export const startFakeIssuer = async (options) => {
+    const subject = options.subject ?? "owner";
+    const pair = await generateKeyPair("EdDSA");
+    const jwk = { ...(await exportJWK(pair.publicKey)), kid: "fixture", alg: "EdDSA", use: "sig" };
+    const keys = new Map();
+    let minted = 0;
+    let lists = 0;
+    let failure;
+    const server = createServer(async (request, response) => {
+        const send = (status, body) => {
+            response.writeHead(status, { "content-type": "application/json" });
+            response.end(body);
+        };
+        if (request.url === "/api/auth/jwks")
+            return send(failure ?? 200, JSON.stringify({ keys: [jwk] }));
+        if (request.url !== "/api/issuer/keyList" || request.method !== "POST")
+            return send(404, "{}");
+        lists++;
+        if (failure !== undefined)
+            return send(failure, "{}");
+        let text = "";
+        for await (const chunk of request)
+            text += String(chunk);
+        const asked = Schema.decodeUnknownOption(ListRequest)(text);
+        if (Option.isNone(asked))
+            return send(400, '{"error":"Invalid request"}');
+        const { resource } = asked.value;
+        // Like the real issuer, a list holds only what is granted on the resource it names,
+        // and only what has not expired.
+        const now = Date.now();
+        const entries = await Promise.all([...keys].flatMap(([key, { keyId, permissions, expiresAt }]) => {
+            const scopes = permissions[resource] ?? [];
+            return scopes.length && (expiresAt === null || expiresAt > now)
+                ? [
+                    KeyList.digest(key).then((digest) => KeyList.seal(digest, resource, { keyId, ownerId: subject, scopes, expiresAt })),
+                ]
+                : [];
+        }));
+        const iat = Math.floor(now / 1000);
+        const list = await new SignJWT({ keys: entries })
+            .setProtectedHeader({ alg: "EdDSA", kid: "fixture", typ: KeyList.type })
+            .setIssuer(issuer)
+            .setAudience(resource)
+            .setIssuedAt(iat)
+            .setExpirationTime(iat + KeyList.lifetime)
+            .sign(pair.privateKey);
+        return send(200, JSON.stringify({ list }));
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!(address instanceof Object))
+        throw new Error("The fake issuer failed to bind a TCP port");
+    const issuer = `http://127.0.0.1:${address.port}/api/auth`;
+    return {
+        issuer,
+        sign: (claims = {}, typ = "at+jwt") => {
+            const now = Math.floor(Date.now() / 1000);
+            return new SignJWT({
+                iss: issuer,
+                sub: subject,
+                aud: options.resource,
+                iat: now,
+                exp: now + 300,
+                client_id: "fixture",
+                scope: options.scopes.join(" "),
+                ...claims,
+            })
+                .setProtectedHeader({ alg: "EdDSA", kid: "fixture", typ })
+                .sign(pair.privateKey);
+        },
+        apiKey: (permissions = { [options.resource]: options.scopes }, expiresAt) => {
+            const key = `clankerauth_${randomBytes(48).toString("base64url")}`;
+            keys.set(key, {
+                keyId: `key-${++minted}`,
+                permissions,
+                expiresAt: expiresAt?.getTime() ?? null,
+            });
+            return key;
+        },
+        revoke: (key) => {
+            keys.delete(key);
+        },
+        fail: (status) => {
+            failure = status;
+        },
+        keyLists: () => lists,
+        close: () => new Promise((resolve, reject) => {
+            server.closeAllConnections();
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+};

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
 import { Effect } from "effect";
-import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpClient, HttpClientRequest } from "effect/http";
 import { ProviderUnavailable } from "./errors.ts";
-export declare const execute: (client: HttpClient.HttpClient, request: HttpClientRequest.HttpClientRequest) => Effect.Effect<import("effect/unstable/http/HttpClientResponse").HttpClientResponse, ProviderUnavailable, import("effect/Scope").Scope>;
+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,5 +1,5 @@
 import { Context, Effect } from "effect";
-import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
 import { ProviderUnavailable } from "./errors.js";
 // Node transports do not follow redirects by default. Also pin FetchHttpClient's policy;
 // forwarding credentials through a redirect is not an authentication fallback.

package/dist/verify.d.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
-import { HttpClient } from "effect/unstable/http";
-import { ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized } from "./errors.ts";
+import { HttpClient } from "effect/http";
+import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized } from "./errors.ts";
 import type { AuthenticationError } from "./errors.ts";
 export interface Principal {
     readonly subject: string;
@@ -14,9 +14,9 @@ export interface Principal {
     };
     /**
      * When this credential stops being valid, in epoch milliseconds: an access token's
-     * verified `exp`, so a host never decodes the token again. `undefined` for an API
-     * key, which has no token lifetime and is re-verified against the issuer on every
-     * request; a host that caches a key decision must choose its own bound.
+     * verified `exp`, so a host never decodes the token again, or an API key's expiry.
+     * `undefined` for a key that does not expire. A key can also be revoked before then;
+     * `Resource.watch` ends a connection at whichever comes first.
      */
     readonly expiresAt: number | undefined;
 }
@@ -24,7 +24,7 @@ export interface Options {
     readonly issuer: string;
     readonly resource: string;
     readonly requiredScopes?: readonly string[];
-    /** `false` rejects API keys without consulting the issuer; only OAuth access tokens are accepted. */
+    /** `false` refuses API keys without reading the issuer's key list; only OAuth access tokens are accepted. */
     readonly apiKeys?: boolean;
 }
 export interface Verifier {
@@ -35,6 +35,7 @@ export interface Verifier {
  * Acquire once per resource; transport is selected by the application, not the SDK.
  * 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 declare const make: (options: Options) => Effect.Effect<{
     verifyToken: (token: string) => Effect.Effect<{
@@ -52,8 +53,8 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
-        expiresAt: undefined;
-    }, InsufficientScope | ProviderUnavailable | RateLimited | Unauthorized, never>;
+        expiresAt: number | undefined;
+    }, InsufficientScope | ProviderUnavailable | Unauthorized, never>;
     verify: (authorization: string | null | undefined) => Effect.Effect<{
         subject: string;
         scopes: string[];
@@ -69,6 +70,6 @@ export declare const make: (options: Options) => Effect.Effect<{
             kind: "key";
             keyId: string;
         };
-        expiresAt: undefined;
-    }, InsufficientScope | ProviderUnavailable | RateLimited | Unauthorized, never>;
+        expiresAt: number | undefined;
+    }, InsufficientScope | ProviderUnavailable | Unauthorized, never>;
 }, ConfigurationError, HttpClient.HttpClient>;

package/dist/verify.js

@@ -1,7 +1,9 @@
-import { Cause, Clock, DateTime, Effect, Exit, Schema } from "effect";
+import { Cause, Clock, Effect, Exit, Ref, Result, Schema } from "effect";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
-import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
-import { ConfigurationError, InsufficientScope, ProviderUnavailable, RateLimited, Unauthorized, } from "./errors.js";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { ConfigurationError, InsufficientScope, ProviderUnavailable, Unauthorized, } from "./errors.js";
+import * as KeyList from "./key-list.js";
+import { keyListRefresh } from "./refresh.js";
 import { execute } from "./transport.js";
 const Jwks = Schema.Struct({
     keys: Schema.Array(Schema.Struct({
@@ -18,31 +20,34 @@ const Claims = Schema.Struct({
     sub: Schema.NonEmptyString,
     client_id: Schema.NonEmptyString,
     scope: Schema.String,
+    iat: Schema.Finite,
     exp: Schema.Finite,
 });
-const KeyResponse = Schema.Struct({
-    keyId: Schema.NonEmptyString,
-    ownerId: Schema.NonEmptyString,
-    resource: Schema.String,
-    scopes: Schema.Array(Schema.NonEmptyString),
-    expiresAt: Schema.NullOr(Schema.DateTimeUtcFromString),
-});
-const unauthorized = () => new Unauthorized({ message: "Authentication required" });
+/** 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 }));
+const unauthorized = (cause) => new Unauthorized({ message: "Authentication required", cause });
 /** How long a JWKS document answers verification before it is read again. */
 const documentLifetime = "1 minute";
 /** How long a failed read holds off the next one. */
 const failureCooldown = "5 seconds";
+/**
+ * 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.
+ */
+const listReadTimeout = "3 seconds";
 /**
  * Acquire once per resource; transport is selected by the application, not the SDK.
  * 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 endpoints = yield* Effect.try({
         try: () => ({
             jwks: new URL(`${options.issuer}/jwks`).href,
-            apiKey: new URL("/api/issuer/verifyApiKey", options.issuer).href,
+            keyList: new URL("/api/issuer/keyList", options.issuer).href,
         }),
         catch: () => new ConfigurationError({ message: "Invalid issuer URL" }),
     });
@@ -61,11 +66,12 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     // One read serves every key identifier until it expires, whatever its outcome, so an
     // unknown `kid` in an unauthenticated request never becomes traffic at the issuer.
     const read = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : failureCooldown);
-    // Replaying that read must not hand a later request the interruption of an earlier
+    // Replaying a read must not hand a later request the interruption of an earlier
     // one's deadline; within the window the issuer simply was not reached.
-    const keys = Effect.catchCause(read, (cause) => Cause.hasInterrupts(cause)
-        ? Effect.fail(new ProviderUnavailable({ operation: "jwks.refresh" }))
+    const replayed = (cached, operation) => Effect.catchCause(cached, (cause) => Cause.hasInterrupts(cause)
+        ? Effect.fail(new ProviderUnavailable({ operation }))
         : Effect.failCause(cause));
+    const keys = replayed(read, "jwks.refresh");
     const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
         const resolve = yield* keys;
         return yield* Effect.tryPromise({
@@ -74,29 +80,38 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             catch: unauthorized,
         });
     });
-    const verifyJwt = Effect.fn("Verifier.jwt")(function* (token) {
+    /**
+     * 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.
+     */
+    const verifySigned = Effect.fn("Verifier.signed")(function* (jws, typ) {
         const header = yield* Effect.try({
-            try: () => decodeProtectedHeader(token),
+            try: () => decodeProtectedHeader(jws),
             catch: unauthorized,
         });
         // The issuer always names its key, so key selection is never ambiguous. Reject other
-        // tokens before doing provider I/O; JOSE still enforces its algorithm allowlist.
+        // documents before doing provider I/O; JOSE still enforces its algorithm allowlist.
         if (header.alg !== "EdDSA" || header.kid === undefined)
             return yield* unauthorized();
         const key = yield* signingKey(header.kid);
         const now = yield* Clock.currentTimeMillis;
         const { payload } = yield* Effect.tryPromise({
-            try: () => jwtVerify(token, key, {
+            try: () => jwtVerify(jws, key, {
                 issuer: options.issuer,
                 audience: options.resource,
                 algorithms: ["EdDSA"],
-                typ: "at+jwt",
-                requiredClaims: ["sub", "client_id", "scope", "iat", "exp"],
+                typ,
                 currentDate: new Date(now),
             }),
             // Verification against a resolved key does no I/O either.
             catch: unauthorized,
         });
+        return payload;
+    });
+    const verifyJwt = Effect.fn("Verifier.jwt")(function* (token) {
+        const payload = yield* verifySigned(token, "at+jwt");
         if (payload.cnf !== undefined)
             return yield* unauthorized();
         const claims = yield* Schema.decodeUnknownEffect(Claims)(payload).pipe(Effect.mapError(unauthorized));
@@ -108,35 +123,67 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             expiresAt: claims.exp * 1000,
         };
     });
-    const verifyKey = Effect.fn("Verifier.apiKey")(function* (key) {
-        const request = HttpClientRequest.post(endpoints.apiKey).pipe(HttpClientRequest.setHeader("authorization", `Bearer ${key}`), HttpClientRequest.bodyJsonUnsafe({ resource: options.resource }));
+    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);
-        // The issuer answers 403 for a key with no grant on this resource. That is the same
-        // case as a token for another audience: the credential is not this resource's.
-        if (response.status === 401 || response.status === 403)
-            return yield* unauthorized();
-        if (response.status === 429)
-            return yield* new RateLimited({ message: "Authentication rate exceeded" });
         if (response.status !== 200)
             return yield* new ProviderUnavailable({
-                operation: "api-key.verify",
+                operation: "key-list.fetch",
                 cause: { status: response.status },
             });
-        const body = yield* HttpClientResponse.schemaBodyJson(KeyResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "api-key.response", cause })));
-        if (body.resource !== options.resource)
-            return yield* new ProviderUnavailable({ operation: "api-key.response" });
-        if (body.expiresAt !== null &&
-            DateTime.toEpochMillis(body.expiresAt) <= (yield* Clock.currentTimeMillis))
-            return yield* unauthorized();
+        const { list } = yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
+        // A list that does not verify is no list: the held one keeps deciding.
+        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))));
+        const claims = yield* Schema.decodeUnknownEffect(KeyListClaims)(payload).pipe(Effect.mapError(rejected));
         return {
-            subject: body.ownerId,
-            scopes: body.scopes,
-            actor: { kind: "key", keyId: body.keyId },
-            // A key's own expiry is enforced above, on every verification; it is not a
-            // lifetime a caller may hold a decision for.
-            expiresAt: undefined,
+            expiresAt: claims.exp * 1000,
+            entries: new Map(claims.keys.map((entry) => [entry.id, entry.sealed])),
         };
     }, Effect.scoped);
+    // While a list is held, a failing issuer is otherwise invisible until that list runs
+    // out. Reads are logged when they start failing and when they recover, not per retry.
+    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))), (exit) => (Exit.isSuccess(exit) ? keyListRefresh : failureCooldown));
+    // The list is verified once, when it is read. Holding its entries, not the document,
+    // is what lets keys verify through an outage that has already taken JWKS with it.
+    const held = yield* Ref.make(undefined);
+    /** The last verified list, while it is inside its window. */
+    const keyList = Effect.gen(function* () {
+        const fetched = yield* Effect.result(replayed(readList, "key-list.refresh"));
+        if (Result.isSuccess(fetched))
+            yield* Ref.set(held, fetched.success);
+        const list = yield* Ref.get(held);
+        // A read is cached past its own check, so the window is checked on every use.
+        if (list !== undefined && list.expiresAt > (yield* Clock.currentTimeMillis))
+            return list;
+        return yield* Result.isFailure(fetched)
+            ? fetched.failure
+            : new ProviderUnavailable({ operation: "key-list.expired" });
+    });
+    const verifyKey = Effect.fn("Verifier.apiKey")(function* (key) {
+        const list = yield* keyList;
+        const grant = yield* Effect.tryPromise({
+            try: () => KeyList.open(key, options.resource, list.entries),
+            catch: unauthorized,
+        });
+        // No entry is the same case as a token for another audience: not this resource's.
+        if (grant === undefined)
+            return yield* unauthorized();
+        if (grant.expiresAt !== null && grant.expiresAt <= (yield* Clock.currentTimeMillis))
+            return yield* unauthorized();
+        return {
+            subject: grant.ownerId,
+            scopes: grant.scopes,
+            actor: { kind: "key", keyId: grant.keyId },
+            expiresAt: grant.expiresAt ?? undefined,
+        };
+    });
     const verifyToken = Effect.fn("Verifier.verifyToken")(function* (token) {
         const principal = yield* token.startsWith("clankerauth_")
             ? options.apiKeys === false

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.9.0",
-  "description": "Effect-native clankerauth access-token and API-key verification, with optional effect-actions integration",
+  "version": "0.11.0",
+  "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,25 +29,34 @@
     "./effect-actions": {
       "types": "./dist/effect-actions.d.ts",
       "import": "./dist/effect-actions.js"
+    },
+    "./key-list": {
+      "types": "./dist/key-list.d.ts",
+      "import": "./dist/key-list.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "effect": "4.0.0-rc.117",
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.7.0",
+    "@gjermundgaraba/effect-actions": "0.8.0",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
+    "effect": "4.0.0-rc.118",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
-    "vite-plus": "0.3.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.7.0"
+    "@gjermundgaraba/effect-actions": "^0.8.0",
+    "effect": "^4.0.0-rc.118"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {