@gjermundgaraba/clankerauth-sdk 0.26.1 → 0.26.3

package/README.md

@@ -340,9 +340,9 @@ 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 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.
+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 runs its two fetches together, the list and the JWKS it is verified with when none is held, and gives each three seconds, so a slow fetch does not cut the other short. A key list read therefore ends within three seconds, whatever stalls, and never fails a key 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.
+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. The same holds on a read with no JWKS held: its JWKS fetch runs beside the list's, so a list signed by a key minted after that fetch began fails verification until the next JWKS read. The bundled issuer mints its signing key when it starts, so a fresh issuer's first list is signed by the key its JWKS publishes. 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's resource maps verification failures to effect-actions' refusals and its own 503; effect-actions supplies request-scoped identity, challenge headers and `Cache-Control: no-store` on every response to a request it authenticates; 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/verify.d.ts

@@ -85,7 +85,8 @@ export declare const store: () => Store;
  * 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 on each of its fetches after three seconds.
+ * The one exception is a key list read, which runs its fetches together and gives up on each
+ * 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, Result, Schema } from "effect";
+import { Clock, Duration, Effect, Fiber, 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";
@@ -37,9 +37,9 @@ const documentLifetime = Duration.minutes(1);
  */
 const cooldown = Duration.seconds(5);
 /**
- * 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.
+ * 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 = Duration.seconds(3);
 const deadline = (operation) => (effect) => Effect.timeoutOrElse(effect, {
@@ -52,7 +52,8 @@ const deadline = (operation) => (effect) => Effect.timeoutOrElse(effect, {
  * 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 on each of its fetches after three seconds.
+ * The one exception is a key list read, which runs its fetches together and gives up on each
+ * after three seconds.
  */
 export const make = Effect.fn("Verifier.make")(function* (options) {
     const client = yield* HttpClient.HttpClient;
@@ -155,10 +156,11 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
                 });
             return yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
         });
+        // why: the JWKS read runs beside the list's, on its own deadline, so neither spends the other's.
+        const signing = yield* Effect.forkScoped(keys.pipe(deadline("jwks.timeout")));
         const { list } = yield* fetched.pipe(deadline("key-list.timeout"));
         const rejected = (cause) => new ProviderUnavailable({ operation: "key-list.verify", 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 payload = yield* verifySigned(list, KeyList.type, Fiber.join(signing)).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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "jose": "6.2.12",
+    "jose": "6.2.13",
     "oauth4webapi": "3.8.8",
     "proper-lockfile": "4.1.2"
   },