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

package/modules/requester/proxy-request.js

@@ -0,0 +1,245 @@
+const { FetchError } = require('../../errors/fetch-error');
+const { ProxyRequestError } = require('../proxy/proxy-errors');
+const {
+    normalizeProxyPath,
+    joinProxyUrl,
+} = require('../proxy/proxy-path');
+
+const MAX_REDIRECTS = 3;
+
+/**
+ * The generic, path-checked request behind the Management API entity proxy
+ * (ADR-052 §8). It runs through the requester's own `_request`, so auth
+ * headers, token refresh (single-flight), the per-attempt timeout, telemetry
+ * and log redaction all apply. What it adds:
+ *
+ * - the URL is always `module base URL + normalised path`; the caller cannot
+ *   name a host, scheme or port;
+ * - no backoff retries (the caller decides; a 429 comes back with its
+ *   Retry-After), and upstream errors are returned, not thrown;
+ * - redirects are handled manually: same origin and under the base path only,
+ *   at most three hops, each re-checked with `isAllowedRedirect`;
+ * - one deadline for the whole call and a cap on the response body.
+ *
+ * @param {import('./requester').Requester} requester
+ * @param {Object} params
+ * @param {string} params.method - upper case
+ * @param {string} params.path - caller path, validated here
+ * @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] - 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
+ * @param {(path: string, method: string) => boolean} [params.isAllowedRedirect]
+ * @returns {Promise<{ status: number, headers: Object, body: Buffer, contentType: string, redirectBlocked: boolean }>}
+ * @throws {ProxyRequestError} INVALID_PROXY_REQUEST, PROXY_NOT_CONFIGURED,
+ *   INVALID_CREDENTIALS, TIMEOUT, NETWORK_ERROR, RESPONSE_TOO_LARGE
+ */
+async function proxyRequest(requester, params) {
+    const {
+        method,
+        path,
+        query,
+        headers = {},
+        body,
+        baseUrl,
+        timeoutMs,
+        maxResponseBytes,
+        isAllowedRedirect,
+    } = params;
+
+    const normalizedPath = normalizeProxyPath(path);
+    const base =
+        baseUrl ??
+        requester.proxyBaseUrl ??
+        requester.baseUrl ??
+        requester.baseURL;
+    if (!base) {
+        throw new ProxyRequestError(
+            'PROXY_NOT_CONFIGURED',
+            'The module declares no base URL to proxy to'
+        );
+    }
+    const target = joinProxyUrl(base, normalizedPath);
+    const deadline = Date.now() + timeoutMs;
+
+    const run = async () => {
+        let url = target.url;
+        let currentMethod = method;
+        let currentBody = body;
+        let currentQuery = query;
+        for (let hop = 0; ; hop++) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) throw timeoutError();
+
+            const response = await requester._request(url, {
+                method: currentMethod,
+                headers: { ...headers },
+                query: currentQuery,
+                body: currentBody,
+                returnFullRes: true,
+                returnErrorResponses: true,
+                noRetry: true,
+                redirect: 'manual',
+                size: maxResponseBytes,
+                timeoutMs: remaining,
+            });
+
+            const location = response.headers.get('location');
+            if (response.status >= 300 && response.status < 400 && location) {
+                const next = sameApiRedirect(location, url, target);
+                const nextMethod = redirectMethod(response.status, currentMethod);
+                if (
+                    next &&
+                    hop < MAX_REDIRECTS &&
+                    (!isAllowedRedirect || isAllowedRedirect(next.path, nextMethod))
+                ) {
+                    if (nextMethod !== currentMethod) currentBody = undefined;
+                    currentMethod = nextMethod;
+                    url = next.url;
+                    currentQuery = undefined;
+                    continue;
+                }
+                return readResponse(response, maxResponseBytes, {
+                    redirectBlocked: !next,
+                });
+            }
+            return readResponse(response, maxResponseBytes, {
+                redirectBlocked: false,
+            });
+        }
+    };
+
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+    });
+    const work = run();
+    // If the deadline wins, the request still settles later; nothing awaits it.
+    work.catch(() => {});
+    try {
+        return await Promise.race([work, timeout]);
+    } catch (error) {
+        throw toProxyError(error);
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+function timeoutError() {
+    return new ProxyRequestError('TIMEOUT', 'The upstream API did not answer in time');
+}
+
+/**
+ * A redirect target the proxy may follow: same origin as the module base URL
+ * and under its base path. Returns null for anything else.
+ */
+function sameApiRedirect(location, currentUrl, target) {
+    let next;
+    try {
+        next = new URL(location, currentUrl);
+    } catch {
+        return null;
+    }
+    if (next.origin !== target.origin || next.protocol !== 'https:') return null;
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(next.pathname);
+    } catch {
+        return null;
+    }
+    if (
+        !(decodedPath === target.basePath || decodedPath.startsWith(`${target.basePath}/`))
+    ) {
+        return null;
+    }
+    const relativePath = decodedPath.slice(target.basePath.length) || '/';
+    let checkedPath;
+    try {
+        checkedPath = normalizeProxyPath(relativePath);
+    } catch {
+        return null;
+    }
+    // _rawRequest percent-encodes the URL once, so hand it the decoded form.
+    return {
+        url: `${target.origin}${target.basePath}${checkedPath}${next.search ? decodeURI(next.search) : ''}`,
+        path: checkedPath,
+    };
+}
+
+/** Method for the next hop, as fetch does it. */
+function redirectMethod(status, method) {
+    if (status === 303 && method !== 'HEAD') return 'GET';
+    if ((status === 301 || status === 302) && method === 'POST') return 'GET';
+    return method;
+}
+
+async function readResponse(response, maxResponseBytes, { redirectBlocked }) {
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > maxResponseBytes) {
+        destroyBody(response);
+        throw tooLarge();
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > maxResponseBytes) throw tooLarge();
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        headers[name.toLowerCase()] = value;
+    });
+    return {
+        status: response.status,
+        headers,
+        body: buffer,
+        contentType: headers['content-type'] || '',
+        redirectBlocked,
+    };
+}
+
+function destroyBody(response) {
+    try {
+        response.body?.destroy?.();
+    } catch {
+        // nothing to clean up
+    }
+}
+
+function tooLarge() {
+    return new ProxyRequestError(
+        'RESPONSE_TOO_LARGE',
+        'The upstream response is larger than the proxy allows'
+    );
+}
+
+/** Maps requester and fetch failures to the proxy's error codes. */
+function toProxyError(error) {
+    if (error instanceof ProxyRequestError) return error;
+    const causeType = error?.cause?.type ?? error?.type;
+    if (causeType === 'max-size') return tooLarge();
+    if (error?.isTimeout) return timeoutError();
+    if (error instanceof FetchError || error?.name === 'FetchError') {
+        if (error.statusCode === 401) {
+            return new ProxyRequestError(
+                'INVALID_CREDENTIALS',
+                'The upstream API rejected the stored credentials; re-authorize the entity',
+                { upstreamStatus: 401 }
+            );
+        }
+        if (!error.statusCode) {
+            return new ProxyRequestError(
+                'NETWORK_ERROR',
+                'Could not reach the upstream API'
+            );
+        }
+        return new ProxyRequestError(
+            'UPSTREAM_ERROR',
+            'The upstream API returned an error',
+            { upstreamStatus: error.statusCode }
+        );
+    }
+    return error;
+}
+
+module.exports = { proxyRequest, MAX_REDIRECTS };

