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

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 };