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

package/integrations/utils/map-integration-dto.js

@@ -19,19 +19,48 @@ function mapIntegrationClassToIntegrationDTO(integration) {
     };
 }
 
+let deprecationLogged = false;
 
-const getModulesDefinitionFromIntegrationClasses = (integrationClasses) => {
-    return [
-        ...new Set(
-            integrationClasses
-                .map((integration) =>
-                    Object.values(integration.Definition.modules).map(
-                        (module) => module.definition
-                    )
-                )
-                .flat()
-        ),
-    ];
-};
+/**
+ * @deprecated Since ADR-059. Read `entityTypeRegistry` / `moduleDefinitions`
+ * from `loadAppDefinition()`, or call `getEntityTypeRegistry(appDefinition)`
+ * and read each entry's `definition`.
+ *
+ * Kept as a wrapper over the entity type registry so callers that imported it
+ * keep working. It returns the registry's definitions, so it follows the
+ * registry's rules: one definition per entity type name (the first wins when
+ * two integrations bind different definitions under one name, as
+ * ModuleFactory already picked), and, when `entities` is passed, registry-only
+ * types are included and conflicts throw `EntityRegistryError`.
+ *
+ * @param {Array<Function>} integrationClasses - integration classes
+ * @param {Object} [entities] - `appDefinition.entities` (ADR-059)
+ * @returns {Array<Object>} API module definitions
+ */
+function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses,
+    entities
+) {
+    // Required here, not at the top: modules/ must not load at require time
+    // of every integration use case that only wants the DTO mapper.
+    const {
+        getEntityTypeRegistry,
+        getEntityTypeDefinitions,
+    } = require('../../modules/entity-type-registry');
+    if (!deprecationLogged) {
+        deprecationLogged = true;
+        const { getLogger } = require('../../logs');
+        getLogger('frigg.integrations').warn(
+            'getModulesDefinitionFromIntegrationClasses is deprecated; use getEntityTypeRegistry (ADR-059)',
+            { eventName: 'frigg.integrations.deprecated_module_definitions' }
+        );
+    }
+    return getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations: integrationClasses, entities })
+    );
+}
 
-module.exports = { mapIntegrationClassToIntegrationDTO, getModulesDefinitionFromIntegrationClasses }; 
+module.exports = {
+    mapIntegrationClassToIntegrationDTO,
+    getModulesDefinitionFromIntegrationClasses,
+};

package/management-api/create-management-api-router.js

@@ -0,0 +1,49 @@
+const express = require('express');
+const { resolveManagementApiConfig } = require('./management-api-config');
+const {
+    createV1DeprecationRouter,
+    createV1DisabledRouter,
+} = require('./v1-deprecation');
+
+/**
+ * The Management API served by the auth Lambda (ADR-053): v2 under /api/v2
+ * and the frozen, deprecated v1 at the unprefixed paths. With
+ * `managementApi.v1: false` the v1 handlers are never built and the v1 paths
+ * answer 410.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.appDefinition] - defaults to loadAppDefinition().
+ * @param {Function} [params.createV1Router] - defaults to createIntegrationRouter.
+ * @param {Function} [params.createV2Router] - defaults to createManagementApiV2Router.
+ */
+function createManagementApiRouter({
+    appDefinition,
+    createV1Router,
+    createV2Router,
+} = {}) {
+    const definition =
+        appDefinition ||
+        require('../handlers/app-definition-loader').loadAppDefinition();
+    const config = resolveManagementApiConfig(definition.managementApi);
+
+    const buildV1 =
+        createV1Router ||
+        require('../integrations/integration-router').createIntegrationRouter;
+    const buildV2 =
+        createV2Router ||
+        require('./v2/create-v2-router').createManagementApiV2Router;
+
+    const router = express.Router();
+    router.use(buildV2({ appDefinition: definition, config }));
+
+    if (config.v1) {
+        router.use(createV1DeprecationRouter());
+        router.use(buildV1());
+    } else {
+        router.use(createV1DisabledRouter());
+    }
+
+    return router;
+}
+
+module.exports = { createManagementApiRouter };

