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

package/management-api/openapi/v2-operations.js

@@ -0,0 +1,264 @@
+const { ref } = require('./components');
+
+/**
+ * Per-operation documentation for Management API v2, keyed by the route
+ * registry's operationId. Paths and methods come from the registry, never
+ * from here, so the document cannot list a route the router does not serve.
+ */
+
+const json = (schema) => ({ content: { 'application/json': { schema } } });
+const ok = (description, schema) => ({ description, ...(schema && json(schema)) });
+const body = (schema, required = true) => ({ required, ...json(schema) });
+const errors = (...names) =>
+    Object.fromEntries(
+        names.map((name) => {
+            const status = {
+                BadRequest: '400',
+                Unauthorized: '401',
+                Forbidden: '403',
+                NotFound: '404',
+                Conflict: '409',
+                BadGateway: '502',
+            }[name];
+            return [status, { $ref: `#/components/responses/${name}` }];
+        })
+    );
+const query = (name, description, schema = { type: 'string' }, required = false) => ({
+    name,
+    in: 'query',
+    required,
+    description,
+    schema,
+});
+const stepQuery = [
+    query('step', 'Step number, 1-based (default 1)', { type: 'integer', minimum: 1 }),
+    query('sessionId', 'Session from step 1; required for later steps'),
+];
+// ADR-056 §3.4: the same two filters on every list that mixes ownership.
+const listFilters = [
+    query('scope', 'Only records of this scope', { type: 'string', enum: ['individual', 'organization'] }),
+    query('owner', 'Only the caller\'s own (`me`) or the active organization\'s (`org`)', { type: 'string', enum: ['me', 'org'] }),
+];
+const anyJson = { description: 'Defined by the integration or module' };
+
+const V2_OPERATIONS = {
+    // Integrations
+    listIntegrations: {
+        summary: "List the caller's integrations",
+        description:
+            'Returns only `{ integrations }`: the caller\'s and the active organization\'s, created in that organization (ADR-056 §3.6). Each carries `scope`, `owner`, `organizationId` and `access`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+        parameters: listFilters,
+        responses: { 200: ok('Integrations', ref('ListIntegrationsResponse')), ...errors('Unauthorized') },
+    },
+    listIntegrationOptions: {
+        summary: 'List the integration types this app offers',
+        responses: { 200: ok('Integration types', ref('ListIntegrationOptionsResponse')), ...errors('Unauthorized') },
+    },
+    createIntegration: {
+        summary: 'Create an integration between entities the caller owns',
+        description: 'An identical existing integration (same user, type and entities) is reused.',
+        requestBody: body(ref('CreateIntegrationRequest')),
+        responses: {
+            201: ok('Created (or reused) integration', ref('Integration')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound'),
+        },
+    },
+    getIntegration: {
+        summary: 'Get an integration',
+        responses: { 200: ok('Integration', ref('Integration')), ...errors('Unauthorized', 'NotFound') },
+    },
+    updateIntegration: {
+        summary: "Replace an integration's config",
+        requestBody: body(ref('UpdateIntegrationRequest')),
+        responses: { 200: ok('Updated integration', ref('Integration')), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
+    },
+    deleteIntegration: {
+        summary: 'Delete an integration',
+        responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound') },
+    },
+    getIntegrationConfigOptions: {
+        summary: 'Get config options (form schema) for an integration',
+        responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    refreshIntegrationConfigOptions: {
+        summary: 'Refresh config options with the current form values',
+        requestBody: body({ type: 'object', additionalProperties: true }, false),
+        responses: { 200: ok('Options', anyJson), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
+    },
+    listIntegrationActions: {
+        summary: 'List user actions an integration offers',
+        parameters: [query('actionType', 'Only actions of this userActionType')],
+        responses: { 200: ok('User actions', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    getIntegrationActionOptions: {
+        summary: 'Get the options form for a user action',
+        requestBody: body({ type: 'object', additionalProperties: true }, false),
+        responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    refreshIntegrationActionOptions: {
+        summary: 'Refresh a user action options form',
+        requestBody: body({ type: 'object', additionalProperties: true }, false),
+        responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    runIntegrationAction: {
+        summary: 'Run a user action',
+        description: 'Only actions the integration lists as user actions can run; anything else is 404 ACTION_NOT_FOUND.',
+        requestBody: body({ type: 'object', additionalProperties: true }, false),
+        responses: { 200: ok('Action result', anyJson), ...errors('BadRequest', 'Unauthorized', 'NotFound') },
+    },
+    testIntegrationAuth: {
+        summary: "Test an integration's connections",
+        responses: { 200: ok('Result', ref('AuthTestResult')), ...errors('Unauthorized', 'NotFound') },
+    },
+
+    // Entities
+    listEntities: {
+        summary: "List the caller's connected entities",
+        description:
+            "The active organization's entities and the caller's individual ones (ADR-056 §3.6): an individual entity belongs to the organization it was connected in, unless `ownership.individualAcross` is `all`. Each carries `scope`, `owner`, `organizationId` and `access`.",
+        parameters: listFilters,
+        responses: { 200: ok('Entities', ref('ListEntitiesResponse')), ...errors('Unauthorized') },
+    },
+    listEntityTypes: {
+        summary: 'List the entity types (API modules) this app can connect',
+        description:
+            'Every type registered in appDefinition.entities plus every module a declared integration binds. `usedBy` lists the integrations that bind each type; it is empty for a type registered without any integration.',
+        responses: { 200: ok('Entity types', ref('ListEntityTypesResponse')), ...errors('Unauthorized') },
+    },
+    getEntityType: {
+        summary: 'Describe an entity type',
+        description:
+            'Includes `usedBy`, the integrations that bind the type (empty for a registry-only type).',
+        responses: { 200: ok('Entity type', ref('EntityType')), ...errors('Unauthorized', 'NotFound') },
+    },
+    getEntityTypeRequirements: {
+        summary: 'Describe one authorization step of an entity type',
+        description: 'Read-only: does not start a session. Use GET /api/v2/authorize to start a flow.',
+        parameters: [stepQuery[0]],
+        responses: {
+            200: ok('Requirements', ref('AuthorizationRequirements')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound'),
+        },
+    },
+    getEntity: {
+        summary: 'Get an entity',
+        responses: { 200: ok('Entity', ref('Entity')), ...errors('Unauthorized', 'NotFound') },
+    },
+    deleteEntity: {
+        summary: 'Delete an entity',
+        description: 'Refused with 409 ENTITY_IN_USE while integrations use it. The credential stays.',
+        responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound', 'Conflict') },
+    },
+    testEntityAuth: {
+        summary: "Test an entity's stored credential",
+        responses: { 200: ok('Result', ref('AuthTestResult')), ...errors('Unauthorized', 'NotFound') },
+    },
+    getEntityOptions: {
+        summary: "Get an entity's options",
+        responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    refreshEntityOptions: {
+        summary: "Refresh an entity's options",
+        requestBody: body({ type: 'object', additionalProperties: true }, false),
+        responses: { 200: ok('Options', anyJson), ...errors('Unauthorized', 'NotFound') },
+    },
+    proxyEntityRequest: {
+        summary: "Call the entity's API through Frigg (beta)",
+        description:
+            "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; deny by default, only operations in the module's (or the app's) allow-list. ADR-056 §3.5: the caller needs use access to the entity in the active organization (an entity they cannot see there is 404), and the entity's scope must be in managementApi.proxy.scopes (default individual only; 403 PROXY_NOT_ALLOWED with details.reason 'scope', or 'access' for view-only access). The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
+        requestBody: body(ref('ProxyRequest')),
+        responses: {
+            200: ok('Upstream answer (the status mirrors the upstream status)', ref('ProxyResponse')),
+            400: ok('INVALID_PROXY_REQUEST', ref('ProxyError')),
+            401: ok('INVALID_CREDENTIALS or unauthenticated', ref('ProxyError')),
+            403: ok("PROXY_NOT_ALLOWED: not in the allow-list, or details.reason 'scope' / 'access'", ref('ProxyError')),
+            404: ok('Entity not found, or not visible in the active organization', ref('Error')),
+            413: ok('PAYLOAD_TOO_LARGE', ref('ProxyError')),
+            415: ok('UNSUPPORTED_MEDIA_TYPE', ref('ProxyError')),
+            429: ok('RATE_LIMITED (Retry-After passed through)', ref('ProxyError')),
+            502: ok('UPSTREAM_ERROR, NETWORK_ERROR or RESPONSE_TOO_LARGE', ref('ProxyError')),
+            504: ok('TIMEOUT', ref('ProxyError')),
+        },
+    },
+
+    // Credentials
+    listCredentials: {
+        summary: "List the caller's credentials (masked)",
+        description:
+            'A credential is listed through the entities that use it that the caller may see, so each organization lists only its own connections; one no entity uses is listed to its owner. Each carries `scope`, `owner`, `organizationId` and `access`, taken from who owns the credential.',
+        parameters: listFilters,
+        responses: { 200: ok('Credentials', ref('ListCredentialsResponse')), ...errors('Unauthorized') },
+    },
+    getCredential: {
+        summary: 'Get a credential (masked)',
+        responses: { 200: ok('Credential', ref('Credential')), ...errors('Unauthorized', 'NotFound') },
+    },
+    deleteCredential: {
+        summary: 'Delete a credential',
+        description: 'Entities that used it stay, with no credential, until re-authorized.',
+        responses: { 204: { description: 'Deleted' }, ...errors('Unauthorized', 'NotFound') },
+    },
+    getCredentialReauthorizeRequirements: {
+        summary: 'Start or continue re-authorizing a credential',
+        parameters: stepQuery,
+        responses: {
+            200: ok('Requirements', ref('AuthorizationRequirements')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict'),
+        },
+    },
+    reauthorizeCredential: {
+        summary: 'Submit a re-authorization step',
+        requestBody: body(ref('ReauthorizeRequest')),
+        responses: {
+            200: ok('Complete or pending', ref('AuthorizeResponse')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict', 'BadGateway'),
+        },
+    },
+
+    // Authorization
+    getAuthorizationRequirements: {
+        summary: 'Start or continue an authorization',
+        description:
+            'Single-step modules return their requirements. Multi-step modules start a session on step 1 (returned as sessionId); later steps need it and must be the current step.',
+        parameters: [
+            query('entityType', 'Module name', { type: 'string' }, true),
+            ...stepQuery,
+            query('state', 'OAuth state forwarded to the provider'),
+        ],
+        responses: {
+            200: ok('Requirements', ref('AuthorizationRequirements')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict'),
+        },
+    },
+    authorize: {
+        summary: 'Submit an authorization step',
+        description:
+            'Answers { status: "complete", entity, credential } or { status: "pending", step, totalSteps, sessionId, requirements }.',
+        requestBody: body(ref('AuthorizeRequest')),
+        responses: {
+            200: ok('Complete or pending', ref('AuthorizeResponse')),
+            ...errors('BadRequest', 'Unauthorized', 'NotFound', 'Conflict', 'BadGateway'),
+        },
+    },
+};
+
+const META_OPERATIONS = {
+    getApiMeta: {
+        summary: 'Supported API versions and capabilities',
+        description: 'No authentication, no database. The core version is added for admin callers only.',
+        security: [],
+        responses: { 200: ok('Discovery document', ref('ApiMeta')) },
+    },
+    getOpenApiV1: {
+        summary: 'OpenAPI document for Management API v1 (deprecated)',
+        security: [],
+        responses: { 200: ok('OpenAPI 3 document', { type: 'object' }) },
+    },
+    getOpenApiV2: {
+        summary: 'OpenAPI document for Management API v2',
+        security: [],
+        responses: { 200: ok('OpenAPI 3 document', { type: 'object' }) },
+    },
+};
+
+module.exports = { V2_OPERATIONS, META_OPERATIONS };

package/management-api/route-registry.js

@@ -0,0 +1,411 @@
+/**
+ * Management API route registry (ADR-053).
+ *
+ * The single source of truth for the Management API surface. Three consumers
+ * read it, so they cannot drift apart:
+ *
+ * - the Express routers (v2 mounts its handlers by `operationId`; v1 gets its
+ *   deprecation headers from the v1 list),
+ * - the OpenAPI documents served at /api/meta/openapi/v{n}.json,
+ * - the API Gateway HTTP API routes that devtools generates
+ *   (`getGatewayRoutes`, used by base-definition-factory).
+ *
+ * Rules (ADR-053):
+ * - v2 lives under `/api/v2/<resource>`. Gateway routes are declared per
+ *   resource, never `ANY /api/v2/{proxy+}`: `/api/v2/reports` (ADR-010) is
+ *   served by the admin-scripts Lambda and must not be shadowed.
+ * - v1 is the frozen unprefixed surface. Its handlers live in
+ *   integrations/integration-router.js and do not change; this list mirrors
+ *   them (a contract test keeps the two equal).
+ * - `/api/meta` is version-neutral and served by the DB-free `health` Lambda.
+ *
+ * This module must stay free of database, AWS and app-definition imports:
+ * devtools loads it at build time.
+ */
+
+/**
+ * Supported Management API majors. `deprecatedAt` feeds the RFC 9745
+ * `Deprecation` header; `sunset` (RFC 8594) stays null until a removal release
+ * is scheduled.
+ */
+const MANAGEMENT_API_VERSIONS = Object.freeze({
+    1: Object.freeze({
+        status: 'deprecated',
+        deprecatedAt: '2026-11-01',
+        sunset: null,
+    }),
+    2: Object.freeze({ status: 'stable' }),
+});
+
+const PREFERRED_API_VERSION = '2';
+
+/**
+ * `/api/v2/<segment>` values no v2 route may take. `reports` belongs to the
+ * admin-scripts Lambda (ADR-010); where it lives long term is open (ADR-053
+ * §7), so it is reserved, kept out of the v2 OpenAPI document and out of the
+ * /api/meta capabilities.
+ */
+const RESERVED_V2_SEGMENTS = Object.freeze(['reports']);
+
+const V1_MIGRATION_DOCS_URL =
+    'https://docs.friggframework.org/api/migrate-v1-v2';
+
+/**
+ * Functions (devtools names) that serve registered routes. `queueWorker` is
+ * the HTTP queue worker of hosts that deliver queue messages over HTTP
+ * (provider-netlify's worker-background); AWS delivers through SQS.
+ */
+const FUNCTIONS = Object.freeze({
+    AUTH: 'auth',
+    HEALTH: 'health',
+    QUEUE_WORKER: 'queueWorker',
+});
+
+const route = (version, fn) => (definition) =>
+    Object.freeze({ version, function: fn, ...definition });
+
+/**
+ * The v1 routes registered by createIntegrationRouter(). `ANY` marks routes
+ * registered with `router.all()`. Frozen: no behaviour change except the
+ * deprecation headers.
+ */
+const V1_ROUTES = Object.freeze(
+    [
+        { method: 'GET', path: '/api/integrations' },
+        { method: 'POST', path: '/api/integrations' },
+        { method: 'PATCH', path: '/api/integrations/:integrationId' },
+        { method: 'DELETE', path: '/api/integrations/:integrationId' },
+        {
+            method: 'GET',
+            path: '/api/integrations/:integrationId/config/options',
+        },
+        {
+            method: 'POST',
+            path: '/api/integrations/:integrationId/config/options/refresh',
+        },
+        { method: 'ANY', path: '/api/integrations/:integrationId/actions' },
+        {
+            method: 'ANY',
+            path: '/api/integrations/:integrationId/actions/:actionId/options',
+        },
+        {
+            method: 'POST',
+            path: '/api/integrations/:integrationId/actions/:actionId/options/refresh',
+        },
+        {
+            method: 'POST',
+            path: '/api/integrations/:integrationId/actions/:actionId',
+        },
+        { method: 'GET', path: '/api/integrations/:integrationId' },
+        { method: 'GET', path: '/api/integrations/:integrationId/test-auth' },
+        { method: 'GET', path: '/api/authorize' },
+        { method: 'POST', path: '/api/authorize' },
+        { method: 'POST', path: '/api/entity' },
+        { method: 'GET', path: '/api/entity/options/:credentialId' },
+        { method: 'GET', path: '/api/entities/:entityId/test-auth' },
+        { method: 'GET', path: '/api/entities/:entityId' },
+        { method: 'POST', path: '/api/entities/:entityId/options' },
+        { method: 'POST', path: '/api/entities/:entityId/options/refresh' },
+    ].map(route('1', FUNCTIONS.AUTH))
+);
+
+/**
+ * The v2 routes. Order matters: Express matches in this order, so literal
+ * segments (`/options`, `/types`) come before `/:id` siblings.
+ *
+ * - `operationId` keys the handler in management-api/v2 and the OpenAPI
+ *   operation.
+ * - `stability: 'beta'` marks routes that may still change in a core minor
+ *   (ADR-053 §2); it is published as `x-frigg-stability`.
+ * - `capability` names the /api/meta capability a route belongs to.
+ */
+const V2_ROUTES = Object.freeze(
+    [
+        // Integrations
+        { operationId: 'listIntegrations', method: 'GET', path: '/api/v2/integrations', tag: 'Integrations' },
+        { operationId: 'listIntegrationOptions', method: 'GET', path: '/api/v2/integrations/options', tag: 'Integrations' },
+        { operationId: 'createIntegration', method: 'POST', path: '/api/v2/integrations', tag: 'Integrations' },
+        { operationId: 'getIntegration', method: 'GET', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
+        { operationId: 'updateIntegration', method: 'PATCH', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
+        { operationId: 'deleteIntegration', method: 'DELETE', path: '/api/v2/integrations/:integrationId', tag: 'Integrations' },
+        { operationId: 'getIntegrationConfigOptions', method: 'GET', path: '/api/v2/integrations/:integrationId/config/options', tag: 'Integrations' },
+        { operationId: 'refreshIntegrationConfigOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/config/options/refresh', tag: 'Integrations' },
+        { operationId: 'listIntegrationActions', method: 'GET', path: '/api/v2/integrations/:integrationId/actions', tag: 'Integrations' },
+        { operationId: 'getIntegrationActionOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId/options', tag: 'Integrations' },
+        { operationId: 'refreshIntegrationActionOptions', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId/options/refresh', tag: 'Integrations' },
+        { operationId: 'runIntegrationAction', method: 'POST', path: '/api/v2/integrations/:integrationId/actions/:actionId', tag: 'Integrations' },
+        { operationId: 'testIntegrationAuth', method: 'GET', path: '/api/v2/integrations/:integrationId/test-auth', tag: 'Integrations' },
+
+        // Entities
+        { operationId: 'listEntities', method: 'GET', path: '/api/v2/entities', tag: 'Entities' },
+        { operationId: 'listEntityTypes', method: 'GET', path: '/api/v2/entities/types', tag: 'Entities' },
+        { operationId: 'getEntityType', method: 'GET', path: '/api/v2/entities/types/:entityType', tag: 'Entities' },
+        { operationId: 'getEntityTypeRequirements', method: 'GET', path: '/api/v2/entities/types/:entityType/requirements', tag: 'Entities' },
+        { operationId: 'getEntity', method: 'GET', path: '/api/v2/entities/:entityId', tag: 'Entities' },
+        { operationId: 'deleteEntity', method: 'DELETE', path: '/api/v2/entities/:entityId', tag: 'Entities' },
+        { operationId: 'testEntityAuth', method: 'GET', path: '/api/v2/entities/:entityId/test-auth', tag: 'Entities' },
+        { operationId: 'getEntityOptions', method: 'GET', path: '/api/v2/entities/:entityId/options', tag: 'Entities' },
+        { operationId: 'refreshEntityOptions', method: 'POST', path: '/api/v2/entities/:entityId/options/refresh', tag: 'Entities' },
+        { operationId: 'proxyEntityRequest', method: 'POST', path: '/api/v2/entities/:entityId/proxy', tag: 'Entities', stability: 'beta', capability: 'entityProxy' },
+
+        // Credentials
+        { operationId: 'listCredentials', method: 'GET', path: '/api/v2/credentials', tag: 'Credentials', capability: 'credentials' },
+        { operationId: 'getCredential', method: 'GET', path: '/api/v2/credentials/:credentialId', tag: 'Credentials', capability: 'credentials' },
+        { operationId: 'deleteCredential', method: 'DELETE', path: '/api/v2/credentials/:credentialId', tag: 'Credentials', capability: 'credentials' },
+        { operationId: 'getCredentialReauthorizeRequirements', method: 'GET', path: '/api/v2/credentials/:credentialId/reauthorize', tag: 'Credentials', capability: 'credentials' },
+        { operationId: 'reauthorizeCredential', method: 'POST', path: '/api/v2/credentials/:credentialId/reauthorize', tag: 'Credentials', capability: 'credentials' },
+
+        // Authorization (multi-step)
+        { operationId: 'getAuthorizationRequirements', method: 'GET', path: '/api/v2/authorize', tag: 'Authorization', capability: 'multiStepAuthorize' },
+        { operationId: 'authorize', method: 'POST', path: '/api/v2/authorize', tag: 'Authorization', capability: 'multiStepAuthorize' },
+    ].map(route('2', FUNCTIONS.AUTH))
+);
+
+/** Version-neutral discovery routes, served without auth or database. */
+const META_ROUTES = Object.freeze(
+    [
+        { operationId: 'getApiMeta', method: 'GET', path: '/api/meta' },
+        ...Object.keys(MANAGEMENT_API_VERSIONS).map((major) => ({
+            operationId: `getOpenApiV${major}`,
+            method: 'GET',
+            path: `/api/meta/openapi/v${major}.json`,
+        })),
+    ].map(route(null, FUNCTIONS.HEALTH))
+);
+
+/**
+ * Unversioned routes the auth Lambda serves next to the Management API
+ * (core/handlers/routers/auth.js). The OAuth redirect is the provider's
+ * callback target, so it is neither deprecated nor disabled with v1.
+ */
+const AUTH_EXTRA_ROUTES = Object.freeze(
+    [
+        {
+            operationId: 'oauthRedirect',
+            method: 'GET',
+            path: '/api/integrations/redirect/:appId',
+        },
+    ].map(route(null, FUNCTIONS.AUTH))
+);
+
+/**
+ * Unversioned routes the DB-free health Lambda serves next to /api/meta.
+ * GET /api/docs redirects to the current OpenAPI document; the docs
+ * themselves live under /api/meta (ADR-053).
+ */
+const DOCS_ROUTES = Object.freeze(
+    [
+        {
+            operationId: 'redirectToOpenApi',
+            method: 'GET',
+            path: '/api/docs',
+        },
+    ].map(route(null, FUNCTIONS.HEALTH))
+);
+
+/**
+ * Admin routes live under /admin (as core's /admin/db-migrate and the
+ * admin-scripts /admin/scripts do), never under the public /api prefix. A
+ * core extension (appDefinition.coreExtensions[].routes.path) mounts its admin
+ * API at /admin/<name>, served by the auth function behind the admin API key;
+ * these segments belong to other functions and cannot be taken.
+ */
+const ADMIN_ROUTE_PREFIX = '/admin/';
+const RESERVED_ADMIN_SEGMENTS = Object.freeze(['scripts', 'db-migrate', 'queue']);
+
+/**
+ * The queue delivery endpoint of hosts that deliver queue messages over HTTP
+ * (QStash posts here on Netlify). Every message must be signed: the worker
+ * verifies it before parsing anything. Not part of the public /api surface.
+ */
+const HTTP_QUEUE_ROUTES = Object.freeze(
+    [
+        {
+            operationId: 'deliverQueueMessage',
+            method: 'POST',
+            path: '/admin/queue',
+        },
+    ].map(route(null, FUNCTIONS.QUEUE_WORKER))
+);
+
+/**
+ * Why a core extension route path is not acceptable, or null when it is:
+ * `/admin/<segment>` (letters, digits, `-` and `_`, one or more segments), not
+ * a reserved segment.
+ *
+ * @param {*} path
+ * @returns {string|null}
+ */
+function coreExtensionRoutePathError(path) {
+    if (typeof path !== 'string' || !path.startsWith(ADMIN_ROUTE_PREFIX)) {
+        return `must start with ${ADMIN_ROUTE_PREFIX} (admin routes are not served under /api)`;
+    }
+    if (!/^\/admin(\/[A-Za-z0-9_-]+)+$/.test(path)) {
+        return 'must be /admin/<segment>[/<segment>...] using letters, digits, - and _';
+    }
+    const segment = path.split('/')[2];
+    if (RESERVED_ADMIN_SEGMENTS.includes(segment)) {
+        return `/admin/${segment} is reserved (${RESERVED_ADMIN_SEGMENTS.map((s) => `/admin/${s}`).join(', ')})`;
+    }
+    return null;
+}
+
+/**
+ * Route records for the core extensions' admin routes: each path and
+ * everything under it, on the auth function (core's auth router mounts the
+ * extension routes behind the admin API key).
+ *
+ * @param {Array<Object>} [coreExtensions] - appDefinition.coreExtensions (plain data;
+ *   only `routes.path` is read)
+ * @returns {Array<Object>}
+ */
+function listCoreExtensionRoutes(coreExtensions = []) {
+    if (!Array.isArray(coreExtensions)) return [];
+    const out = [];
+    for (const ext of coreExtensions) {
+        const path = ext?.routes?.path;
+        if (typeof path !== 'string' || coreExtensionRoutePathError(path)) continue;
+        out.push(
+            Object.freeze({ version: null, function: FUNCTIONS.AUTH, method: 'ANY', path, extension: ext.name }),
+            Object.freeze({ version: null, function: FUNCTIONS.AUTH, method: 'ANY', path: `${path}/{proxy+}`, extension: ext.name })
+        );
+    }
+    return out;
+}
+
+/**
+ * The v2 routes an app serves. Routes tied to an opt-in capability (the entity
+ * proxy, ADR-052) are left out unless the app enables it.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.proxy=false] - `managementApi.proxy.enable`
+ */
+function listV2Routes({ proxy = false } = {}) {
+    return V2_ROUTES.filter(
+        (record) => proxy || record.capability !== 'entityProxy'
+    );
+}
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.v1=true] - false drops the v1 routes
+ *   (`managementApi.v1: false` in the app definition).
+ * @param {boolean} [options.proxy=false] - true keeps the entity proxy route.
+ * @returns {Array<Object>} Every registered route record.
+ */
+function listRoutes({ v1 = true, proxy = false } = {}) {
+    return [
+        ...(v1 ? V1_ROUTES : []),
+        ...listV2Routes({ proxy }),
+        ...META_ROUTES,
+        ...AUTH_EXTRA_ROUTES,
+        ...DOCS_ROUTES,
+    ];
+}
+
+/** `/api/v2/entities/:entityId` -> `/api/v2/entities/{entityId}` */
+function toGatewayPath(expressPath) {
+    return expressPath.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+}
+
+/**
+ * The resource root a route is grouped under for API Gateway:
+ * `/api/v2/<resource>` for v2, `/api/<resource>` for v1, `/api/meta` for meta.
+ */
+function resourceRoot(record) {
+    const segments = record.path.split('/').filter(Boolean);
+    const depth = record.version === '2' ? 3 : 2;
+    return `/${segments.slice(0, depth).join('/')}`;
+}
+
+/**
+ * Gateway routes derived from the registry: the Management API, its
+ * discovery and docs routes, the core extensions' admin routes and, for
+ * hosts that deliver queue messages over HTTP, the queue endpoint. Each
+ * Management API resource root gets an exact route when the root itself is
+ * registered and a greedy `{proxy+}` route when deeper paths are. The auth
+ * function uses `ANY` (as it always has, so CORS preflights reach Express);
+ * the health function only serves GET.
+ *
+ * devtools turns these into API Gateway HTTP API events; provider-netlify
+ * into netlify.toml redirects.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.v1=true]
+ * @param {boolean} [options.proxy=false]
+ * @param {Array<Object>} [options.coreExtensions=[]] - appDefinition.coreExtensions
+ * @param {boolean} [options.httpQueue=false] - include the HTTP queue route
+ * @returns {Array<{function: string, method: string, path: string}>}
+ */
+function getGatewayRoutes({ v1 = true, proxy = false, coreExtensions = [], httpQueue = false } = {}) {
+    const out = [];
+    const seen = new Set();
+    const add = (fn, method, path) => {
+        const key = `${fn} ${method} ${path}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        out.push({ function: fn, method, path });
+    };
+
+    const grouped = [
+        ...(v1 ? V1_ROUTES : []),
+        ...listV2Routes({ proxy }),
+        ...META_ROUTES,
+    ];
+    const greedyRoots = new Set();
+    for (const record of grouped) {
+        const root = resourceRoot(record);
+        const method = record.function === FUNCTIONS.AUTH ? 'ANY' : 'GET';
+        if (record.path === root) {
+            add(record.function, method, root);
+        } else {
+            add(record.function, method, `${root}/{proxy+}`);
+            greedyRoots.add(`${record.function} ${root}`);
+        }
+    }
+
+    // Extra routes get an exact route unless a greedy route on the same
+    // function already covers them.
+    for (const record of [...AUTH_EXTRA_ROUTES, ...DOCS_ROUTES]) {
+        const covered = greedyRoots.has(
+            `${record.function} ${resourceRoot(record)}`
+        );
+        if (!covered) {
+            add(record.function, record.method, toGatewayPath(record.path));
+        }
+    }
+
+    for (const record of listCoreExtensionRoutes(coreExtensions)) {
+        add(record.function, record.method, record.path);
+    }
+
+    if (httpQueue) {
+        for (const record of HTTP_QUEUE_ROUTES) {
+            add(record.function, record.method, record.path);
+        }
+    }
+
+    return out;
+}
+
+module.exports = {
+    MANAGEMENT_API_VERSIONS,
+    PREFERRED_API_VERSION,
+    RESERVED_V2_SEGMENTS,
+    V1_MIGRATION_DOCS_URL,
+    FUNCTIONS,
+    V1_ROUTES,
+    V2_ROUTES,
+    META_ROUTES,
+    AUTH_EXTRA_ROUTES,
+    DOCS_ROUTES,
+    HTTP_QUEUE_ROUTES,
+    ADMIN_ROUTE_PREFIX,
+    RESERVED_ADMIN_SEGMENTS,
+    coreExtensionRoutePathError,
+    listCoreExtensionRoutes,
+    listRoutes,
+    listV2Routes,
+    getGatewayRoutes,
+    toGatewayPath,
+};