@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/integrations/use-cases/resolve-integration-ownership.js

@@ -0,0 +1,177 @@
+const Boom = require('@hapi/boom');
+const { SCOPES, resolveScope } = require('../../modules/scope-resolution');
+const {
+    integrationOwnerKind,
+    resolveIntegrationOwner,
+} = require('../../modules/scope-resolution');
+const {
+    describeRecord,
+    unscopedRowsBelongHere,
+} = require('../../modules/scope-visibility');
+const {
+    bindingScopeSetting,
+    readIntegrationOwnership,
+} = require('../../modules/scope-config');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { entityTypeNameOf } = require('../../modules/entity-type-registry');
+
+const notFound = (entityId) =>
+    Boom.notFound(`Entity ${entityId} not found`, { code: 'ENTITY_NOT_FOUND' });
+
+/**
+ * Who owns an integration about to be created, and in which organization
+ * (ADR-056 §3, §3.3, §3.6). Shared by the v1 and v2 create paths. Nothing is
+ * persisted before this has answered, so a refusal leaves no row behind.
+ *
+ * Every entity must be one the caller may use in the active organization. A
+ * missing one, another organization's and a `global` one are the same 404, so
+ * ids cannot be probed. When the integration declares a scope (a binding's
+ * `scope` or `Definition.entities[key].scope`, or `Definition.ownership.scope`)
+ * the entity's scope must be in it. Levels below the integration (entity type,
+ * app, default) decide where a connection is CREATED and do not restrict what
+ * an integration may bind, so an app that adds a registry scope later does not
+ * break integrations that already use older connections.
+ *
+ * The owner follows the entities (all organization: the organization;
+ * otherwise the person) unless `Definition.ownership.owner` says. Every entity
+ * must then be of the owner's own scope: an integration is loaded by its owner,
+ * who must own what it uses, so an integration that mixes an organization
+ * entity with a person's own, or that names an owner that does not match, is
+ * refused with a 400 here, before anything is written.
+ */
+class ResolveIntegrationOwnership {
+    /**
+     * @param {Object} params
+     * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
+     * @param {Array<Function>} params.integrationClasses
+     * @param {Object} [params.scopePolicy] - from createScopePolicy
+     */
+    constructor({ moduleRepository, integrationClasses, scopePolicy }) {
+        this.moduleRepository = moduleRepository;
+        this.integrationClasses = integrationClasses || [];
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Array<string|number>} params.entityIds
+     * @param {Object} params.config - `{ type }`
+     * @param {Object} params.user - authenticated User
+     * @returns {Promise<{ownerId: string, organizationId: (string|null), ownerKind: string, adoptUnscoped: boolean}>}
+     */
+    async execute({ entityIds, config, user }) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const integrationClass = this.integrationClasses.find(
+            (IntegrationClass) => IntegrationClass.Definition?.name === config?.type
+        );
+        const ownership = readIntegrationOwnership(integrationClass);
+
+        const entities = await this.loadEntities(entityIds);
+        const scoped = entities.map((entity) => ({
+            entity,
+            scope: this.acceptedScope({ entity, ctx, integrationClass, ownership }),
+        }));
+
+        const ownerKind = integrationOwnerKind(
+            scoped.map(({ scope }) => scope),
+            ownership.owner
+        );
+        this.assertOneScope(scoped, ownerKind, config?.type);
+        return {
+            ...resolveIntegrationOwner(ownerKind, ctx),
+            ownerKind,
+            // Whether an existing integration with no organization (written
+            // before scoping) is this caller's to reuse. An organization-owned
+            // one is unambiguous: its owner is the organization, whoever asks
+            // and whatever their own legacy pointer says. A person's is theirs
+            // only where scope-visibility says (their legacy organization).
+            adoptUnscoped:
+                ownerKind === SCOPES.ORGANIZATION ||
+                unscopedRowsBelongHere(ctx, 'integration'),
+        };
+    }
+
+    /** Every entity must be of the integration owner's own scope (see the class comment). */
+    assertOneScope(scoped, ownerKind, type) {
+        for (const { entity, scope } of scoped) {
+            if (scope === ownerKind) continue;
+            // The load-time check (resolveOwnershipConfig) only sees declared
+            // scopes; this one sees the entities actually named.
+            if (ownerKind === SCOPES.ORGANIZATION) {
+                throw Boom.badRequest(
+                    "An organization-owned integration cannot use an 'individual' entity: a shared integration must not run on one person's credential",
+                    {
+                        code: 'ORG_INTEGRATION_INDIVIDUAL_ENTITY',
+                        details: { entityId: String(entity.id) },
+                    }
+                );
+            }
+            throw Boom.badRequest(
+                `Integration '${type}' would be owned by the person but uses the organization entity ${entity.id}. An integration must use entities of one scope: all of the person's, or all of the organization's.`,
+                {
+                    code: 'MIXED_ENTITY_SCOPES',
+                    details: { entityId: String(entity.id), scope },
+                }
+            );
+        }
+    }
+
+    async loadEntities(entityIds) {
+        const ids = (entityIds || []).map(String);
+        if (ids.length === 0) return [];
+        let found;
+        try {
+            found = await this.moduleRepository.findEntitiesByIds(ids);
+        } catch (error) {
+            // A malformed id (e.g. not an integer on PostgreSQL) is "not found".
+            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+                throw notFound(ids[0]);
+            }
+            throw error;
+        }
+        const byId = new Map((found || []).filter(Boolean).map((e) => [String(e.id), e]));
+        return ids.map((id) => {
+            if (!byId.has(id)) throw notFound(id);
+            return byId.get(id);
+        });
+    }
+
+    /** The entity's scope for this caller, or a refusal. */
+    acceptedScope({ entity, ctx, integrationClass, ownership }) {
+        const described = describeRecord(entity, ctx, 'entity');
+        if (!described) throw notFound(entity.id);
+        const { scope } = described;
+
+        const declared = this.declaredScope({ entity, integrationClass, ownership });
+        if (declared && !declared.allow.includes(scope)) {
+            throw Boom.badRequest(
+                `Entity ${entity.id} is ${scope}-scoped, but this integration binds ${entity.moduleName} at ${declared.allow.join(' or ')} scope`,
+                {
+                    code: 'ENTITY_SCOPE_MISMATCH',
+                    details: { entityId: String(entity.id), scope, allowed: declared.allow },
+                }
+            );
+        }
+        return scope;
+    }
+
+    /**
+     * What the integration itself declares for this entity's binding (levels 2
+     * and 3 only), or null when it declares nothing.
+     */
+    declaredScope({ entity, integrationClass, ownership }) {
+        const Definition = integrationClass?.Definition;
+        const key = Object.keys(Definition?.modules || {}).find(
+            (candidate) =>
+                entityTypeNameOf(Definition.modules[candidate]?.definition) ===
+                entity.moduleName
+        );
+        const resolved = resolveScope({
+            binding: key === undefined ? undefined : bindingScopeSetting(Definition, key),
+            integration: ownership.scope,
+        });
+        return resolved.decidedBy === 'default' ? null : resolved;
+    }
+}
+
+module.exports = { ResolveIntegrationOwnership };

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