@columenlabs/lumen-auth 0.1.232 → 0.1.234

package/README.md

@@ -19,7 +19,8 @@ Pin it to the same exact version as the other Lumen packages.
 ```ts
 import { AccessVerifier, accessToken } from '@columenlabs/lumen-auth';
 
-// One per isolate: the team's signing keys are fetched once and kept an hour.
+// One per isolate: the team's signing keys are fetched once and kept an hour. A key fetch gives up after
+// 3 s (ACCESS_CERTS_MS), only one runs at a time, and keys already held keep verifying while it retries.
 const access = new AccessVerifier({
   teamDomain: 'myteam.cloudflareaccess.com',
   aud: [env.ACCESS_AUD],            // one application's AUD tag, or several (one Worker, several hosts)

package/dist/access.d.ts

@@ -10,23 +10,38 @@ export interface AccessIdentity {
     /** Service-token client ID (`common_name`) when an Access service token, not a person, signed in. */
     serviceToken?: string;
 }
-type FetchFn = (input: string) => Promise<Response>;
 /** The header Access puts its signed token in. */
 export declare const ACCESS_HEADER = "cf-access-jwt-assertion";
 /** A request's Access token, if it has one. */
 export declare const accessToken: (request: Request) => string | undefined;
+type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * How long a fetch of the signing keys may take (ms). A key fetch sits in front of every request, so
+ * one that hangs (an Access or network incident) must never hold them: past this it fails, and the
+ * keys already held keep verifying.
+ */
+export declare const ACCESS_CERTS_MS = 3000;
 /**
  * Verifies Access tokens against the team's signing keys (fetched from
  * `https://<teamDomain>/cdn-cgi/access/certs`, kept an hour, fetched again for an unknown key id):
  * RS256 only, the audience one of `aud`, the issuer the team, not expired and not before its time.
  * Keep one per isolate so the keys are fetched once.
+ *
+ * The key fetch never holds a request for long: it gives up after `ACCESS_CERTS_MS`, only one runs at
+ * a time (every request waiting shares it), and when the hour is up the keys already held keep
+ * verifying while new ones load in the background. Only a token signed by a key never seen waits for
+ * a fetch, and fails (null) if that fetch fails.
  */
 export declare class AccessVerifier {
     private readonly cfg;
     private readonly fetchImpl;
     private readonly now;
     private keys;
+    private loading;
+    private tried;
     constructor(cfg: AccessConfig, fetchImpl?: FetchFn, now?: () => number);
+    /** Fetches the keys once for everyone waiting; bounded by ACCESS_CERTS_MS. */
+    private load;
     private keyFor;
     /** Returns the identity, or null when the token is missing/invalid. */
     verify(token: string | undefined): Promise<AccessIdentity | null>;

package/dist/access.js

@@ -18,37 +18,77 @@ const decodeJson = (s) => JSON.parse(new TextDecoder().decode(b64urlToBytes(s)))
 export const ACCESS_HEADER = 'cf-access-jwt-assertion';
 /** A request's Access token, if it has one. */
 export const accessToken = (request) => request.headers.get(ACCESS_HEADER) ?? undefined;
+/** How long the signing keys are trusted before they are fetched again (ms). */
+const KEYS_MS = 60 * 60_000;
+/**
+ * How long a fetch of the signing keys may take (ms). A key fetch sits in front of every request, so
+ * one that hangs (an Access or network incident) must never hold them: past this it fails, and the
+ * keys already held keep verifying.
+ */
+export const ACCESS_CERTS_MS = 3_000;
+/** A token naming a key id we do not hold refetches at most this often (ms), so bad tokens cannot flood the endpoint. */
+const UNKNOWN_KID_MS = 10_000;
 /**
  * Verifies Access tokens against the team's signing keys (fetched from
  * `https://<teamDomain>/cdn-cgi/access/certs`, kept an hour, fetched again for an unknown key id):
  * RS256 only, the audience one of `aud`, the issuer the team, not expired and not before its time.
  * Keep one per isolate so the keys are fetched once.
+ *
+ * The key fetch never holds a request for long: it gives up after `ACCESS_CERTS_MS`, only one runs at
+ * a time (every request waiting shares it), and when the hour is up the keys already held keep
+ * verifying while new ones load in the background. Only a token signed by a key never seen waits for
+ * a fetch, and fails (null) if that fetch fails.
  */
 export class AccessVerifier {
     cfg;
     fetchImpl;
     now;
     keys;
-    constructor(cfg, fetchImpl = (u) => fetch(u), now = Date.now) {
+    loading;
+    tried = 0;
+    constructor(cfg, fetchImpl = (u, init) => fetch(u, init), now = Date.now) {
         this.cfg = cfg;
         this.fetchImpl = fetchImpl;
         this.now = now;
     }
-    async keyFor(kid) {
-        const fresh = this.keys && this.now() - this.keys.at < 60 * 60_000;
-        if (!fresh || !this.keys?.keys.has(kid)) {
-            const res = await this.fetchImpl(`https://${this.cfg.teamDomain}/cdn-cgi/access/certs`);
-            if (!res.ok)
-                throw new Error(`access certs ${res.status}`);
-            const { keys } = (await res.json());
-            const map = new Map();
-            for (const k of keys) {
-                map.set(k.kid, await crypto.subtle.importKey('jwk', 
-                // JWK from Access's certs endpoint; the lib's JsonWebKey type isn't in scope here.
-                k, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']));
+    /** Fetches the keys once for everyone waiting; bounded by ACCESS_CERTS_MS. */
+    load() {
+        this.tried = this.now();
+        this.loading ??= (async () => {
+            try {
+                const res = await this.fetchImpl(`https://${this.cfg.teamDomain}/cdn-cgi/access/certs`, {
+                    signal: AbortSignal.timeout(ACCESS_CERTS_MS),
+                });
+                if (!res.ok)
+                    throw new Error(`access certs ${res.status}`);
+                const { keys } = (await res.json());
+                const map = new Map();
+                for (const k of keys) {
+                    map.set(k.kid, await crypto.subtle.importKey('jwk', 
+                    // JWK from Access's certs endpoint; the lib's JsonWebKey type isn't in scope here.
+                    k, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']));
+                }
+                this.keys = { at: this.now(), keys: map };
             }
-            this.keys = { at: this.now(), keys: map };
+            finally {
+                this.loading = undefined;
+            }
+        })();
+        return this.loading;
+    }
+    async keyFor(kid) {
+        const held = this.keys?.keys.get(kid);
+        if (held) {
+            // Past the hour: keep verifying with the key held while fresh ones load (a failed refresh is
+            // tried again on a later request).
+            if (this.keys && this.now() - this.keys.at >= KEYS_MS && !this.loading)
+                this.load().catch(() => { });
+            return held;
         }
+        // A key never seen: wait for a fetch (shared, bounded), unless one just failed to name it.
+        if (this.keys && !this.loading && this.now() - this.tried < UNKNOWN_KID_MS)
+            return undefined;
+        await this.load();
         return this.keys?.keys.get(kid);
     }
     /** Returns the identity, or null when the token is missing/invalid. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-auth",
-  "version": "0.1.232",
+  "version": "0.1.234",
   "description": "Lumen's sign-in checks: Cloudflare Access tokens and service tokens, verified in the Worker.",
   "license": "MIT",
   "type": "module",