@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

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

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

package/integrations/utils/map-integration-dto.js

@@ -19,5 +19,48 @@ function mapIntegrationClassToIntegrationDTO(integration) {
     };
 }
 
+let deprecationLogged = false;
 
-module.exports = { mapIntegrationClassToIntegrationDTO };
+/**
+ * @deprecated Since ADR-059. Read `entityTypeRegistry` / `moduleDefinitions`
+ * from `loadAppDefinition()`, or call `getEntityTypeRegistry(appDefinition)`
+ * and read each entry's `definition`.
+ *
+ * Kept as a wrapper over the entity type registry so callers that imported it
+ * keep working. It returns the registry's definitions, so it follows the
+ * registry's rules: one definition per entity type name (the first wins when
+ * two integrations bind different definitions under one name, as
+ * ModuleFactory already picked), and, when `entities` is passed, registry-only
+ * types are included and conflicts throw `EntityRegistryError`.
+ *
+ * @param {Array<Function>} integrationClasses - integration classes
+ * @param {Object} [entities] - `appDefinition.entities` (ADR-059)
+ * @returns {Array<Object>} API module definitions
+ */
+function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses,
+    entities
+) {
+    // Required here, not at the top: modules/ must not load at require time
+    // of every integration use case that only wants the DTO mapper.
+    const {
+        getEntityTypeRegistry,
+        getEntityTypeDefinitions,
+    } = require('../../modules/entity-type-registry');
+    if (!deprecationLogged) {
+        deprecationLogged = true;
+        const { getLogger } = require('../../logs');
+        getLogger('frigg.integrations').warn(
+            'getModulesDefinitionFromIntegrationClasses is deprecated; use getEntityTypeRegistry (ADR-059)',
+            { eventName: 'frigg.integrations.deprecated_module_definitions' }
+        );
+    }
+    return getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations: integrationClasses, entities })
+    );
+}
+
+module.exports = {
+    mapIntegrationClassToIntegrationDTO,
+    getModulesDefinitionFromIntegrationClasses,
+};

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

