@gjermundgaraba/clankerauth-sdk 0.13.0 → 0.14.0

package/README.md

@@ -17,7 +17,7 @@ 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.10.0
+vp add @gjermundgaraba/effect-actions@^0.11.0
 ```
 
 ## Entry points
@@ -296,7 +296,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, 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.
+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.
 
 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.js

@@ -63,9 +63,9 @@ const build = Effect.fn("Resource.layer")(function* (authentication, { scopes, r
         requiredScopes: [required],
         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. A key list read gives up
-    // sooner, so a held list still decides a key.
+    // A request must not wait on an issuer that does not answer: the credential is refused
+    // as unavailable, and a read no other request waits on is interrupted. 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" })),

package/dist/verify.js

@@ -1,4 +1,4 @@
-import { Cause, Clock, Duration, Effect, Exit, Ref, Result, Schema } from "effect";
+import { 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";
@@ -66,15 +66,10 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             keys: jwks.keys.map(({ key_ops, ...key }) => key_ops ? { ...key, key_ops: [...key_ops] } : key),
         });
     }, 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 : 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)
-        ? Effect.fail(new ProviderUnavailable({ operation }))
-        : Effect.failCause(cause));
-    const keys = replayed(read, "jwks.refresh");
+    // One read serves every key identifier until it expires, or for the cooldown if it
+    // failed, so an unknown `kid` in an unauthenticated request never becomes traffic at
+    // the issuer. A read every caller gave up on is dropped, and the next caller reads again.
+    const keys = yield* Effect.cachedWithTTL(document(), (exit) => Exit.isSuccess(exit) ? documentLifetime : cooldown);
     const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
         const resolve = yield* keys;
         return yield* Effect.tryPromise({
@@ -159,7 +154,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     const held = yield* Ref.make(undefined);
     /** 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"));
+        const fetched = yield* Effect.result(readList);
         if (Result.isSuccess(fetched))
             yield* Ref.set(held, fetched.success);
         const list = yield* Ref.get(held);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.13.0",
+  "version": "0.14.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.10.0",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@types/node": "26.6.2",
-    "effect": "4.0.0",
+    "@gjermundgaraba/effect-actions": "0.11.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@types/node": "26.6.4",
+    "effect": "4.0.2",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
-    "vite-plus": "1.0.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.10.0",
-    "effect": "^4.0.0"
+    "@gjermundgaraba/effect-actions": "^0.11.0",
+    "effect": "^4.0.2"
   },
   "peerDependenciesMeta": {
     "@gjermundgaraba/effect-actions": {