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

package/management-api/test-support/http-client.js

@@ -0,0 +1,39 @@
+/**
+ * Test helper: send one real HTTP request to an Express app on an ephemeral
+ * port and return { status, headers, body }. Real HTTP (not a mocked req/res)
+ * so body parsing, the error boundary and headers behave as in Lambda.
+ */
+async function request(app, { method = 'GET', path, headers = {}, body, rawBody } = {}) {
+    const server = await new Promise((resolve) => {
+        const s = app.listen(0, '127.0.0.1', () => resolve(s));
+    });
+    try {
+        const init = { method, headers: { ...headers } };
+        if (rawBody !== undefined) {
+            init.body = rawBody;
+        } else if (body !== undefined) {
+            init.body = JSON.stringify(body);
+            init.headers['content-type'] = 'application/json';
+        }
+        const res = await fetch(
+            `http://127.0.0.1:${server.address().port}${path}`,
+            init
+        );
+        const text = await res.text();
+        let parsed = text;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        } catch {
+            // not JSON; keep the text
+        }
+        return {
+            status: res.status,
+            headers: Object.fromEntries(res.headers.entries()),
+            body: parsed,
+        };
+    } finally {
+        await new Promise((resolve) => server.close(resolve));
+    }
+}
+
+module.exports = { request };

package/management-api/use-cases/get-management-api-meta.js

@@ -0,0 +1,57 @@
+const {
+    MANAGEMENT_API_VERSIONS,
+    PREFERRED_API_VERSION,
+    listV2Routes,
+} = require('../route-registry');
+
+/**
+ * Builds the GET /api/meta document (ADR-053 §4): the API majors this
+ * deployment serves, their status and OpenAPI links, and the capability flags
+ * clients feature-detect with. Reads configuration only: no database, no
+ * network.
+ */
+class GetManagementApiMeta {
+    /**
+     * @param {Object} params
+     * @param {ReturnType<import('../management-api-config').resolveManagementApiConfig>} params.config
+     * @param {string} params.coreVersion - @friggframework/core version, admin-only.
+     */
+    constructor({ config, coreVersion }) {
+        this.config = config;
+        this.coreVersion = coreVersion;
+    }
+
+    /**
+     * @param {Object} [options]
+     * @param {boolean} [options.isAdmin=false] - caller presented the admin key.
+     */
+    execute({ isAdmin = false } = {}) {
+        const versions = {};
+        for (const [major, info] of Object.entries(MANAGEMENT_API_VERSIONS)) {
+            const disabled = major === '1' && !this.config.v1;
+            versions[major] = {
+                ...info,
+                ...(disabled && { status: 'disabled' }),
+                openapi: `/api/meta/openapi/v${major}.json`,
+            };
+        }
+
+        // Capabilities come from the routes the app actually serves, so a flag
+        // can never advertise a route that is not mounted.
+        const capabilities = [
+            ...new Set(
+                listV2Routes({ proxy: this.config.proxy.enable })
+                    .map((r) => r.capability)
+                    .filter(Boolean)
+            ),
+        ].sort();
+
+        return {
+            api: { versions, preferred: PREFERRED_API_VERSION },
+            capabilities,
+            ...(isAdmin && { frigg: { coreVersion: this.coreVersion } }),
+        };
+    }
+}
+
+module.exports = { GetManagementApiMeta };

package/management-api/v1-deprecation.js