package/management-api/error-response.js

@@ -0,0 +1,116 @@
+const Boom = require('@hapi/boom');
+
+/**
+ * Error responses for the HTTP boundary (handlers/app-handler-helpers.js).
+ *
+ * - v1 and other unversioned routes keep their historical body:
+ *   `{ error: message }` for 4xx, `{ error: 'Internal Server Error' }` for 5xx.
+ * - Management API v2 and /api/meta answer `{ error: { code, message, details? } }`
+ *   and carry `Frigg-API-Version: 2` even when the error happened before any
+ *   v2 router ran (for example a body-parser failure).
+ */
+
+const API_VERSION_HEADER = 'Frigg-API-Version';
+
+const CODE_BY_STATUS = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    405: 'METHOD_NOT_ALLOWED',
+    409: 'CONFLICT',
+    410: 'GONE',
+    413: 'PAYLOAD_TOO_LARGE',
+    415: 'UNSUPPORTED_MEDIA_TYPE',
+    422: 'UNPROCESSABLE_ENTITY',
+    429: 'RATE_LIMITED',
+    500: 'INTERNAL_ERROR',
+    501: 'NOT_IMPLEMENTED',
+    502: 'BAD_GATEWAY',
+    503: 'SERVICE_UNAVAILABLE',
+    504: 'GATEWAY_TIMEOUT',
+};
+
+// body-parser (via http-errors) tags its failures with `type`.
+const CODE_BY_BODY_PARSER_TYPE = {
+    'entity.parse.failed': 'INVALID_JSON',
+    'entity.too.large': 'PAYLOAD_TOO_LARGE',
+    'encoding.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
+    'charset.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
+    'request.aborted': 'BAD_REQUEST',
+};
+
+/** True for paths that use the v2 error contract. */
+function isVersionedManagementApiPath(path = '') {
+    return (
+        path === '/api/v2' ||
+        path.startsWith('/api/v2/') ||
+        path === '/api/meta' ||
+        path.startsWith('/api/meta/')
+    );
+}
+
+/**
+ * The HTTP status for an error. Boom errors carry theirs. Other errors are
+ * trusted only when they declare a client error as safe to expose, as
+ * http-errors (and so body-parser) does; anything else is a 500, so an
+ * upstream FetchError's `statusCode` is never mistaken for ours.
+ */
+function resolveStatusCode(err) {
+    if (err?.isBoom) return err.output.statusCode;
+    const status = err?.status ?? err?.statusCode;
+    if (
+        err?.expose === true &&
+        Number.isInteger(status) &&
+        status >= 400 &&
+        status < 500
+    ) {
+        return status;
+    }
+    return 500;
+}
+
+/** Normalises any thrown value into a Boom error with the right status. */
+function toBoom(err) {
+    if (err?.isBoom) return err;
+    const error = err instanceof Error ? err : new Error(String(err));
+    return Boom.boomify(error, { statusCode: resolveStatusCode(err) });
+}
+
+/** The v2 error body for a Boom error. */
+function toV2ErrorBody(boomError) {
+    const statusCode = boomError.output.statusCode;
+    const data =
+        boomError.data && typeof boomError.data === 'object'
+            ? boomError.data
+            : {};
+    const exposeServerError = statusCode >= 500 && data.expose === true;
+
+    const code =
+        (typeof data.code === 'string' && data.code) ||
+        CODE_BY_BODY_PARSER_TYPE[boomError.type] ||
+        CODE_BY_STATUS[statusCode] ||
+        (statusCode >= 500 ? 'INTERNAL_ERROR' : 'BAD_REQUEST');
+
+    const message =
+        statusCode < 500 || exposeServerError
+            ? boomError.message
+            : 'Internal Server Error';
+
+    const body = { code, message };
+    if (
+        data.details !== undefined &&
+        (statusCode < 500 || exposeServerError)
+    ) {
+        body.details = data.details;
+    }
+    return { error: body };
+}
+
+module.exports = {
+    API_VERSION_HEADER,
+    isVersionedManagementApiPath,
+    resolveStatusCode,
+    toBoom,
+    toV2ErrorBody,
+};

