@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

package/modules/module.js

@@ -21,8 +21,17 @@ class Module extends Delegate {
      * @param {string} params.userId The user id
      * @param {Object} params.entity The entity record from the database
      * @param {string} [params.state] Optional OAuth state value forwarded to the API client (round-trips through the OAuth provider).
+     * @param {Object} [params.resolvedEnv] definition.env as Module.create() resolved it (may be undefined).
+     * @param {boolean} [params.envResolved=false] true when resolvedEnv carries the resolved env, even an undefined one; otherwise the static definition.env is used.
      */
-    constructor({ definition, userId = null, entity: entityObj = null, state = null }) {
+    constructor({
+        definition,
+        userId = null,
+        entity: entityObj = null,
+        state = null,
+        resolvedEnv,
+        envResolved = false,
+    }) {
         super({ definition, userId, entity: entityObj });
 
         this.validateDefinition(definition);
@@ -54,8 +63,23 @@ class Module extends Delegate {
 
         Object.assign(this, this.definition.requiredAuthMethods);
 
+        // A pre-resolved env (Module.create()) supports definition.env as an
+        // async function, e.g. OAuth app credentials loaded from the database
+        // by the db-credentials extension; otherwise the static object.
+        // "Resolved" is an explicit flag, not a non-null value: a function env
+        // may legitimately resolve to undefined (no static env, no DB row),
+        // and falling back to definition.env would then read the function.
+        const envValues = envResolved ? resolvedEnv : this.definition.env;
+        if (typeof envValues === 'function') {
+            // Spreading a function yields no keys, so the API client would
+            // silently get no client_id / client_secret.
+            throw new TypeError(
+                `Module ${this.name}: definition.env is a function; build the module with await Module.create(...)`
+            );
+        }
+
         const apiParams = {
-            ...this.definition.env,
+            ...envValues,
             delegate: this,
             logger: this.logger,
             ...(state ? { state } : {}),
@@ -67,6 +91,33 @@ class Module extends Delegate {
         this.api = new this.apiClass(apiParams);
     }
 
+    /**
+     * Resolves definition.env, supporting both a static object and a
+     * (possibly async) function.
+     *
+     * @param {Object} definition - Module definition
+     * @returns {Promise<Object|undefined>} Resolved env values
+     */
+    static async resolveEnv(definition) {
+        if (typeof definition.env === 'function') {
+            return await definition.env();
+        }
+        return definition.env;
+    }
+
+    /**
+     * Async factory that resolves definition.env first, so a module whose
+     * env is a function gets its values. Prefer it over `new Module(...)`
+     * wherever the call site can await.
+     *
+     * @param {Object} params - same as the constructor, minus resolvedEnv
+     * @returns {Promise<Module>}
+     */
+    static async create({ definition, userId = null, entity = null, state = null }) {
+        const resolvedEnv = await Module.resolveEnv(definition);
+        return new Module({ definition, userId, entity, state, resolvedEnv, envResolved: true });
+    }
+
     getName() {
         return this.name;
     }

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

@@ -0,0 +1,31 @@
+/**
+ * A proxied call was refused or failed in a way the Management API maps to a
+ * documented status (ADR-052 §10). `code` is the public error code; nothing
+ * here carries the upstream URL, headers or credential material.
+ */
+class ProxyRequestError extends Error {
+    /**
+     * @param {string} code - e.g. INVALID_PROXY_REQUEST, PROXY_NOT_ALLOWED, TIMEOUT
+     * @param {string} message - safe to show the caller
+     * @param {Object} [details] - safe structured details
+     */
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'ProxyRequestError';
+        this.code = code;
+        this.details = details;
+    }
+}
+
+/**
+ * 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

@@ -0,0 +1,183 @@
+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
+ * relative to the module's base URL and nothing else: the host, scheme and
+ * port always come from the module.
+ */
+
+const invalid = (reason) =>
+    new ProxyRequestError('INVALID_PROXY_REQUEST', `Invalid proxy path: ${reason}`, {
+        field: 'path',
+    });
+
+// Control characters (C0, DEL, C1), any whitespace, and invisible format
+// characters such as zero-width spaces and byte-order marks.
+const FORBIDDEN_CHARS = /[\x00-\x20\x7f-\x9f]|\s|\p{Cf}/u;
+
+/**
+ * Validates and normalises a caller-supplied path.
+ *
+ * - must start with a single `/`; `//` (anywhere), `\`, `?`, `#`, control
+ *   and whitespace characters are rejected;
+ * - encoded separators (`%2f`, `%5c`) are rejected, then the path is
+ *   percent-decoded exactly once; a `%` left after decoding (double
+ *   encoding) is rejected, as is any decoded control or whitespace
+ *   character other than a space (`%20`);
+ * - `.` and `..` segments are rejected rather than resolved.
+ *
+ * @param {unknown} path
+ * @returns {string} the decoded path, e.g. `/crm/v3/objects/contacts`
+ * @throws {ProxyRequestError} INVALID_PROXY_REQUEST
+ */
+function normalizeProxyPath(path) {
+    if (typeof path !== 'string' || path.length === 0) {
+        throw invalid('path must be a non-empty string');
+    }
+    if (path.length > 2048) throw invalid('path is too long');
+    if (!path.startsWith('/')) throw invalid('path must start with /');
+    if (path.startsWith('//') || path.includes('//')) {
+        throw invalid('empty path segments (//) are not allowed');
+    }
+    if (path.includes('\\')) throw invalid('backslashes are not allowed');
+    if (path.includes('?') || path.includes('#')) {
+        throw invalid('send the query string in `query`, not in the path');
+    }
+    if (FORBIDDEN_CHARS.test(path)) {
+        throw invalid('control and whitespace characters are not allowed');
+    }
+    if (/%(2f|5c)/i.test(path)) {
+        throw invalid('encoded path separators are not allowed');
+    }
+
+    let decoded;
+    try {
+        decoded = decodeURIComponent(path);
+    } catch {
+        throw invalid('malformed percent-encoding');
+    }
+    if (
+        decoded.includes('%') ||
+        decoded.includes('\\') ||
+        decoded.includes('?') ||
+        decoded.includes('#') ||
+        decoded.includes('//') ||
+        // An encoded space (%20) is a legitimate path character; every other
+        // control or whitespace character stays forbidden.
+        FORBIDDEN_CHARS.test(decoded.replaceAll(' ', ''))
+    ) {
+        throw invalid('encoded characters decode to something not allowed');
+    }
+
+    const segments = decoded.split('/').slice(1);
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        throw invalid('dot segments (. and ..) are not allowed');
+    }
+    return decoded;
+}
+
+/**
+ * Joins a module base URL and a normalised path, then proves the result
+ * cannot leave the module's API: https only, same origin as the base URL,
+ * and under the base URL's path.
+ *
+ * @param {string} baseUrl - from the module, never from the request
+ * @param {string} normalizedPath - from normalizeProxyPath()
+ * @returns {{ url: string, basePath: string, origin: string }} `url` is not
+ *   percent-encoded; the Requester encodes it once.
+ * @throws {ProxyRequestError} PROXY_NOT_CONFIGURED or INVALID_PROXY_REQUEST
+ */
+function joinProxyUrl(baseUrl, normalizedPath) {
+    let base;
+    try {
+        base = new URL(baseUrl);
+    } catch {
+        throw new ProxyRequestError(
+            'PROXY_NOT_CONFIGURED',
+            'The module has no valid base URL to proxy to'
+        );
+    }
+    if (base.protocol !== 'https:') {
+        throw new ProxyRequestError(
+            'PROXY_NOT_CONFIGURED',
+            'The module base URL must use https to be proxied'
+        );
+    }
+    if (base.username || base.password || base.search || base.hash) {
+        throw new ProxyRequestError(
+            'PROXY_NOT_CONFIGURED',
+            'The module base URL must not carry credentials, a query or a fragment'
+        );
+    }
+
+    const basePath = base.pathname.replace(/\/+$/, '');
+    const url = `${base.origin}${basePath}${normalizedPath}`;
+
+    let joined;
+    try {
+        joined = new URL(url);
+    } catch {
+        throw invalid('the joined URL is not valid');
+    }
+    const joinedPath = decodeURIComponent(joined.pathname);
+    if (
+        joined.protocol !== 'https:' ||
+        joined.origin !== base.origin ||
+        joined.username ||
+        joined.password ||
+        !(joinedPath === basePath || joinedPath.startsWith(`${basePath}/`))
+    ) {
+        throw invalid('the path leaves the module API');
+    }
+    return { url, basePath, origin: base.origin };
+}
+
+/**
+ * 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.
+ *
+ * @param {Array<{method: string, path: string}>} rules
+ * @param {string} method - upper case
+ * @param {string} path - normalised path
+ * @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, 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;
+    }
+    return null;
+}
+
+function patternMatches(pattern, requestSegments) {
+    if (!pattern.startsWith('/')) return false;
+    let patternSegments = pattern.split('/').slice(1);
+    let subtree = false;
+    if (patternSegments[patternSegments.length - 1] === '**') {
+        subtree = true;
+        patternSegments = patternSegments.slice(0, -1);
+    }
+    if (subtree) {
+        if (requestSegments.length < patternSegments.length) return false;
+    } else if (requestSegments.length !== patternSegments.length) {
+        return false;
+    }
+    return patternSegments.every((segment, index) => {
+        const actual = requestSegments[index];
+        if (segment.startsWith(':')) return actual !== undefined && actual !== '';
+        return segment === actual;
+    });
+}
+
+module.exports = { normalizeProxyPath, joinProxyUrl, matchAllowRule };