@gjermundgaraba/clankerauth-sdk 0.11.0 → 0.12.0

package/README.md

@@ -8,16 +8,16 @@ Effect-native [clankerauth](https://github.com/gjermundgaraba/clankerauth) verif
 vp add @gjermundgaraba/clankerauth-sdk
 ```
 
-Effect is a peer: the application installs Effect 4, still a release candidate, and the SDK shares that copy.
+Effect is a peer: the application installs Effect 4, and the SDK shares that copy.
 
 ```sh
-vp add effect@rc
+vp add effect
 ```
 
 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.8.0
+vp add @gjermundgaraba/effect-actions@^0.9.0
 ```
 
 ## Entry points
@@ -225,7 +225,7 @@ 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`.
+`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 once a minute for the keys it names, so a test that revokes a key and expects a refusal verifies with a fresh verifier, or advances its clock past that minute. A key minted after a verifier's read is refused until that read is five seconds old, so a test mints its keys before its first request. To test against the whole issuer — sign-in, consent, forward auth — use `@gjermundgaraba/clankerauth-dev`.
 
 ## Errors and observability
 
@@ -233,7 +233,7 @@ Schema-tagged errors, all from `@gjermundgaraba/clankerauth-sdk/errors`: `Unauth
 
 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 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.
+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, 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 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, 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; 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/refresh.d.ts

@@ -1,7 +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
+ * How long a key list answers the keys it names before it is read again: the delay after
+ * which a revoked, disabled or re-scoped key loses what it had, 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

@@ -1,7 +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
+ * How long a key list answers the keys it names before it is read again: the delay after
+ * which a revoked, disabled or re-scoped key loses what it had, 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/verify.js

@@ -1,4 +1,4 @@
-import { Cause, Clock, Effect, Exit, Ref, Result, Schema } from "effect";
+import { Cause, Clock, Duration, Effect, Exit, Ref, 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";
@@ -29,8 +29,11 @@ const KeyListClaims = KeyList.Claims.pipe(Schema.fieldsAssign({ exp: Schema.Fini
 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 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.
@@ -65,7 +68,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     }, Effect.scoped);
     // 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);
+    const read = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : cooldown);
     // 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 replayed = (cached, operation) => Effect.catchCause(cached, (cause) => Cause.hasInterrupts(cause)
@@ -137,6 +140,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         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 {
+            readAt: yield* Clock.currentTimeMillis,
             expiresAt: claims.exp * 1000,
             entries: new Map(claims.keys.map((entry) => [entry.id, entry.sealed])),
         };
@@ -149,17 +153,17 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         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));
+        : 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);
     // 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* () {
+    /** 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(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.
+        // A list is held 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)
@@ -167,11 +171,22 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             : new ProviderUnavailable({ operation: "key-list.expired" });
     });
     const verifyKey = Effect.fn("Verifier.apiKey")(function* (key) {
-        const list = yield* keyList;
-        const grant = yield* Effect.tryPromise({
+        const open = (list) => Effect.tryPromise({
             try: () => KeyList.open(key, options.resource, list.entries),
             catch: unauthorized,
         });
+        const now = yield* Clock.currentTimeMillis;
+        const current = yield* Ref.get(held);
+        // One read decides the keys it names for a minute, without the issuer.
+        const list = current !== undefined &&
+            now - current.readAt < Duration.toMillis(keyListRefresh) &&
+            current.expiresAt > now
+            ? current
+            : yield* latest;
+        // A key it does not name may have been created since, so the list is read again,
+        // unless a read answered within the cooldown and there is nothing new to look in.
+        const grant = (yield* open(list)) ??
+            (yield* Effect.flatMap(latest, (next) => next === list ? Effect.succeed(undefined) : open(next)));
         // No entry is the same case as a token for another audience: not this resource's.
         if (grant === undefined)
             return yield* unauthorized();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -46,17 +46,17 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@gjermundgaraba/effect-actions": "0.8.0",
+    "@gjermundgaraba/effect-actions": "0.9.0",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
-    "effect": "4.0.0-rc.118",
+    "effect": "4.0.0",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
     "vite-plus": "1.0.0"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.8.0",
-    "effect": "^4.0.0-rc.118"
+    "@gjermundgaraba/effect-actions": "^0.9.0",
+    "effect": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {