@friggframework/core 2.0.0--canary.681.2df9ef0.0 → 2.0.0--canary.682.cbca9e2.0

package/management-api/v2/dependencies.js

@@ -2,7 +2,16 @@
  * Wires the repositories and use cases behind Management API v2. Kept apart
  * from the router so tests can hand the router doubles instead.
  */
-function buildV2Dependencies({ appDefinition, config }) {
+/**
+ * @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');
@@ -17,8 +26,16 @@ function buildV2Dependencies({ appDefinition, config }) {
     } = require('../../user/repositories/user-repository-factory');
     const { ModuleFactory } = require('../../modules/module-factory');
     const {
-        getModulesDefinitionFromIntegrationClasses,
-    } = require('../../integrations/utils/map-integration-dto');
+        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');
@@ -68,8 +85,18 @@ function buildV2Dependencies({ appDefinition, config }) {
 
     const integrationClasses = appDefinition.integrations || [];
     const userConfig = appDefinition.userConfig || {};
-    const moduleDefinitions =
-        getModulesDefinitionFromIntegrationClasses(integrationClasses);
+    // 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();
@@ -92,6 +119,7 @@ function buildV2Dependencies({ appDefinition, config }) {
     const getEntityModuleForUser = new GetEntityModuleForUser({
         moduleRepository,
         moduleDefinitions,
+        scopePolicy,
     });
     const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
         credentialRepository,
@@ -109,17 +137,22 @@ function buildV2Dependencies({ appDefinition, config }) {
         moduleDefinitions,
         getAuthorizationRequirements,
         authorizationSessionRepository,
-        processAuthorizationCallback: new ProcessAuthorizationCallback({
-            moduleRepository,
-            credentialRepository,
-            integrationRepository,
-            moduleDefinitions,
+        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,
@@ -129,6 +162,7 @@ function buildV2Dependencies({ appDefinition, config }) {
     return {
         config,
         moduleDefinitions,
+        scopePolicy,
         repositories: {
             moduleRepository,
             integrationRepository,
@@ -144,6 +178,7 @@ function buildV2Dependencies({ appDefinition, config }) {
             integrationClasses,
             moduleFactory,
             moduleRepository,
+            scopePolicy,
         }),
         getPossibleIntegrations: new GetPossibleIntegrations({ integrationClasses }),
         createIntegrationForUser: new integrationOps.CreateIntegrationForUser({
@@ -152,7 +187,11 @@ function buildV2Dependencies({ appDefinition, config }) {
                 integrationClasses,
                 moduleFactory,
             }),
-            getEntityModuleForUser,
+            resolveIntegrationOwnership: new ResolveIntegrationOwnership({
+                moduleRepository,
+                integrationClasses,
+                scopePolicy,
+            }),
             integrationClasses,
         }),
         getIntegrationInstanceForUser,
@@ -184,7 +223,10 @@ function buildV2Dependencies({ appDefinition, config }) {
 
         // Entities
         getEntityModuleForUser,
-        listEntitiesForUser: new entityOps.ListEntitiesForUser({ moduleRepository }),
+        listEntitiesForUser: new entityOps.ListEntitiesForUser({
+            moduleRepository,
+            scopePolicy,
+        }),
         getEntityForUser: new entityOps.GetEntityForUser({ getEntityModuleForUser }),
         deleteEntityForUser: new entityOps.DeleteEntityForUser({
             getEntityModuleForUser,
@@ -196,8 +238,8 @@ function buildV2Dependencies({ appDefinition, config }) {
         refreshEntityOptionsForUser: new entityOps.RefreshEntityOptionsForUser({
             getEntityModuleForUser,
         }),
-        listEntityTypes: new ListEntityTypes({ moduleDefinitions }),
-        getEntityType: new GetEntityType({ moduleDefinitions }),
+        listEntityTypes: new ListEntityTypes({ entityTypeRegistry: registry, scopePolicy }),
+        getEntityType: new GetEntityType({ entityTypeRegistry: registry, scopePolicy }),
         getAuthorizationRequirements,
 
         // Credentials

package/management-api/v2/dto.js

@@ -13,6 +13,20 @@ const idOf = (value) => {
     return String(value);
 };
 
+/**
+ * `{ scope, owner, organizationId, access }` (ADR-056 §3.4): whose a record is
+ * and what the caller may do with it. Empty when the use case did not say.
+ */
+function tenancyFields(tenancy) {
+    if (!tenancy) return {};
+    return {
+        scope: tenancy.scope,
+        owner: tenancy.owner,
+        organizationId: tenancy.organizationId ?? null,
+        access: tenancy.access,
+    };
+}
+
 /** An entity (connected account). */
 function toEntityDto(entity) {
     const credential =
@@ -30,6 +44,7 @@ function toEntityDto(entity) {
             typeof credential?.authIsValid === 'boolean'
                 ? credential.authIsValid
                 : null,
+        ...tenancyFields(entity.tenancy),
     };
 }
 
@@ -42,6 +57,7 @@ function toIntegrationDto(integration) {
         config: integration.config ?? {},
         version: integration.version ?? null,
         messages: integration.messages ?? {},
+        ...tenancyFields(integration.tenancy),
     };
 }
 