package/modules/requester/requester.js

@@ -8,6 +8,7 @@ const { getLogger } = require('../../logs');
 const { redactUrl } = require('../../logs/redact');
 const { toSanitizedSurrogate } = require('../../logs/serialize');
 const { getLoggerScope } = require('../../logs/context');
+const { proxyRequest } = require('./proxy-request');
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 
@@ -218,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);
         }
@@ -237,7 +243,9 @@ class Requester extends Delegate {
         // recursion (with its own backoff sleeps) always gets a clean
         // signal. Timer is cleared in the finally block regardless of
         // outcome.
-        const timeoutMs = this.requestTimeoutMs;
+        // options.timeoutMs lets one call use a tighter budget (the
+        // Management API proxy passes what is left of its deadline).
+        const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
         const controller = timeoutMs > 0 ? new AbortController() : null;
         const timeoutHandle = controller
             ? setTimeout(() => controller.abort(), timeoutMs)
@@ -275,7 +283,11 @@ class Requester extends Delegate {
                 // stall at batch scale.
                 const isTimeout =
                     e?.name === 'AbortError' || e?.type === 'aborted';
-                if (e?.code === 'ECONNRESET' && attempt < this.backOff.length) {
+                if (
+                    e?.code === 'ECONNRESET' &&
+                    !options.noRetry &&
+                    attempt < this.backOff.length
+                ) {
                     clearRequestTimer();
                     const delay = this.backOff[attempt] * 1000;
                     await new Promise((resolve) => setTimeout(resolve, delay));
@@ -301,6 +313,7 @@ class Requester extends Delegate {
             // If the status is retriable and there are back off requests left, retry the request
             if (
                 (status === 429 || status >= 500) &&
+                !options.noRetry &&
                 attempt < this.backOff.length
             ) {
                 clearRequestTimer();
@@ -386,6 +399,12 @@ class Requester extends Delegate {
             // If the error wasn't retried, throw. FetchError.create reads
             // the response body (response.text()) — timer must still be
             // alive to catch a stalled body stream.
+            // The proxy relays upstream errors to its caller instead of
+            // throwing; 401 keeps the refresh / invalidate handling above.
+            if (status >= 400 && options.returnErrorResponses) {
+                return response;
+            }
+
             if (status >= 400) {
                 this._logRequestFailed(encodedUrl, options, status);
                 const fetchError = await FetchError.create({
@@ -528,6 +547,17 @@ class Requester extends Delegate {
         return res;
     }
 
+    /**
+     * Generic, path-checked request for the Management API entity proxy
+     * (ADR-052 §8). The URL is always the module base URL plus a validated
+     * path; see ./proxy-request.js. Module methods are not involved.
+     *
+     * @param {Object} params - see proxyRequest()
+     */
+    async _proxyRequest(params) {
+        return proxyRequest(this, params);
+    }
+
     async _delete(options) {
         const fetchOptions = {
             method: 'DELETE',

package/modules/scope-config.js

@@ -0,0 +1,192 @@
+/**
+ * Reading and validating ownership settings in an app definition (ADR-056
+ * §3.1, §3.3). Called once by loadAppDefinition, so a bad setting stops the app
+ * at load, not on the first request. No I/O.
+ */
+
+const {
+    SCOPES,
+    INDIVIDUAL_ACROSS_VALUES,
+    OWNER_RULES,
+    DEFAULT_ORG_ADMIN_ROLES,
+    configError,
+    isPlainObject,
+    parseScopeSetting,
+    resolveScope,
+} = require('./scope-resolution');
+const { entityTypeNameOf } = require('./entity-type-registry');
+
+/** The binding scope an integration declares for `modules[key]`, if any. */
+function bindingScopeSetting(Definition, key) {
+    const binding = Definition?.modules?.[key];
+    if (binding?.scope !== undefined) return binding.scope;
+    const entityEntry = Definition?.entities?.[key];
+    if (entityEntry?.scope !== undefined) return entityEntry.scope;
+    // Deprecated alias from the global-entities branch: `global: true`.
+    if (entityEntry?.global === true) return SCOPES.GLOBAL;
+    return undefined;
+}
+
+function readAppOwnership(appDefinition) {
+    const raw = appDefinition?.ownership;
+    if (raw === undefined || raw === null) {
+        return { scope: null, individualAcross: 'organization' };
+    }
+    if (!isPlainObject(raw)) {
+        throw configError('appDefinition.ownership', 'must be an object');
+    }
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'individualAcross'
+    );
+    if (unknown.length) {
+        throw configError(
+            'appDefinition.ownership',
+            `unknown setting(s): ${unknown.join(', ')}`
+        );
+    }
+    const individualAcross = raw.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+    return {
+        scope: parseScopeSetting(raw.scope, 'appDefinition.ownership.scope'),
+        individualAcross,
+    };
+}
+
+function readIntegrationOwnership(integrationClass) {
+    const name = integrationClass?.Definition?.name || 'unnamed';
+    const raw = integrationClass?.Definition?.ownership;
+    if (raw === undefined || raw === null) return { scope: null, owner: 'derive' };
+    const where = `integration '${name}' ownership`;
+    if (!isPlainObject(raw)) throw configError(where, 'must be an object');
+    const unknown = Object.keys(raw).filter(
+        (key) => key !== 'scope' && key !== 'owner'
+    );
+    if (unknown.length) {
+        throw configError(where, `unknown setting(s): ${unknown.join(', ')}`);
+    }
+    const owner = raw.owner ?? 'derive';
+    if (!OWNER_RULES.includes(owner)) {
+        throw configError(where, `owner must be one of ${OWNER_RULES.join(', ')}`);
+    }
+    return { scope: parseScopeSetting(raw.scope, `${where}.scope`), owner };
+}
+
+/**
+ * `user.orgAdminRoles`: the token roles that may manage organization-level
+ * things. Default `['ADMIN']`. A shared-secret caller needs no role.
+ */
+function readOrgAdminRoles(appDefinition) {
+    const raw = appDefinition?.user?.orgAdminRoles;
+    if (raw === undefined || raw === null) return [...DEFAULT_ORG_ADMIN_ROLES];
+    if (
+        !Array.isArray(raw) ||
+        raw.length === 0 ||
+        raw.some((role) => typeof role !== 'string' || role.trim() === '')
+    ) {
+        throw configError(
+            'appDefinition.user.orgAdminRoles',
+            'must be a non-empty array of role names'
+        );
+    }
+    return [...raw];
+}
+
+/**
+ * `user.orgAdminGateBearerTokens`: judge Frigg bearer-token callers by role
+ * like adopter-token callers. Default false: they keep their pre-roles
+ * behaviour and may manage the organization they act in.
+ */
+function readGateBearerTokens(appDefinition) {
+    const raw = appDefinition?.user?.orgAdminGateBearerTokens;
+    if (raw === undefined || raw === null) return false;
+    if (typeof raw !== 'boolean') {
+        throw configError('appDefinition.user.orgAdminGateBearerTokens', 'must be a boolean');
+    }
+    return raw;
+}
+
+/**
+ * Every binding of every integration with its resolved scope and where it came
+ * from, parsing each integration's settings once. Throws OwnershipConfigError
+ * for any invalid one. Exported for tooling that wants to show the chain.
+ */
+function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
+    const app = readAppOwnership(appDefinition);
+    const rows = [];
+    for (const integrationClass of appDefinition?.integrations || []) {
+        const Definition = integrationClass?.Definition;
+        const name = Definition?.name || 'unnamed';
+        const ownership = readIntegrationOwnership(integrationClass);
+        for (const [key, binding] of Object.entries(Definition?.modules || {})) {
+            const moduleName = entityTypeNameOf(binding?.definition);
+            const resolved = resolveScope({
+                binding: parseScopeSetting(
+                    bindingScopeSetting(Definition, key),
+                    `integration '${name}' binding '${key}' scope`
+                ),
+                integration: ownership.scope,
+                entityType: moduleName
+                    ? entityTypeRegistry?.get(moduleName)?.settings?.scope
+                    : undefined,
+                app: app.scope,
+                primary,
+            });
+            rows.push({
+                integration: name,
+                binding: key,
+                moduleName: moduleName ?? null,
+                scope: resolved.scope,
+                source: resolved.source,
+                owner: ownership.owner,
+            });
+        }
+    }
+    return rows;
+}
+
+/**
+ * Validates every ownership setting in one pass and returns the app-level
+ * config the runtime needs.
+ *
+ * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[], gateBearerTokens: boolean}}
+ * @throws {OwnershipConfigError}
+ */
+function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
+    const app = readAppOwnership(appDefinition);
+    for (const [name, entry] of entityTypeRegistry || []) {
+        parseScopeSetting(entry?.settings?.scope, `entity type '${name}' scope`);
+    }
+    const rows = listBindingScopes(
+        appDefinition,
+        entityTypeRegistry,
+        appDefinition?.user?.primary
+    );
+    // §3.3: a shared integration must not run on one person's credential.
+    for (const row of rows) {
+        if (row.owner === 'organization' && row.scope === SCOPES.INDIVIDUAL) {
+            throw configError(
+                `integration '${row.integration}' binding '${row.binding}'`,
+                "an organization-owned integration cannot bind an 'individual' entity"
+            );
+        }
+    }
+    return Object.freeze({
+        scope: app.scope,
+        individualAcross: app.individualAcross,
+        orgAdminRoles: Object.freeze(readOrgAdminRoles(appDefinition)),
+        gateBearerTokens: readGateBearerTokens(appDefinition),
+    });
+}
+
+module.exports = {
+    bindingScopeSetting,
+    readAppOwnership,
+    readIntegrationOwnership,
+    listBindingScopes,
+    resolveOwnershipConfig,
+};

package/modules/scope-policy.js

@@ -0,0 +1,112 @@
+/**
+ * The object a use case asks about scopes (ADR-056 §3): the app's ownership
+ * config and entity type registry bound once, as closures. With no arguments it
+ * is the behaviour of an app that configures nothing.
+ */
+
+const {
+    INDIVIDUAL_ACROSS_VALUES,
+    DEFAULT_ORG_ADMIN_ROLES,
+    configError,
+    parseScopeSetting,
+    resolveScope,
+    resolveOwnerForScope,
+} = require('./scope-resolution');
+const {
+    accessContext,
+    accessToOwner,
+    describeRecord,
+} = require('./scope-visibility');
+
+/**
+ * @param {Object} [params]
+ * @param {{scope: *, individualAcross: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [params.ownership] - the raw
+ *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
+ *   `{ default, allow }` parses to itself)
+ * @param {Map} [params.entityTypeRegistry]
+ */
+function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
+    const appScope = parseScopeSetting(
+        ownership?.scope,
+        'appDefinition.ownership.scope'
+    );
+    const individualAcross = ownership?.individualAcross ?? 'organization';
+    if (!INDIVIDUAL_ACROSS_VALUES.includes(individualAcross)) {
+        throw configError(
+            'appDefinition.ownership.individualAcross',
+            `must be one of ${INDIVIDUAL_ACROSS_VALUES.join(', ')}`
+        );
+    }
+
+    const orgAdminRoles = ownership?.orgAdminRoles ?? DEFAULT_ORG_ADMIN_ROLES;
+    const gateBearerTokens = ownership?.gateBearerTokens === true;
+
+    const contextFor = (user) =>
+        accessContext(user, { individualAcross, orgAdminRoles, gateBearerTokens });
+
+    /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
+    const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
+        resolveScope({
+            request: requestScope,
+            binding,
+            integration,
+            entityType: entityTypeRegistry?.get?.(entityType)?.settings?.scope,
+            app: appScope,
+            primary: user?.config?.primary,
+        });
+
+    /**
+     * Scope, then owner and organization, for a new entity. `legacyOrgId` (the
+     * person's legacy organization pointer) rides along so a later lookup can
+     * reuse an entity written before scoping.
+     */
+    const resolveOwnership = ({ entityType, requestScope, user }) => {
+        const ctx = contextFor(user);
+        const resolved = resolveEntityScope({ entityType, requestScope, user });
+        return {
+            ...resolveOwnerForScope(resolved.scope, ctx),
+            legacyOrgId: ctx.legacyOrgId,
+            source: resolved.source,
+        };
+    };
+
+    /**
+     * The owner and organization for a scope that is already decided: a
+     * re-authorization keeps the scope its connection has, whatever the config
+     * says now. The admin gate applies as it does on create.
+     */
+    const ownershipForScope = ({ scope, user }) => {
+        const ctx = contextFor(user);
+        return {
+            ...resolveOwnerForScope(scope, ctx),
+            legacyOrgId: ctx.legacyOrgId,
+            source: 'fixed',
+        };
+    };
+
+    /** Whether `user` may load this stored entity for use (same clauses as the list). */
+    const canUseEntity = (user, entity) =>
+        describeRecord(entity, contextFor(user), 'entity') !== null;
+
+    /**
+     * What `user` may do with a record owned by `ownerId` that has no
+     * organization of its own (a credential): manage, or null when not theirs.
+     */
+    const accessToOwnedBy = (user, ownerId) => accessToOwner(ownerId, contextFor(user));
+
+    return Object.freeze({
+        individualAcross,
+        orgAdminRoles,
+        accessToOwnedBy,
+        accessContext: contextFor,
+        resolveScope: resolveEntityScope,
+        resolveOwnership,
+        ownershipForScope,
+        canUseEntity,
+    });
+}
+
+/** The policy of an app that configures nothing; what a use case gets by default. */
+const DEFAULT_SCOPE_POLICY = createScopePolicy();
+
+module.exports = { createScopePolicy, DEFAULT_SCOPE_POLICY };