@friggframework/core 2.0.0--canary.680.6bacd26.0 → 2.0.0--canary.663.8de669c.0

package/management-api/v1-deprecation.js

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

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

@@ -1,256 +0,0 @@
-/**
- * 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 { GetUserFromBearerToken } = require('../../user/use-cases/get-user-from-bearer-token');
-    const { GetUserFromXFriggHeaders } = require('../../user/use-cases/get-user-from-x-frigg-headers');
-    const { GetUserFromAdopterJwt } = require('../../user/use-cases/get-user-from-adopter-jwt');
-    const {
-        AuthenticateWithSharedSecret,
-    } = require('../../user/use-cases/authenticate-with-shared-secret');
-    const { AuthenticateUser } = require('../../user/use-cases/authenticate-user');
-    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);
-
-    const moduleRepository = createModuleRepository();
-    const integrationRepository = createIntegrationRepository();
-    const credentialRepository = createCredentialRepository();
-    const userRepository = createUserRepository();
-    const authorizationSessionRepository = createAuthorizationSessionRepository();
-
-    const authenticateUser = new AuthenticateUser({
-        getUserFromBearerToken: new GetUserFromBearerToken({ userRepository, userConfig }),
-        getUserFromXFriggHeaders: new GetUserFromXFriggHeaders({ userRepository, userConfig }),
-        getUserFromAdopterJwt: new GetUserFromAdopterJwt({ userRepository, userConfig }),
-        authenticateWithSharedSecret: new AuthenticateWithSharedSecret(),
-        userConfig,
-    });
-
-    const moduleFactory = new ModuleFactory({ moduleRepository, moduleDefinitions });
-    const getIntegrationInstance = new GetIntegrationInstance({
-        integrationRepository,
-        integrationClasses,
-        moduleFactory,
-    });
-    const getEntityModuleForUser = new GetEntityModuleForUser({
-        moduleRepository,
-        moduleDefinitions,
-    });
-    const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
-        credentialRepository,
-        moduleRepository,
-    });
-    const getAuthorizationRequirements = new GetAuthorizationRequirements({
-        moduleDefinitions,
-    });
-    const getAuthorizationStep = new GetAuthorizationStep({
-        moduleDefinitions,
-        getAuthorizationRequirements,
-        authorizationSessionRepository,
-    });
-    const submitAuthorizationStep = new SubmitAuthorizationStep({
-        moduleDefinitions,
-        getAuthorizationRequirements,
-        authorizationSessionRepository,
-        processAuthorizationCallback: new ProcessAuthorizationCallback({
-            moduleRepository,
-            credentialRepository,
-            integrationRepository,
-            moduleDefinitions,
-        }),
-        moduleRepository,
-        credentialRepository,
-    });
-    const getOwnedIntegrationRecord = new integrationOps.GetOwnedIntegrationRecord({
-        integrationRepository,
-    });
-    const getIntegrationInstanceForUser = new integrationOps.GetIntegrationInstanceForUser({
-        getOwnedIntegrationRecord,
-        getIntegrationInstance,
-    });
-
-    return {
-        config,
-        moduleDefinitions,
-        repositories: {
-            moduleRepository,
-            integrationRepository,
-            credentialRepository,
-            userRepository,
-            authorizationSessionRepository,
-        },
-        authenticateUser,
-
-        // Integrations
-        getIntegrationsForUser: new GetIntegrationsForUser({
-            integrationRepository,
-            integrationClasses,
-            moduleFactory,
-            moduleRepository,
-        }),
-        getPossibleIntegrations: new GetPossibleIntegrations({ integrationClasses }),
-        createIntegrationForUser: new integrationOps.CreateIntegrationForUser({
-            createIntegration: new CreateIntegration({
-                integrationRepository,
-                integrationClasses,
-                moduleFactory,
-            }),
-            getEntityModuleForUser,
-            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 }),
-        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 }),
-        getEntityType: new GetEntityType({ entityTypeRegistry: registry }),
-        getAuthorizationRequirements,
-
-        // Credentials
-        listCredentialsForUser: new credentialOps.ListCredentialsForUser({
-            credentialRepository,
-            moduleRepository,
-        }),
-        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 };

package/management-api/v2/dto.js

@@ -1,123 +0,0 @@
-/**
- * Response shapes for Management API v2. Use cases return domain records;
- * these functions decide what leaves the server. Credential material never
- * does (see maskCredential).
- */
-
-const idOf = (value) => {
-    if (value === undefined || value === null) return null;
-    if (typeof value === 'object') {
-        const id = value.id ?? value._id;
-        return id === undefined || id === null ? null : String(id);
-    }
-    return String(value);
-};
-
-/** An entity (connected account). */
-function toEntityDto(entity) {
-    const credential =
-        entity.credential && typeof entity.credential === 'object'
-            ? entity.credential
-            : null;
-    return {
-        id: String(entity.id),
-        type: entity.moduleName ?? null,
-        name: entity.name ?? null,
-        externalId: entity.externalId ?? null,
-        credentialId: idOf(entity.credential ?? entity.credentialId),
-        userId: idOf(entity.userId ?? entity.user),
-        authIsValid:
-            typeof credential?.authIsValid === 'boolean'
-                ? credential.authIsValid
-                : null,
-    };
-}
-
-/** An integration, from a hydrated instance or a stored DTO. */
-function toIntegrationDto(integration) {
-    return {
-        id: String(integration.id),
-        entities: integration.entities ?? [],
-        status: integration.status ?? null,
-        config: integration.config ?? {},
-        version: integration.version ?? null,
-        messages: integration.messages ?? {},
-    };
-}
-
-// Fields every repository adds around the stored data; everything else on a
-// credential record came from the provider and is treated as secret.
-const CREDENTIAL_METADATA = new Set([
-    'id',
-    '_id',
-    'userId',
-    'user',
-    'externalId',
-    'authIsValid',
-    'createdAt',
-    'updatedAt',
-    'type',
-    'entityIds',
-    'status',
-]);
-
-/**
- * Masks one stored credential value. Strings keep at most their last four
- * characters, and only when long enough that four characters reveal nothing
- * useful; objects and arrays are hidden whole. Numbers, booleans and null
- * (expiry times, flags) are not secret and pass through.
- */
-function maskValue(value) {
-    if (value === null || typeof value === 'number' || typeof value === 'boolean') {
-        return value;
-    }
-    if (typeof value === 'string') {
-        return value.length >= 16 ? `****${value.slice(-4)}` : '****';
-    }
-    return '****';
-}
-
-const toIso = (value) => {
-    if (!value) return null;
-    const date = value instanceof Date ? value : new Date(value);
-    return Number.isNaN(date.getTime()) ? null : date.toISOString();
-};
-
-/**
- * A credential with every provider field masked. The keys stay visible so a
- * client can tell an OAuth credential from an API-key one; the values never
- * leave the server.
- */
-function maskCredential(credential) {
-    const data = {};
-    for (const [key, value] of Object.entries(credential)) {
-        if (CREDENTIAL_METADATA.has(key) || value === undefined) continue;
-        data[key] = maskValue(value);
-    }
-    const entityIds = Array.isArray(credential.entityIds)
-        ? credential.entityIds.map(String)
-        : [];
-    return {
-        id: String(credential.id),
-        type: credential.type ?? null,
-        externalId: credential.externalId ?? null,
-        userId: idOf(credential.userId),
-        authIsValid:
-            typeof credential.authIsValid === 'boolean'
-                ? credential.authIsValid
-                : null,
-        entityIds,
-        entityCount: entityIds.length,
-        createdAt: toIso(credential.createdAt),
-        updatedAt: toIso(credential.updatedAt),
-        data,
-    };
-}
-
-module.exports = {
-    toEntityDto,
-    toIntegrationDto,
-    maskCredential,
-    maskValue,
-    idOf,
-};

