@friggframework/core 2.0.0--canary.686.df38e8e.0 → 2.0.0--canary.710.9045bbc.0

package/management-api/error-response.js

@@ -1,116 +0,0 @@
-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

@@ -1,151 +0,0 @@
-/**
- * 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

@@ -1,76 +0,0 @@
-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

@@ -1,144 +0,0 @@
-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 };