@friggframework/core 2.0.0--canary.686.3e27a92.0 → 2.0.0--canary.663.8de669c.0

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

@@ -1,177 +0,0 @@
-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/management-api/create-management-api-router.js

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

@@ -1,116 +0,0 @@
-const Boom = require('@hapi/boom');
-
-/**
- * Error responses for the HTTP boundary (handlers/app-handler-helpers.js).
- *
- * - v1 and other unversioned routes keep their historical body:
- *   `{ error: message }` for 4xx, `{ error: 'Internal Server Error' }` for 5xx.
- * - Management API v2 and /api/meta answer `{ error: { code, message, details? } }`
- *   and carry `Frigg-API-Version: 2` even when the error happened before any
- *   v2 router ran (for example a body-parser failure).
- */
-
-const API_VERSION_HEADER = 'Frigg-API-Version';
-
-const CODE_BY_STATUS = {
-    400: 'BAD_REQUEST',
-    401: 'UNAUTHORIZED',
-    403: 'FORBIDDEN',
-    404: 'NOT_FOUND',
-    405: 'METHOD_NOT_ALLOWED',
-    409: 'CONFLICT',
-    410: 'GONE',
-    413: 'PAYLOAD_TOO_LARGE',
-    415: 'UNSUPPORTED_MEDIA_TYPE',
-    422: 'UNPROCESSABLE_ENTITY',
-    429: 'RATE_LIMITED',
-    500: 'INTERNAL_ERROR',
-    501: 'NOT_IMPLEMENTED',
-    502: 'BAD_GATEWAY',
-    503: 'SERVICE_UNAVAILABLE',
-    504: 'GATEWAY_TIMEOUT',
-};
-
-// body-parser (via http-errors) tags its failures with `type`.
-const CODE_BY_BODY_PARSER_TYPE = {
-    'entity.parse.failed': 'INVALID_JSON',
-    'entity.too.large': 'PAYLOAD_TOO_LARGE',
-    'encoding.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
-    'charset.unsupported': 'UNSUPPORTED_MEDIA_TYPE',
-    'request.aborted': 'BAD_REQUEST',
-};
-
-/** True for paths that use the v2 error contract. */
-function isVersionedManagementApiPath(path = '') {
-    return (
-        path === '/api/v2' ||
-        path.startsWith('/api/v2/') ||
-        path === '/api/meta' ||
-        path.startsWith('/api/meta/')
-    );
-}
-
-/**
- * The HTTP status for an error. Boom errors carry theirs. Other errors are
- * trusted only when they declare a client error as safe to expose, as
- * http-errors (and so body-parser) does; anything else is a 500, so an
- * upstream FetchError's `statusCode` is never mistaken for ours.
- */
-function resolveStatusCode(err) {
-    if (err?.isBoom) return err.output.statusCode;
-    const status = err?.status ?? err?.statusCode;
-    if (
-        err?.expose === true &&
-        Number.isInteger(status) &&
-        status >= 400 &&
-        status < 500
-    ) {
-        return status;
-    }
-    return 500;
-}
-
-/** Normalises any thrown value into a Boom error with the right status. */
-function toBoom(err) {
-    if (err?.isBoom) return err;
-    const error = err instanceof Error ? err : new Error(String(err));
-    return Boom.boomify(error, { statusCode: resolveStatusCode(err) });
-}
-
-/** The v2 error body for a Boom error. */
-function toV2ErrorBody(boomError) {
-    const statusCode = boomError.output.statusCode;
-    const data =
-        boomError.data && typeof boomError.data === 'object'
-            ? boomError.data
-            : {};
-    const exposeServerError = statusCode >= 500 && data.expose === true;
-
-    const code =
-        (typeof data.code === 'string' && data.code) ||
-        CODE_BY_BODY_PARSER_TYPE[boomError.type] ||
-        CODE_BY_STATUS[statusCode] ||
-        (statusCode >= 500 ? 'INTERNAL_ERROR' : 'BAD_REQUEST');
-
-    const message =
-        statusCode < 500 || exposeServerError
-            ? boomError.message
-            : 'Internal Server Error';
-
-    const body = { code, message };
-    if (
-        data.details !== undefined &&
-        (statusCode < 500 || exposeServerError)
-    ) {
-        body.details = data.details;
-    }
-    return { error: body };
-}
-
-module.exports = {
-    API_VERSION_HEADER,
-    isVersionedManagementApiPath,
-    resolveStatusCode,
-    toBoom,
-    toV2ErrorBody,
-};

package/management-api/management-api-config.js

