@friggframework/core 2.0.0--canary.643.45b1fbc.0 → 2.0.0--canary.636.7dc8dca.0

package/modules/requester/requester.js

@@ -1,4 +1,5 @@
 const fetch = require('node-fetch');
+const { AsyncLocalStorage } = require('async_hooks');
 const { Delegate } = require('../../core');
 const { FetchError } = require('../../errors');
 const { get } = require('../../assertions');
@@ -7,6 +8,14 @@ const { getTelemetry } = require('../../telemetry/telemetry-runtime');
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const MAX_AUTH_RETRIES = 3;
 
+// This context marks the async call chain that holds the refresh slot, and
+// names the requester that holds it. Token requests re-enter _rawRequest
+// through this._post. A 401 from inside that chain must fail fast: if it
+// joins the refresh in flight, it awaits its own promise and hangs. The
+// identity keeps a second requester used inside the chain out of the check.
+// AsyncLocalStorage reaches the nested calls without help from the subclasses.
+const refreshContext = new AsyncLocalStorage();
+
 class Requester extends Delegate {
     constructor(params) {
         super(params);
@@ -14,6 +23,11 @@ class Requester extends Delegate {
         this.isRefreshable = false;
         this.refreshCount = 0;
         this.authGraceRetryCount = 0;
+        // Concurrent 401s share one refreshAuth() run. See _refreshAuthOnce().
+        this._inFlightRefresh = null;
+        // This counter increases when the tokens change. A stale 401 (the
+        // token changed already) then retries and does not refresh again.
+        this._authGeneration = 0;
         this.DLGT_INVALID_AUTH = 'INVALID_AUTH';
         this.delegateTypes.push(this.DLGT_INVALID_AUTH);
         this.agent = get(params, 'agent', null);
@@ -184,6 +198,10 @@ class Requester extends Delegate {
 
         options.headers = await this.addAuthHeaders(options.headers);
 
+        // A 401 that arrives after a concurrent refresh is stale. It is not
+        // proof that the new token failed.
+        const authGenerationAtDispatch = this._authGeneration;
+
         if (this.agent) options.agent = this.agent;
 
         // Per-attempt timeout — fresh AbortController per call so the retry
@@ -266,6 +284,26 @@ class Requester extends Delegate {
             }
 
             if (status === 401) {
+                // A 401 from inside the refresh flow means the provider
+                // rejected the credential itself (invalid_client). A new
+                // refresh cannot help. A join would await this same call.
+                if (this._isInsideRefreshFlow()) {
+                    throw await this._invalidateAuth(
+                        encodedUrl,
+                        options,
+                        response
+                    );
+                }
+
+                const tokenReplacedWhileInFlight =
+                    this._authGeneration !== authGenerationAtDispatch;
+                if (this.isRefreshable && tokenReplacedWhileInFlight) {
+                    // This request did not try the current token. Retry with
+                    // it. Do not spend one more provider-side rotation.
+                    clearRequestTimer();
+                    return this._rawRequest(url, options, attempt + 1);
+                }
+
                 if (!this.isRefreshable) {
                     // Up to MAX_AUTH_RETRIES grace retries before invalidating
                     // — a 401 alone isn't proof the credential is bad.
@@ -290,14 +328,15 @@ class Requester extends Delegate {
                     );
                 }
 
-                if (this.refreshCount < MAX_AUTH_RETRIES) {
-                    this.refreshCount++;
-                    const refreshSucceeded = await this.refreshAuth();
-                    if (refreshSucceeded) {
-                        clearRequestTimer();
-                        return this._rawRequest(url, options, attempt + 1);
-                    }
+                // Concurrent 401s share one refresh. Independent refreshes
+                // kill each other, because many providers use single-use
+                // refresh tokens. Only the initiator spends the retry budget.
+                const refreshAlreadyInFlight = Boolean(this._inFlightRefresh);
 
+                if (
+                    !refreshAlreadyInFlight &&
+                    this.refreshCount >= MAX_AUTH_RETRIES
+                ) {
                     throw await this._invalidateAuth(
                         encodedUrl,
                         options,
@@ -305,6 +344,16 @@ class Requester extends Delegate {
                     );
                 }
 
+                if (!refreshAlreadyInFlight) {
+                    this.refreshCount++;
+                }
+
+                const refreshSucceeded = await this._refreshAuthOnce();
+                if (refreshSucceeded) {
+                    clearRequestTimer();
+                    return this._rawRequest(url, options, attempt + 1);
+                }
+
                 throw await this._invalidateAuth(encodedUrl, options, response);
             }
 
@@ -427,6 +476,64 @@ class Requester extends Delegate {
         return this._request(options.url, fetchOptions);
     }
 
+    /**
+     * Runs one refreshAuth() at a time. The first caller starts the refresh.
+     * Callers that arrive during the refresh await the same promise. The
+     * check-and-store step is synchronous. Thus two concurrent callers
+     * cannot both start a refresh.
+     *
+     * @returns {Promise<boolean>} True if the refresh succeeded.
+     */
+    _refreshAuthOnce() {
+        if (!this._inFlightRefresh) {
+            // Keep .finally last. The stored promise must be the promise
+            // that clears the slot. Then the slot is free before a waiter
+            // resumes.
+            this._inFlightRefresh = this._adoptOrRefresh().finally(() => {
+                this._inFlightRefresh = null;
+            });
+        }
+        return this._inFlightRefresh;
+    }
+
+    /**
+     * Adopts a newer stored credential, or refreshes. Both steps run inside
+     * the marker, because the marker must cover the whole time this instance
+     * holds the slot. The adoption lives here, not in refreshAuth(), so a
+     * module that overrides refreshAuth() still gets it.
+     *
+     * @returns {Promise<boolean>} True if the instance holds a usable token.
+     */
+    async _adoptOrRefresh() {
+        const refreshSucceeded = await refreshContext.run(
+            { requester: this },
+            async () => {
+                if (await this._adoptNewerCredential()) return true;
+                return this.refreshAuth();
+            }
+        );
+        if (refreshSucceeded) this._authGeneration++;
+        return refreshSucceeded;
+    }
+
+    /**
+     * Hook for requesters that hold a rotating stored credential. Return true
+     * when the instance adopted a newer stored credential and needs no
+     * refresh. A module backed by a vendor SDK overrides this, calls super,
+     * and then copies the adopted tokens into its SDK client.
+     *
+     * @returns {Promise<boolean>} True if the instance adopted a newer
+     *   credential.
+     */
+    async _adoptNewerCredential() {
+        return false;
+    }
+
+    /** True while this instance runs its own refresh. */
+    _isInsideRefreshFlow() {
+        return refreshContext.getStore()?.requester === this;
+    }
+
     async refreshAuth() {
         throw new Error('refreshAuth not yet defined in child of Requester');
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.643.45b1fbc.0",
+    "version": "2.0.0--canary.636.7dc8dca.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.643.45b1fbc.0",
-        "@friggframework/prettier-config": "2.0.0--canary.643.45b1fbc.0",
-        "@friggframework/test": "2.0.0--canary.643.45b1fbc.0",
+        "@friggframework/eslint-config": "2.0.0--canary.636.7dc8dca.0",
+        "@friggframework/prettier-config": "2.0.0--canary.636.7dc8dca.0",
+        "@friggframework/test": "2.0.0--canary.636.7dc8dca.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "45b1fbc6d4d5ef082814f0cfa848dad2838a97ca"
+    "gitHead": "7dc8dca491feccbc4bc9933b971ac8044155efb3"
 }

package/types/module-plugin/index.d.ts

@@ -41,6 +41,7 @@ declare module "@friggframework/module-plugin" {
     ): Promise<any>;
     parseBody(response: any): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
 
     delegate: any;
     delegateTypes: any[];
@@ -72,6 +73,7 @@ declare module "@friggframework/module-plugin" {
     _put(options: RequestOptions): Promise<any>;
     _delete(options: RequestOptions): Promise<any>;
     refreshAuth(): Promise<any>;
+    _adoptNewerCredential(): Promise<boolean>;
   }
 
   type RequestOptions = {
@@ -201,6 +203,7 @@ declare module "@friggframework/module-plugin" {
     addAuthHeaders(headers: object): Promise<object>;
     isAuthenticated(): boolean;
     refreshAuth(): Promise<void>;
+    _adoptNewerCredential(): Promise<boolean>;
     getTokenFromUsernamePassword(): Promise<Token>;
     getTokenFromClientCredentials(): Promise<Token>;
   }

package/handlers/rate-limiter.js

@@ -1,90 +0,0 @@
-/**
- * Minimal, dependency-free, in-process fixed-window rate limiter for the
- * unauthenticated login route (ADR-034 §Security requirement 3).
- *
- * Two independent windows are enforced per call:
- *   - per key (typically the client IP), and
- *   - a global counter across all keys.
- *
- * Purpose is to blunt use of the endpoint as a key-validation oracle against the
- * upstream provider. In a multi-instance serverless deployment each container
- * holds its own counters, so this is a floor, not a global guarantee — pair it
- * with an infra-level limit (API Gateway / WAF) for a hard ceiling. It is
- * deliberately self-contained and unit-testable.
- *
- * @class FixedWindowRateLimiter
- */
-class FixedWindowRateLimiter {
-    /**
-     * @param {Object} [options]
-     * @param {number} [options.windowMs=60000] - Window length in milliseconds.
-     * @param {number} [options.maxPerKey=10] - Max attempts per key per window.
-     * @param {number} [options.maxGlobal=1000] - Max attempts across all keys per window.
-     * @param {() => number} [options.now] - Clock (injectable for tests).
-     */
-    constructor({
-        windowMs = 60000,
-        maxPerKey = 10,
-        maxGlobal = 1000,
-        now = () => Date.now(),
-    } = {}) {
-        this.windowMs = windowMs;
-        this.maxPerKey = maxPerKey;
-        this.maxGlobal = maxGlobal;
-        this.now = now;
-        this.buckets = new Map(); // key -> { count, windowStart }
-        this.global = { count: 0, windowStart: 0 };
-    }
-
-    _rollGlobal(ts) {
-        if (ts - this.global.windowStart >= this.windowMs) {
-            this.global = { count: 0, windowStart: ts };
-        }
-    }
-
-    _rollKey(bucket, ts) {
-        if (!bucket || ts - bucket.windowStart >= this.windowMs) {
-            return { count: 0, windowStart: ts };
-        }
-        return bucket;
-    }
-
-    /**
-     * Record an attempt for `key` and report whether it is allowed.
-     * @param {string} key - Identity for the per-key window (e.g. client IP).
-     * @returns {{ allowed: boolean, scope?: 'key'|'global' }}
-     */
-    check(key) {
-        const ts = this.now();
-        const bucketKey = key || 'unknown';
-
-        this._rollGlobal(ts);
-        if (this.global.count >= this.maxGlobal) {
-            return { allowed: false, scope: 'global' };
-        }
-
-        let bucket = this._rollKey(this.buckets.get(bucketKey), ts);
-        if (bucket.count >= this.maxPerKey) {
-            this.buckets.set(bucketKey, bucket);
-            return { allowed: false, scope: 'key' };
-        }
-
-        bucket = { count: bucket.count + 1, windowStart: bucket.windowStart };
-        this.buckets.set(bucketKey, bucket);
-        this.global = {
-            count: this.global.count + 1,
-            windowStart: this.global.windowStart,
-        };
-
-        // Opportunistic cleanup so the Map cannot grow unbounded across windows.
-        if (this.buckets.size > 10000) {
-            for (const [k, b] of this.buckets) {
-                if (ts - b.windowStart >= this.windowMs) this.buckets.delete(k);
-            }
-        }
-
-        return { allowed: true };
-    }
-}
-
-module.exports = { FixedWindowRateLimiter };

package/handlers/routers/user-router.js

@@ -1,226 +0,0 @@
-const express = require('express');
-const Boom = require('@hapi/boom');
-const { checkRequiredParams } = require('@friggframework/core');
-const catchAsyncError = require('express-async-handler');
-
-const LOCAL_STAGES = ['dev', 'test', 'local'];
-
-/**
- * Number of trusted proxies (API Gateway, ALB, CloudFront, …) in front of the
- * app. The client IP is taken this many hops from the RIGHT of X-Forwarded-For.
- * Defaults to 1 (the single trusted hop AWS API Gateway adds). Only a positive
- * finite integer is honored; anything else falls back to 1.
- */
-function trustedProxyDepth(userConfig) {
-    const configured =
-        userConfig?.authModes?.apiKey?.rateLimit?.trustedProxyDepth;
-    if (
-        typeof configured === 'number' &&
-        Number.isInteger(configured) &&
-        configured > 0
-    ) {
-        return configured;
-    }
-    return 1;
-}
-
-/**
- * Client IP for the per-IP rate-limit bucket, derived from a TRUSTED position in
- * X-Forwarded-For.
- *
- * X-Forwarded-For is `client, proxy1, …, proxyN`, where each trusted proxy
- * APPENDS the address it received the request from. The LEFTMOST entry is
- * therefore attacker-controlled (a client can pre-seed it), so keying the limiter
- * off `split(',')[0]` let an attacker mint a fresh bucket per request and defeat
- * the per-IP cap entirely. We instead read the entry `trustedProxyDepth` hops
- * from the right — the value stamped by the first trusted proxy — which the
- * client cannot forge. Falls back to the socket address when no XFF is present.
- *
- * NOTE: `maxGlobal` on the limiter is the only hard in-process ceiling this
- * endpoint has, and even that is per-container in a multi-instance serverless
- * deployment. The real per-IP control belongs at the edge (WAF / API Gateway
- * throttling); this limiter is a floor, not a guarantee.
- */
-function getClientIp(req, userConfig) {
-    const xff = req.headers['x-forwarded-for'];
-    if (typeof xff === 'string' && xff.length > 0) {
-        const parts = xff
-            .split(',')
-            .map((p) => p.trim())
-            .filter(Boolean);
-        if (parts.length > 0) {
-            const depth = trustedProxyDepth(userConfig);
-            const idx = Math.max(0, parts.length - depth);
-            return parts[idx];
-        }
-    }
-    return req.ip || req.connection?.remoteAddress || 'unknown';
-}
-
-/**
- * CSRF Origin/Referer allowlist for the cookie-bearing apiKey login (ADR-034 §7).
- * Enforced only when the app configures `authModes.apiKey.allowedOrigins`.
- * Default (unconfigured): no origin restriction beyond the SameSite cookie —
- * documented, and appropriate for token-only (non-cookie) SPA usage.
- */
-function assertOriginAllowed(req, userConfig) {
-    const allowed = userConfig?.authModes?.apiKey?.allowedOrigins;
-    if (!Array.isArray(allowed) || allowed.length === 0) {
-        return; // not configured → rely on SameSite; see ADR-034 §7.
-    }
-    const origin = req.headers.origin;
-    const referer = req.headers.referer || req.headers.referrer;
-    const candidate =
-        origin ||
-        (referer
-            ? (() => {
-                  try {
-                      const u = new URL(referer);
-                      return `${u.protocol}//${u.host}`;
-                  } catch {
-                      return null;
-                  }
-              })()
-            : null);
-
-    if (!candidate || !allowed.includes(candidate)) {
-        throw Boom.forbidden('Origin not allowed');
-    }
-}
-
-/**
- * Set the session cookie with the hygiene ADR-034 §7 requires: httpOnly, secure
- * in non-local stages, SameSite. The cookie lifetime is aligned to the session
- * token TTL so the browser drops the cookie exactly when the token stops being
- * valid (no stale cookie outliving its token, and no token outliving its cookie).
- * The access token is ALSO returned in the body so token-only (header-bearer)
- * clients work without reading the cookie.
- *
- * @param {import('express').Response} res
- * @param {string} token
- * @param {number} [ttlMinutes=120] - Session token TTL; drives Max-Age/Expires.
- */
-function setSessionCookie(res, token, ttlMinutes = 120) {
-    const isLocal = LOCAL_STAGES.includes(process.env.STAGE);
-    const options = {
-        httpOnly: true,
-        secure: !isLocal,
-        sameSite: 'strict',
-        path: '/',
-    };
-    // Align cookie lifetime to the token TTL (express sets both Max-Age and
-    // Expires from maxAge). Guard against a non-positive/NaN TTL.
-    if (Number.isFinite(ttlMinutes) && ttlMinutes > 0) {
-        options.maxAge = ttlMinutes * 60 * 1000;
-    }
-    res.cookie('frigg_session', token, options);
-}
-
-/**
- * Build the user router. Dependencies are injected so the routes can be tested
- * in isolation. `POST /user/login` is polymorphic (ADR-034):
- *   { username, password } → friggToken (unchanged)
- *   { apiKey }             → apiKey mode (module-validated), when enabled.
- *
- * This module has NO import-time side effects — the production wiring lives in
- * `user.js`, which loads the app definition and calls this factory.
- *
- * @param {Object} deps
- * @param {Object} deps.userConfig
- * @param {import('../../user/use-cases/login-user').LoginUser} deps.loginUser
- * @param {import('../../user/use-cases/create-individual-user').CreateIndividualUser} deps.createIndividualUser
- * @param {import('../../user/use-cases/create-token-for-user-id').CreateTokenForUserId} deps.createTokenForUserId
- * @param {import('../../user/use-cases/login-with-api-key').LoginWithApiKey|null} deps.loginWithApiKey - null when apiKey mode is off.
- * @param {import('../rate-limiter').FixedWindowRateLimiter} deps.apiKeyLoginLimiter
- * @returns {express.Router}
- */
-function buildUserRouter({
-    userConfig,
-    loginUser,
-    createIndividualUser,
-    createTokenForUserId,
-    loginWithApiKey,
-    apiKeyLoginLimiter,
-}) {
-    const router = express();
-    const apiKeyModeEnabled = Boolean(loginWithApiKey);
-
-    router.route('/user/login').post(
-        catchAsyncError(async (req, res) => {
-            const body = req.body || {};
-
-            // Dispatch: an { apiKey } body selects the apiKey mode. The bodies
-            // are disjoint, so a password login is never affected by this branch.
-            if (typeof body.apiKey === 'string') {
-                // Generic rejection when the mode is not enabled — no enumeration.
-                if (!apiKeyModeEnabled) {
-                    throw Boom.unauthorized('Invalid credentials');
-                }
-
-                // Rate limit BEFORE any provider work (oracle protection). The
-                // bucket key is derived from a trusted XFF position so a client
-                // cannot rotate it to escape the per-IP cap.
-                const { allowed } = apiKeyLoginLimiter.check(
-                    getClientIp(req, userConfig)
-                );
-                if (!allowed) {
-                    throw Boom.tooManyRequests('Too many requests');
-                }
-
-                // CSRF: cookie-bearing route.
-                assertOriginAllowed(req, userConfig);
-
-                const { token } = await loginWithApiKey.execute({
-                    apiKey: body.apiKey,
-                    module: body.module,
-                });
-
-                // Align the cookie lifetime to the minted token's TTL.
-                setSessionCookie(
-                    res,
-                    token,
-                    loginWithApiKey.tokenExpiryMinutes ?? 120
-                );
-                res.status(201);
-                res.json({ token });
-                return;
-            }
-
-            // friggToken path — UNCHANGED.
-            const { username, password } = checkRequiredParams(req.body, [
-                'username',
-                'password',
-            ]);
-            const user = await loginUser.execute({ username, password });
-            const token = await createTokenForUserId.execute(user.getId(), 120);
-            res.status(201);
-            res.json({ token });
-        })
-    );
-
-    router.route('/user/create').post(
-        catchAsyncError(async (req, res) => {
-            const { username, password } = checkRequiredParams(req.body, [
-                'username',
-                'password',
-            ]);
-
-            const user = await createIndividualUser.execute({
-                username,
-                password,
-            });
-            const token = await createTokenForUserId.execute(user.getId(), 120);
-            res.status(201);
-            res.json({ token });
-        })
-    );
-
-    return router;
-}
-
-module.exports = {
-    buildUserRouter,
-    getClientIp,
-    assertOriginAllowed,
-    setSessionCookie,
-};