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

package/handlers/rate-limiter.js

@@ -0,0 +1,90 @@
+/**
+ * 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

@@ -0,0 +1,226 @@
+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,
+};

package/handlers/routers/user.js

@@ -1,9 +1,19 @@
-const express = require('express');
 const { createAppHandler } = require('../app-handler-helpers');
-const { checkRequiredParams } = require('@friggframework/core');
 const {
     createUserRepository,
 } = require('../../user/repositories/user-repository-factory');
+const {
+    createModuleRepository,
+} = require('../../modules/repositories/module-repository-factory');
+const {
+    createCredentialRepository,
+} = require('../../credential/repositories/credential-repository-factory');
+const {
+    createIntegrationRepository,
+} = require('../../integrations/repositories/integration-repository-factory');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../../integrations/utils/map-integration-dto');
 const {
     CreateIndividualUser,
 } = require('../../user/use-cases/create-individual-user');
@@ -11,52 +21,101 @@ const { LoginUser } = require('../../user/use-cases/login-user');
 const {
     CreateTokenForUserId,
 } = require('../../user/use-cases/create-token-for-user-id');
-const catchAsyncError = require('express-async-handler');
+const {
+    GetUserFromXFriggHeaders,
+} = require('../../user/use-cases/get-user-from-x-frigg-headers');
+const { LoginWithApiKey } = require('../../user/use-cases/login-with-api-key');
+const {
+    validateApiKeyAuthMode,
+} = require('../../user/use-cases/validate-api-key-auth-mode');
+const {
+    ProcessAuthorizationCallback,
+} = require('../../modules/use-cases/process-authorization-callback');
+const { FixedWindowRateLimiter } = require('../rate-limiter');
 const { loadAppDefinition } = require('../app-definition-loader');
+const { buildUserRouter } = require('./user-router');
+
+// ---------------------------------------------------------------------------
+// Module-scope wiring (production). Kept thin; all logic lives in use cases.
+// The route factory (buildUserRouter) is side-effect-free and lives in
+// ./user-router.js so it can be unit-tested without loading an app definition.
+// ---------------------------------------------------------------------------
+const { integrations: integrationClasses, userConfig } = loadAppDefinition();
+const moduleDefinitions =
+    getModulesDefinitionFromIntegrationClasses(integrationClasses);
+
+// Fail fast if apiKey mode names a module the app does not have (no-op when off).
+validateApiKeyAuthMode(userConfig, moduleDefinitions);
+
+const apiKeyModeEnabled = Boolean(userConfig?.authModes?.apiKey);
 
-const router = express();
-const { userConfig } = loadAppDefinition();
+// 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,
     userConfig,
 });
-const loginUser = new LoginUser({
-    userRepository,
-    userConfig,
-});
+const loginUser = new LoginUser({ userRepository, userConfig });
 const createTokenForUserId = new CreateTokenForUserId({ userRepository });
 
-// define the login endpoint
-router.route('/user/login').post(
-    catchAsyncError(async (req, res) => {
-        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 });
-    })
-);
+// apiKey-mode collaborators are only wired when the mode is enabled, so an app
+// that never opts in pays nothing and behaves exactly as before.
+let loginWithApiKey = null;
+if (apiKeyModeEnabled) {
+    const moduleRepository = createModuleRepository();
+    const credentialRepository = createCredentialRepository();
+    const integrationRepository = createIntegrationRepository();
+
+    const getUserFromXFriggHeaders = new GetUserFromXFriggHeaders({
+        userRepository,
+        userConfig,
+    });
+    const processAuthorizationCallback = new ProcessAuthorizationCallback({
+        moduleRepository,
+        credentialRepository,
+        integrationRepository,
+        moduleDefinitions,
+    });
+
+    loginWithApiKey = new LoginWithApiKey({
+        userConfig,
+        moduleDefinitions,
+        getUserFromXFriggHeaders,
+        processAuthorizationCallback,
+        createTokenForUserId,
+    });
+}
+
+const rlConfig = userConfig?.authModes?.apiKey?.rateLimit || {};
+const apiKeyLoginLimiter = new FixedWindowRateLimiter({
+    windowMs: rlConfig.windowMs ?? 60000,
+    maxPerKey: rlConfig.maxPerKey ?? 10,
+    maxGlobal: rlConfig.maxGlobal ?? 1000,
+});
+
+const router = buildUserRouter({
+    userConfig,
+    loginUser,
+    createIndividualUser,
+    createTokenForUserId,
+    loginWithApiKey,
+    apiKeyLoginLimiter,
+});
 
 const handler = createAppHandler('HTTP Event: User', router);
 

package/index.js

@@ -31,6 +31,10 @@ const {
     GetUserFromAdopterJwt,
 } = require('./user/use-cases/get-user-from-adopter-jwt');
 const { AuthenticateUser } = require('./user/use-cases/authenticate-user');
+const { LoginWithApiKey } = require('./user/use-cases/login-with-api-key');
+const {
+    validateApiKeyAuthMode,
+} = require('./user/use-cases/validate-api-key-auth-mode');
 
 const {
     CredentialRepository,
@@ -121,6 +125,8 @@ module.exports = {
     GetUserFromXFriggHeaders,
     GetUserFromAdopterJwt,
     AuthenticateUser,
+    LoginWithApiKey,
+    validateApiKeyAuthMode,
     CredentialRepository,
     ModuleRepository,
     IntegrationMappingRepository,

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.640.5140601.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.640.5140601.0",
-        "@friggframework/prettier-config": "2.0.0--canary.640.5140601.0",
-        "@friggframework/test": "2.0.0--canary.640.5140601.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": "51406015cf670753915e87f84a29f2d6067cd5be"
+    "gitHead": "35eaec004dc09e6263633014ba019d7b12ba07ad"
 }

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

@@ -0,0 +1,325 @@
+const Boom = require('@hapi/boom');
+const { Module } = require('../../modules/module');
+
+/**
+ * Maximum accepted length of a submitted API key. Capped before any provider
+ * work so the endpoint cannot be used to smuggle arbitrarily large payloads or
+ * amplify an oracle attack. Generous enough for JWT-shaped or concatenated keys.
+ * @constant {number}
+ */
+const DEFAULT_MAX_API_KEY_LENGTH = 8192;
+
+/**
+ * Classify an error thrown by the module's Requester while validating or
+ * identifying a key, per ADR-034 §Security requirement 6 ("Outage ≠ invalid").
+ *
+ * A definitive provider rejection (401/403, or any other non-5xx client error)
+ * means the key is bad. A 5xx, a network failure, or a timeout means the
+ * provider is unavailable and MUST NOT be reported as an invalid key nor allowed
+ * to mint a session.
+ *
+ * @param {*} err - The thrown error.
+ * @returns {'invalid'|'unavailable'} classification
+ */
+function classifyProviderError(err) {
+    const status =
+        err?.statusCode ?? err?.response?.status ?? err?.status ?? undefined;
+
+    if (typeof status === 'number' && status >= 400 && status < 500) {
+        // 401/403 and any other definitive 4xx from the provider → bad key.
+        return 'invalid';
+    }
+    // 5xx, or no status at all (timeout / DNS / socket error) → outage.
+    return 'unavailable';
+}
+
+/**
+ * Generic invalid-credentials error. Deliberately identical for every failure
+ * reason on the bad-key path so the endpoint never enumerates users or keys
+ * (ADR-034 §Security requirement 3).
+ * @returns {Boom} 401
+ */
+function invalidCredentials() {
+    return Boom.unauthorized('Invalid credentials');
+}
+
+/**
+ * Provider-unavailable error, distinct from invalid credentials. No session is
+ * created and no cookie is cleared when this is thrown (ADR-034 §6).
+ * @returns {Boom} 503
+ */
+function providerUnavailable() {
+    return Boom.serverUnavailable('Identity provider unavailable');
+}
+
+/**
+ * Use case implementing the ADR-034 `apiKey` auth mode: log a browser end user
+ * in with their own product API key, validated *through the api-module itself*.
+ *
+ * Flow (see ADR-034):
+ *   1. Validate + identify the key via the configured identity module's
+ *      Requester (`testAuthRequest`, then `getEntityDetails`).
+ *   2. Derive a provider-authoritative tenant identity — NEVER from client input.
+ *   3. Find-or-create the Frigg user from that identity (ordinary app user).
+ *   4. Create the Credential + Entity via `ProcessAuthorizationCallback`.
+ *   5. Mint a short-lived Frigg session token and return it.
+ *
+ * @class LoginWithApiKey
+ */
+class LoginWithApiKey {
+    /**
+     * @param {Object} params
+     * @param {Object} params.userConfig - App-definition `user` config (reads `authModes.apiKey`).
+     * @param {Array<Object>} params.moduleDefinitions - Module definitions available to the app.
+     * @param {import('./get-user-from-x-frigg-headers').GetUserFromXFriggHeaders} params.getUserFromXFriggHeaders - Reused find-or-create path.
+     * @param {import('../../modules/use-cases/process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback - Reused credential/entity creation.
+     * @param {import('./create-token-for-user-id').CreateTokenForUserId} params.createTokenForUserId - Reused session-token minting.
+     * @param {number} [params.tokenExpiryMinutes=120] - Access token TTL. Short by design (ADR-034 §5): revocation latency is bounded by this.
+     * @param {number} [params.maxApiKeyLength=8192] - Length cap enforced before any provider work.
+     * @param {typeof Module} [params.ModuleClass=Module] - Injectable Module class (for testing without a real Requester).
+     */
+    constructor({
+        userConfig,
+        moduleDefinitions,
+        getUserFromXFriggHeaders,
+        processAuthorizationCallback,
+        createTokenForUserId,
+        tokenExpiryMinutes = 120,
+        maxApiKeyLength = DEFAULT_MAX_API_KEY_LENGTH,
+        ModuleClass = Module,
+    }) {
+        this.userConfig = userConfig || {};
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.getUserFromXFriggHeaders = getUserFromXFriggHeaders;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.createTokenForUserId = createTokenForUserId;
+        this.tokenExpiryMinutes = tokenExpiryMinutes;
+        this.maxApiKeyLength = maxApiKeyLength;
+        this.ModuleClass = ModuleClass;
+    }
+
+    /**
+     * Resolve which identity module a request may use.
+     *
+     * The module is fixed by config (`authModes.apiKey.module`). A multi-identity
+     * app MAY configure an allowlist (`authModes.apiKey.modules`) and let the
+     * client pick one via the request body — but only from that allowlist. A
+     * client-supplied module that is not allowlisted is rejected generically, so
+     * the endpoint cannot be steered at an arbitrary module.
+     *
+     * @param {string} [requestedModule] - Optional module name from the request body.
+     * @returns {string} The resolved module name.
+     * @throws {Boom} 401 generic if apiKey mode is unconfigured or the request names a non-allowlisted module.
+     */
+    resolveModuleName(requestedModule) {
+        const config = this.userConfig.authModes?.apiKey;
+        if (!config) {
+            // apiKey mode not enabled for this app.
+            throw invalidCredentials();
+        }
+
+        // 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();
+        }
+
+        if (requestedModule) {
+            if (!allowlist.includes(requestedModule)) {
+                throw invalidCredentials();
+            }
+            return requestedModule;
+        }
+
+        // No client-specified module: only unambiguous when exactly one is configured.
+        if (allowlist.length === 1) {
+            return allowlist[0];
+        }
+
+        // Multi-identity app but the client did not name a module.
+        throw invalidCredentials();
+    }
+
+    /**
+     * Validate the key against the provider and derive a provider-authoritative
+     * tenant identity. Reused by login (and available for refresh re-validation,
+     * ADR-034 §5): a revoked key stops validating here.
+     *
+     * @param {string} apiKey
+     * @param {string} moduleName
+     * @returns {Promise<{ externalId: string, moduleDefinition: Object }>}
+     * @throws {Boom} 401 invalid credentials on a bad/rejected key or missing identifier; 503 on provider outage.
+     */
+    async validateAndIdentify(apiKey, moduleName) {
+        const moduleDefinition = this.moduleDefinitions.find(
+            (def) => def.moduleName === moduleName
+        );
+        if (!moduleDefinition) {
+            // Should be caught at config-validation time; treat a runtime miss
+            // as a server misconfiguration rather than leaking specifics.
+            throw Boom.badImplementation(
+                `apiKey identity module '${moduleName}' is not registered`
+            );
+        }
+
+        const module = new this.ModuleClass({ definition: moduleDefinition });
+
+        // Seed the api client with the key without persisting anything.
+        const setAuthParams =
+            moduleDefinition.requiredAuthMethods?.setAuthParams;
+        if (typeof setAuthParams === 'function') {
+            await setAuthParams(module.api, { api_key: apiKey });
+        } else if (typeof module.api?.setApiKey === 'function') {
+            module.api.setApiKey(apiKey);
+        }
+
+        // 1) Validity. Call testAuthRequest directly (NOT module.testAuth, which
+        //    swallows the error and would collapse 401 and 503 into one `false`).
+        let isValid;
+        try {
+            isValid =
+                await moduleDefinition.requiredAuthMethods.testAuthRequest(
+                    module.api
+                );
+        } catch (err) {
+            throw classifyProviderError(err) === 'unavailable'
+                ? providerUnavailable()
+                : invalidCredentials();
+        }
+        // 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();
+        }
+
+        // 2) Identity. Derive the tenant id from the provider response only.
+        let entityDetails;
+        try {
+            entityDetails =
+                await moduleDefinition.requiredAuthMethods.getEntityDetails(
+                    module.api,
+                    { api_key: apiKey },
+                    undefined,
+                    undefined
+                );
+        } catch (err) {
+            throw classifyProviderError(err) === 'unavailable'
+                ? providerUnavailable()
+                : invalidCredentials();
+        }
+
+        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 (
+            (typeof externalId !== 'string' &&
+                typeof externalId !== 'number') ||
+            String(externalId).trim() === ''
+        ) {
+            throw invalidCredentials();
+        }
+
+        return { externalId: String(externalId), moduleDefinition };
+    }
+
+    /**
+     * Execute the api-key login.
+     *
+     * @param {Object} input
+     * @param {string} input.apiKey - The submitted product API key.
+     * @param {string} [input.module] - Optional module name (multi-identity apps only; allowlisted).
+     * @returns {Promise<{ token: string, userId: string, module: string }>} The minted session token and principal.
+     * @throws {Boom} 401 generic on invalid key / missing identifier / unconfigured mode; 503 on provider outage.
+     */
+    async execute({ apiKey, module: requestedModule } = {}) {
+        // Cap length and shape BEFORE any provider work (ADR-034 §3).
+        if (typeof apiKey !== 'string' || apiKey.length === 0) {
+            throw invalidCredentials();
+        }
+        if (apiKey.length > this.maxApiKeyLength) {
+            throw invalidCredentials();
+        }
+
+        const moduleName = this.resolveModuleName(requestedModule);
+
+        const { externalId } = await this.validateAndIdentify(
+            apiKey,
+            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 ? 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
+        );
+        const userId = user.getId();
+        if (!userId) {
+            throw invalidCredentials();
+        }
+
+        // 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.
+        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(
+            userId,
+            this.tokenExpiryMinutes
+        );
+
+        return { token, userId, module: moduleName };
+    }
+}
+
+module.exports = {
+    LoginWithApiKey,
+    classifyProviderError,
+    DEFAULT_MAX_API_KEY_LENGTH,
+};

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