@@ -9,6 +9,7 @@
  *         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/**' }] },
@@ -16,7 +17,36 @@
  *     },
  * }
  * ```
+ *
+ * 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
@@ -44,9 +74,41 @@ 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, modules: Object } }}
+ * @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 =
@@ -71,6 +133,7 @@ function resolveManagementApiConfig(managementApi) {
                 proxy.maxResponseBytes,
                 DEFAULT_PROXY_LIMITS.maxResponseBytes
             ),
+            scopes: resolveProxyScopes(proxy.scopes),
             modules:
                 proxy.modules && typeof proxy.modules === 'object'
                     ? proxy.modules
@@ -79,4 +142,10 @@ function resolveManagementApiConfig(managementApi) {
     };
 }
 
-module.exports = { resolveManagementApiConfig, DEFAULT_PROXY_LIMITS };
+module.exports = {
+    resolveManagementApiConfig,
+    DEFAULT_PROXY_LIMITS,
+    DEFAULT_PROXY_SCOPES,
+    PROXY_SCOPE_VALUES,
+    ManagementApiConfigError,
+};

package/management-api/meta-router.js

@@ -6,7 +6,11 @@ const {
 } = require('./use-cases/get-management-api-meta');
 const { isValidAdminApiKey } = require('../handlers/middleware/admin-auth');
 const { version: coreVersion } = require('../package.json');
-const { MANAGEMENT_API_VERSIONS } = require('./route-registry');
+const {
+    MANAGEMENT_API_VERSIONS,
+    PREFERRED_API_VERSION,
+    DOCS_ROUTES,
+} = require('./route-registry');
 const { buildOpenApiDocument } = require('./openapi/build-openapi');
 
 /**
@@ -54,4 +58,19 @@ function createManagementApiMetaRouter({ appDefinition = {} } = {}) {
     return router;
 }
 
-module.exports = { createManagementApiMetaRouter };
+/**
+ * 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 };

package/management-api/openapi/components.js

@@ -8,6 +8,27 @@ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
 
 const nullable = (schema) => ({ ...schema, nullable: true });
 
+// Whose a record is and what the caller may do with it (ADR-056 §3.4). Added to
+// entities, credentials and integrations by the list and get use cases.
+const tenancyProperties = {
+    scope: { type: 'string', enum: ['individual', 'organization'], description: 'Whose it is. `global` records are not shown to tenants.' },
+    owner: {
+        type: 'object',
+        properties: { type: { type: 'string', enum: ['individual', 'organization'] }, id: { type: 'string' } },
+        description: "The user that owns it: the person, or the organization's user",
+    },
+    organizationId: nullable({
+        type: 'string',
+        description:
+            'The organization it belongs to. Null for an individual entity connected outside an organization, or under ownership.individualAcross "all".',
+    }),
+    access: {
+        type: 'string',
+        enum: ['manage', 'use', 'view'],
+        description: 'manage (create, reauthorize, delete), use (bind it, proxy through it) or view (metadata only)',
+    },
+};
+
 const errorBody = {
     type: 'object',
     required: ['error'],
@@ -69,6 +90,7 @@ const SCHEMAS = {
             config: { type: 'object', additionalProperties: true },
             version: nullable({ type: 'string' }),
             messages: { type: 'object', additionalProperties: true },
+            ...tenancyProperties,
         },
     },
     ListIntegrationsResponse: {
@@ -129,6 +151,7 @@ const SCHEMAS = {
             credentialId: nullable({ type: 'string' }),
             userId: nullable({ type: 'string' }),
             authIsValid: nullable({ type: 'boolean' }),
+            ...tenancyProperties,
         },
     },
     ListEntitiesResponse: {
@@ -153,6 +176,16 @@ const SCHEMAS = {
             isMultiStep: { type: 'boolean' },
             stepCount: { type: 'integer', minimum: 1 },
             capabilities: {},
+            scope: {
+                type: 'object',
+                description:
+                    'The scope a new connection of this type gets and the scopes a request may choose (ADR-056 §3.1). `global` is never offered.',
+                properties: {
+                    default: { type: 'string', enum: ['individual', 'organization', 'global'] },
+                    allow: { type: 'array', items: { type: 'string', enum: ['individual', 'organization'] } },
+                    source: { type: 'string', enum: ['binding', 'integration', 'entityType', 'app', 'default'] },
+                },
+            },
         },
     },
     ListEntityTypesResponse: {
@@ -173,6 +206,7 @@ const SCHEMAS = {
             authIsValid: nullable({ type: 'boolean' }),
             entityIds: { type: 'array', items: { type: 'string' } },
             entityCount: { type: 'integer', minimum: 0 },
+            ...tenancyProperties,
             createdAt: nullable({ type: 'string', format: 'date-time' }),
             updatedAt: nullable({ type: 'string', format: 'date-time' }),
             data: {
@@ -197,6 +231,12 @@ const SCHEMAS = {
             data: { type: 'object', additionalProperties: true, description: 'OAuth callback params or step form data' },
             step: { type: 'integer', minimum: 1, default: 1 },
             sessionId: { type: 'string', description: 'Required for step 2 and later' },
+            scope: {
+                type: 'string',
+                enum: ['individual', 'organization'],
+                description:
+                    "The scope to connect at, from the entity type's allow list (ADR-056 §3.1). Omit to take the type's default. `global` is refused (403).",
+            },
         },
     },
     ReauthorizeRequest: {

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

@@ -34,6 +34,11 @@ 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 = {
@@ -41,7 +46,8 @@ const V2_OPERATIONS = {
     listIntegrations: {
         summary: "List the caller's integrations",
         description:
-            'Returns only `{ integrations }`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+            '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: {
@@ -108,6 +114,9 @@ const V2_OPERATIONS = {
     // 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: {
@@ -156,14 +165,14 @@ const V2_OPERATIONS = {
     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. The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
+            "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', ref('ProxyError')),
-            404: ok('Entity not found', ref('Error')),
+            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')),
@@ -175,6 +184,9 @@ const V2_OPERATIONS = {
     // 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: {