@friggframework/core 2.0.0--canary.671.e50fe9c.0 → 2.0.0--canary.680.b3ca7f1.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# Unreleased
+
+#### Behaviour change: module credential fields are now encrypted
+
+- `credentialFields` declared in an API module's `encryption` config (for example `Definition.encryption.credentialFields`) were never registered for encryption: `loadModuleEncryptionSchemas` required a path that does not exist and the error was swallowed. They are now registered, for modules bound by integrations and for modules registered in `appDefinition.entities` (ADR-059).
+- Existing rows are not rewritten. A credential saved before this release stays plaintext until it is next written, and is read as stored.
+- Reads now tolerate plaintext: a value is only treated as ciphertext when it has the exact `keyId:iv:ciphertext:encryptedKey` shape (previously any string with three or more colons, such as `https://user:pw@host:443`), and a value that fails to decrypt is returned as stored with a warning instead of failing the whole read.
+- An app's own `encryption.schema` is no longer replaced when module fields are added to it.
+
+---
+
 # v1.2.2 (Fri Aug 09 2024)
 
 #### 🐛 Bug Fix

package/application/commands/integration-commands.js

@@ -30,8 +30,9 @@ const {
     PatchIntegrationConfig,
 } = require('../../integrations/use-cases/patch-integration-config');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../../modules/entity-type-registry');
 
 const ERROR_CODE_MAP = {
     ENTITY_NOT_FOUND: 401,
@@ -51,7 +52,16 @@ function mapErrorToResponse(error) {
     };
 }
 