@@ -0,0 +1,120 @@
+const { Router } = require('express');
+const Boom = require('@hapi/boom');
+const { getLogger } = require('../logs');
+const { getTelemetry } = require('../telemetry/telemetry-runtime');
+const {
+    MANAGEMENT_API_VERSIONS,
+    V1_MIGRATION_DOCS_URL,
+    V1_ROUTES,
+} = require('./route-registry');
+
+const log = getLogger('frigg.api');
+
+const V1_LINK_HEADER = `<${V1_MIGRATION_DOCS_URL}>; rel="deprecation"; type="text/html"`;
+
+/**
+ * RFC 9745 `Deprecation` value: an RFC 9651 structured-field date, i.e. `@`
+ * followed by seconds since the epoch.
+ * @param {string} isoDate - YYYY-MM-DD
+ */
+function deprecationHeaderValue(isoDate) {
+    return `@${Math.floor(Date.parse(`${isoDate}T00:00:00Z`) / 1000)}`;
+}
+
+const registerOn = (router, { method, path }, handler) => {
+    const verb = method === 'ANY' ? 'all' : method.toLowerCase();
+    router[verb](path, handler);
+};
+
+function setDeprecationHeaders(res) {
+    const { deprecatedAt, sunset } = MANAGEMENT_API_VERSIONS['1'];
+    res.set('Deprecation', deprecationHeaderValue(deprecatedAt));
+    if (sunset) {
+        // RFC 8594: an HTTP-date.
+        res.set('Sunset', new Date(`${sunset}T00:00:00Z`).toUTCString());
+    }
+    res.append('Link', V1_LINK_HEADER);
+}
+
+/**
+ * Marks every v1 response as deprecated and records the call (ADR-053 §6):
+ * `Deprecation` + `Link: rel="deprecation"` headers, one ADR-048 log record
+ * and one ADR-011 counter increment per call. Mounted ahead of the frozen v1
+ * router; it calls `next()` so the v1 handler answers unchanged.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.telemetry] - defaults to the process telemetry.
+ */
+function createV1DeprecationRouter({ telemetry } = {}) {
+    const router = Router();
+
+    for (const route of V1_ROUTES) {
+        registerOn(router, route, (req, res, next) => {
+            // One signal per request, even if two v1 patterns match it.
+            if (res.locals.friggV1Deprecated) return next();
+            res.locals.friggV1Deprecated = true;
+            setDeprecationHeaders(res);
+            const method = req.method;
+            log.info('Deprecated Management API v1 route called', {
+                eventName: 'frigg.api.deprecated_route',
+                route: route.path,
+                method,
+                client: req.get('Frigg-Client'),
+            });
+            try {
+                (telemetry || getTelemetry()).count('frigg.api.v1.requests', 1, {
+                    route: route.path,
+                    method,
+                });
+            } catch {
+                // Telemetry must never break a request.
+            }
+            next();
+        });
+    }
+
+    return router;
+}
+
+/**
+ * Answers the v1 routes with 410 Gone when the app sets
+ * `managementApi.v1: false`. Only the registry's v1 routes are claimed, so
+ * the OAuth redirect and adopter routes keep working.
+ */
+function createV1DisabledRouter() {
+    const router = Router();
+    for (const route of V1_ROUTES) {
+        registerOn(router, route, (_req, res, next) => {
+            res.append('Link', V1_LINK_HEADER);
+            next(
+                Boom.resourceGone(
+                    'Management API v1 is disabled for this app. Use /api/v2; see the migration guide.',
+                    {
+                        code: 'API_VERSION_DISABLED',
+                        details: { migrationGuide: V1_MIGRATION_DOCS_URL },
+                    }
+                )
+            );
+        });
+    }
+    // A disabled v1 answers in the v2 error shape: there is no v1 contract
+    // left to honour, and the body should point at the replacement.
+    router.use((err, req, res, next) => {
+        if (err?.data?.code !== 'API_VERSION_DISABLED') return next(err);
+        res.status(410).json({
+            error: {
+                code: 'API_VERSION_DISABLED',
+                message: err.message,
+                details: err.data.details,
+            },
+        });
+    });
+    return router;
+}
+
+module.exports = {
+    createV1DeprecationRouter,
+    createV1DisabledRouter,
+    deprecationHeaderValue,
+    V1_LINK_HEADER,
+};

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