package/management-api/v2/handlers/authorization.js

@@ -1,93 +0,0 @@
-const { toEntityDto, maskCredential } = require('../dto');
-const { objectBody, requireFields, parseStep, optionalString } = require('../request');
-
-/** The v2 body for a submitted step: masked records when complete. */
-function toAuthorizationResponse(result) {
-    if (result.status !== 'complete') return result;
-    return {
-        status: 'complete',
-        entity: result.entity ? toEntityDto(result.entity) : null,
-        credential: result.credential ? maskCredential(result.credential) : null,
-        ...(result.previousCredentialId && {
-            previousCredentialId: result.previousCredentialId,
-        }),
-    };
-}
-
-/**
- * Management API v2 authorization handlers (multi-step authorize and
- * credential re-authorization), keyed by operationId.
- */
-function createAuthorizationHandlers(useCases) {
-    const {
-        getAuthorizationStep,
-        submitAuthorizationStep,
-        getCredentialReauthorization,
-        reauthorizeCredentialForUser,
-    } = useCases;
-
-    const stepQuery = (req) => ({
-        step: parseStep(req.query.step),
-        sessionId: optionalString(req.query.sessionId, 'sessionId'),
-        state: optionalString(req.query.state, 'state'),
-    });
-
-    const stepBody = (req) => {
-        const body = objectBody(req);
-        return {
-            body,
-            step: parseStep(body.step),
-            sessionId: optionalString(body.sessionId, 'sessionId'),
-        };
-    };
-
-    return {
-        async getAuthorizationRequirements(req, res, user) {
-            const entityType = optionalString(req.query.entityType, 'entityType');
-            requireFields({ entityType }, ['entityType']);
-            res.json(
-                await getAuthorizationStep.execute({
-                    user,
-                    entityType,
-                    ...stepQuery(req),
-                })
-            );
-        },
-
-        async authorize(req, res, user) {
-            const { body, step, sessionId } = stepBody(req);
-            requireFields(body, ['entityType', 'data']);
-            const result = await submitAuthorizationStep.execute({
-                user,
-                entityType: optionalString(body.entityType, 'entityType'),
-                data: body.data,
-                step,
-                sessionId,
-            });
-            res.json(toAuthorizationResponse(result));
-        },
-
-        async getCredentialReauthorizeRequirements(req, res, user) {
-            res.json(
-                await getCredentialReauthorization.execute(
-                    req.params.credentialId,
-                    user,
-                    stepQuery(req)
-                )
-            );
-        },
-
-        async reauthorizeCredential(req, res, user) {
-            const { body, step, sessionId } = stepBody(req);
-            requireFields(body, ['data']);
-            const result = await reauthorizeCredentialForUser.execute(
-                req.params.credentialId,
-                user,
-                { data: body.data, step, sessionId }
-            );
-            res.json(toAuthorizationResponse(result));
-        },
-    };
-}
-
-module.exports = { createAuthorizationHandlers, toAuthorizationResponse };