@@ -0,0 +1,103 @@
+/**
+ * Validate the `user.authModes.apiKey` block of an app definition against the
+ * app's registered module definitions (ADR-034 §Config).
+ *
+ * Default-off: when `authModes.apiKey` is absent this is a no-op, so apps that
+ * do not opt in are completely unaffected. When present, every named identity
+ * module MUST exist in the app's modules, or the app is misconfigured and we
+ * fail fast at wiring time rather than at first login.
+ *
+ * Accepts either:
+ *   - `authModes.apiKey.module`  — a single identity module (the common case), or
+ *   - `authModes.apiKey.modules` — an allowlist of identity modules (multi-identity apps).
+ *
+ * @param {Object} userConfig - The app definition's `user` config (may be null).
+ * @param {Array<Object>} moduleDefinitions - Registered module definitions (each with `moduleName`).
+ * @throws {Error} If apiKey mode is declared but names no module, or names a module the app does not register.
+ * @returns {void}
+ */
+function validateApiKeyAuthMode(userConfig, moduleDefinitions = []) {
+    const config = userConfig?.authModes?.apiKey;
+    if (!config) {
+        return; // apiKey mode not enabled — nothing to validate.
+    }
+
+    const named = [];
+    if (Array.isArray(config.modules)) {
+        named.push(...config.modules);
+    }
+    if (config.module) {
+        named.push(config.module);
+    }
+
+    if (named.length === 0) {
+        throw new Error(
+            'Invalid app definition: user.authModes.apiKey is enabled but names no identity module. ' +
+                "Set authModes.apiKey.module = '<moduleName>' (or authModes.apiKey.modules = ['<moduleName>', ...])."
+        );
+    }
+
+    const known = new Set(
+        (moduleDefinitions || [])
+            .map((def) => def && def.moduleName)
+            .filter(Boolean)
+    );
+
+    for (const moduleName of named) {
+        if (typeof moduleName !== 'string' || moduleName.trim() === '') {
+            throw new Error(
+                'Invalid app definition: user.authModes.apiKey names a non-string module.'
+            );
+        }
+        if (!known.has(moduleName)) {
+            throw new Error(
+                `Invalid app definition: user.authModes.apiKey.module '${moduleName}' is not a registered module. ` +
+                    `Registered modules: ${[...known].join(', ') || '(none)'}.`
+            );
+        }
+    }
+
+    // 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 };