@xeplr/base-apis 2.0.3 → 2.0.5

package/README.md

@@ -114,18 +114,21 @@ createApp(3000, 'myapp', {
 
 Why on by default: a service that forgot to configure auth used to boot clean, pass every health check, and serve every route to anybody — nothing distinguished it from a working one.
 
-`remoteAuth` sends the caller's `Authorization: Bearer …` to `url + endpoint` (`/auth/api/me`) and puts the answer's `user` and `access` on `req.user` / `req.access`.
+`remoteAuth` sends the caller's `Authorization: Bearer …` **and the request it is serving** (`x-verify-method`, `x-verify-path`) to `url + endpoint` (`/auth/api/verify`). Auth answers who the caller is and whether they may call that API, so **every request is checked for access, not only for a signed-in token**; the answer's `user` and `access` go on `req.user` / `req.access`. See `@xeplr/auth`'s "Every request is checked".
 
 | situation | response |
 |---|---|
 | path starts with a `publicPaths` entry | skipped |
 | no `Bearer` token | 401 `No token provided` |
-| auth answers 401 / 403 | same status, `Invalid or expired token` |
+| auth answers `403` with `code` `DISABLED`, `HIDDEN` or `UNLICENSED` | 403 with that `code`: signed in, but not allowed this API (`UNLICENSED`: its module is not in the caller's licence) |
+| auth answers 401 / other 403 | same status, `Invalid or expired token` |
+| auth answers 200 **without** `state: 'enabled'` (an older auth, or an `endpoint` such as `/me` that only says who the caller is) | **503**: "did not say no" is not "said yes" |
 | auth unreachable, times out (`timeoutMs`, 5000), answers anything else, or answers non-JSON | **503 `Authentication service unavailable` — never let through** |
 
 - **Validated over HTTP, not in-process** — so a service needs no `@xeplr/auth` dependency (it would be a cycle), no JWT secret and no Redis. The cost is a hop per request.
-- **`cacheSeconds` (default 5)** caches a validated token per process; a revoked token keeps working that long here. `0` checks every request.
-- **`X-New-Token` is forwarded** (with `Access-Control-Expose-Headers`) when the auth service slides a token, and that answer is **not cached** — otherwise the next requests would be answered from memory without telling the client to switch, and it would be logged out when the window closed.
+- **A burst makes one call.** Requests with the same token, method and path that arrive while a check is on its way share its answer: ten at once, one call to auth. This holds with `cacheSeconds: 0` too.
+- **`cacheSeconds` (default 5)** caches each answer (allowed or refused) per token, method and path, per process; a revoked token or a changed mapping takes that long to reach here. `0` checks every request.
+- **`X-New-Token` is forwarded** (with `Access-Control-Expose-Headers`) when the auth service slides a token, to every request in the burst that shared the check, so none is rejected because the token changed. That answer is **not cached** — otherwise the next requests would be answered from memory without telling the client to switch, and it would be logged out when the window closed.
 
 ### Uploads
 

package/lib/remoteAuth.js

@@ -18,7 +18,10 @@
 // everything — deliberately, because the alternative to "auth is down so
 // nothing serves" is "auth is down so everything serves unauthenticated".
 
-var DEFAULT_ENDPOINT = '/auth/api/me';
+// Who the caller is AND whether they may call the API being served, in one
+// answer. Every request asks both: there is no identity-only check, so an app
+// cannot forget to ask about access. See @xeplr/auth's GET /verify.
+var DEFAULT_ENDPOINT = '/auth/api/verify';
 
 // Five seconds. Long enough that a busy endpoint stops making a round trip per
 // request; short enough that a logout takes effect before anyone notices.
@@ -31,6 +34,11 @@ var DEFAULT_CACHE_SECONDS = 5;
 // closed after 5s is bad; failing closed after forever is an outage.
 var DEFAULT_TIMEOUT_MS = 5000;
 
+// The 403 codes auth gives for a signed-in caller this API is refused to. Any
+// other 403 is a token problem. UNLICENSED: the API's module is not in the
+// caller's licence (@xeplr/auth's licence.use).
+var REFUSALS = ['DISABLED', 'HIDDEN', 'UNLICENSED'];
+
 /**
  * @param {object} config
  * @param {string} config.url - base URL of the auth service, e.g.
@@ -40,7 +48,9 @@ var DEFAULT_TIMEOUT_MS = 5000;
  * @param {string[]} [config.publicPaths] - path PREFIXES that skip the gate.
  * @param {number} [config.cacheSeconds=5] - per-process cache of validated
  *   tokens. 0 disables.
- * @param {string} [config.endpoint='/auth/api/me'] - the validation route.
+ * @param {string} [config.endpoint='/auth/api/verify'] - the validation route.
+ *   It must answer the access state; one that does not (an older auth, or
+ *   /me) is refused, never taken as "allowed".
  * @param {number} [config.timeoutMs=5000]
  * @returns {Function} express middleware
  */
@@ -56,11 +66,18 @@ function remoteAuth(config) {
   var timeoutMs = config.timeoutMs || DEFAULT_TIMEOUT_MS;
   var cacheSeconds = config.cacheSeconds == null ? DEFAULT_CACHE_SECONDS : config.cacheSeconds;
 
-  // token → { expires, user, access }. Per-process and deliberately not
+  // token + request → { expires, outcome }. Per-process and deliberately not
   // shared: a cache in Redis would put back the dependency this exists to
-  // remove, to save a hop it already saves.
+  // remove, to save a hop it already saves. Keyed by the request too, because
+  // the answer is about one API, not just about the token.
   var cache = new Map();
 
+  // The same key while its answer is on the way → the same promise. A burst
+  // (a dashboard firing ten widget requests at once) makes ONE call to auth,
+  // and all ten get its answer: the same user, the same state, and the same
+  // replacement token if it slid.
+  var pending = new Map();
+
   if (cacheSeconds > 0) {
     // Bounded growth. Without this a process that sees many distinct tokens
     // (every user, every rotation) keeps every one of them forever.
@@ -81,28 +98,12 @@ function remoteAuth(config) {
     return false;
   }
 
-  return async function remoteAuthMiddleware(req, res, next) {
-    if (isPublic(req.path)) return next();
-
-    var header = req.headers.authorization;
-    if (!header || header.indexOf('Bearer ') !== 0) {
-      return res.status(401).json({ error: 'No token provided' });
-    }
-    var token = header.slice('Bearer '.length);
-
-    if (cacheSeconds > 0) {
-      var hit = cache.get(token);
-      if (hit && hit.expires > Date.now()) {
-        req.user = hit.user;
-        req.access = hit.access;
-        return next();
-      }
-    }
-
+  // One call to auth → an outcome every waiter can apply.
+  async function ask(header, method, path) {
     var response;
     try {
       response = await fetch(url + endpoint, {
-        headers: { authorization: header },
+        headers: { authorization: header, 'x-verify-method': method, 'x-verify-path': path },
         signal: AbortSignal.timeout(timeoutMs)
       });
     } catch (err) {
@@ -110,34 +111,9 @@ function remoteAuth(config) {
       // establish who this is — and "cannot establish" must never resolve to
       // "let them in". Failing open here would turn one service's outage into
       // an authentication bypass across every app that trusts this gate.
-      if (req.log) req.log.error('auth unreachable: ' + err.message);
-      return res.status(503).json({ error: 'Authentication service unavailable' });
+      return { kind: 'unavailable', why: 'auth unreachable: ' + err.message };
     }
 
-    if (!response.ok) {
-      // The auth service's own answer, passed through unchanged. A 401 is a
-      // bad token; anything else is the auth service having a problem, and
-      // relabelling that as 401 would send the caller looking at their token.
-      if (response.status === 401 || response.status === 403) {
-        return res.status(response.status).json({ error: 'Invalid or expired token' });
-      }
-      if (req.log) req.log.error('auth returned ' + response.status);
-      return res.status(503).json({ error: 'Authentication service unavailable' });
-    }
-
-    var body;
-    try {
-      body = await response.json();
-    } catch (err) {
-      return res.status(503).json({ error: 'Authentication service unavailable' });
-    }
-
-    req.user = body.user;
-    // Permissions arrive with identity, in the same answer — so a route that
-    // needs to know what this caller may do does not make a second call for
-    // it.
-    req.access = body.access;
-
     // SLIDING REFRESH, FORWARDED.
     //
     // With a tolerance configured, the auth service serves an expired-but-
@@ -150,27 +126,96 @@ function remoteAuth(config) {
     // tolerance window closes, and then the user is logged out mid-session
     // with nothing in any log to connect the two.
     var newToken = response.headers.get('x-new-token');
-    if (newToken) {
-      res.setHeader('X-New-Token', newToken);
+
+    var body = null;
+    try { body = await response.json(); } catch (err) { body = null; }
+
+    if (response.status === 403 && body && REFUSALS.indexOf(body.code) !== -1) {
+      // Signed in, but not allowed this API. The code says which, so a UI can
+      // grey a disabled item out rather than treat it as missing, and tell
+      // "not in your licence" from "not for your role".
+      return { kind: 'refused', newToken: newToken, body: { error: body.error || 'Access denied', code: body.code } };
+    }
+
+    if (!response.ok) {
+      // The auth service's own answer, passed through unchanged. A 401 is a
+      // bad token; anything else is the auth service having a problem, and
+      // relabelling that as 401 would send the caller looking at their token.
+      if (response.status === 401 || response.status === 403) {
+        return { kind: 'invalid', status: response.status };
+      }
+      return { kind: 'unavailable', why: 'auth returned ' + response.status };
+    }
+
+    // 200 but no access answer: this auth does not check access (an older
+    // version, or an endpoint that only says who the caller is). Refused,
+    // because "did not say no" is not "said yes".
+    if (!body || body.state !== 'enabled') {
+      return { kind: 'unavailable', why: 'auth answered without an access state; update @xeplr/auth' };
+    }
+
+    return { kind: 'ok', newToken: newToken, user: body.user, access: body.access };
+  }
+
+  function apply(outcome, req, res, next) {
+    if (outcome.newToken) {
+      res.setHeader('X-New-Token', outcome.newToken);
       // Without this a browser cannot READ the header, so forwarding it would
       // be invisible anyway — same pair @xeplr/auth sets locally.
       res.setHeader('Access-Control-Expose-Headers', 'X-New-Token');
     }
+    if (outcome.kind === 'ok') {
+      req.user = outcome.user;
+      // Permissions arrive with identity, in the same answer — so a route that
+      // needs to know what this caller may do does not make a second call for
+      // it.
+      req.access = outcome.access;
+      return next();
+    }
+    if (outcome.kind === 'refused') return res.status(403).json(outcome.body);
+    if (outcome.kind === 'invalid') return res.status(outcome.status).json({ error: 'Invalid or expired token' });
+    if (req.log) req.log.error(outcome.why);
+    return res.status(503).json({ error: 'Authentication service unavailable' });
+  }
 
-    // NOT CACHED WHEN THE TOKEN SLID. The caller is being told to switch to a
-    // replacement, and caching the old one would answer its next few requests
-    // from memory — without the header telling it to switch. A client that
-    // missed the first one would never be told again, and would be cut off
-    // when the window closed.
-    if (cacheSeconds > 0 && !newToken) {
-      cache.set(token, {
-        user: body.user,
-        access: body.access,
-        expires: Date.now() + cacheSeconds * 1000
-      });
+  return async function remoteAuthMiddleware(req, res, next) {
+    if (isPublic(req.path)) return next();
+
+    var header = req.headers.authorization;
+    if (!header || header.indexOf('Bearer ') !== 0) {
+      return res.status(401).json({ error: 'No token provided' });
     }
+    var token = header.slice('Bearer '.length);
+    var method = req.method;
+    var path = (req.baseUrl || '') + req.path;
+    var key = token + '\n' + method + ' ' + path;
 
-    next();
+    if (cacheSeconds > 0) {
+      var hit = cache.get(key);
+      if (hit && hit.expires > Date.now()) return apply(hit.outcome, req, res, next);
+    }
+
+    var inFlight = pending.get(key);
+    if (!inFlight) {
+      inFlight = ask(header, method, path);
+      pending.set(key, inFlight);
+      inFlight.then(function (outcome) {
+        pending.delete(key);
+        // NOT CACHED WHEN THE TOKEN SLID. The caller is being told to switch
+        // to a replacement, and caching the old one would answer its next few
+        // requests from memory — without the header telling it to switch. A
+        // client that missed the first one would never be told again, and
+        // would be cut off when the window closed.
+        //
+        // Only a real answer is cached: an outage or a bad token is asked
+        // again next time.
+        var answer = outcome.kind === 'ok' || outcome.kind === 'refused';
+        if (cacheSeconds > 0 && answer && !outcome.newToken) {
+          cache.set(key, { outcome: outcome, expires: Date.now() + cacheSeconds * 1000 });
+        }
+      });
+    }
+    apply(await inFlight, req, res, next);
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/base-apis",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Base API bootstrapper — Express and plain HTTP server factories with middleware injection",
   "main": "index.js",
   "bin": {