@@ -115,6 +131,7 @@ function maskCredential(credential) {
 }
 
 module.exports = {
+    tenancyFields,
     toEntityDto,
     toIntegrationDto,
     maskCredential,

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

@@ -63,6 +63,7 @@ function createAuthorizationHandlers(useCases) {
                 data: body.data,
                 step,
                 sessionId,
+                scope: optionalString(body.scope, 'scope'),
             });
             res.json(toAuthorizationResponse(result));
         },

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

@@ -1,5 +1,5 @@
 const { toEntityDto } = require('../dto');
-const { objectBody, parseStep } = require('../request');
+const { objectBody, parseStep, parseListFilters } = require('../request');
 
 /** Management API v2 entity and entity-type handlers, keyed by operationId. */
 function createEntityHandlers(useCases) {
@@ -16,17 +16,20 @@ function createEntityHandlers(useCases) {
     } = useCases;
 
     return {
-        async listEntities(_req, res, user) {
-            const entities = await listEntitiesForUser.execute(user);
+        async listEntities(req, res, user) {
+            const entities = await listEntitiesForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ entities: entities.map(toEntityDto) });
         },
 
-        async listEntityTypes(_req, res) {
-            res.json({ types: await listEntityTypes.execute() });
+        async listEntityTypes(_req, res, user) {
+            res.json({ types: await listEntityTypes.execute({ user }) });
         },
 
-        async getEntityType(req, res) {
-            res.json(await getEntityType.execute(req.params.entityType));
+        async getEntityType(req, res, user) {
+            res.json(await getEntityType.execute(req.params.entityType, { user }));
         },
 
         // Describes a step's requirements without starting an authorization

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

@@ -1,5 +1,5 @@
 const { toIntegrationDto } = require('../dto');
-const { objectBody, optionalString } = require('../request');
+const { objectBody, optionalString, parseListFilters } = require('../request');
 
 /**
  * Management API v2 integration handlers, keyed by registry operationId.
@@ -27,8 +27,11 @@ function createIntegrationHandlers(useCases) {
         );
 
     return {
-        async listIntegrations(_req, res, user) {
-            const integrations = await getIntegrationsForUser.execute(user.getId());
+        async listIntegrations(req, res, user) {
+            const integrations = await getIntegrationsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ integrations: integrations.map(toIntegrationDto) });
         },
 

package/management-api/v2/request.js

@@ -1,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { LIST_OWNERS } = require('../../modules/scope-visibility');
 
 /** The JSON body as an object, or a 400 VALIDATION_ERROR. */
 function objectBody(req) {
@@ -51,4 +52,34 @@ function optionalString(value, name) {
     return value;
 }
 
-module.exports = { objectBody, requireFields, parseStep, optionalString };
+const LIST_SCOPES = ['individual', 'organization'];
+
+/**
+ * `?scope=individual|organization` and `?owner=me|org` on a list (ADR-056
+ * §3.4). Anything else is a 400.
+ */
+function parseListFilters(query = {}) {
+    const scope = optionalString(query.scope, 'scope');
+    const owner = optionalString(query.owner, 'owner');
+    if (scope !== undefined && !LIST_SCOPES.includes(scope)) {
+        throw Boom.badRequest(`scope must be one of ${LIST_SCOPES.join(', ')}`, {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'scope' },
+        });
+    }
+    if (owner !== undefined && !Object.hasOwn(LIST_OWNERS, owner)) {
+        throw Boom.badRequest('owner must be me or org', {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'owner' },
+        });
+    }
+    return { scope, owner };
+}
+
+module.exports = {
+    objectBody,
+    requireFields,
+    parseStep,
+    optionalString,
+    parseListFilters,
+};

package/modules/entity-scope.js

@@ -0,0 +1,15 @@
+/**
+ * Entity scopes and ownership (ADR-056 §3), re-exported from the four files it
+ * is split into:
+ *
+ *   scope-resolution  constants, scope resolution, ownership on create
+ *   scope-config      reading and validating app-definition settings
+ *   scope-visibility  who may see which stored row
+ *   scope-policy      the object a use case asks
+ */
+module.exports = {
+    ...require('./scope-resolution'),
+    ...require('./scope-config'),
+    ...require('./scope-visibility'),
+    ...require('./scope-policy'),
+};

package/modules/entity-type-registry.js

@@ -0,0 +1,311 @@
+/**
+ * App-level entity type registry (ADR-059).
+ *
+ * Pure: reads an app definition, does no I/O. It answers "which entity types
+ * (API modules) can this app connect?" from two sources:
+ *
+ *   1. `appDefinition.entities`, an object keyed by entity type name whose
+ *      values are `{ definition, scope?, proxy?, display? }`.
+ *   2. Inference: every module bound by `appDefinition.integrations[*]
+ *      .Definition.modules` (skipped when `entities.$infer === false`).
+ *
+ * `loadAppDefinition()` builds the registry once, at load, and returns it as
+ * `entityTypeRegistry` / `moduleDefinitions`; every consumer that holds a
+ * loaded app definition reads those instead of rebuilding.
+ */
+
+const { BaseError } = require('../errors/base-error');
+const { getLogger } = require('../logs');
+
+const log = getLogger('frigg.modules.entity_registry');
+
+const INFER_KEY = '$infer';
+const UNNAMED = '(unnamed definition)';
+
+/**
+ * Raised for an invalid `entities` registry. `code` is always
+ * `ENTITY_REGISTRY_INVALID`, so callers can tell it from other load errors.
+ */
+class EntityRegistryError extends BaseError {
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'ENTITY_REGISTRY_INVALID';
+    }
+}
+
+const isPlainObject = (value) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const appSource = () => ({ kind: 'app' });
+const integrationSource = (integrationClass) => ({
+    kind: 'integration',
+    name: integrationClass?.Definition?.name || 'unnamed',
+});
+const describeSource = (source) =>
+    source.kind === 'app' ? 'app' : `integration:${source.name}`;
+
+const safeGetName = (definition) => {
+    if (typeof definition.getName !== 'function') return undefined;
+    try {
+        const name = definition.getName();
+        return typeof name === 'string' && name ? name : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const moduleNameOf = (definition) =>
+    typeof definition?.moduleName === 'string' && definition.moduleName
+        ? definition.moduleName
+        : undefined;
+
+/** The name an entity type is known by: moduleName, else getName(). */
+function entityTypeNameOf(definition) {
+    if (!definition) return undefined;
+    return moduleNameOf(definition) ?? safeGetName(definition);
+}
+
+/** Same object, or the same package name and version when both can be read. */
+function isSameDefinition(a, b) {
+    if (a === b) return true;
+    const packageId = (definition) => {
+        const { packageName, version } = definition || {};
+        return typeof packageName === 'string' &&
+            packageName &&
+            typeof version === 'string' &&
+            version
+            ? `${packageName}@${version}`
+            : null;
+    };
+    const left = packageId(a);
+    return left !== null && left === packageId(b);
+}
+
+function conflictError(name, existing, source) {
+    return new EntityRegistryError(
+        `Entity type '${name}' is supplied by two different definitions: ` +
+            `${existing.sources
+                .map(describeSource)
+                .join(', ')} and ${describeSource(source)}. ` +
+            'They must be the same definition object (or the same package name and version).'
+    );
+}
+
+/**
+ * A registry key must equal the definition's moduleName and, when it has one,
+ * its getName(). Case matters. This leaves one name per entity type.
+ */
+function assertKeyMatchesDefinition(key, definition) {
+    const moduleName = moduleNameOf(definition);
+    const getName = safeGetName(definition);
+    const matches =
+        (moduleName !== undefined || getName !== undefined) &&
+        (moduleName === undefined || key === moduleName) &&
+        (getName === undefined || key === getName);
+    if (!matches) {
+        throw new EntityRegistryError(
+            `appDefinition.entities key '${key}' does not match its definition's name ` +
+                `(moduleName '${moduleName ?? '(none)'}', getName() '${
+                    getName ?? '(none)'
+                }'). ` +
+                'The key must equal both, so each entity type has one name.'
+        );
+    }
+}
+
+const settingsOf = (entry) => {
+    const settings = {};
+    for (const field of ['scope', 'proxy', 'display']) {
+        if (entry[field] !== undefined) settings[field] = entry[field];
+    }
+    return settings;
+};
+
+/**
+ * `entities` absent keeps today's behaviour: inference on, and a name clash
+ * between integrations is not fatal. `entities` present (even `{}`) opts in to
+ * the strict rules.
+ */
+function readEntities(appDefinition) {
+    const entities = appDefinition?.entities;
+    if (entities === undefined || entities === null) {
+        return { strict: false, infer: true, entries: [] };
+    }
+    if (!isPlainObject(entities)) {
+        throw new EntityRegistryError(
+            'appDefinition.entities must be an object keyed by entity type name'
+        );
+    }
+    const { [INFER_KEY]: inferFlag, ...rest } = entities;
+    if (inferFlag !== undefined && typeof inferFlag !== 'boolean') {
+        throw new EntityRegistryError(
+            `appDefinition.entities.${INFER_KEY} must be a boolean`
+        );
+    }
+    return {
+        strict: true,
+        infer: inferFlag !== false,
+        entries: Object.entries(rest),
+    };
+}
+
+function registerAppEntries(registry, entries) {
+    for (const [key, entry] of entries) {
+        if (
+            !isPlainObject(entry) ||
+            !entry.definition ||
+            typeof entry.definition !== 'object'
+        ) {
+            throw new EntityRegistryError(
+                `appDefinition.entities.${key} must be an object with a 'definition'`
+            );
+        }
+        assertKeyMatchesDefinition(key, entry.definition);
+        registry.set(key, {
+            definition: entry.definition,
+            sources: [appSource()],
+            settings: settingsOf(entry),
+        });
+    }
+}
+
+function* boundDefinitions(integrationClass) {
+    const modules = integrationClass?.Definition?.modules;
+    if (!isPlainObject(modules)) return;
+    for (const bound of Object.values(modules)) {
+        if (bound?.definition) yield bound.definition;
+    }
+}
+
+const addSource = (entry, source) => {
+    const known = entry.sources.some(
+        (s) => s.kind === source.kind && s.name === source.name
+    );
+    if (!known) entry.sources.push(source);
+};
+
+/**
+ * Folds one integration-bound definition into the registry. Returns the name
+ * it could not register (only possible when inference is off), else undefined.
+ */
+function mergeBoundDefinition(registry, definition, source, { strict, infer }) {
+    const name = entityTypeNameOf(definition);
+
+    if (!name) {
+        // No moduleName / getName(): it cannot be keyed by name. Offering it
+        // as before, de-duplicated by identity, keeps apps that never named
+        // one working. It cannot be registered, so `$infer: false` rejects it.
+        if (!infer) return UNNAMED;
+        const known = [...registry.values()].find(
+            (entry) => entry.definition === definition
+        );
+        if (known) addSource(known, source);
+        else {
+            registry.set(`${UNNAMED} #${registry.size}`, {
+                definition,
+                sources: [source],
+                settings: {},
+            });
+        }
+        return undefined;
+    }
+
+    const existing = registry.get(name);
+    if (existing) {
+        if (isSameDefinition(existing.definition, definition)) {
+            addSource(existing, source);
+        } else if (strict) {
+            throw conflictError(name, existing, source);
+        } else {
+            // Pre-ADR-059 apps keep working: the first definition wins, as
+            // ModuleFactory would have picked it.
+            log.warn('Two different definitions share one entity type name', {
+                eventName: `${log.name}.duplicate_definition`,
+                entityType: name,
+                kept: existing.sources.map(describeSource).join(', '),
+                ignored: describeSource(source),
+            });
+        }
+        return undefined;
+    }
+
+    if (!infer) return name;
+    registry.set(name, { definition, sources: [source], settings: {} });
+    return undefined;
+}
+
+function assertAllRegistered(unregistered) {
+    if (unregistered.size === 0) return;
+    const detail = [...unregistered]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(
+            ([name, sources]) => `${name} (bound by ${[...sources].join(', ')})`
+        );
+    throw new EntityRegistryError(
+        `appDefinition.entities.${INFER_KEY} is false, so every module an integration binds must be registered. Missing: ${detail.join(
+            '; '
+        )}`
+    );
+}
+
+const freezeEntries = (registry) => {
+    for (const entry of registry.values()) {
+        entry.sources.forEach(Object.freeze);
+        Object.freeze(entry.sources);
+        Object.freeze(entry.settings);
+        Object.freeze(entry);
+    }
+};
+
+/**
+ * Builds the registry for an app definition.
+ *
+ * @param {object} [appDefinition] - `{ entities?, integrations? }`
+ * @returns {Map<string, {definition: object, sources: Array<{kind: 'app'} | {kind: 'integration', name: string}>, settings: {scope?: string|object, proxy?: object, display?: object}}>}
+ * @throws {EntityRegistryError} on a key/name mismatch, two different
+ *   definitions under one name (when `entities` is present), or, with
+ *   `$infer: false`, a bound module that is not registered.
+ */
+function getEntityTypeRegistry(appDefinition = {}) {
+    const mode = readEntities(appDefinition);
+    const registry = new Map();
+    registerAppEntries(registry, mode.entries);
+
+    const unregistered = new Map();
+    for (const integrationClass of appDefinition?.integrations || []) {
+        const source = integrationSource(integrationClass);
+        for (const definition of boundDefinitions(integrationClass)) {
+            const missing = mergeBoundDefinition(
+                registry,
+                definition,
+                source,
+                mode
+            );
+            if (missing !== undefined) {
+                if (!unregistered.has(missing))
+                    unregistered.set(missing, new Set());
+                unregistered.get(missing).add(describeSource(source));
+            }
+        }
+    }
+    assertAllRegistered(unregistered);
+
+    freezeEntries(registry);
+    return registry;
+}
+
+/** The definitions of a registry, in registry order. */
+const getEntityTypeDefinitions = (registry) =>
+    [...registry.values()].map((entry) => entry.definition);
+
+/** Names of the integrations that bind an entity type; empty for registry-only. */
+const usedByOf = (entry) =>
+    entry.sources.filter((s) => s.kind === 'integration').map((s) => s.name);
+
+module.exports = {
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+    usedByOf,
+    entityTypeNameOf,
+    EntityRegistryError,
+};

package/modules/index.js

@@ -4,6 +4,15 @@ const { OAuth2Requester } = require('./requester/oauth-2');
 const { Requester } = require('./requester/requester');
 const { ModuleConstants } = require('./ModuleConstants');
 const { ModuleFactory } = require('./module-factory');
+const {
+    getEntityTypeRegistry,
+    EntityRegistryError,
+} = require('./entity-type-registry');
+const {
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
+} = require('./entity-scope');
 
 module.exports = {
     ApiKeyRequester,
@@ -12,4 +21,9 @@ module.exports = {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
 };