@friggframework/core 2.0.0--canary.643.5ac10b7.0 → 2.0.0--canary.643.35eaec0.0

package/handlers/routers/user-router.js

@@ -6,13 +6,53 @@ const catchAsyncError = require('express-async-handler');
 const LOCAL_STAGES = ['dev', 'test', 'local'];
 
 /**
- * Best-effort client IP for the per-IP rate-limit bucket. Prefers the first hop
- * of X-Forwarded-For (set by API Gateway / proxies), falls back to the socket.
+ * 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 getClientIp(req) {
+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) {
-        return xff.split(',')[0].trim();
+        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';
 }
@@ -50,17 +90,30 @@ function assertOriginAllowed(req, userConfig) {
 
 /**
  * Set the session cookie with the hygiene ADR-034 §7 requires: httpOnly, secure
- * in non-local stages, SameSite. The access token is ALSO returned in the body
- * so token-only (header-bearer) clients work without reading the cookie.
+ * 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) {
+function setSessionCookie(res, token, ttlMinutes = 120) {
     const isLocal = LOCAL_STAGES.includes(process.env.STAGE);
-    res.cookie('frigg_session', token, {
+    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);
 }
 
 /**
@@ -104,8 +157,12 @@ function buildUserRouter({
                     throw Boom.unauthorized('Invalid credentials');
                 }
 
-                // Rate limit BEFORE any provider work (oracle protection).
-                const { allowed } = apiKeyLoginLimiter.check(getClientIp(req));
+                // 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');
                 }
@@ -118,7 +175,12 @@ function buildUserRouter({
                     module: body.module,
                 });
 
-                setSessionCookie(res, token);
+                // Align the cookie lifetime to the minted token's TTL.
+                setSessionCookie(
+                    res,
+                    token,
+                    loginWithApiKey.tokenExpiryMinutes ?? 120
+                );
                 res.status(201);
                 res.json({ token });
                 return;

package/handlers/routers/user.js

@@ -48,6 +48,23 @@ const moduleDefinitions =
 validateApiKeyAuthMode(userConfig, moduleDefinitions);
 
 const apiKeyModeEnabled = Boolean(userConfig?.authModes?.apiKey);
+
+// One-time wiring-time warning: apiKey mode is enabled but no Origin/Referer
+// allowlist is configured, so the CSRF check (assertOriginAllowed) is a no-op
+// and the SameSite=strict session cookie is the only residual protection. This
+// is intentionally NOT a hard failure — it must not break unconfigured local
+// dev — but adopters serving a browser SPA should set allowedOrigins (ADR-034 §7).
+if (
+    apiKeyModeEnabled &&
+    !Array.isArray(userConfig?.authModes?.apiKey?.allowedOrigins)
+) {
+    // eslint-disable-next-line no-console
+    console.warn(
+        '[Frigg] apiKey auth mode is enabled without user.authModes.apiKey.allowedOrigins. ' +
+            'CSRF Origin/Referer enforcement is OFF; the SameSite=strict session cookie is the only ' +
+            'residual protection. Set allowedOrigins to a list of trusted browser origins to lock this down (ADR-034 §7).'
+    );
+}
 const userRepository = createUserRepository();
 const createIndividualUser = new CreateIndividualUser({
     userRepository,

package/logs/index.js

@@ -1,7 +1,15 @@
-const {debug, initDebugLog, flushDebugLog} = require('./logger');
+const {
+    debug,
+    initDebugLog,
+    flushDebugLog,
+    redactSensitive,
+    SENSITIVE_KEYS,
+} = require('./logger');
 
 module.exports = {
     debug,
     initDebugLog,
-    flushDebugLog
-}
+    flushDebugLog,
+    redactSensitive,
+    SENSITIVE_KEYS,
+};

package/logs/logger.js

@@ -6,6 +6,127 @@ const util = require('util');
 const logs = [];
 let flushCalled = false;
 
+/**
+ * Keys whose values must never reach the logs. Matched case-insensitively.
+ * These are the credential-bearing fields a request body / headers can carry —
+ * the apiKey-login body (`{ apiKey }`), the friggToken body (`{ password }`),
+ * OAuth material, and Authorization headers. Buffered debug output (and the
+ * verbose `DEBUG_VERBOSE=1` path) is dumped verbatim on any 5xx, so a raw secret
+ * in `event.body` would otherwise land in CloudWatch (ADR-034 §4).
+ * @constant {Set<string>}
+ */
+const SENSITIVE_KEYS = new Set([
+    'apikey',
+    'api_key',
+    'password',
+    'token',
+    'authorization',
+    'refresh_token',
+    'access_token',
+]);
+
+const REDACTED = '[REDACTED]';
+// Bound recursion and body-parse cost so a pathological event can never hang or
+// blow the stack inside the logger. The logger must never throw.
+const MAX_REDACT_DEPTH = 8;
+const MAX_BODY_PARSE_LENGTH = 100000;
+
+function isSensitiveKey(key) {
+    return typeof key === 'string' && SENSITIVE_KEYS.has(key.toLowerCase());
+}
+
+/**
+ * Substring/regex fallback for a request body we could not (or should not)
+ * JSON-parse: a non-JSON body, a form-urlencoded body, or one too large to parse
+ * cheaply. Masks `"key":"value"` (JSON-ish) and `key=value` (form) shapes for the
+ * denylisted keys. Best-effort — never throws.
+ */
+function redactBodyStringFallback(body) {
+    let out = body;
+    for (const key of SENSITIVE_KEYS) {
+        // JSON-ish:  "apiKey": "secret"  ->  "apiKey":"[REDACTED]"
+        out = out.replace(
+            new RegExp(`("${key}"\\s*:\\s*)"(?:[^"\\\\]|\\\\.)*"`, 'gi'),
+            `$1"${REDACTED}"`
+        );
+        // Form-urlencoded:  apiKey=secret  ->  apiKey=[REDACTED]
+        out = out.replace(
+            new RegExp(`(${key}=)[^&\\s]*`, 'gi'),
+            `$1${REDACTED}`
+        );
+    }
+    return out;
+}
+
+/**
+ * Redact a serialized request `body` string. JSON bodies are parsed, deep-redacted
+ * and re-serialized; non-JSON / oversized bodies fall back to pattern masking.
+ * Never throws.
+ */
+function redactBodyString(body) {
+    if (body.length <= MAX_BODY_PARSE_LENGTH) {
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed === 'object') {
+                return JSON.stringify(redactValue(parsed, 0, new Set()));
+            }
+        } catch (_) {
+            // Not JSON — fall through to pattern masking below.
+        }
+    }
+    return redactBodyStringFallback(body);
+}
+
+/**
+ * Deep-clone `value`, masking any denylisted key anywhere in the structure and
+ * redacting an embedded `body` string (the Lambda/API-Gateway convention).
+ * Returns a NEW object so the caller's data is never mutated; circular refs and
+ * excessive depth are handled defensively. Never throws (guarded by the public
+ * `redactSensitive`).
+ */
+function redactValue(value, depth, seen) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (depth > MAX_REDACT_DEPTH || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+
+    if (Array.isArray(value)) {
+        return value.map((v) => redactValue(v, depth + 1, seen));
+    }
+
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (isSensitiveKey(k)) {
+            out[k] = REDACTED;
+        } else if (k.toLowerCase() === 'body' && typeof v === 'string') {
+            out[k] = redactBodyString(v);
+        } else {
+            out[k] = redactValue(v, depth + 1, seen);
+        }
+    }
+    return out;
+}
+
+/**
+ * Framework-wide redaction applied to anything buffered for logging. Strips
+ * credential-bearing fields from objects (e.g. a buffered Lambda event) before
+ * they are serialized. Non-object arguments (the event name, plain strings) pass
+ * through untouched. Guaranteed not to throw.
+ * @param {*} value
+ * @returns {*}
+ */
+function redactSensitive(value) {
+    try {
+        return redactValue(value, 0, new Set());
+    } catch (_) {
+        // A logger must never break the request it is trying to describe.
+        return value;
+    }
+}
+
 function debug(...messages) {
     if (messages.length) {
         const date = new Date();
@@ -25,8 +146,11 @@ function initDebugLog(...initMessages) {
     // Hacky but fast way to empty an array.
     logs.length = 0;
 
-    // Log initial event
-    debug(...initMessages);
+    // Redact credential-bearing fields (e.g. the login request body buffered in
+    // the Lambda event) BEFORE they are serialized and buffered. This is the one
+    // choke point every handler passes its raw event through, so masking here
+    // protects both the buffered dump and the DEBUG_VERBOSE=1 immediate path.
+    debug(...initMessages.map(redactSensitive));
 }
 
 function flushDebugLog(error) {
@@ -62,4 +186,10 @@ function flushDebugLog(error) {
     }
 }
 
-module.exports = { debug, initDebugLog, flushDebugLog };
+module.exports = {
+    debug,
+    initDebugLog,
+    flushDebugLog,
+    redactSensitive,
+    SENSITIVE_KEYS,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.643.5ac10b7.0",
+    "version": "2.0.0--canary.643.35eaec0.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.5ac10b7.0",
-        "@friggframework/prettier-config": "2.0.0--canary.643.5ac10b7.0",
-        "@friggframework/test": "2.0.0--canary.643.5ac10b7.0",
+        "@friggframework/eslint-config": "2.0.0--canary.643.35eaec0.0",
+        "@friggframework/prettier-config": "2.0.0--canary.643.35eaec0.0",
+        "@friggframework/test": "2.0.0--canary.643.35eaec0.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": "5ac10b78dec8cf766dd80584f201c7e132aeee12"
+    "gitHead": "35eaec004dc09e6263633014ba019d7b12ba07ad"
 }

package/user/use-cases/login-with-api-key.js

@@ -118,13 +118,16 @@ class LoginWithApiKey {
             throw invalidCredentials();
         }
 
-        // Allowlist = the explicit `modules` array if present, else the single
-        // `module`. Never an open set.
-        const allowlist = Array.isArray(config.modules)
-            ? config.modules
-            : config.module
-            ? [config.module]
-            : [];
+        // Allowlist = the UNION of the explicit `modules` array and the single
+        // `module` (matching validateApiKeyAuthMode's own union). This keeps the
+        // resolver and the wiring-time validator in agreement: a config like
+        // `{ modules: [], module: 'reevo' }` passes validation AND resolves to
+        // ['reevo'] here, rather than validation passing while the resolver saw
+        // an empty list and rejected every login. Never an open set.
+        const allowlist = [
+            ...(Array.isArray(config.modules) ? config.modules : []),
+            ...(config.module ? [config.module] : []),
+        ];
 
         if (allowlist.length === 0) {
             throw invalidCredentials();
@@ -192,7 +195,11 @@ class LoginWithApiKey {
                 ? providerUnavailable()
                 : invalidCredentials();
         }
-        if (!isValid) {
+        // Require a STRICT boolean pass. A module that returns a truthy value on
+        // a bad key (e.g. an error object, a non-empty string, a response body)
+        // must NOT clear the validity gate — only an explicit `true` does. The
+        // login-path contract for testAuthRequest is: throw, or return `true`.
+        if (isValid !== true) {
             throw invalidCredentials();
         }
 
@@ -213,12 +220,15 @@ class LoginWithApiKey {
         }
 
         const externalId = entityDetails?.identifiers?.externalId;
+        // Require a scalar, string-or-number identifier. Anything else (an
+        // object, array, boolean, null/undefined) is NOT a stable identifier and
+        // must be rejected rather than String()-coerced into a bogus one like
+        // "[object Object]" (ADR-034 §Security requirement 1).
         if (
-            externalId === undefined ||
-            externalId === null ||
+            (typeof externalId !== 'string' &&
+                typeof externalId !== 'number') ||
             String(externalId).trim() === ''
         ) {
-            // No stable identifier → reject (ADR-034 §Security requirement 1).
             throw invalidCredentials();
         }
 
@@ -250,13 +260,26 @@ class LoginWithApiKey {
             moduleName
         );
 
+        // Namespace the provider identity by the RESOLVED module. In a
+        // multi-module allowlist two different providers can legitimately return
+        // the SAME externalId (e.g. both use the numeric account id "42"); a bare
+        // externalId would then collapse those two distinct tenants onto one
+        // Frigg user. Prefixing with the module keeps them separate for BOTH the
+        // org-user and individual-user identity.
+        const identity = `${moduleName}:${externalId}`;
+
         // Find-or-create the Frigg user from the PROVIDER-DERIVED identity only.
         // A client-supplied appOrgId/appUserId is never read here — the caller
         // passes nothing but the key and (optionally) the allowlisted module.
         const useOrg = this.userConfig.organizationUserRequired === true;
-        const appOrgId = useOrg ? externalId : undefined;
-        const appUserId = useOrg ? undefined : externalId;
+        const appOrgId = useOrg ? identity : undefined;
+        const appUserId = useOrg ? undefined : identity;
 
+        // NOTE (accepted cleanup debt): the user is found-or-created before the
+        // credential is provisioned below. If ProcessAuthorizationCallback fails,
+        // a user with no credential/entity is left behind. Reordering to create
+        // the credential first is intentionally out of scope here; orphaned users
+        // on partial failure are tolerated and cleaned up out of band.
         const user = await this.getUserFromXFriggHeaders.execute(
             appUserId,
             appOrgId
@@ -269,9 +292,21 @@ class LoginWithApiKey {
         // Create/refresh the Credential + Entity through the same path
         // /api/authorize uses. The key is persisted only as the encrypted
         // Credential — never returned, never logged, never a JWT claim.
-        await this.processAuthorizationCallback.execute(userId, moduleName, {
-            api_key: apiKey,
-        });
+        const callbackResult = await this.processAuthorizationCallback.execute(
+            userId,
+            moduleName,
+            { api_key: apiKey }
+        );
+
+        // Defense-in-depth: never mint a session unless the credential was
+        // actually persisted. A callback that returns without a credential id
+        // means the key was not connected; minting anyway would hand out a
+        // session over a half-provisioned tenant. Fail 500-class, not 401.
+        if (!callbackResult || !callbackResult.credential_id) {
+            throw Boom.badImplementation(
+                'Login failed to create a credential for the api-key identity'
+            );
+        }
 
         // Mint an ordinary, short-lived app-user session token (never admin).
         const token = await this.createTokenForUserId.execute(

package/user/use-cases/validate-api-key-auth-mode.js

@@ -56,6 +56,48 @@ function validateApiKeyAuthMode(userConfig, moduleDefinitions = []) {
             );
         }
     }
+
+    // allowedOrigins, when present, MUST be an array. A bare string would be
+    // iterated character-by-character by the Origin/Referer allowlist check
+    // (`allowed.includes(candidate)` on a string tests substrings), silently
+    // widening or breaking CSRF enforcement.
+    if (
+        config.allowedOrigins !== undefined &&
+        !Array.isArray(config.allowedOrigins)
+    ) {
+        throw new Error(
+            'Invalid app definition: user.authModes.apiKey.allowedOrigins must be an array of origin strings.'
+        );
+    }
+
+    // rateLimit, when present, must be an object whose numeric knobs are positive
+    // finite numbers. A `0`, negative, or NaN would disable or corrupt the
+    // limiter (e.g. maxPerKey:0 rejects every request; windowMs:NaN never rolls),
+    // so fail fast at wiring time rather than shipping a broken oracle guard.
+    if (config.rateLimit !== undefined) {
+        if (
+            typeof config.rateLimit !== 'object' ||
+            config.rateLimit === null ||
+            Array.isArray(config.rateLimit)
+        ) {
+            throw new Error(
+                'Invalid app definition: user.authModes.apiKey.rateLimit must be an object.'
+            );
+        }
+        for (const field of ['maxPerKey', 'maxGlobal', 'windowMs']) {
+            const value = config.rateLimit[field];
+            if (
+                value !== undefined &&
+                (typeof value !== 'number' ||
+                    !Number.isFinite(value) ||
+                    value <= 0)
+            ) {
+                throw new Error(
+                    `Invalid app definition: user.authModes.apiKey.rateLimit.${field} must be a positive finite number.`
+                );
+            }
+        }
+    }
 }
 
 module.exports = { validateApiKeyAuthMode };