@@ -1,151 +0,0 @@
-/**
- * Resolves `appDefinition.managementApi` (ADR-052, ADR-053).
- *
- * ```js
- * managementApi: {
- *     v1: false,              // drop the deprecated v1 routes (default true)
- *     proxy: {
- *         enable: true,       // entity proxy, off by default (ADR-052)
- *         timeoutMs: 25000,   // whole upstream call, lower only
- *         maxRequestBytes: 1048576,
- *         maxResponseBytes: 5242880, // lower only
- *         scopes: ['individual'], // entity scopes the proxy accepts (ADR-056 §3.5)
- *         modules: {          // per-module allow-list override
- *             hubspot: { allow: 'module' },
- *             erp: { allow: [{ method: 'GET', path: '/v1/customers/**' }] },
- *         },
- *     },
- * }
- * ```
- *
- * Limits that are out of range fall back to their defaults. `proxy.scopes` is a
- * security setting, so it does not fall back: a value that is not a list of
- * known tenant scopes throws ManagementApiConfigError, and loadAppDefinition
- * calls this so the app stops at load.
- */
-
-const { BaseError } = require('../errors/base-error');
-const { SCOPES } = require('../modules/scope-resolution');
-
-/** Raised for an invalid `appDefinition.managementApi` setting. */
-class ManagementApiConfigError extends BaseError {
-    constructor(message, options) {
-        super(message, options);
-        this.code = 'MANAGEMENT_API_CONFIG_INVALID';
-    }
-}
-
-/**
- * The scopes `managementApi.proxy.scopes` may list. `global` is not one of
- * them: a global entity is the app owner's and is never a tenant's to proxy.
- */
-const PROXY_SCOPE_VALUES = Object.freeze([SCOPES.INDIVIDUAL, SCOPES.ORGANIZATION]);
-
-/**
- * Narrowest by default (ADR-056 §3.5): proxying through a shared credential
- * lets any member act on the organization's account, so an app opts in to
- * `organization` explicitly.
- */
-const DEFAULT_PROXY_SCOPES = Object.freeze([SCOPES.INDIVIDUAL]);
-
-// ADR-052 §7. API Gateway HTTP APIs time out at 30s and Lambda responses cap
-// at 6MB, so the timeout and response defaults are also ceilings: an app may
-// lower them, not raise them.
-const DEFAULT_PROXY_LIMITS = Object.freeze({
-    timeoutMs: 25_000,
-    maxRequestBytes: 1024 * 1024,
-    maxResponseBytes: 5 * 1024 * 1024,
-});
-
-// The request-body limit has no platform ceiling below API Gateway's 10MB, so
-// an app may raise it up to that.
-const MAX_REQUEST_BYTES_CEILING = 10 * 1024 * 1024;
-
-const isPositiveNumber = (value) =>
-    typeof value === 'number' && Number.isFinite(value) && value > 0;
-
-/** The value, capped at `ceiling`; the ceiling when the value is unusable. */
-function positiveCapped(value, ceiling) {
-    return isPositiveNumber(value) ? Math.min(value, ceiling) : ceiling;
-}
-
-/** The value, capped at `ceiling`; `fallback` when the value is unusable. */
-function positiveOr(value, fallback, ceiling) {
-    return isPositiveNumber(value) ? Math.min(value, ceiling) : fallback;
-}
-
-const proxyScopesError = (message) =>
-    new ManagementApiConfigError(`managementApi.proxy.scopes: ${message}`);
-
-/**
- * `managementApi.proxy.scopes`: absent means the default; anything else must be
- * a non-empty list of PROXY_SCOPE_VALUES, each once.
- * @returns {ReadonlyArray<string>}
- * @throws {ManagementApiConfigError}
- */
-function resolveProxyScopes(scopes) {
-    if (scopes === undefined) return DEFAULT_PROXY_SCOPES;
-    const allowed = PROXY_SCOPE_VALUES.join(', ');
-    if (!Array.isArray(scopes) || scopes.length === 0) {
-        throw proxyScopesError(`must be a non-empty list drawn from ${allowed}`);
-    }
-    for (const scope of scopes) {
-        if (scope === SCOPES.GLOBAL) {
-            throw proxyScopesError(
-                "'global' is not allowed: global entities belong to the app owner and are never proxied for a tenant"
-            );
-        }
-        if (!PROXY_SCOPE_VALUES.includes(scope)) {
-            throw proxyScopesError(`unknown scope ${JSON.stringify(scope)}; use ${allowed}`);
-        }
-    }
-    if (new Set(scopes).size !== scopes.length) {
-        throw proxyScopesError('lists a scope more than once');
-    }
-    return Object.freeze([...scopes]);
-}
-
-/**
- * @param {Object} [managementApi] - `appDefinition.managementApi`
- * @returns {{ v1: boolean, proxy: { enable: boolean, timeoutMs: number, maxRequestBytes: number, maxResponseBytes: number, scopes: ReadonlyArray<string>, modules: Object } }}
- * @throws {ManagementApiConfigError} for an invalid `proxy.scopes`
- */
-function resolveManagementApiConfig(managementApi) {
-    const config =
-        managementApi && typeof managementApi === 'object' ? managementApi : {};
-    const proxy =
-        config.proxy && typeof config.proxy === 'object' ? config.proxy : {};
-
-    return {
-        v1: config.v1 !== false,
-        proxy: {
-            enable: proxy.enable === true,
-            timeoutMs: positiveCapped(
-                proxy.timeoutMs,
-                DEFAULT_PROXY_LIMITS.timeoutMs
-            ),
-            maxRequestBytes: positiveOr(
-                proxy.maxRequestBytes,
-                DEFAULT_PROXY_LIMITS.maxRequestBytes,
-                MAX_REQUEST_BYTES_CEILING
-            ),
-            maxResponseBytes: positiveCapped(
-                proxy.maxResponseBytes,
-                DEFAULT_PROXY_LIMITS.maxResponseBytes
-            ),
-            scopes: resolveProxyScopes(proxy.scopes),
-            modules:
-                proxy.modules && typeof proxy.modules === 'object'
-                    ? proxy.modules
-                    : {},
-        },
-    };
-}
-
-module.exports = {
-    resolveManagementApiConfig,
-    DEFAULT_PROXY_LIMITS,
-    DEFAULT_PROXY_SCOPES,
-    PROXY_SCOPE_VALUES,
-    ManagementApiConfigError,
-};

