@friggframework/core 2.0.0--canary.640.b31eb4a.0 → 2.0.0--canary.643.5ac10b7.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,164 @@
+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'];
+
+/**
+ * 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.
+ */
+function getClientIp(req) {
+    const xff = req.headers['x-forwarded-for'];
+    if (typeof xff === 'string' && xff.length > 0) {
+        return xff.split(',')[0].trim();
+    }
+    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 access token is ALSO returned in the body
+ * so token-only (header-bearer) clients work without reading the cookie.
+ */
+function setSessionCookie(res, token) {
+    const isLocal = LOCAL_STAGES.includes(process.env.STAGE);
+    res.cookie('frigg_session', token, {
+        httpOnly: true,
+        secure: !isLocal,
+        sameSite: 'strict',
+        path: '/',
+    });
+}
+
+/**
+ * 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).
+                const { allowed } = apiKeyLoginLimiter.check(getClientIp(req));
+                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,
+                });
+
+                setSessionCookie(res, token);
+                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,84 @@ 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);
 
-const router = express();
-const { userConfig } = loadAppDefinition();
+// 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 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/package.json

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

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

@@ -0,0 +1,290 @@
+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 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]
+            : [];
+
+        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();
+        }
+        if (!isValid) {
+            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;
+        if (
+            externalId === undefined ||
+            externalId === null ||
+            String(externalId).trim() === ''
+        ) {
+            // No stable identifier → reject (ADR-034 §Security requirement 1).
+            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
+        );
+
+        // 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 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.
+        await this.processAuthorizationCallback.execute(userId, moduleName, {
+            api_key: apiKey,
+        });
+
+        // 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,61 @@
+/**
+ * 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)'}.`
+            );
+        }
+    }
+}
+
+module.exports = { validateApiKeyAuthMode };