@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/handlers/app-definition-loader.js

@@ -2,21 +2,27 @@ const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
+const { assertAdopterJwtConfig } = require('../user/adopter-jwt-config');
 const { registerDeniedKeys } = require('../logs/denied-keys');
 const {
     extractCredentialFieldsFromModules,
 } = require('../database/encryption/encryption-schema-registry');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    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');
+const { resolveScheduleConfig } = require('../integrations/schedule-config');
 
 // Handlers without a database never load the encryption registry, so the
 // credential leaf keys are registered for redaction here too.
-function registerCredentialLogKeys(appDefinition, integrations) {
+function registerCredentialLogKeys(appDefinition, moduleDefinitions) {
     try {
-        extractCredentialFieldsFromModules(
-            getModulesDefinitionFromIntegrationClasses(integrations)
-        );
+        extractCredentialFieldsFromModules(moduleDefinitions);
     } catch {
         // An odd integration shape must not stop the app from loading.
     }
@@ -29,18 +35,53 @@ function registerCredentialLogKeys(appDefinition, integrations) {
 }
 
 /**
- * Loads the App definition from the nearest backend package
- * @function loadAppDefinition
- * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
- * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null}} An object containing the application definition.
- * @throws {Error} Throws error if backend package.json cannot be found.
- * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
- * @example
- * const { integrations, userConfig, telemetry } = loadAppDefinition();
- * console.log(`Found ${integrations.length} integrations`);
+ * The definition handed to setAppDefinition(), or null when the backend is
+ * discovered from process.cwd().
  */
-function loadAppDefinition() {
+let presetDefinition = null;
+
+/**
+ * Pre-set the app definition so loadAppDefinition() does not discover the
+ * backend through process.cwd().
+ *
+ * Platforms such as Netlify need this: the function bundler (nft/esbuild)
+ * only traces static require() calls, and at runtime process.cwd() is the
+ * function root, not the backend. A generated function entry point therefore
+ * requires the backend's index.js statically and passes its Definition here.
+ *
+ * The preset definition is validated and derived exactly like a discovered
+ * one: adopter-JWT config, the entity registry, ownership and the Management
+ * API config all apply, so a Netlify function and an AWS Lambda load the
+ * same app the same way. Pass null to clear it.
+ *
+ * @param {Object|null} definition - the backend's `Definition` export
+ */
+function setAppDefinition(definition) {
+    if (
+        definition !== null &&
+        (typeof definition !== 'object' || Array.isArray(definition))
+    ) {
+        throw new TypeError(
+            'setAppDefinition expects the app Definition object (or null)'
+        );
+    }
+    presetDefinition = definition;
+}
+
+/**
+ * The definition preset with setAppDefinition(), unvalidated, or null.
+ *
+ * For low-level readers that only need one raw field before the app is
+ * fully loaded (the database type, the custom encryption schema) and keep
+ * their own process.cwd() discovery as the fallback.
+ *
+ * @returns {Object|null}
+ */
+function getPresetAppDefinition() {
+    return presetDefinition;
+}
+
+function discoverAppDefinition() {
     const backendPath = findNearestBackendPackageJson();
     if (!backendPath) {
         throw new Error('Could not find backend package.json');
@@ -53,18 +94,78 @@ function loadAppDefinition() {
     }
 
     const backendJsFile = require(backendFilePath);
-    const appDefinition = backendJsFile.Definition;
+    return backendJsFile.Definition;
+}
 
+/**
+ * Loads the App definition: the one preset with setAppDefinition(), or the
+ * nearest backend package's index.js.
+ * @function loadAppDefinition
+ * @description Uses the definition preset by setAppDefinition() when there is one; otherwise searches for the nearest backend package.json, loads the corresponding index.js file,
+ * and extracts the application definition containing integrations and user configuration.
+ * @returns {{appDefinition: object, integrations: Array<object>, entities: object | null, entityTypeRegistry: Map<string, object>, moduleDefinitions: Array<object>, ownership: {scope: ({default: string, allow: string[]}|null), individualAcross: string}, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null, managementApi: object}} An object containing the application definition. `appDefinition` is the raw Definition object.
+ * @throws {Error} Throws error if backend package.json cannot be found.
+ * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
+ * @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();
+ * console.log(`Found ${integrations.length} integrations`);
+ */
+function loadAppDefinition() {
+    const appDefinition = presetDefinition || discoverAppDefinition();
+    return resolveAppDefinition(appDefinition);
+}
+
+function resolveAppDefinition(appDefinition) {
     const {
         integrations = [],
+        entities = null,
         user: userConfig = null,
         adminScripts = [],
         reports = [],
         admin = {},
         logging = null,
+        managementApi = {},
     } = appDefinition;
 
-    registerCredentialLogKeys(appDefinition, integrations);
+    // Fail at load, not on the first request: an adopter-token mode with no
+    // key source would otherwise start cleanly and answer every login with 500.
+    assertAdopterJwtConfig(userConfig);
+
+    // Fail fast: a bad `entities` registry (key/name mismatch, conflicting
+    // definitions, `$infer: false` with an unregistered module) must stop the
+    // app at load, not on the first request that needs a module.
+    const entityTypeRegistry = getEntityTypeRegistry(appDefinition);
+    const moduleDefinitions = getEntityTypeDefinitions(entityTypeRegistry);
+
+    // Same reason for entity scopes (ADR-056 §3.1): a mistyped scope, an unknown
+    // `individualAcross`, or an organization-owned integration that binds an
+    // individual entity stops the app at load.
+    const ownership = resolveOwnershipConfig(appDefinition, entityTypeRegistry);
+
+    // 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.
+    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.
+    for (const IntegrationClass of integrations) {
+        if (IntegrationClass?.Definition) {
+            resolveScheduleConfig(IntegrationClass.Definition);
+        }
+    }
+
+    registerCredentialLogKeys(appDefinition, moduleDefinitions);
 
     // Degrade consistently: an invalid telemetry block must never take down a
     // router bundle that loads the app definition at module scope (telemetry is
@@ -88,16 +189,24 @@ function loadAppDefinition() {
     }
 
     return {
+        appDefinition,
         integrations,
+        entities,
+        entityTypeRegistry,
+        moduleDefinitions,
+        ownership,
         userConfig,
         adminScripts,
         reports,
         admin,
         telemetry,
         logging,
+        managementApi,
     };
 }
 
 module.exports = {
     loadAppDefinition,
+    setAppDefinition,
+    getPresetAppDefinition,
 };

package/handlers/app-handler-helpers.js

@@ -6,17 +6,20 @@ const bodyParser = require('body-parser');
 const cors = require('cors');
 const Boom = require('@hapi/boom');
 const serverlessHttp = require('serverless-http');
+const {
+    API_VERSION_HEADER,
+    isVersionedManagementApiPath,
+    toBoom,
+    toV2ErrorBody,
+} = require('../management-api/error-response');
 
 const log = getLogger('frigg.http');
 
 const createApp = (applyMiddleware) => {
     const app = express();
 
-    // Keep the bytes as received: webhook signatures (HubSpot, Slack, Stripe, Linear…) are computed over the exact
-    // raw body, which re-serialising the parsed body does not reproduce. A reference to the buffer, not a copy.
-    const keepRaw = (req, res, buf) => { req.rawBody = buf; };
-    app.use(bodyParser.json({ limit: '10mb', verify: keepRaw }));
-    app.use(bodyParser.urlencoded({ extended: true, verify: keepRaw }));
+    app.use(bodyParser.json({ limit: '10mb' }));
+    app.use(bodyParser.urlencoded({ extended: true }));
     app.use(
         cors({
             origin: '*',
@@ -29,11 +32,15 @@ const createApp = (applyMiddleware) => {
     if (applyMiddleware) applyMiddleware(app);
 
     // The express boundary: send the error response and log it one time.
+    // A Boom error keeps its status; other errors keep theirs only when they
+    // mark a 4xx safe to expose (body-parser's 400/413 via http-errors), so a
+    // malformed body is a 400, not a 500.
     app.use((err, req, res, next) => {
-        const boomError = err.isBoom ? err : Boom.boomify(err);
+        const boomError = toBoom(err);
         const {
             output: { statusCode = 500 },
         } = boomError;
+        const versioned = isVersionedManagementApiPath(req.path);
 
         if (statusCode >= 500) {
             log.error('Request failed', {
@@ -42,7 +49,6 @@ const createApp = (applyMiddleware) => {
                 invocation: summarizeExpressRequest(req),
                 error: boomError,
             });
-            res.status(statusCode).json({ error: 'Internal Server Error' });
         } else {
             // A client error needs no stack; the logger scrubs the reason.
             log.warn('Request rejected', {
@@ -50,8 +56,21 @@ const createApp = (applyMiddleware) => {
                 statusCode,
                 reason: boomError.message,
             });
-            res.status(statusCode).json({ error: err.message });
         }
+
+        if (versioned) {
+            // Management API v2 / meta: { error: { code, message, details? } }.
+            if (req.path.startsWith('/api/v2')) {
+                res.set(API_VERSION_HEADER, '2');
+            }
+            return res.status(statusCode).json(toV2ErrorBody(boomError));
+        }
+
+        // v1 and other routes keep their historical body.
+        if (statusCode >= 500) {
+            return res.status(statusCode).json({ error: 'Internal Server Error' });
+        }
+        return res.status(statusCode).json({ error: err.message });
     });
 
     return app;

package/handlers/backend-utils.js

@@ -18,8 +18,9 @@ const {
     createModuleRepository,
 } = require('../modules/repositories/module-repository-factory');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../modules/entity-type-registry');
 const { processNotFound } = require('../integrations/use-cases/process-errors');
 
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
@@ -61,30 +62,18 @@ const initializeRepositories = () => {
     return { processRepository, integrationRepository, moduleRepository };
 };
 
-const createModuleFactoryWithDefinitions = (
-    moduleRepository,
-    integrationClasses
-) => {
-    const moduleDefinitions =
-        getModulesDefinitionFromIntegrationClasses(integrationClasses);
-
-    return new ModuleFactory({
-        moduleRepository,
-        moduleDefinitions,
-    });
-};
-
 const loadIntegrationForWebhook = async (integrationId) => {
     const { loadAppDefinition } = require('./app-definition-loader');
-    const { integrations: integrationClasses } = loadAppDefinition();
+    const { integrations: integrationClasses, moduleDefinitions } =
+        loadAppDefinition();
 
     const { integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(
+    const moduleFactory = new ModuleFactory({
         moduleRepository,
-        integrationClasses
-    );
+        moduleDefinitions,
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -129,13 +118,23 @@ const integrationExists = async (integrationId) => {
     }
 };
 
-const loadIntegrationForProcess = async (processId, integrationClass) => {
+const loadIntegrationForProcess = async (
+    processId,
+    integrationClass,
+    moduleDefinitions
+) => {
     const { processRepository, integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(moduleRepository, [
-        integrationClass,
-    ]);
+    const moduleFactory = new ModuleFactory({
+        moduleRepository,
+        moduleDefinitions:
+            moduleDefinitions ??
+            // No app definition handed in: this integration's own modules only.
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -161,7 +160,13 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
     return instance;
 };
 
-const createQueueWorker = (integrationClass) => {
+/**
+ * @param {Function} integrationClass
+ * @param {{moduleDefinitions?: Array<object>}} [options] - the app's offered
+ *   module definitions (`loadAppDefinition().moduleDefinitions`). When omitted
+ *   the worker hydrates with this integration's own modules only.
+ */
+const createQueueWorker = (integrationClass, { moduleDefinitions } = {}) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
@@ -183,7 +188,8 @@ const createQueueWorker = (integrationClass) => {
                     console.log(`[QueueWorker] hydrating by processId`, logCtx);
                     integrationInstance = await loadIntegrationForProcess(
                         params.data.processId,
-                        integrationClass
+                        integrationClass,
+                        moduleDefinitions
                     );
                     console.log(`[QueueWorker] hydrated`, {
                         ...logCtx,

package/handlers/integration-event-dispatcher.js

@@ -19,13 +19,9 @@ class IntegrationEventDispatcher {
     }
 
     async dispatchJob({ event, data, context, delivery }) {
-        return this._dispatch(event, (instance, handler) => {
-            const invoke = () => handler.call(instance, { data, context, delivery });
-            // An integration that keeps run history records each queued event as a run (integration runtime).
-            return typeof instance.runEvent === 'function'
-                ? instance.runEvent(event, invoke)
-                : invoke();
-        });
+        return this._dispatch(event, (instance, handler) =>
+            handler.call(instance, { data, context, delivery })
+        );
     }
 
     /**

package/handlers/middleware/admin-auth.js

@@ -29,6 +29,19 @@ function secretsMatch(provided, expected) {
     return crypto.timingSafeEqual(providedHash, expectedHash);
 }
 
+/**
+ * True when `provided` matches the configured ADMIN_API_KEY. False when no
+ * key is configured or none was provided. For callers that change a response
+ * for admins rather than reject everyone else (GET /api/meta).
+ * @param {string|undefined} provided
+ * @returns {boolean}
+ */
+function isValidAdminApiKey(provided) {
+    const expectedKey = process.env.ADMIN_API_KEY;
+    if (!expectedKey || !provided) return false;
+    return secretsMatch(provided, expectedKey);
+}
+
 /**
  * Validate admin API key from request header
  * @param {import('express').Request} req
@@ -70,4 +83,4 @@ function validateAdminApiKey(req, res, next) {
     next();
 }
 
-module.exports = { validateAdminApiKey };
+module.exports = { validateAdminApiKey, isValidAdminApiKey };

package/handlers/routers/auth.js

@@ -1,15 +1,51 @@
-const { createIntegrationRouter } = require('@friggframework/core');
+const express = require('express');
+const {
+    createManagementApiRouter,
+} = require('../../management-api/create-management-api-router');
+const {
+    createExtensionRoutesRouter,
+} = require('../../extensions/route-mounter');
 const { createAppHandler } = require('./../app-handler-helpers');
 
-const router = createIntegrationRouter();
+// The Management API (ADR-053): v2 under /api/v2, the deprecated v1 at the
+// unprefixed paths (or 410 when managementApi.v1 is false).
+//
+// Built on first access, not at require time (friggframework/frigg#545,
+// c40eca49): a host that presets the app definition (setAppDefinition, as
+// provider-netlify's function entry points do) can require this module
+// before or after doing so.
+let router;
+let handler;
 
-router.route('/api/integrations/redirect/:appId').get((req, res) => {
-    res.redirect(
-        `${process.env.FRONTEND_URI}/redirect/${req.params.appId
-        }?${new URLSearchParams(req.query)}`
-    );
-});
+function buildRouter() {
+    const built = express.Router();
+    built.use(createManagementApiRouter());
 
-const handler = createAppHandler('HTTP Event: Auth', router);
+    // The OAuth provider's redirect target. Unversioned: it is neither part
+    // of v1 nor v2, so it is never deprecated or disabled.
+    built.route('/api/integrations/redirect/:appId').get((req, res) => {
+        res.redirect(
+            `${process.env.FRONTEND_URI}/redirect/${req.params.appId
+            }?${new URLSearchParams(req.query)}`
+        );
+    });
 
-module.exports = { handler };
+    // Core extension routes (appDefinition.coreExtensions[].routes), each
+    // behind the admin API key.
+    built.use(createExtensionRoutesRouter());
+
+    return built;
+}
+
+module.exports = {
+    get router() {
+        if (!router) router = buildRouter();
+        return router;
+    },
+    get handler() {
+        if (!handler) {
+            handler = createAppHandler('HTTP Event: Auth', module.exports.router);
+        }
+        return handler;
+    },
+};

package/handlers/routers/health.js

@@ -2,9 +2,6 @@ const { Router } = require('express');
 const { createAppHandler } = require('./../app-handler-helpers');
 const { loadAppDefinition } = require('./../app-definition-loader');
 const { ModuleFactory } = require('../../modules/module-factory');
-const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
@@ -28,18 +25,25 @@ const {
     CheckIntegrationsHealthUseCase,
 } = require('../use-cases/check-integrations-health-use-case');
 
+const {
+    createManagementApiMetaRouter,
+    createDocsRedirectRouter,
+} = require('../../management-api/meta-router');
+
 const router = Router();
 const healthCheckRepository = createHealthCheckRepository({ prismaClient: prisma });
 
 // Load integrations and create factories just like auth router does
 // This verifies the system can properly load integrations
 let moduleFactory, integrationClasses;
+let appDefinition = {};
 try {
     const appDef = loadAppDefinition();
+    appDefinition = appDef;
     integrationClasses = appDef.integrations || [];
 
     const moduleRepository = createModuleRepository();
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrationClasses);
+    const { moduleDefinitions } = appDef;
 
     moduleFactory = new ModuleFactory({
         moduleRepository,
@@ -85,6 +89,11 @@ const validateApiKey = (req, res, next) => {
     next();
 };
 
+// Management API discovery (ADR-053 §4) and the /api/docs redirect to it are
+// public and DB-free, so they are mounted ahead of the health API key check.
+router.use(createManagementApiMetaRouter({ appDefinition }));
+router.use(createDocsRedirectRouter());
+
 router.use(validateApiKey);
 
 // Helper to detect VPC configuration