@@ -0,0 +1,85 @@
+const express = require('express');
+const Boom = require('@hapi/boom');
+const catchAsyncError = require('express-async-handler');
+const { API_VERSION_HEADER } = require('../error-response');
+const { listV2Routes } = require('../route-registry');
+const { resolveManagementApiConfig } = require('../management-api-config');
+const { createIntegrationHandlers } = require('./handlers/integrations');
+const { createEntityHandlers } = require('./handlers/entities');
+const { createCredentialHandlers } = require('./handlers/credentials');
+const { createAuthorizationHandlers } = require('./handlers/authorization');
+const { createProxyHandlers } = require('./handlers/proxy');
+
+/** Every v2 handler, keyed by the registry's operationId. */
+function createV2Handlers(dependencies) {
+    return {
+        ...createIntegrationHandlers(dependencies),
+        ...createEntityHandlers(dependencies),
+        ...createCredentialHandlers(dependencies),
+        ...createAuthorizationHandlers(dependencies),
+        ...(dependencies.executeEntityProxyRequest
+            ? createProxyHandlers(dependencies)
+            : {}),
+    };
+}
+
+/**
+ * Management API v2 router (ADR-053). Routes come from the registry, in
+ * registry order; each authenticates the caller with the same
+ * AuthenticateUser as v1 (bearer token, x-frigg headers, adopter JWT) and then
+ * runs the handler for its operationId. Every response under /api/v2 carries
+ * `Frigg-API-Version: 2`; an unknown /api/v2 path is a v2 404.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.appDefinition]
+ * @param {Object} [params.config] - resolveManagementApiConfig() output.
+ * @param {Object} [params.dependencies] - use cases and authenticateUser;
+ *   built from the app definition when omitted.
+ */
+function createManagementApiV2Router({
+    appDefinition = {},
+    config,
+    dependencies,
+} = {}) {
+    const resolvedConfig =
+        config || resolveManagementApiConfig(appDefinition.managementApi);
+    const deps =
+        dependencies ||
+        require('./dependencies').buildV2Dependencies({
+            appDefinition,
+            config: resolvedConfig,
+        });
+    const handlers = createV2Handlers(deps);
+
+    const router = express.Router();
+
+    router.use('/api/v2', (_req, res, next) => {
+        res.set(API_VERSION_HEADER, '2');
+        next();
+    });
+
+    for (const route of listV2Routes({ proxy: resolvedConfig.proxy.enable })) {
+        const handler = handlers[route.operationId];
+        if (!handler) continue;
+        router[route.method.toLowerCase()](
+            route.path,
+            catchAsyncError(async (req, res) => {
+                const user = await deps.authenticateUser.execute(req);
+                if (!user) throw Boom.unauthorized('Authentication required');
+                await handler(req, res, user);
+            })
+        );
+    }
+
+    router.use('/api/v2', (req, _res, next) => {
+        next(
+            Boom.notFound(
+                `No Management API v2 route for ${req.method} ${req.baseUrl}${req.path}`
+            )
+        );
+    });
+
+    return router;
+}
+
+module.exports = { createManagementApiV2Router, createV2Handlers };

package/management-api/v2/dependencies.js