package/management-api/management-api-config.js

@@ -0,0 +1,151 @@
+/**
+ * Resolves `appDefinition.managementApi` (ADR-052, ADR-053).
+ *
+ * ```js
+ * managementApi: {
+ *     v1: false,              // drop the deprecated v1 routes (default true)
+ *     proxy: {
+ *         enable: true,       // entity proxy, off by default (ADR-052)
+ *         timeoutMs: 25000,   // whole upstream call, lower only
+ *         maxRequestBytes: 1048576,
+ *         maxResponseBytes: 5242880, // lower only
+ *         scopes: ['individual'], // entity scopes the proxy accepts (ADR-056 §3.5)
+ *         modules: {          // per-module allow-list override
+ *             hubspot: { allow: 'module' },
+ *             erp: { allow: [{ method: 'GET', path: '/v1/customers/**' }] },
+ *         },
+ *     },
+ * }
+ * ```
+ *
+ * Limits that are out of range fall back to their defaults. `proxy.scopes` is a
+ * security setting, so it does not fall back: a value that is not a list of
+ * known tenant scopes throws ManagementApiConfigError, and loadAppDefinition
+ * calls this so the app stops at load.
+ */
+
+const { BaseError } = require('../errors/base-error');
+const { SCOPES } = require('../modules/scope-resolution');
+
+/** Raised for an invalid `appDefinition.managementApi` setting. */
+class ManagementApiConfigError extends BaseError {
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'MANAGEMENT_API_CONFIG_INVALID';
+    }
+}
+
+/**
+ * The scopes `managementApi.proxy.scopes` may list. `global` is not one of
+ * them: a global entity is the app owner's and is never a tenant's to proxy.
+ */
+const PROXY_SCOPE_VALUES = Object.freeze([SCOPES.INDIVIDUAL, SCOPES.ORGANIZATION]);
+
+/**
+ * Narrowest by default (ADR-056 §3.5): proxying through a shared credential
+ * lets any member act on the organization's account, so an app opts in to
+ * `organization` explicitly.
+ */
+const DEFAULT_PROXY_SCOPES = Object.freeze([SCOPES.INDIVIDUAL]);
+
+// ADR-052 §7. API Gateway HTTP APIs time out at 30s and Lambda responses cap
+// at 6MB, so the timeout and response defaults are also ceilings: an app may
+// lower them, not raise them.
+const DEFAULT_PROXY_LIMITS = Object.freeze({
+    timeoutMs: 25_000,
+    maxRequestBytes: 1024 * 1024,
+    maxResponseBytes: 5 * 1024 * 1024,
+});
+
+// The request-body limit has no platform ceiling below API Gateway's 10MB, so
+// an app may raise it up to that.
+const MAX_REQUEST_BYTES_CEILING = 10 * 1024 * 1024;
+
+const isPositiveNumber = (value) =>
+    typeof value === 'number' && Number.isFinite(value) && value > 0;
+
+/** The value, capped at `ceiling`; the ceiling when the value is unusable. */
+function positiveCapped(value, ceiling) {
+    return isPositiveNumber(value) ? Math.min(value, ceiling) : ceiling;
+}
+
+/** The value, capped at `ceiling`; `fallback` when the value is unusable. */
+function positiveOr(value, fallback, ceiling) {
+    return isPositiveNumber(value) ? Math.min(value, ceiling) : fallback;
+}
+
+const proxyScopesError = (message) =>
+    new ManagementApiConfigError(`managementApi.proxy.scopes: ${message}`);
+
+/**
+ * `managementApi.proxy.scopes`: absent means the default; anything else must be
+ * a non-empty list of PROXY_SCOPE_VALUES, each once.
+ * @returns {ReadonlyArray<string>}
+ * @throws {ManagementApiConfigError}
+ */
+function resolveProxyScopes(scopes) {
+    if (scopes === undefined) return DEFAULT_PROXY_SCOPES;
+    const allowed = PROXY_SCOPE_VALUES.join(', ');
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+        throw proxyScopesError(`must be a non-empty list drawn from ${allowed}`);
+    }
+    for (const scope of scopes) {
+        if (scope === SCOPES.GLOBAL) {
+            throw proxyScopesError(
+                "'global' is not allowed: global entities belong to the app owner and are never proxied for a tenant"
+            );
+        }
+        if (!PROXY_SCOPE_VALUES.includes(scope)) {
+            throw proxyScopesError(`unknown scope ${JSON.stringify(scope)}; use ${allowed}`);
+        }
+    }
+    if (new Set(scopes).size !== scopes.length) {
+        throw proxyScopesError('lists a scope more than once');
+    }
+    return Object.freeze([...scopes]);
+}
+
+/**
+ * @param {Object} [managementApi] - `appDefinition.managementApi`
+ * @returns {{ v1: boolean, proxy: { enable: boolean, timeoutMs: number, maxRequestBytes: number, maxResponseBytes: number, scopes: ReadonlyArray<string>, modules: Object } }}
+ * @throws {ManagementApiConfigError} for an invalid `proxy.scopes`
+ */
+function resolveManagementApiConfig(managementApi) {
+    const config =
+        managementApi && typeof managementApi === 'object' ? managementApi : {};
+    const proxy =
+        config.proxy && typeof config.proxy === 'object' ? config.proxy : {};
+
+    return {
+        v1: config.v1 !== false,
+        proxy: {
+            enable: proxy.enable === true,
+            timeoutMs: positiveCapped(
+                proxy.timeoutMs,
+                DEFAULT_PROXY_LIMITS.timeoutMs
+            ),
+            maxRequestBytes: positiveOr(
+                proxy.maxRequestBytes,
+                DEFAULT_PROXY_LIMITS.maxRequestBytes,
+                MAX_REQUEST_BYTES_CEILING
+            ),
+            maxResponseBytes: positiveCapped(
+                proxy.maxResponseBytes,
+                DEFAULT_PROXY_LIMITS.maxResponseBytes
+            ),
+            scopes: resolveProxyScopes(proxy.scopes),
+            modules:
+                proxy.modules && typeof proxy.modules === 'object'
+                    ? proxy.modules
+                    : {},
+        },
+    };
+}
+
+module.exports = {
+    resolveManagementApiConfig,
+    DEFAULT_PROXY_LIMITS,
+    DEFAULT_PROXY_SCOPES,
+    PROXY_SCOPE_VALUES,
+    ManagementApiConfigError,
+};

