@gjermundgaraba/clankerauth-sdk 0.26.0 → 0.26.1

package/README.md

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

package/dist/verify.d.ts

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

package/dist/verify.js

@@ -37,17 +37,22 @@ const documentLifetime = Duration.minutes(1);
  */
 const cooldown = Duration.seconds(5);
 /**
- * How long a key list read may take. Under `Resource`'s five-second deadline, so a stalled
- * issuer fails the read, not the request, and a held list still decides.
+ * How long each fetch of a key list read may take: the list, and the JWKS it is verified
+ * with when none is held. Under `Resource`'s five-second deadline, so an issuer that stops
+ * answering fails the read, not the request, and a held list still decides.
  */
-const listReadTimeout = "3 seconds";
+const listReadTimeout = Duration.seconds(3);
+const deadline = (operation) => (effect) => Effect.timeoutOrElse(effect, {
+    duration: listReadTimeout,
+    orElse: () => Effect.fail(new ProviderUnavailable({ operation })),
+});
 /**
  * A verifier over `options.store`; transport is selected by the application, not the SDK.
  * It holds nothing but its options, the store and the HTTP client, so acquiring one per
  * request costs nothing: every read it makes runs in the verification that needs it.
  * Verification runs to completion: a deadline is the request edge's policy, which
  * `Resource` applies, so an in-process caller can await a provider call it cannot cancel.
- * The one exception is a key list read, which gives up after three seconds.
+ * The one exception is a key list read, which gives up on each of its fetches after three seconds.
  */
 export const make = Effect.fn("Verifier.make")(function* (options) {
     const client = yield* HttpClient.HttpClient;
@@ -72,26 +77,28 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     /** The keys read within their lifetime, a failed read's failure within its cooldown, or a read now. */
     const keys = Effect.gen(function* () {
         const settled = options.store.jwks.get(options.issuer);
-        const now = yield* Clock.currentTimeMillis;
+        const startedAt = yield* Clock.currentTimeMillis;
         if (settled !== undefined) {
             const answers = "keys" in settled ? documentLifetime : cooldown;
-            if (now - settled.readAt < Duration.toMillis(answers))
+            if (startedAt - settled.readAt < Duration.toMillis(answers))
                 return "keys" in settled
                     ? settled.keys
                     : yield* new ProviderUnavailable({ operation: settled.failure });
         }
         const read = yield* Effect.result(document());
         const readAt = yield* Clock.currentTimeMillis;
-        // why: a failure never replaces an outcome that ended after it began; a success always writes.
-        if (Result.isSuccess(read) ||
-            (options.store.jwks.get(options.issuer)?.readAt ?? -Infinity) < now)
-            options.store.jwks.set(options.issuer, Result.isSuccess(read)
-                ? { readAt, keys: read.success }
-                : { readAt, failure: read.failure.operation });
-        return Result.isSuccess(read) ? read.success : yield* read.failure;
+        if (Result.isSuccess(read)) {
+            options.store.jwks.set(options.issuer, { readAt, keys: read.success });
+            return read.success;
+        }
+        // why: a failure never replaces an outcome that ended after it began.
+        if ((options.store.jwks.get(options.issuer)?.readAt ?? -Infinity) >= startedAt)
+            return yield* read.failure;
+        options.store.jwks.set(options.issuer, { readAt, failure: read.failure.operation });
+        return yield* read.failure;
     });
-    const signingKey = Effect.fn("Verifier.signingKey")(function* (kid) {
-        const jwks = { keys: [...(yield* keys)] };
+    const signingKey = Effect.fn("Verifier.signingKey")(function* (kid, held) {
+        const jwks = { keys: [...(yield* held)] };
         return yield* Effect.tryPromise({
             try: () => createLocalJWKSet(jwks)({ alg: "EdDSA", kid }),
             catch: unauthorized,
@@ -101,9 +108,9 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
      * A document this issuer signed for this resource: EdDSA under a key it names, with the
      * expected `typ`, issuer and audience, and not expired. Which claims it must carry is
      * its schema's to say. `Unauthorized` means it is not to be trusted; what that amounts
-     * to is the caller's to say.
+     * to is the caller's to say. Its signing keys are `held`'s, the store's JWKS by default.
      */
-    const verifySigned = Effect.fn("Verifier.signed")(function* (jws, typ) {
+    const verifySigned = Effect.fn("Verifier.signed")(function* (jws, typ, held = keys) {
         const header = yield* Effect.try({
             try: () => decodeProtectedHeader(jws),
             catch: unauthorized,
@@ -111,7 +118,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
         // why: refused before any JWKS read, so an unauthenticated request causes no issuer traffic.
         if (header.alg !== "EdDSA" || header.kid === undefined)
             return yield* unauthorized();
-        const key = yield* signingKey(header.kid);
+        const key = yield* signingKey(header.kid, held);
         const now = yield* Clock.currentTimeMillis;
         const { payload } = yield* Effect.tryPromise({
             try: () => jwtVerify(jws, key, {
@@ -139,15 +146,19 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
     });
     const listDocument = Effect.fn("Verifier.keyList")(function* () {
         const request = HttpClientRequest.post(endpoints.keyList).pipe(HttpClientRequest.bodyJsonUnsafe({ resource: options.resource }));
-        const response = yield* execute(client, request);
-        if (response.status !== 200)
-            return yield* new ProviderUnavailable({
-                operation: "key-list.fetch",
-                cause: { status: response.status },
-            });
-        const { list } = yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
+        const fetched = Effect.gen(function* () {
+            const response = yield* execute(client, request);
+            if (response.status !== 200)
+                return yield* new ProviderUnavailable({
+                    operation: "key-list.fetch",
+                    cause: { status: response.status },
+                });
+            return yield* HttpClientResponse.schemaBodyJson(KeyListResponse)(response).pipe(Effect.mapError((cause) => new ProviderUnavailable({ operation: "key-list.decode", cause })));
+        });
+        const { list } = yield* fetched.pipe(deadline("key-list.timeout"));
         const rejected = (cause) => new ProviderUnavailable({ operation: "key-list.verify", cause });
-        const payload = yield* verifySigned(list, KeyList.type).pipe(Effect.catchTag("Unauthorized", (cause) => Effect.fail(rejected(cause))));
+        // why: a JWKS read on its own deadline, so a cold one does not spend the list's.
+        const payload = yield* verifySigned(list, KeyList.type, keys.pipe(deadline("jwks.timeout"))).pipe(Effect.catchTag("Unauthorized", (cause) => Effect.fail(rejected(cause))));
         const claims = yield* Schema.decodeUnknownEffect(KeyListClaims)(payload).pipe(Effect.mapError(rejected));
         return {
             readAt: yield* Clock.currentTimeMillis,
@@ -167,10 +178,7 @@ export const make = Effect.fn("Verifier.make")(function* (options) {
             return settled.failure === undefined
                 ? undefined
                 : yield* new ProviderUnavailable({ operation: settled.failure });
-        const read = yield* Effect.result(listDocument().pipe(Effect.timeoutOrElse({
-            duration: listReadTimeout,
-            orElse: () => Effect.fail(new ProviderUnavailable({ operation: "key-list.timeout" })),
-        })));
+        const read = yield* Effect.result(listDocument());
         const readAt = yield* Clock.currentTimeMillis;
         const before = options.store.keyLists.get(listed);
         const failing = before?.failure !== undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/clankerauth-sdk",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "description": "Effect-native clankerauth access-token and offline API-key verification, with optional effect-actions integration",
   "license": "MIT",
   "repository": {