-function createIntegrationCommands({ integrationClass } = {}) {
+/**
+ * @param {Object} [params]
+ * @param {Function} [params.integrationClass]
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module
+ *   definitions (`loadAppDefinition().moduleDefinitions`). Integration code
+ *   calls this from a constructor with no app definition in hand, so when it
+ *   is omitted the commands hydrate with this integration's own modules only
+ *   (a registry built from `{ integrations: [integrationClass] }`).
+ */
+function createIntegrationCommands({ integrationClass, moduleDefinitions } = {}) {
     // Always use Frigg's default repositories and use cases
     const integrationRepository = createIntegrationRepository();
 
@@ -108,13 +118,13 @@ function createIntegrationCommands({ integrationClass } = {}) {
 
     const moduleRepository = createModuleRepository();
 
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses([
-        integrationClass,
-    ]);
-
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions,
+        moduleDefinitions:
+            moduleDefinitions ??
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
     });
 
     const loadIntegrationContextUseCase = new LoadIntegrationContextUseCase({

package/application/index.js

@@ -17,6 +17,7 @@ const { createUsageCommands } = require('./commands/usage-commands');
  *
  * @param {Object} params
  * @param {Object} params.integrationClass - Integration class (required)
+ * @param {Array<object>} [params.moduleDefinitions] - the app's offered module definitions; defaults to the integration's own modules
  * @returns {Object} Unified commands object with all CRUD operations
  *
  * @example
@@ -24,9 +25,12 @@ const { createUsageCommands } = require('./commands/usage-commands');
  * const user = await commands.createUser({ username: 'user@example.com' });
  * const credential = await commands.createCredential({ userId: user.id, ... });
  */
-function createFriggCommands({ integrationClass }) {
+function createFriggCommands({ integrationClass, moduleDefinitions }) {
     // All commands use Frigg's default repositories and use cases
-    const integrationCommands = createIntegrationCommands({ integrationClass });
+    const integrationCommands = createIntegrationCommands({
+        integrationClass,
+        moduleDefinitions,
+    });
 
     const userCommands = createUserCommands();
 

package/database/encryption/README.md

@@ -428,6 +428,8 @@ Format: "keyId:encryptedText:encryptedKey"
 Example: "base64KeyId:iv:ciphertext:base64EncryptedDataKey"
 ```
 
+**Recognising ciphertext on read.** A value is decrypted only when it has exactly four colon-separated parts: base64 `keyId`, 32-hex-character `iv`, hex ciphertext, base64 `encryptedKey`. Plaintext that merely contains colons (`https://user:pw@host:443`) is left alone. A value with that shape that still fails to decrypt is returned as stored and logged as a warning, so one bad field never fails a whole read. A field that becomes encrypted later (for example a module's `credentialFields`) stays plaintext in existing rows until they are next written.
+
 **Why Envelope Encryption?**
 
 -   Reduces KMS API calls (one DEK per field, cached)

package/database/encryption/encryption-schema-registry.js

@@ -10,6 +10,11 @@
 
 const { logger } = require('./logger');
 const { registerDeniedKeys } = require('../../logs/denied-keys');
+const {
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+    EntityRegistryError,
+} = require('../../modules/entity-type-registry');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -166,8 +171,9 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
  * Each module can declare credentialFields to encrypt in its encryption config.
  *
  * @param {Array} integrations - Array of integration classes with modules
+ * @param {object} [entities] - `appDefinition.entities` (ADR-059 registry)
  */
-function loadModuleEncryptionSchemas(integrations) {
+function loadModuleEncryptionSchemas(integrations, entities) {
     if (!integrations) {
         throw new Error('integrations parameter is required');
     }
@@ -176,27 +182,39 @@ function loadModuleEncryptionSchemas(integrations) {
         throw new Error('integrations must be an array');
     }
 
-    if (integrations.length === 0) {
+    // `entities` is the app definition's registry (ADR-059): a module an app
+    // registers without any integration still carries credentials to encrypt.
+    if (integrations.length === 0 && !entities) {
         return;
     }
 
-    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
-
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
+    const moduleDefinitions = getEntityTypeDefinitions(
+        getEntityTypeRegistry({ integrations, entities })
+    );
     const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
 
-    if (credentialFields.length === 0) {
+    // Core fields are encrypted already and a custom schema may not repeat
+    // them. Everything the app registered itself stays: module fields are added
+    // to the custom schema, never substituted for it (other models included).
+    const coreFields = new Set(CORE_ENCRYPTION_SCHEMA.Credential?.fields || []);
+    const fields = [
+        ...new Set([
+            ...(customSchema.Credential?.fields || []),
+            ...credentialFields.filter((field) => !coreFields.has(field)),
+        ]),
+    ];
+
+    if (fields.length === 0) {
         return;
     }
 
     const moduleSchema = {
-        Credential: {
-            fields: credentialFields
-        }
+        ...customSchema,
+        Credential: { ...customSchema.Credential, fields },
     };
 
     logger.info(
-        `Registering module-level encryption for ${credentialFields.length} credential fields`
+        `Registering module-level encryption for ${fields.length} credential fields`
     );
 
     registerCustomSchema(moduleSchema);
@@ -248,10 +266,15 @@ function loadCustomEncryptionSchema() {
 
         // Load module-level encryption schemas from integrations
         const integrations = appDefinition.integrations;
-        if (integrations && Array.isArray(integrations)) {
-            loadModuleEncryptionSchemas(integrations);
+        if (Array.isArray(integrations) || appDefinition.entities) {
+            loadModuleEncryptionSchemas(
+                Array.isArray(integrations) ? integrations : [],
+                appDefinition.entities
+            );
         }
     } catch (error) {
+        // A bad entity registry is a configuration error, not "no custom schema".
+        if (error instanceof EntityRegistryError) throw error;
         // Silently ignore errors - custom schema is optional
         // This handles cases like:
         // - Backend package.json not found (tests, standalone usage)

package/database/encryption/field-encryption-service.js

@@ -4,6 +4,16 @@
  * Infrastructure layer service that orchestrates field-level encryption/decryption.
  * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
  */
+const { logger } = require('./logger');
+
+// Cryptor.encrypt() returns `${keyId}:${iv}:${ciphertext}:${encryptedKey}`:
+// keyId and encryptedKey are base64, iv is 16 bytes of hex, ciphertext is hex.
+// Plaintext with three colons (`https://user:pw@host:443`, `a:b:c:d`) must not
+// be mistaken for it.
+const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/;
+const IV_PART = /^[0-9a-f]{32}$/i;
+const CIPHERTEXT_PART = /^(?:[0-9a-f]{2})+$/i;
+
 class FieldEncryptionService {
     constructor({ cryptor, schema }) {
         if (!cryptor) {
@@ -97,12 +107,23 @@ class FieldEncryptionService {
         const decryptionPromises = fields.map(async (fieldPath) => {
             const value = this._getNestedValue(decrypted, fieldPath);
 
-            if (this._isEncrypted(value)) {
+            if (!this._isEncrypted(value)) {
+                return null;
+            }
+            try {
                 const decryptedValue = await this.cryptor.decrypt(value);
                 const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
                 return { fieldPath, decryptedValue: deserializedValue };
+            } catch (error) {
+                // A value that looks like ciphertext but is not (or was written
+                // before the field was encrypted) is read as it is stored. One
+                // such field must not fail the whole read, findMany included.
+                logger.warn(
+                    `Could not decrypt ${modelName}.${fieldPath}; returning the stored value`,
+                    { errorName: error?.name }
+                );
+                return null;
             }
-            return null;
         });
 
         const results = await Promise.all(decryptionPromises);
@@ -152,7 +173,13 @@ class FieldEncryptionService {
         }
 
         const parts = value.split(':');
-        return parts.length >= 4;
+        return (
+            parts.length === 4 &&
+            BASE64_PART.test(parts[0]) &&
+            IV_PART.test(parts[1]) &&
+            CIPHERTEXT_PART.test(parts[2]) &&
+            BASE64_PART.test(parts[3])
+        );
     }
 
     _getNestedValue(obj, path) {

package/database/encryption/test-support/fake-ciphertext.js

@@ -0,0 +1,15 @@
+/**
+ * Test double for Cryptor output. Same shape as the real thing
+ * (`keyId:iv:ciphertext:encryptedKey`: base64, 16-byte hex, hex, base64) so
+ * FieldEncryptionService._isEncrypted accepts it, with the plaintext
+ * recoverable for the fake decrypt.
+ */
+const fakeCiphertext = (plain) =>
+    `a2V5SWQ=:${'0'.repeat(32)}:${Buffer.from(String(plain)).toString(
+        'hex'
+    )}:ZW5jS2V5`;
+
+const fakePlaintext = (ciphertext) =>
+    Buffer.from(String(ciphertext).split(':')[2], 'hex').toString();
+
+module.exports = { fakeCiphertext, fakePlaintext };

package/handlers/app-definition-loader.js

@@ -7,16 +7,15 @@ const {
     extractCredentialFieldsFromModules,
 } = require('../database/encryption/encryption-schema-registry');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../modules/entity-type-registry');
 
 // Handlers without a database never load the encryption registry, so the
 // credential leaf keys are registered for redaction here too.
-function registerCredentialLogKeys(appDefinition, integrations) {
+function registerCredentialLogKeys(appDefinition, moduleDefinitions) {
     try {
-        extractCredentialFieldsFromModules(
-            getModulesDefinitionFromIntegrationClasses(integrations)
-        );
+        extractCredentialFieldsFromModules(moduleDefinitions);
     } catch {
         // An odd integration shape must not stop the app from loading.
     }
@@ -33,7 +32,7 @@ function registerCredentialLogKeys(appDefinition, integrations) {
  * @function loadAppDefinition
  * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
  * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null, managementApi: object}} An object containing the application definition.
+ * @returns {{integrations: Array<object>, entities: object | null, entityTypeRegistry: Map<string, object>, moduleDefinitions: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null, managementApi: object}} An object containing the application definition.
  * @throws {Error} Throws error if backend package.json cannot be found.
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
  * @example
@@ -57,6 +56,7 @@ function loadAppDefinition() {
 
     const {
         integrations = [],
+        entities = null,
         user: userConfig = null,
         adminScripts = [],
         reports = [],
@@ -65,7 +65,13 @@ function loadAppDefinition() {
         managementApi = {},
     } = appDefinition;
 
-    registerCredentialLogKeys(appDefinition, integrations);
+    // Fail fast: a bad `entities` registry (key/name mismatch, conflicting
+    // definitions, `$infer: false` with an unregistered module) must stop the
+    // app at load, not on the first request that needs a module.
+    const entityTypeRegistry = getEntityTypeRegistry(appDefinition);
+    const moduleDefinitions = getEntityTypeDefinitions(entityTypeRegistry);
+
+    registerCredentialLogKeys(appDefinition, moduleDefinitions);
 
     // Degrade consistently: an invalid telemetry block must never take down a
     // router bundle that loads the app definition at module scope (telemetry is
@@ -90,6 +96,9 @@ function loadAppDefinition() {
 
     return {
         integrations,
+        entities,
+        entityTypeRegistry,
+        moduleDefinitions,
         userConfig,
         adminScripts,
         reports,

package/handlers/backend-utils.js

@@ -18,8 +18,9 @@ const {
     createModuleRepository,
 } = require('../modules/repositories/module-repository-factory');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../modules/entity-type-registry');
 const { processNotFound } = require('../integrations/use-cases/process-errors');
 
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
@@ -61,30 +62,18 @@ const initializeRepositories = () => {
     return { processRepository, integrationRepository, moduleRepository };
 };
 
-const createModuleFactoryWithDefinitions = (
-    moduleRepository,
-    integrationClasses
-) => {
-    const moduleDefinitions =
-        getModulesDefinitionFromIntegrationClasses(integrationClasses);
-
-    return new ModuleFactory({
-        moduleRepository,
-        moduleDefinitions,
-    });
-};
-
 const loadIntegrationForWebhook = async (integrationId) => {
     const { loadAppDefinition } = require('./app-definition-loader');
-    const { integrations: integrationClasses } = loadAppDefinition();
+    const { integrations: integrationClasses, moduleDefinitions } =
+        loadAppDefinition();
 
     const { integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(
+    const moduleFactory = new ModuleFactory({
         moduleRepository,
-        integrationClasses
-    );
+        moduleDefinitions,
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -129,13 +118,23 @@ const integrationExists = async (integrationId) => {
     }
 };
 
-const loadIntegrationForProcess = async (processId, integrationClass) => {
+const loadIntegrationForProcess = async (
+    processId,
+    integrationClass,
+    moduleDefinitions
+) => {
     const { processRepository, integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(moduleRepository, [
-        integrationClass,
-    ]);
+    const moduleFactory = new ModuleFactory({
+        moduleRepository,
+        moduleDefinitions:
+            moduleDefinitions ??
+            // No app definition handed in: this integration's own modules only.
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -161,7 +160,13 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
     return instance;
 };
 
-const createQueueWorker = (integrationClass) => {
+/**
+ * @param {Function} integrationClass
+ * @param {{moduleDefinitions?: Array<object>}} [options] - the app's offered
+ *   module definitions (`loadAppDefinition().moduleDefinitions`). When omitted
+ *   the worker hydrates with this integration's own modules only.
+ */
+const createQueueWorker = (integrationClass, { moduleDefinitions } = {}) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
@@ -183,7 +188,8 @@ const createQueueWorker = (integrationClass) => {
                     console.log(`[QueueWorker] hydrating by processId`, logCtx);
                     integrationInstance = await loadIntegrationForProcess(
                         params.data.processId,
-                        integrationClass
+                        integrationClass,
+                        moduleDefinitions
                     );
                     console.log(`[QueueWorker] hydrated`, {
                         ...logCtx,

package/handlers/routers/health.js

@@ -2,9 +2,6 @@ const { Router } = require('express');
 const { createAppHandler } = require('./../app-handler-helpers');
 const { loadAppDefinition } = require('./../app-definition-loader');
 const { ModuleFactory } = require('../../modules/module-factory');
-const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
@@ -45,7 +42,7 @@ try {
     integrationClasses = appDef.integrations || [];
 
     const moduleRepository = createModuleRepository();
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrationClasses);
+    const { moduleDefinitions } = appDef;
 
     moduleFactory = new ModuleFactory({
         moduleRepository,

package/handlers/workers/integration-defined-workers.js

@@ -10,10 +10,13 @@ const { createQueueWorker } = require('../backend-utils');
 // const { getExtensionWorkers } = require('../../integrations/extension');
 
 const handlers = {};
-const { integrations: integrationClasses } = loadAppDefinition();
+const { integrations: integrationClasses, moduleDefinitions } =
+    loadAppDefinition();
 
 integrationClasses.forEach((IntegrationClass) => {
-    const defaultQueueWorker = createQueueWorker(IntegrationClass);
+    const defaultQueueWorker = createQueueWorker(IntegrationClass, {
+        moduleDefinitions,
+    });
 
     handlers[`${IntegrationClass.Definition.name}`] = {
         queueWorker: createHandler({

package/index.js

@@ -63,7 +63,6 @@ const {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
-    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
 } = require('./integrations/index');
 const {
@@ -99,6 +98,8 @@ const {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
 } = require('./modules/index');
 const application = require('./application');
 const utils = require('./utils');
@@ -150,7 +151,6 @@ module.exports = {
     Options,
     checkRequiredParams,
     createIntegrationRouter,
-    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     CreateProcess,
     UpdateProcessState,
@@ -206,6 +206,8 @@ module.exports = {
     Requester,
     ModuleConstants,
     ModuleFactory,
+    getEntityTypeRegistry,
+    EntityRegistryError,
     // queues
     QueuerUtil,
 

package/integrations/index.js

@@ -4,9 +4,6 @@ const {
     createIntegrationRouter,
     checkRequiredParams,
 } = require('./integration-router');
-const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('./utils/map-integration-dto');
 const {
     LoadIntegrationContextUseCase,
 } = require('./use-cases/load-integration-context');
@@ -21,7 +18,6 @@ module.exports = {
     Options,
     createIntegrationRouter,
     checkRequiredParams,
-    getModulesDefinitionFromIntegrationClasses,
     LoadIntegrationContextUseCase,
     validateExtensionBinding,
     getExtensionRoutes,

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');
@@ -74,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();
@@ -108,8 +110,7 @@ function createIntegrationRouter() {
 
     const moduleFactory = new ModuleFactory({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
     const deleteIntegrationForUser = new DeleteIntegrationForUser({
         integrationRepository,
@@ -136,8 +137,7 @@ function createIntegrationRouter() {
 
     const getEntitiesForUser = new GetEntitiesForUser({
         moduleRepository,
-        moduleDefinitions:
-            getModulesDefinitionFromIntegrationClasses(integrationClasses),
+        moduleDefinitions,
     });
 
     const getIntegrationInstance = new GetIntegrationInstance({
@@ -153,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({
@@ -194,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,8 +26,9 @@ 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');
@@ -70,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();
@@ -200,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);
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.671.e50fe9c.0",
+    "version": "2.0.0--canary.680.b3ca7f1.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -47,9 +47,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.671.e50fe9c.0",
-        "@friggframework/prettier-config": "2.0.0--canary.671.e50fe9c.0",
-        "@friggframework/test": "2.0.0--canary.671.e50fe9c.0",
+        "@friggframework/eslint-config": "2.0.0--canary.680.b3ca7f1.0",
+        "@friggframework/prettier-config": "2.0.0--canary.680.b3ca7f1.0",
+        "@friggframework/test": "2.0.0--canary.680.b3ca7f1.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -89,5 +89,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "e50fe9c3d910653eef00ca7248658e7a7f637493"
+    "gitHead": "b3ca7f1295d79b4d0cb5fb9fb4ec41093033ba4d"
 }

package/types/index.d.ts

@@ -12,3 +12,4 @@
 /// <reference path="./eslint-config/index.d.ts" />
 /// <reference path="./associations/index.d.ts" />
 /// <reference path="./syncs/index.d.ts" />
+/// <reference path="./modules/index.d.ts" />

package/types/modules/index.d.ts

@@ -0,0 +1,58 @@
+declare module "@friggframework/core" {
+  /** Where an entity type comes from: the app's `entities` map or an integration binding it. */
+  export type EntityTypeSource =
+    | { kind: "app" }
+    | { kind: "integration"; name: string };
+
+  export type EntityScope = "individual" | "organization" | "global";
+
+  /** App-level settings carried from the `entities` entry; empty for an inferred-only type. */
+  export interface EntityTypeSettings {
+    scope?: EntityScope | { default?: EntityScope; allow?: EntityScope[] };
+    proxy?: Record<string, unknown>;
+    display?: Record<string, unknown>;
+  }
+
+  export interface EntityTypeEntry {
+    /** The API module definition. */
+    definition: any;
+    /** Frozen. `{ kind: 'app' }` first when registered, then each binding integration. */
+    sources: readonly EntityTypeSource[];
+    /** Frozen. */
+    settings: Readonly<EntityTypeSettings>;
+  }
+
+  /** Entity type name (the definition's moduleName) to its entry. */
+  export type EntityTypeRegistry = Map<string, EntityTypeEntry>;
+
+  /** One `appDefinition.entities` entry. The key must equal the definition's moduleName (and getName() when defined). */
+  export interface EntityRegistration extends EntityTypeSettings {
+    definition: any;
+  }
+
+  export interface AppDefinitionEntities {
+    /** false turns inference off: every module an integration binds must be registered. Default true. */
+    $infer?: boolean;
+    [entityType: string]: EntityRegistration | boolean | undefined;
+  }
+
+  export interface AppDefinition {
+    integrations: any[];
+    /** App-level entity type registry (ADR-059). */
+    entities?: AppDefinitionEntities;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Builds the registry from `entities` plus the modules integrations bind.
+   * Throws EntityRegistryError on an invalid registry.
+   */
+  export function getEntityTypeRegistry(
+    appDefinition?: Pick<AppDefinition, "entities" | "integrations">
+  ): EntityTypeRegistry;
+
+  /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
+  export class EntityRegistryError extends Error {
+    code: "ENTITY_REGISTRY_INVALID";
+  }
+}