package/management-api/meta-router.js

@@ -0,0 +1,76 @@
+const { Router } = require('express');
+const Boom = require('@hapi/boom');
+const { resolveManagementApiConfig } = require('./management-api-config');
+const {
+    GetManagementApiMeta,
+} = require('./use-cases/get-management-api-meta');
+const { isValidAdminApiKey } = require('../handlers/middleware/admin-auth');
+const { version: coreVersion } = require('../package.json');
+const {
+    MANAGEMENT_API_VERSIONS,
+    PREFERRED_API_VERSION,
+    DOCS_ROUTES,
+} = require('./route-registry');
+const { buildOpenApiDocument } = require('./openapi/build-openapi');
+
+/**
+ * Version-neutral discovery routes (ADR-053 §4, §5), mounted on the DB-free
+ * health Lambda. No authentication: the admin API key only adds the core
+ * version to the response.
+ *
+ * @param {Object} params
+ * @param {Object} params.appDefinition - the loaded app definition
+ *   (`managementApi` is read).
+ */
+function createManagementApiMetaRouter({ appDefinition = {} } = {}) {
+    const config = resolveManagementApiConfig(appDefinition.managementApi);
+    const getMeta = new GetManagementApiMeta({ config, coreVersion });
+
+    const router = Router();
+
+    router.get('/api/meta', (req, res) => {
+        const isAdmin = isValidAdminApiKey(req.get('x-frigg-admin-api-key'));
+        res.set('Cache-Control', 'no-store');
+        res.json(getMeta.execute({ isAdmin }));
+    });
+
+    // One OpenAPI document per major (ADR-053 §5). Static per deployment, so
+    // built once; the entity proxy appears only when the app enables it.
+    const documents = new Map();
+    for (const major of Object.keys(MANAGEMENT_API_VERSIONS)) {
+        router.get(`/api/meta/openapi/v${major}.json`, (_req, res) => {
+            if (!documents.has(major)) {
+                documents.set(
+                    major,
+                    buildOpenApiDocument(major, { proxy: config.proxy.enable })
+                );
+            }
+            res.set('Cache-Control', 'public, max-age=300');
+            res.json(documents.get(major));
+        });
+    }
+
+    // Anything else under /api/meta is a v2-shaped 404, not Express's page.
+    router.use('/api/meta', (req, _res, next) => {
+        next(Boom.notFound(`No Management API meta route for ${req.method} ${req.originalUrl.split('?')[0]}`));
+    });
+
+    return router;
+}
+
+/**
+ * GET /api/docs (DOCS_ROUTES): a redirect to the current OpenAPI document,
+ * mounted next to the meta router on the DB-free health Lambda. Public, like
+ * /api/meta.
+ */
+function createDocsRedirectRouter() {
+    const router = Router();
+    for (const { path } of DOCS_ROUTES) {
+        router.get(path, (_req, res) =>
+            res.redirect(302, `/api/meta/openapi/v${PREFERRED_API_VERSION}.json`)
+        );
+    }
+    return router;
+}
+
+module.exports = { createManagementApiMetaRouter, createDocsRedirectRouter };

