@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.686.821f8a3.0

package/modules/repositories/module-repository-postgres.js

@@ -1,5 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * PostgreSQL Module Repository Adapter
@@ -108,6 +109,26 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         return credentialMap;
     }
 
+    /**
+     * The one place a stored entity row becomes the entity the application sees.
+     * The provider's `data` is spread FIRST and every column is pinned after it:
+     * a stored `id`, `userId` or `organizationId` in `data` must not decide who
+     * owns the entity or who sees it.
+     * @private
+     */
+    _mapEntity(row, credential) {
+        return {
+            ...(row.data || {}),
+            id: row.id.toString(),
+            credential,
+            userId: row.userId?.toString(),
+            name: row.name,
+            externalId: row.externalId,
+            moduleName: row.moduleName,
+            organizationId: row.organizationId?.toString() ?? null,
+        };
+    }
+
     /**
      * Find entity by ID with credential
      * Replaces: Entity.findById(entityId).populate('credential')
@@ -124,20 +145,12 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -157,15 +170,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -185,15 +190,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -217,15 +214,32 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
+    }
+
+    /**
+     * Find entities matching any of the owner/organization pairs, in one query.
+     * `organizationId: null` matches rows with no organization. The caller
+     * (a use case) decides which pairs; this only runs them.
+     *
+     * @param {Array<{userId: string, organizationId: (string|null)}>} clauses
+     * @returns {Promise<Array>} Array of entity objects with string IDs
+     */
+    async findEntitiesByOwnership(clauses) {
+        if (!Array.isArray(clauses) || clauses.length === 0) return [];
+        const entities = await this.prisma.entity.findMany({
+            where: {
+                OR: clauses.map(({ userId, organizationId }) => ({
+                    userId: this._convertId(userId),
+                    organizationId: this._convertId(organizationId),
+                })),
+            },
+        });
+
+        const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
+        const credentialMap = await this._fetchCredentialsBulk(credentialIds);
+
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -264,15 +278,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -292,15 +298,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
             .filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id.toString(),
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId?.toString(),
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -308,9 +306,13 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
      * Replaces: Entity.create(entityData)
      *
      * @param {Object} entityData - Entity data (with string IDs from application layer)
+     * @param {{organizationId?: (string|null)}} [tenancy] - the organization the entity
+     *   belongs to (ADR-056 §3.6). A separate argument, not a field of `entityData`,
+     *   because `entityData` carries provider fields and one named `organizationId`
+     *   must not be taken for ours.
      * @returns {Promise<Object>} Created entity object with string IDs
      */
-    async createEntity(entityData) {
+    async createEntity(entityData, tenancy = {}) {
         const {
             user,
             userId,
@@ -328,6 +330,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
             name,
             moduleName,
             externalId,
+            organizationId: this._convertId(tenancy.organizationId ?? null),
             data: dynamicData,
         };
 
@@ -337,15 +340,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
         const credentialObj = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id.toString(),
-            credential: credentialObj,
-            userId: entity.userId?.toString(),
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credentialObj);
     }
 
     /**
@@ -401,15 +396,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
 
             const credentialObj = await this._fetchCredential(entity.credentialId);
 
-            return {
-                id: entity.id.toString(),
-                credential: credentialObj,
-                userId: entity.userId?.toString(),
-                name: entity.name,
-                externalId: entity.externalId,
-                moduleName: entity.moduleName,
-                ...(entity.data || {}),
-            };
+            return this._mapEntity(entity, credentialObj);
         } catch (error) {
             if (error.code === 'P2025') {
                 return null;
@@ -474,6 +461,11 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         if (filter.moduleName) where.moduleName = filter.moduleName;
         if (filter.externalId) where.externalId = this._toString(filter.externalId);
 
+        // `null` means "no organization"; absent means "any".
+        if (filter.organizationId !== undefined) {
+            where.organizationId = this._convertId(filter.organizationId);
+        }
+
         return where;
     }
 }

package/modules/repositories/module-repository.js

@@ -1,5 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * Prisma-based Module Repository
@@ -37,7 +38,7 @@ class ModuleRepository extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         return {

package/modules/requester/proxy-request.js

@@ -0,0 +1,244 @@
+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] - module-declared proxy base URL; 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;
 
@@ -237,7 +238,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 +278,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 +308,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 +394,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 +542,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',