package/management-api/meta-router.js

@@ -1,76 +0,0 @@
-const { Router } = require('express');
-const Boom = require('@hapi/boom');
-const { resolveManagementApiConfig } = require('./management-api-config');
-const {
-    GetManagementApiMeta,
-} = require('./use-cases/get-management-api-meta');
-const { isValidAdminApiKey } = require('../handlers/middleware/admin-auth');
-const { version: coreVersion } = require('../package.json');
-const {
-    MANAGEMENT_API_VERSIONS,
-    PREFERRED_API_VERSION,
-    DOCS_ROUTES,
-} = require('./route-registry');
-const { buildOpenApiDocument } = require('./openapi/build-openapi');
-
-/**
- * Version-neutral discovery routes (ADR-053 §4, §5), mounted on the DB-free
- * health Lambda. No authentication: the admin API key only adds the core
- * version to the response.
- *
- * @param {Object} params
- * @param {Object} params.appDefinition - the loaded app definition
- *   (`managementApi` is read).
- */
-function createManagementApiMetaRouter({ appDefinition = {} } = {}) {
-    const config = resolveManagementApiConfig(appDefinition.managementApi);
-    const getMeta = new GetManagementApiMeta({ config, coreVersion });
-
-    const router = Router();
-
-    router.get('/api/meta', (req, res) => {
-        const isAdmin = isValidAdminApiKey(req.get('x-frigg-admin-api-key'));
-        res.set('Cache-Control', 'no-store');
-        res.json(getMeta.execute({ isAdmin }));
-    });
-
-    // One OpenAPI document per major (ADR-053 §5). Static per deployment, so
-    // built once; the entity proxy appears only when the app enables it.
-    const documents = new Map();
-    for (const major of Object.keys(MANAGEMENT_API_VERSIONS)) {
-        router.get(`/api/meta/openapi/v${major}.json`, (_req, res) => {
-            if (!documents.has(major)) {
-                documents.set(
-                    major,
-                    buildOpenApiDocument(major, { proxy: config.proxy.enable })
-                );
-            }
-            res.set('Cache-Control', 'public, max-age=300');
-            res.json(documents.get(major));
-        });
-    }
-
-    // Anything else under /api/meta is a v2-shaped 404, not Express's page.
-    router.use('/api/meta', (req, _res, next) => {
-        next(Boom.notFound(`No Management API meta route for ${req.method} ${req.originalUrl.split('?')[0]}`));
-    });
-
-    return router;
-}
-
-/**
- * GET /api/docs (DOCS_ROUTES): a redirect to the current OpenAPI document,
- * mounted next to the meta router on the DB-free health Lambda. Public, like
- * /api/meta.
- */
-function createDocsRedirectRouter() {
-    const router = Router();
-    for (const { path } of DOCS_ROUTES) {
-        router.get(path, (_req, res) =>
-            res.redirect(302, `/api/meta/openapi/v${PREFERRED_API_VERSION}.json`)
-        );
-    }
-    return router;
-}
-
-module.exports = { createManagementApiMetaRouter, createDocsRedirectRouter };