package/management-api/openapi/build-openapi.js

@@ -0,0 +1,144 @@
+const {
+    MANAGEMENT_API_VERSIONS,
+    V1_ROUTES,
+    META_ROUTES,
+    V1_MIGRATION_DOCS_URL,
+    listV2Routes,
+    toGatewayPath,
+} = require('../route-registry');
+const { SCHEMAS, RESPONSES, SECURITY_SCHEMES } = require('./components');
+const { V2_OPERATIONS, META_OPERATIONS } = require('./v2-operations');
+const { V1_OPERATIONS } = require('./v1-operations');
+const { version: coreVersion } = require('../../package.json');
+
+const COMPATIBILITY_RULES = `
+Compatibility (ADR-053): within a major, changes are additive only. Clients
+must ignore response fields and enum values they do not know. Operations
+marked \`x-frigg-stability: beta\` may still change in a core minor.
+
+Errors: \`{ "error": { "code", "message", "details"? } }\`. Every response
+carries \`Frigg-API-Version: 2\`.`;
+
+const DESCRIPTIONS = {
+    1: `The original, unprefixed Management API. Deprecated (ADR-053): every response carries
+\`Deprecation\` and \`Link: <${V1_MIGRATION_DOCS_URL}>; rel="deprecation"\`. It is frozen,
+and \`managementApi.v1: false\` turns it off. Use v2.`,
+    2: `Integrations, entities, credentials, multi-step authorization and the entity proxy, under
+\`/api/v2\`. Discover what a deployment serves with \`GET /api/meta\`.
+${COMPATIBILITY_RULES}`,
+};
+
+const TAGS = [
+    { name: 'Integrations', description: 'Integrations between connected entities' },
+    { name: 'Entities', description: 'Connected accounts, entity types and the entity proxy' },
+    { name: 'Credentials', description: 'Stored credentials (always masked) and re-authorization' },
+    { name: 'Authorization', description: 'Single- and multi-step authorization' },
+    { name: 'Meta', description: 'Version-neutral discovery' },
+];
+
+/** Path parameters, derived from the Express path. */
+function pathParameters(expressPath) {
+    return [...expressPath.matchAll(/:([A-Za-z0-9_]+)/g)].map(([, name]) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+    }));
+}
+
+function operationFor(route, docs, extra = {}) {
+    if (!docs) {
+        throw new Error(
+            `No OpenAPI documentation for ${route.method} ${route.path} (${route.operationId || 'v1'})`
+        );
+    }
+    const parameters = [...pathParameters(route.path), ...(docs.parameters || [])];
+    return {
+        operationId: route.operationId,
+        ...(route.tag && { tags: [route.tag] }),
+        ...docs,
+        ...(parameters.length && { parameters }),
+        ...(route.stability && { 'x-frigg-stability': route.stability }),
+        ...extra,
+    };
+}
+
+function addOperation(paths, route, operation) {
+    const path = toGatewayPath(route.path);
+    paths[path] = paths[path] || {};
+    // An ANY route (router.all in v1) is documented as GET and POST, the two
+    // methods callers use.
+    const methods = route.method === 'ANY' ? ['get', 'post'] : [route.method.toLowerCase()];
+    for (const method of methods) {
+        paths[path][method] = {
+            ...operation,
+            ...(methods.length > 1 && {
+                operationId: `${operation.operationId}${method === 'get' ? '' : 'Post'}`,
+            }),
+        };
+    }
+}
+
+/**
+ * Builds the OpenAPI 3 document for one Management API major from the route
+ * registry (ADR-053 §5).
+ *
+ * @param {string} major - '1' or '2'
+ * @param {Object} [options]
+ * @param {boolean} [options.proxy=true] - include the entity proxy (served
+ *   documents follow managementApi.proxy.enable)
+ * @returns {Object}
+ */
+function buildOpenApiDocument(major, { proxy = true } = {}) {
+    const info = MANAGEMENT_API_VERSIONS[major];
+    if (!info) throw new Error(`Unknown Management API version: ${major}`);
+
+    const paths = {};
+    if (major === '1') {
+        for (const route of V1_ROUTES) {
+            const key = `${route.method} ${route.path}`;
+            addOperation(
+                paths,
+                route,
+                operationFor({ ...route, operationId: V1_OPERATIONS[key]?.operationId }, V1_OPERATIONS[key], {
+                    deprecated: true,
+                })
+            );
+        }
+    } else {
+        for (const route of listV2Routes({ proxy })) {
+            addOperation(paths, route, operationFor(route, V2_OPERATIONS[route.operationId]));
+        }
+    }
+    for (const route of META_ROUTES) {
+        addOperation(
+            paths,
+            route,
+            operationFor({ ...route, tag: 'Meta' }, META_OPERATIONS[route.operationId])
+        );
+    }
+
+    return {
+        openapi: '3.0.3',
+        info: {
+            title: `Frigg Management API v${major}`,
+            version: coreVersion,
+            description: DESCRIPTIONS[major],
+            license: { name: 'MIT' },
+        },
+        'x-frigg-api-version': major,
+        'x-frigg-api-status': info.status,
+        ...(info.deprecatedAt && { 'x-frigg-deprecated-at': info.deprecatedAt }),
+        servers: [{ url: '/', description: 'This Frigg deployment' }],
+        security: [{ bearerAuth: [] }, { friggApiKey: [] }],
+        tags: TAGS,
+        paths,
+        components: {
+            schemas: SCHEMAS,
+            responses: RESPONSES,
+            securitySchemes: SECURITY_SCHEMES,
+        },
+    };
+}
+
+module.exports = { buildOpenApiDocument };