@@ -0,0 +1,281 @@
+/**
+ * Wires the repositories and use cases behind Management API v2. Kept apart
+ * from the router so tests can hand the router doubles instead.
+ */
+/**
+ * @param {Object} params
+ * @param {Object} params.appDefinition - the loaded app definition. Its
+ *   `entityTypeRegistry` (built once by loadAppDefinition) is used.
+ * @param {Object} params.config
+ * @param {Map} [params.entityTypeRegistry] - overrides the registry on the
+ *   app definition. When neither exists (a raw definition in a test), it is
+ *   built here from the definition.
+ */
+function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
+    const {
+        createIntegrationRepository,
+    } = require('../../integrations/repositories/integration-repository-factory');
+    const {
+        createCredentialRepository,
+    } = require('../../credential/repositories/credential-repository-factory');
+    const {
+        createModuleRepository,
+    } = require('../../modules/repositories/module-repository-factory');
+    const {
+        createUserRepository,
+    } = require('../../user/repositories/user-repository-factory');
+    const { ModuleFactory } = require('../../modules/module-factory');
+    const {
+        getEntityTypeRegistry,
+        getEntityTypeDefinitions,
+    } = require('../../modules/entity-type-registry');
+    const { createScopePolicy } = require('../../modules/scope-policy');
+    const {
+        AuthorizeEntityForUser,
+    } = require('../../modules/use-cases/authorize-entity-for-user');
+    const {
+        ResolveIntegrationOwnership,
+    } = require('../../integrations/use-cases/resolve-integration-ownership');
+    const {
+        AuthenticateWithSharedSecret,
+    } = require('../../user/use-cases/authenticate-with-shared-secret');
+    const { AuthenticateUser } = require('../../user/use-cases/authenticate-user');
+    const { buildUserAuthentication } = require('../../user/create-user-authentication');
+    const { CreateIntegration } = require('../../integrations/use-cases/create-integration');
+    const { UpdateIntegration } = require('../../integrations/use-cases/update-integration');
+    const {
+        DeleteIntegrationForUser,
+    } = require('../../integrations/use-cases/delete-integration-for-user');
+    const {
+        GetIntegrationsForUser,
+    } = require('../../integrations/use-cases/get-integrations-for-user');
+    const {
+        GetIntegrationInstance,
+    } = require('../../integrations/use-cases/get-integration-instance');
+    const {
+        GetPossibleIntegrations,
+    } = require('../../integrations/use-cases/get-possible-integrations');
+    const integrationOps = require('../../integrations/use-cases/integration-operations-for-user');
+    const {
+        GetEntityModuleForUser,
+    } = require('../../modules/use-cases/get-entity-module-for-user');
+    const entityOps = require('../../modules/use-cases/entity-operations-for-user');
+    const { ListEntityTypes, GetEntityType } = require('../../modules/use-cases/entity-types');
+    const credentialOps = require('../../credential/use-cases/credential-operations-for-user');
+    const {
+        GetCredentialReauthorization,
+        ReauthorizeCredentialForUser,
+    } = require('../../credential/use-cases/reauthorize-credential-for-user');
+    const {
+        GetAuthorizationStep,
+        SubmitAuthorizationStep,
+    } = require('../../modules/use-cases/multi-step-authorization');
+    const {
+        ProcessAuthorizationCallback,
+    } = require('../../modules/use-cases/process-authorization-callback');
+    const {
+        ExecuteEntityProxyRequest,
+    } = require('../../modules/use-cases/execute-entity-proxy-request');
+    const {
+        createAuthorizationSessionRepository,
+    } = require('../../modules/repositories/authorization-session-repository-factory');
+    const {
+        GetAuthorizationRequirements,
+    } = require('../../modules/use-cases/get-authorization-requirements');
+
+    const integrationClasses = appDefinition.integrations || [];
+    const userConfig = appDefinition.userConfig || {};
+    // The registry holds entity types registered on the app as well as those
+    // integrations bind (ADR-059), so v2 authorize/entities accept both.
+    const registry =
+        entityTypeRegistry ??
+        appDefinition.entityTypeRegistry ??
+        getEntityTypeRegistry(appDefinition);
+    const moduleDefinitions = getEntityTypeDefinitions(registry);
+    // Ownership by scope (ADR-056 §3): one object every use case asks.
+    const scopePolicy = createScopePolicy({
+        ownership: appDefinition.ownership,
+        entityTypeRegistry: registry,
+    });
+
+    const moduleRepository = createModuleRepository();
+    const integrationRepository = createIntegrationRepository();
+    const credentialRepository = createCredentialRepository();
+    const userRepository = createUserRepository();
+    const authorizationSessionRepository = createAuthorizationSessionRepository();
+
+    const authenticateUser = new AuthenticateUser({
+        ...buildUserAuthentication({ userConfig, userRepository }),
+        authenticateWithSharedSecret: new AuthenticateWithSharedSecret(),
+        userConfig,
+    });
+
+    const moduleFactory = new ModuleFactory({ moduleRepository, moduleDefinitions });
+    const getIntegrationInstance = new GetIntegrationInstance({
+        integrationRepository,
+        integrationClasses,
+        moduleFactory,
+    });
+    const getEntityModuleForUser = new GetEntityModuleForUser({
+        moduleRepository,
+        moduleDefinitions,
+        scopePolicy,
+    });
+    const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
+        credentialRepository,
+        moduleRepository,
+        scopePolicy,
+    });
+    const getAuthorizationRequirements = new GetAuthorizationRequirements({
+        moduleDefinitions,
+    });
+    const getAuthorizationStep = new GetAuthorizationStep({
+        moduleDefinitions,
+        getAuthorizationRequirements,
+        authorizationSessionRepository,
+    });
+    const submitAuthorizationStep = new SubmitAuthorizationStep({
+        moduleDefinitions,
+        getAuthorizationRequirements,
+        authorizationSessionRepository,
+        authorizeEntityForUser: new AuthorizeEntityForUser({
+            scopePolicy,
+            processAuthorizationCallback: new ProcessAuthorizationCallback({
+                moduleRepository,
+                credentialRepository,
+                integrationRepository,
+                moduleDefinitions,
+            }),
+        }),
+        moduleRepository,
+        credentialRepository,
+        scopePolicy,
+    });
+    const getOwnedIntegrationRecord = new integrationOps.GetOwnedIntegrationRecord({
+        integrationRepository,
+        scopePolicy,
+    });
+    const getIntegrationInstanceForUser = new integrationOps.GetIntegrationInstanceForUser({
+        getOwnedIntegrationRecord,
+        getIntegrationInstance,
+    });
+
+    return {
+        config,
+        moduleDefinitions,
+        scopePolicy,
+        repositories: {
+            moduleRepository,
+            integrationRepository,
+            credentialRepository,
+            userRepository,
+            authorizationSessionRepository,
+        },
+        authenticateUser,
+
+        // Integrations
+        getIntegrationsForUser: new GetIntegrationsForUser({
+            integrationRepository,
+            integrationClasses,
+            moduleFactory,
+            moduleRepository,
+            scopePolicy,
+        }),
+        getPossibleIntegrations: new GetPossibleIntegrations({ integrationClasses }),
+        createIntegrationForUser: new integrationOps.CreateIntegrationForUser({
+            createIntegration: new CreateIntegration({
+                integrationRepository,
+                integrationClasses,
+                moduleFactory,
+            }),
+            resolveIntegrationOwnership: new ResolveIntegrationOwnership({
+                moduleRepository,
+                integrationClasses,
+                scopePolicy,
+            }),
+            integrationClasses,
+        }),
+        getIntegrationInstanceForUser,
+        updateIntegrationForUser: new integrationOps.UpdateIntegrationForUser({
+            getOwnedIntegrationRecord,
+            updateIntegration: new UpdateIntegration({
+                integrationRepository,
+                integrationClasses,
+                moduleFactory,
+            }),
+        }),
+        removeIntegrationForUser: new integrationOps.RemoveIntegrationForUser({
+            getOwnedIntegrationRecord,
+            deleteIntegrationForUser: new DeleteIntegrationForUser({
+                integrationRepository,
+                integrationClasses,
+                moduleFactory,
+            }),
+        }),
+        sendIntegrationEventForUser: new integrationOps.SendIntegrationEventForUser({
+            getIntegrationInstanceForUser,
+        }),
+        runIntegrationActionForUser: new integrationOps.RunIntegrationActionForUser({
+            getIntegrationInstanceForUser,
+        }),
+        testIntegrationAuthForUser: new integrationOps.TestIntegrationAuthForUser({
+            getIntegrationInstanceForUser,
+        }),
+
+        // Entities
+        getEntityModuleForUser,
+        listEntitiesForUser: new entityOps.ListEntitiesForUser({
+            moduleRepository,
+            scopePolicy,
+        }),
+        getEntityForUser: new entityOps.GetEntityForUser({ getEntityModuleForUser }),
+        deleteEntityForUser: new entityOps.DeleteEntityForUser({
+            getEntityModuleForUser,
+            moduleRepository,
+            integrationRepository,
+        }),
+        testEntityAuthForUser: new entityOps.TestEntityAuthForUser({ getEntityModuleForUser }),
+        getEntityOptionsForUser: new entityOps.GetEntityOptionsForUser({ getEntityModuleForUser }),
+        refreshEntityOptionsForUser: new entityOps.RefreshEntityOptionsForUser({
+            getEntityModuleForUser,
+        }),
+        listEntityTypes: new ListEntityTypes({ entityTypeRegistry: registry, scopePolicy }),
+        getEntityType: new GetEntityType({ entityTypeRegistry: registry, scopePolicy }),
+        getAuthorizationRequirements,
+
+        // Credentials
+        listCredentialsForUser: new credentialOps.ListCredentialsForUser({
+            credentialRepository,
+            moduleRepository,
+            scopePolicy,
+        }),
+        getCredentialForUser,
+        deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({
+            credentialRepository,
+            moduleRepository,
+            getCredentialForUser,
+        }),
+        getCredentialReauthorization: new GetCredentialReauthorization({
+            getCredentialForUser,
+            getAuthorizationStep,
+        }),
+        reauthorizeCredentialForUser: new ReauthorizeCredentialForUser({
+            getCredentialForUser,
+            submitAuthorizationStep,
+        }),
+
+        // Authorization (multi-step)
+        getAuthorizationStep,
+        submitAuthorizationStep,
+
+        // Entity proxy (ADR-052): only built when the app enables it.
+        ...(config.proxy.enable && {
+            executeEntityProxyRequest: new ExecuteEntityProxyRequest({
+                getEntityModuleForUser,
+                proxyConfig: config.proxy,
+            }),
+        }),
+    };
+}
+
+module.exports = { buildV2Dependencies };