@friggframework/core 2.0.0--canary.678.58db4b2.0 → 2.0.0--canary.680.b3ca7f1.0

package/integrations/integration-router.js

@@ -31,9 +31,6 @@ const {
     GetIntegrationInstance,
 } = require('./use-cases/get-integration-instance');
 const { UpdateIntegration } = require('./use-cases/update-integration');
-const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('./utils/map-integration-dto');
 const {
     GetModuleInstanceFromType,
 } = require('../modules/use-cases/get-module-instance-from-type');
@@ -63,9 +60,6 @@ const {
 const {
     GetUserFromAdopterJwt,
 } = require('../user/use-cases/get-user-from-adopter-jwt');
-const {
-    createAdopterTokenVerifier,
-} = require('../user/adopter-token-verifier');
 const {
     AuthenticateWithSharedSecret,
 } = require('../user/use-cases/authenticate-with-shared-secret');
@@ -77,8 +71,13 @@ const {
 const log = getLogger('frigg.integrations');
 
 function createIntegrationRouter() {
-    const { integrations: integrationClasses, userConfig } =
-        loadAppDefinition();
+    // moduleDefinitions is the app registry's definitions (ADR-059), so
+    // /api/authorize and friends accept a type no integration binds.
+    const {
+        integrations: integrationClasses,
+        userConfig,
+        moduleDefinitions,
+    } = loadAppDefinition();
     const moduleRepository = createModuleRepository();
     const integrationRepository = createIntegrationRepository();
     const credentialRepository = createCredentialRepository();
@@ -97,9 +96,6 @@ function createIntegrationRouter() {
     const getUserFromAdopterJwt = new GetUserFromAdopterJwt({
         userRepository,
         userConfig,
-        tokenVerifier: createAdopterTokenVerifier({
-            jwtConfig: userConfig?.jwtConfig,
-        }),
     });
 
     const authenticateWithSharedSecret = new AuthenticateWithSharedSecret();
@@ -114,8 +110,7 @@ function createIntegrationRouter() {
 
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
     const deleteIntegrationForUser = new DeleteIntegrationForUser({
         integrationRepository,
@@ -142,8 +137,7 @@ function createIntegrationRouter() {
 
     const getEntitiesForUser = new GetEntitiesForUser({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getIntegrationInstance = new GetIntegrationInstance({
@@ -159,37 +153,31 @@ function createIntegrationRouter() {
     });
 
     const getModuleInstanceFromType = new GetModuleInstanceFromType({
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getEntityOptionsByType = new GetEntityOptionsByType({
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const testModuleAuth = new TestModuleAuth({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getModule = new GetModule({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getEntityOptionsById = new GetEntityOptionsById({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const refreshEntityOptions = new RefreshEntityOptions({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getPossibleIntegrations = new GetPossibleIntegrations({
@@ -200,8 +188,7 @@ function createIntegrationRouter() {
         moduleRepository,
         credentialRepository,
         integrationRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const router = express();

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

@@ -20,18 +20,4 @@ function mapIntegrationClassToIntegrationDTO(integration) {
 }
 
 
-const getModulesDefinitionFromIntegrationClasses = (integrationClasses) => {
-    return [
-        ...new Set(
-            integrationClasses
-                .map((integration) =>
-                    Object.values(integration.Definition.modules).map(
-                        (module) => module.definition
-                    )
-                )
-                .flat()
-        ),
-    ];
-};
-
-module.exports = { mapIntegrationClassToIntegrationDTO, getModulesDefinitionFromIntegrationClasses }; 
+module.exports = { mapIntegrationClassToIntegrationDTO };

package/management-api/openapi/components.js

@@ -138,11 +138,17 @@ const SCHEMAS = {
     },
     EntityType: {
         type: 'object',
-        required: ['type', 'name', 'authType', 'isMultiStep', 'stepCount'],
+        required: ['type', 'name', 'authType', 'isMultiStep', 'stepCount', 'usedBy'],
         properties: {
             type: { type: 'string' },
             name: { type: 'string' },
             description: { type: 'string' },
+            usedBy: {
+                type: 'array',
+                items: { type: 'string' },
+                description:
+                    'Names of the integrations that bind this entity type. Empty for a type registered only in appDefinition.entities.',
+            },
             authType: { type: 'string', description: 'oauth2, oauth1, api-key, basic or custom' },
             isMultiStep: { type: 'boolean' },
             stepCount: { type: 'integer', minimum: 1 },

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

@@ -112,10 +112,14 @@ const V2_OPERATIONS = {
     },
     listEntityTypes: {
         summary: 'List the entity types (API modules) this app can connect',
+        description:
+            'Every type registered in appDefinition.entities plus every module a declared integration binds. `usedBy` lists the integrations that bind each type; it is empty for a type registered without any integration.',
         responses: { 200: ok('Entity types', ref('ListEntityTypesResponse')), ...errors('Unauthorized') },
     },
     getEntityType: {
         summary: 'Describe an entity type',
+        description:
+            'Includes `usedBy`, the integrations that bind the type (empty for a registry-only type).',
         responses: { 200: ok('Entity type', ref('EntityType')), ...errors('Unauthorized', 'NotFound') },
     },
     getEntityTypeRequirements: {

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,12 +26,12 @@ 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 { 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 { createAdopterTokenVerifier } = require('../../user/adopter-token-verifier');
     const {
         AuthenticateWithSharedSecret,
     } = require('../../user/use-cases/authenticate-with-shared-secret');
@@ -71,8 +80,13 @@ 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);
 
     const moduleRepository = createModuleRepository();
     const integrationRepository = createIntegrationRepository();
@@ -83,11 +97,7 @@ function buildV2Dependencies({ appDefinition, config }) {
     const authenticateUser = new AuthenticateUser({
         getUserFromBearerToken: new GetUserFromBearerToken({ userRepository, userConfig }),
         getUserFromXFriggHeaders: new GetUserFromXFriggHeaders({ userRepository, userConfig }),
-        getUserFromAdopterJwt: new GetUserFromAdopterJwt({
-            userRepository,
-            userConfig,
-            tokenVerifier: createAdopterTokenVerifier({ jwtConfig: userConfig.jwtConfig }),
-        }),
+        getUserFromAdopterJwt: new GetUserFromAdopterJwt({ userRepository, userConfig }),
         authenticateWithSharedSecret: new AuthenticateWithSharedSecret(),
         userConfig,
     });
@@ -205,8 +215,8 @@ function buildV2Dependencies({ appDefinition, config }) {
         refreshEntityOptionsForUser: new entityOps.RefreshEntityOptionsForUser({
             getEntityModuleForUser,
         }),
-        listEntityTypes: new ListEntityTypes({ moduleDefinitions }),
-        getEntityType: new GetEntityType({ moduleDefinitions }),
+        listEntityTypes: new ListEntityTypes({ entityTypeRegistry: registry }),
+        getEntityType: new GetEntityType({ entityTypeRegistry: registry }),
         getAuthorizationRequirements,
 
         // Credentials

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,10 @@ 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');
 
 module.exports = {
     ApiKeyRequester,
@@ -12,4 +16,6 @@ module.exports = {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
 };

package/modules/use-cases/entity-types.js

@@ -1,5 +1,6 @@
 const Boom = require('@hapi/boom');
 const { ModuleConstants } = require('../ModuleConstants');
+const { usedByOf } = require('../entity-type-registry');
 
 const AUTH_TYPE_BY_REQUESTER = {
     [ModuleConstants.authType.oauth2]: 'oauth2',
@@ -22,16 +23,16 @@ function getAuthStepCount(definition) {
  * definition: display metadata, auth type and step count. Never credentials
  * or env values.
  */
-function describeEntityType(definition) {
+function describeEntityType(definition, typeName = definition.moduleName) {
     const stepCount = getAuthStepCount(definition);
     const display = definition.display || {};
     const description = {
-        type: definition.moduleName,
+        type: typeName,
         name:
             callIfFunction(definition, 'getDisplayName') ??
             display.label ??
             display.name ??
-            definition.moduleName,
+            typeName,
         authType:
             callIfFunction(definition, 'getAuthType') ??
             AUTH_TYPE_BY_REQUESTER[definition.API?.requesterType] ??
@@ -58,27 +59,50 @@ function findDefinition(moduleDefinitions, entityType) {
     return definition;
 }
 
-/** Lists the entity types (API modules) this app can authorize. */
+const describeEntry = (name, entry) => ({
+    // The registry key is the name the API uses, whatever the definition spells.
+    ...describeEntityType(entry.definition, name),
+    usedBy: usedByOf(entry),
+});
+
+function requireRegistry(entityTypeRegistry) {
+    if (!(entityTypeRegistry instanceof Map)) {
+        throw new TypeError('entityTypeRegistry is required (see getEntityTypeRegistry)');
+    }
+    return entityTypeRegistry;
+}
+
+/**
+ * Lists the entity types this app can authorize: registry entries plus every
+ * module an integration binds (ADR-059). `usedBy` names the integrations that
+ * bind each type; it is empty for a registry-only type.
+ */
 class ListEntityTypes {
-    constructor({ moduleDefinitions }) {
-        this.moduleDefinitions = moduleDefinitions || [];
+    constructor({ entityTypeRegistry }) {
+        this.registry = requireRegistry(entityTypeRegistry);
     }
 
     async execute() {
-        return this.moduleDefinitions
-            .map(describeEntityType)
+        return [...this.registry]
+            .map(([name, entry]) => describeEntry(name, entry))
             .sort((a, b) => a.name.localeCompare(b.name));
     }
 }
 
-/** Describes one entity type; 404 when the app does not configure it. */
+/** Describes one entity type, looked up by its registry key; 404 when absent. */
 class GetEntityType {
-    constructor({ moduleDefinitions }) {
-        this.moduleDefinitions = moduleDefinitions || [];
+    constructor({ entityTypeRegistry }) {
+        this.registry = requireRegistry(entityTypeRegistry);
     }
 
     async execute(entityType) {
-        return describeEntityType(findDefinition(this.moduleDefinitions, entityType));
+        const entry = this.registry.get(entityType);
+        if (!entry) {
+            throw Boom.notFound(`Entity type '${entityType}' not found`, {
+                code: 'ENTITY_TYPE_NOT_FOUND',
+            });
+        }
+        return describeEntry(entityType, entry);
     }
 }