@friggframework/core 2.0.0--canary.686.ba9ded3.0 → 2.0.0--canary.690.33ca435.0

package/handlers/app-definition-loader.js

@@ -12,6 +12,7 @@ const {
     getEntityTypeDefinitions,
 } = require('../modules/entity-type-registry');
 const { resolveOwnershipConfig } = require('../modules/entity-scope');
+const { assertProxyConfig } = require('../modules/proxy/proxy-bases');
 const {
     resolveManagementApiConfig,
 } = require('../management-api/management-api-config');
@@ -108,6 +109,7 @@ function discoverAppDefinition() {
  * @throws {Error} Throws error if user.authModes.adopterJwt is enabled without a usable user.jwtConfig.
  * @throws {OwnershipConfigError} Throws if an ownership or scope setting is invalid (ADR-056 §3.1).
  * @throws {ManagementApiConfigError} Throws if `managementApi.proxy.scopes` is invalid (ADR-056 §3.5).
+ * @throws {ProxyConfigError} Throws if a module's `proxy.baseUrls` or an allow rule's `base` is invalid (ADR-052).
  * @throws {ScheduleConfigError} Throws if an integration's `Definition.schedule` is invalid.
  * @example
  * const { integrations, userConfig, telemetry } = loadAppDefinition();
@@ -148,7 +150,12 @@ function resolveAppDefinition(appDefinition) {
     // And for the Management API: `managementApi.proxy.scopes` decides whose
     // credentials the entity proxy may act through (ADR-056 §3.5), so an
     // unknown scope stops the app here rather than being read as a default.
-    resolveManagementApiConfig(managementApi);
+    const managementApiConfig = resolveManagementApiConfig(managementApi);
+
+    // Named proxy bases (ADR-052 amendment): a module that declares both
+    // `baseUrl` and `baseUrls`, a bad base URL or name, or an allow rule for a
+    // base the module lacks, stops the app here.
+    assertProxyConfig(moduleDefinitions, managementApiConfig.proxy);
 
     // And for each integration's `Definition.schedule`: a mistyped scope would
     // otherwise tick ONGOING_SYNC per class when per installation was meant.

package/management-api/openapi/components.js

@@ -40,7 +40,7 @@ const errorBody = {
                 code: {
                     type: 'string',
                     description:
-                        'Machine-readable code, e.g. VALIDATION_ERROR, NOT_FOUND, ENTITY_NOT_FOUND, AUTHORIZATION_SESSION_NOT_FOUND, PROXY_NOT_ALLOWED. New codes may be added.',
+                        'Machine-readable code, e.g. VALIDATION_ERROR, NOT_FOUND, ENTITY_NOT_FOUND, AUTHORIZATION_SESSION_NOT_FOUND, PROXY_NOT_ALLOWED, PROXY_UNKNOWN_BASE. New codes may be added.',
                 },
                 message: { type: 'string' },
                 details: { description: 'Optional structured details' },
@@ -287,7 +287,13 @@ const SCHEMAS = {
                 type: 'string',
                 pattern: '^/',
                 description:
-                    "Path relative to the module's base URL. No //, backslashes, ? or #, dot segments, encoded separators or double encoding. The host always comes from the module.",
+                    "Path relative to the module's base URL (the one named by `base`). No //, backslashes, ? or #, dot segments, encoded separators or double encoding. The host always comes from the module.",
+            },
+            base: {
+                type: 'string',
+                pattern: '^[a-z][a-z0-9-]*$',
+                description:
+                    "Name of one of the module's base URLs (ADR-052 amendment); default when omitted. A name the module declares, never a URL or host. An unknown name is 400 PROXY_UNKNOWN_BASE.",
             },
             query: {
                 type: 'object',
@@ -299,7 +305,8 @@ const SCHEMAS = {
                         { type: 'array', items: { type: 'string' } },
                     ],
                 },
-                description: 'Array values are sent comma-separated',
+                description:
+                    'Array values are sent comma-separated (`ids: ["1","2"]` → `ids=1,2`), except under a key ending in `[]`, which is sent once per value (`"fields[]": ["a","b"]` → `fields%5B%5D=a&fields%5B%5D=b`; an empty array sends nothing).',
             },
             headers: {
                 type: 'object',

package/management-api/openapi/v2-operations.js

@@ -165,11 +165,11 @@ const V2_OPERATIONS = {
     proxyEntityRequest: {
         summary: "Call the entity's API through Frigg (beta)",
         description:
-            "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; deny by default, only operations in the module's (or the app's) allow-list. ADR-056 §3.5: the caller needs use access to the entity in the active organization (an entity they cannot see there is 404), and the entity's scope must be in managementApi.proxy.scopes (default individual only; 403 PROXY_NOT_ALLOWED with details.reason 'scope', or 'access' for view-only access). The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
+            "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; `base` optionally names one of the module's several base URLs (default `default`; a name, never a URL), and allow-list rules match per base. Deny by default, only operations in the module's (or the app's) allow-list. ADR-056 §3.5: the caller needs use access to the entity in the active organization (an entity they cannot see there is 404), and the entity's scope must be in managementApi.proxy.scopes (default individual only; 403 PROXY_NOT_ALLOWED with details.reason 'scope', or 'access' for view-only access). The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
         requestBody: body(ref('ProxyRequest')),
         responses: {
             200: ok('Upstream answer (the status mirrors the upstream status)', ref('ProxyResponse')),
-            400: ok('INVALID_PROXY_REQUEST', ref('ProxyError')),
+            400: ok('INVALID_PROXY_REQUEST, or PROXY_UNKNOWN_BASE (`base` is not one of the module\'s base names; the message lists them)', ref('ProxyError')),
             401: ok('INVALID_CREDENTIALS or unauthenticated', ref('ProxyError')),
             403: ok("PROXY_NOT_ALLOWED: not in the allow-list, or details.reason 'scope' / 'access'", ref('ProxyError')),
             404: ok('Entity not found, or not visible in the active organization', ref('Error')),

package/modules/proxy/proxy-bases.js

@@ -0,0 +1,169 @@
+const { ProxyConfigError } = require('./proxy-errors');
+
+/**
+ * Named base URLs for the entity proxy (ADR-052, amendment 2026-10-18).
+ *
+ * A module declares where its API lives. One host is `proxy.baseUrl`, which
+ * means `{ default: baseUrl }`. A module whose API spans several hosts (Google:
+ * Drive, Docs, Sheets, Analytics Data, Ads) declares `proxy.baseUrls`, a map of
+ * name to URL. A caller picks a base by NAME in the proxy request's `base`
+ * field; it never supplies a URL or a host, so the host still comes only from
+ * the module.
+ */
+
+const DEFAULT_BASE = 'default';
+const BASE_NAME = /^[a-z][a-z0-9-]*$/;
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const describeRule = (rule) =>
+    `${rule && typeof rule.method === 'string' ? rule.method : '?'} ${
+        rule && typeof rule.path === 'string' ? rule.path : '?'
+    }`;
+
+function isValidBaseName(name) {
+    return typeof name === 'string' && name.length <= 64 && BASE_NAME.test(name);
+}
+
+function assertBaseUrl(moduleName, name, value) {
+    const where = `Module ${moduleName} proxy.baseUrls.${name}`;
+    if (typeof value !== 'string') {
+        throw new ProxyConfigError(`${where} must be an absolute https URL string (functions are not accepted)`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new ProxyConfigError(`${where} is not a valid absolute URL`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new ProxyConfigError(`${where} must use https`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new ProxyConfigError(
+            `${where} must not carry credentials, a query or a fragment`
+        );
+    }
+}
+
+/**
+ * The bases a module declares, validated.
+ *
+ * @param {object} definition - a module definition
+ * @returns {{ names: string[], values: Map<string, string|Function|undefined>, declared: boolean }}
+ *   `declared` is false when the module names no base of its own; it then has
+ *   the single base `default`, resolved from the requester at call time.
+ * @throws {ProxyConfigError}
+ */
+function resolveModuleBases(definition) {
+    const moduleName = definition?.moduleName ?? '(unnamed)';
+    const proxy = definition?.proxy;
+    const hasBaseUrl = proxy?.baseUrl !== undefined;
+    const hasBaseUrls = proxy?.baseUrls !== undefined;
+
+    if (hasBaseUrl && hasBaseUrls) {
+        throw new ProxyConfigError(
+            `Module ${moduleName} declares both proxy.baseUrl and proxy.baseUrls; use one ` +
+                '(baseUrl means { default: baseUrl })'
+        );
+    }
+    if (hasBaseUrls) {
+        if (!isPlainObject(proxy.baseUrls) || Object.keys(proxy.baseUrls).length === 0) {
+            throw new ProxyConfigError(
+                `Module ${moduleName} proxy.baseUrls must be a non-empty object of name to URL`
+            );
+        }
+        const values = new Map();
+        for (const [name, value] of Object.entries(proxy.baseUrls)) {
+            if (!isValidBaseName(name)) {
+                throw new ProxyConfigError(
+                    `Module ${moduleName} proxy.baseUrls has the invalid name ${JSON.stringify(
+                        name
+                    )}; names match ${BASE_NAME}`
+                );
+            }
+            assertBaseUrl(moduleName, name, value);
+            values.set(name, value);
+        }
+        return { names: [...values.keys()], values, declared: true };
+    }
+    return {
+        names: [DEFAULT_BASE],
+        values: new Map([[DEFAULT_BASE, proxy?.baseUrl]]),
+        declared: hasBaseUrl,
+    };
+}
+
+/** The base a rule applies to; a rule without `base` applies to `default`. */
+const ruleBase = (rule) => (rule && rule.base !== undefined ? rule.base : DEFAULT_BASE);
+
+/**
+ * Load-time check of every allow rule that names a base: the app's
+ * `managementApi.proxy.modules.<module>.allow` and each module's own
+ * `proxy.allow`. A rule for a base the module does not declare could never
+ * match, which reads as "allowed" and is not, so it stops the app.
+ *
+ * @param {Array<object>} moduleDefinitions
+ * @param {{ modules?: Object }} [proxyConfig] - resolved managementApi.proxy
+ * @throws {ProxyConfigError}
+ */
+function assertProxyConfig(moduleDefinitions, proxyConfig = {}) {
+    const namesByModule = new Map();
+    for (const definition of moduleDefinitions || []) {
+        if (!definition?.moduleName) continue;
+        const { names } = resolveModuleBases(definition);
+        namesByModule.set(definition.moduleName, names);
+        const own = definition.proxy?.allow;
+        if (Array.isArray(own)) {
+            assertRulesUseDeclaredBases(
+                definition.moduleName,
+                names,
+                own,
+                `Module ${definition.moduleName} proxy.allow`
+            );
+        }
+    }
+    for (const [moduleName, override] of Object.entries(proxyConfig.modules || {})) {
+        const names = namesByModule.get(moduleName);
+        // An override for a module that is not registered is not new: it never applied.
+        if (!names || !Array.isArray(override?.allow)) continue;
+        assertRulesUseDeclaredBases(
+            moduleName,
+            names,
+            override.allow,
+            `managementApi.proxy.modules.${moduleName}.allow`
+        );
+    }
+}
+
+function assertRulesUseDeclaredBases(moduleName, names, rules, where) {
+    for (const rule of rules) {
+        if (!isPlainObject(rule) || rule.base === undefined) continue;
+        if (!isValidBaseName(rule.base) || !names.includes(rule.base)) {
+            throw new ProxyConfigError(
+                `${where}: the rule ${describeRule(rule)} names the base ${JSON.stringify(
+                    rule.base
+                )}, which module ${moduleName} does not declare (declared: ${names.join(', ')})`
+            );
+        }
+    }
+    // A rule with no base means `default`; the module must have one.
+    if (!names.includes(DEFAULT_BASE)) {
+        const bare = rules.find((rule) => isPlainObject(rule) && rule.base === undefined);
+        if (bare) {
+            throw new ProxyConfigError(
+                `${where}: the rule ${describeRule(bare)} names no base, so it applies to ` +
+                    `"default", which module ${moduleName} does not declare (declared: ${names.join(', ')})`
+            );
+        }
+    }
+}
+
+module.exports = {
+    DEFAULT_BASE,
+    isValidBaseName,
+    resolveModuleBases,
+    ruleBase,
+    assertProxyConfig,
+};

package/modules/proxy/proxy-errors.js

@@ -17,4 +17,15 @@ class ProxyRequestError extends Error {
     }
 }
 
-module.exports = { ProxyRequestError };
+/**
+ * A module definition or the app's proxy settings are wrong. Thrown at load,
+ * so the app stops starting instead of failing on the first proxied call.
+ */
+class ProxyConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProxyConfigError';
+    }
+}
+
+module.exports = { ProxyRequestError, ProxyConfigError };

package/modules/proxy/proxy-path.js

@@ -1,4 +1,5 @@
 const { ProxyRequestError } = require('./proxy-errors');
+const { DEFAULT_BASE, ruleBase } = require('./proxy-bases');
 
 /**
  * Path rules for the entity proxy (ADR-052 §4). The caller supplies a path
@@ -133,7 +134,7 @@ function joinProxyUrl(baseUrl, normalizedPath) {
 }
 
 /**
- * Finds the allow-list rule that permits `method` on `path`.
+ * Finds the allow-list rule that permits `method` on `path` of `base`.
  *
  * Patterns use `:param` for exactly one segment and a trailing `/**` for a
  * subtree (the prefix itself included). `method: '*'` matches any method.
@@ -141,14 +142,17 @@ function joinProxyUrl(baseUrl, normalizedPath) {
  * @param {Array<{method: string, path: string}>} rules
  * @param {string} method - upper case
  * @param {string} path - normalised path
- * @returns {{method: string, path: string}|null}
+ * @param {string} [base='default'] - the named base the request targets; a
+ *   rule applies to its own `base` only (no `base` means `default`)
+ * @returns {{method: string, path: string, base?: string}|null}
  */
-function matchAllowRule(rules, method, path) {
+function matchAllowRule(rules, method, path, base = DEFAULT_BASE) {
     const requestSegments = path.split('/').slice(1);
     for (const rule of rules || []) {
         if (!rule || typeof rule.path !== 'string' || typeof rule.method !== 'string') {
             continue;
         }
+        if (ruleBase(rule) !== base) continue;
         const ruleMethod = rule.method.toUpperCase();
         if (ruleMethod !== '*' && ruleMethod !== method) continue;
         if (patternMatches(rule.path, requestSegments)) return rule;

package/modules/proxy/proxy-policy.js

@@ -1,4 +1,5 @@
 const { ProxyRequestError } = require('./proxy-errors');
+const { isValidBaseName } = require('./proxy-bases');
 
 /**
  * What the entity proxy accepts and returns (ADR-052 §5-§7). Pure functions:
@@ -52,6 +53,13 @@ const REMOVED_RESPONSE_HEADERS = [
 const invalid = (message, details) =>
     new ProxyRequestError('INVALID_PROXY_REQUEST', message, details);
 
+/**
+ * A query key ending in `[]` is sent as one `key=value` pair per array
+ * element; the requester applies the same rule (see
+ * `_rawRequest` in requester.js).
+ */
+const isRepeatedQueryKey = (key) => key.endsWith('[]');
+
 const isPlainObject = (value) =>
     value !== null && typeof value === 'object' && !Array.isArray(value);
 
@@ -61,7 +69,7 @@ const isPlainObject = (value) =>
  *
  * @param {unknown} request
  * @param {{ maxRequestBytes: number }} limits
- * @returns {{ method: string, path: string, query?: Object, headers: Object, body?: string, requestBytes: number, bodyIsJson: boolean }}
+ * @returns {{ method: string, path: string, base?: string, query?: Object, headers: Object, body?: string, requestBytes: number, bodyIsJson: boolean }}
  */
 function validateProxyRequest(request, { maxRequestBytes }) {
     if (!isPlainObject(request)) throw invalid('The proxy request must be a JSON object');
@@ -73,6 +81,19 @@ function validateProxyRequest(request, { maxRequestBytes }) {
         throw invalid('path is required', { field: 'path' });
     }
 
+    // `base` is a name, never a URL or host; anything else is refused before
+    // a module is looked up. Omitted means `default` (the caller applies it).
+    let base;
+    if (request.base !== undefined && request.base !== null) {
+        if (typeof request.base !== 'string' || !isValidBaseName(request.base)) {
+            throw invalid(
+                'base must be the name of one of the module\'s base URLs (lower case letters, digits and -), not a URL or host',
+                { field: 'base' }
+            );
+        }
+        base = request.base;
+    }
+
     let query;
     if (request.query !== undefined && request.query !== null) {
         if (!isPlainObject(request.query)) throw invalid('query must be an object', { field: 'query' });
@@ -85,8 +106,13 @@ function validateProxyRequest(request, { maxRequestBytes }) {
                     field: `query.${key}`,
                 });
             }
-            // The requester sends one value per key; arrays go comma-separated.
-            query[key] = list ? value.join(',') : value;
+            // A key ending in `[]` (`fields[]`) is sent once per value, as
+            // Airtable and Fathom expect; every other array goes comma-separated.
+            if (list) {
+                query[key] = isRepeatedQueryKey(key) ? [...value] : value.join(',');
+            } else {
+                query[key] = value;
+            }
         }
     }
 
@@ -121,16 +147,19 @@ function validateProxyRequest(request, { maxRequestBytes }) {
             `The proxied request body is larger than ${maxRequestBytes} bytes`
         );
     }
-    return { method, path: request.path, query, headers, body, bodyIsJson, requestBytes };
+    return { method, path: request.path, ...(base !== undefined && { base }), query, headers, body, bodyIsJson, requestBytes };
 }
 
 const isWildcardRule = (rule) => rule?.method === '*' || rule?.path === '/**';
 
+// A rule's `base` is checked against the module's declared bases at load, by
+// assertProxyConfig (proxy-bases.js); here only its shape is.
 const isValidRule = (rule) =>
     isPlainObject(rule) &&
     typeof rule.method === 'string' &&
     typeof rule.path === 'string' &&
-    rule.path.startsWith('/');
+    rule.path.startsWith('/') &&
+    (rule.base === undefined || isValidBaseName(rule.base));
 
 /**
  * The allow-list in force for a module: the app definition's list for it when

package/modules/requester/proxy-request.js

@@ -28,7 +28,8 @@ const MAX_REDIRECTS = 3;
  * @param {Object} [params.query]
  * @param {Object} [params.headers] - already filtered by the caller's policy
  * @param {string|Buffer} [params.body] - already serialised
- * @param {string} [params.baseUrl] - module-declared proxy base URL; falls
+ * @param {string} [params.baseUrl] - the module-declared URL of the base the
+ *   caller named (ADR-052 amendment; resolved by the use case); falls
  *   back to the requester's `proxyBaseUrl`, `baseUrl` or `baseURL`
  * @param {number} params.timeoutMs - budget for the whole call
  * @param {number} params.maxResponseBytes

package/modules/requester/requester.js

@@ -219,9 +219,14 @@ class Requester extends Delegate {
         if (options.query) {
             let queryBuild = '?';
             for (const key in options.query) {
-                queryBuild += `${encodeURIComponent(key)}=${encodeURIComponent(
-                    options.query[key]
-                )}&`;
+                const value = options.query[key];
+                // `fields[]: ['a', 'b']` -> `fields%5B%5D=a&fields%5B%5D=b`.
+                // Any other array keeps String(value), i.e. comma-joined.
+                const values =
+                    Array.isArray(value) && key.endsWith('[]') ? value : [value];
+                for (const v of values) {
+                    queryBuild += `${encodeURIComponent(key)}=${encodeURIComponent(v)}&`;
+                }
             }
             encodedUrl += queryBuild.slice(0, -1);
         }

package/modules/use-cases/execute-entity-proxy-request.js

@@ -1,10 +1,11 @@
 const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
 const { getTelemetry } = require('../../telemetry/telemetry-runtime');
-const { ProxyRequestError } = require('../proxy/proxy-errors');
+const { ProxyRequestError, ProxyConfigError } = require('../proxy/proxy-errors');
 const { SCOPES } = require('../scope-resolution');
 const { grantsUse } = require('../scope-visibility');
 const { normalizeProxyPath, matchAllowRule } = require('../proxy/proxy-path');
+const { DEFAULT_BASE, resolveModuleBases } = require('../proxy/proxy-bases');
 const {
     validateProxyRequest,
     resolveAllowRules,
@@ -18,6 +19,7 @@ const log = getLogger('frigg.api.proxy');
 /** HTTP status and audit outcome for each proxy error code (ADR-052 §10). */
 const ERROR_MAP = {
     INVALID_PROXY_REQUEST: { status: 400, outcome: 'denied' },
+    PROXY_UNKNOWN_BASE: { status: 400, outcome: 'denied' },
     PROXY_NOT_ALLOWED: { status: 403, outcome: 'denied' },
     PAYLOAD_TOO_LARGE: { status: 413, outcome: 'too_large' },
     UNSUPPORTED_MEDIA_TYPE: { status: 415, outcome: 'denied' },
@@ -110,6 +112,19 @@ class ExecuteEntityProxyRequest {
             audit.module = definition.moduleName;
             this.assertProxyable(entityId, entity, definition, user);
 
+            // The base is a name the module declared; the host comes from the
+            // module's declaration, never from the request.
+            const base = validated.base ?? DEFAULT_BASE;
+            audit.base = base;
+            const bases = this.basesOf(definition);
+            if (!bases.names.includes(base)) {
+                throw new ProxyRequestError(
+                    'PROXY_UNKNOWN_BASE',
+                    `Module ${definition.moduleName} has no base named ${base}; use one of: ${bases.names.join(', ')}`,
+                    { module: definition.moduleName, base, bases: bases.names }
+                );
+            }
+
             const credentialRef = entity.credential;
             const credentialId =
                 credentialRef && typeof credentialRef === 'object'
@@ -120,12 +135,14 @@ class ExecuteEntityProxyRequest {
             }
 
             const { rules } = resolveAllowRules(definition, this.proxyConfig.modules);
-            const rule = matchAllowRule(rules, validated.method, path);
+            const rule = matchAllowRule(rules, validated.method, path, base);
             if (!rule) {
                 throw new ProxyRequestError(
                     'PROXY_NOT_ALLOWED',
-                    `Module ${definition.moduleName} does not allow ${validated.method} on this path`,
-                    { module: definition.moduleName, method: validated.method }
+                    `Module ${definition.moduleName} does not allow ${validated.method} on this path` +
+                        // Single-base modules keep the message they always had.
+                        (bases.names.length > 1 ? ` of base ${base}` : ''),
+                    { module: definition.moduleName, method: validated.method, base }
                 );
             }
             audit.pattern = rule.path;
@@ -153,11 +170,11 @@ class ExecuteEntityProxyRequest {
                 query: validated.query,
                 headers,
                 body: validated.body,
-                baseUrl: this.resolveBaseUrl(definition, module.api),
+                baseUrl: this.resolveBaseUrl(bases, module.api, base),
                 timeoutMs: this.proxyConfig.timeoutMs,
                 maxResponseBytes: this.proxyConfig.maxResponseBytes,
                 isAllowedRedirect: (nextPath, nextMethod) =>
-                    Boolean(matchAllowRule(rules, nextMethod, nextPath)),
+                    Boolean(matchAllowRule(rules, nextMethod, nextPath, base)),
             });
             audit.upstreamStatus = upstream.status;
             audit.responseBytes = upstream.body?.length ?? 0;
@@ -249,12 +266,40 @@ class ExecuteEntityProxyRequest {
         }
     }
 
-    /** A module may pin its proxy base URL (string, or a function of the api). */
-    resolveBaseUrl(definition, api) {
-        const declared = definition.proxy?.baseUrl;
-        if (typeof declared === 'function') return declared(api);
-        if (typeof declared === 'string') return declared;
-        return undefined;
+    /**
+     * The module's bases. Load already validated the definition
+     * (assertProxyConfig), so this only fails for a definition that skipped
+     * load; that is a configuration fault (501), never an unmapped 500.
+     */
+    basesOf(definition) {
+        try {
+            return resolveModuleBases(definition);
+        } catch (error) {
+            if (!(error instanceof ProxyConfigError)) throw error;
+            throw new ProxyRequestError(
+                'PROXY_NOT_CONFIGURED',
+                `Module ${definition.moduleName} has invalid proxy settings`
+            );
+        }
+    }
+
+    /**
+     * The URL of the named base. A base the module declared never falls back
+     * to the requester's own host (that would send the module's token to a
+     * host the module did not name); only a module that declares nothing at
+     * all uses the requester's base URL, signalled by undefined.
+     */
+    resolveBaseUrl(bases, api, name) {
+        const declared = bases.values.get(name);
+        if (!bases.declared) return undefined;
+        const url = typeof declared === 'function' ? declared(api) : declared;
+        if (typeof url !== 'string' || url === '') {
+            throw new ProxyRequestError(
+                'PROXY_NOT_CONFIGURED',
+                `The module declares no usable URL for base ${name}`
+            );
+        }
+        return url;
     }
 
     /** One audit record (ADR-048) and one usage count (ADR-011) per call. */

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.686.ba9ded3.0",
+    "version": "2.0.0--canary.690.33ca435.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.686.ba9ded3.0",
-        "@friggframework/prettier-config": "2.0.0--canary.686.ba9ded3.0",
-        "@friggframework/test": "2.0.0--canary.686.ba9ded3.0",
+        "@friggframework/eslint-config": "2.0.0--canary.690.33ca435.0",
+        "@friggframework/prettier-config": "2.0.0--canary.690.33ca435.0",
+        "@friggframework/test": "2.0.0--canary.690.33ca435.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": "ba9ded3f6b459c74127bac73ac5c0696a1144421"
+    "gitHead": "33ca4351de5bab91e3aaf137f4758cb9380fcebb"
 }

package/types/modules/index.d.ts

@@ -15,7 +15,7 @@ declare module "@friggframework/core" {
 
   export interface EntityTypeEntry {
     /** The API module definition. */
-    definition: any;
+    definition: { moduleName?: string; proxy?: ModuleProxyConfig; [key: string]: any };
     /** Frozen. `{ kind: 'app' }` first when registered, then each binding integration. */
     sources: readonly EntityTypeSource[];
     /** Frozen. */
@@ -73,6 +73,23 @@ declare module "@friggframework/core" {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "*";
     /** Relative to the module's base URL. `:param` is one segment; a trailing `/**` is a subtree. */
     path: string;
+    /** Which of the module's named base URLs the rule applies to. Default `"default"`. Must be declared by the module (checked at load). */
+    base?: string;
+  }
+
+  /**
+   * A module definition's `proxy` setting (ADR-052). Declare `baseUrl` (one host,
+   * meaning `{ default: baseUrl }`) or `baseUrls` (several), never both.
+   * `baseUrls` values are absolute https URLs with no credentials, query or
+   * fragment (strings only, unlike `baseUrl`); names match `^[a-z][a-z0-9-]*$`.
+   * A caller picks a base by name in the proxy request's `base`.
+   */
+  export interface ModuleProxyConfig {
+    baseUrl?: string | ((api: any) => string);
+    baseUrls?: Record<string, string>;
+    allow?: ProxyAllowRule[];
+    headers?: string[];
+    binary?: boolean;
   }
 
   /** `appDefinition.managementApi.proxy`: the entity proxy, POST /api/v2/entities/:id/proxy (ADR-052). */