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

package/integrations/use-cases/get-integrations-for-user.js

@@ -2,9 +2,17 @@
 const {
     mapIntegrationClassToIntegrationDTO,
 } = require('../utils/map-integration-dto');
+const {
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+} = require('../../modules/scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
 
 /**
- * Use case for retrieving all integrations for a specific user.
+ * Use case for retrieving the integrations a caller may see: the ones they own
+ * or their active organization owns, created in that organization (ADR-056
+ * §3.6), each with `tenancy` ({scope, owner, organizationId, access}).
  * @class GetIntegrationsForUser
  */
 class GetIntegrationsForUser {
@@ -15,13 +23,16 @@ class GetIntegrationsForUser {
      * @param {Array<import('../integration').Integration>} params.integrationClasses - Array of available integration classes.
      * @param {import('../../modules/module-factory').ModuleFactory} params.moduleFactory - Service for module instantiation and management.
      * @param {import('../../modules/repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module and entity data operations.
+     * @param {Object} [params.scopePolicy] - from createScopePolicy
      */
     constructor({
         integrationRepository,
         integrationClasses,
         moduleFactory,
         moduleRepository,
+        scopePolicy,
     }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         /**
          * @type {import('../repositories/integration-repository-interface').IntegrationRepositoryInterface}
          */
@@ -32,57 +43,86 @@ class GetIntegrationsForUser {
     }
 
     /**
-     * Executes the retrieval of all integrations for a user.
      * @async
-     * @param {string} userId - ID of the user whose integrations to retrieve.
-     * @returns {Promise<Object[]>} Array of integration DTOs for the specified user.
+     * @param {Object} user - authenticated User
+     * @param {{scope?: string, owner?: string}} [filters] - `?scope=` and `?owner=`
+     * @returns {Promise<Object[]>} Array of integration DTOs.
      */
-    async execute(userId) {
-        const integrationRecords =
-            await this.integrationRepository.findIntegrationsByUserId(userId);
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const records = await this.integrationRepository.findIntegrationsByOwnership(
+            visibilityClauses(ctx, 'integration')
+        );
 
         const integrations = [];
+        for (const record of records) {
+            // The query is the filter; the same rule again means a repository
+            // that returns too much cannot widen the list.
+            const tenancy = describeRecord(record, ctx, 'integration');
+            if (!tenancy || !matchesListFilters(tenancy, filters)) continue;
+            integrations.push({ ...(await this.toDto(record)), tenancy });
+        }
+        return integrations;
+    }
 
-        for (const integrationRecord of integrationRecords) {
-            const entities = await this.moduleRepository.findEntitiesByIds(
-                integrationRecord.entitiesIds
-            );
+    /** Hydrates one stored integration record into its DTO. */
+    async toDto(integrationRecord) {
+        const entities = await this.moduleRepository.findEntitiesByIds(
+            integrationRecord.entitiesIds
+        );
+
+        const integrationClass = this.integrationClasses.find(
+            (integrationClass) =>
+                integrationClass.Definition.name ===
+                integrationRecord.config.type
+        );
 
-            const integrationClass = this.integrationClasses.find(
-                (integrationClass) =>
-                    integrationClass.Definition.name ===
-                    integrationRecord.config.type
+        const modules = [];
+        for (const entity of entities) {
+            const moduleInstance = await this.moduleFactory.getModuleInstance(
+                entity.id,
+                integrationRecord.userId
             );
+            modules.push(moduleInstance);
+        }
 
-            const modules = [];
-            for (const entity of entities) {
-                const moduleInstance =
-                    await this.moduleFactory.getModuleInstance(
-                        entity.id,
-                        integrationRecord.userId
-                    );
-                modules.push(moduleInstance);
-            }
+        return mapIntegrationClassToIntegrationDTO({
+            id: integrationRecord.id,
+            userId: integrationRecord.userId,
+            entities: entities,
+            config: integrationRecord.config,
+            status: integrationRecord.status,
+            version: integrationRecord.version,
+            messages: integrationRecord.messages || { errors: [], warnings: [] },
+            modules,
+            options: integrationClass.getOptionDetails(),
+        });
+    }
+}
 
-            const integrationData = {
-                id: integrationRecord.id,
-                userId: integrationRecord.userId,
-                entities: entities,
-                config: integrationRecord.config,
-                status: integrationRecord.status,
-                version: integrationRecord.version,
-                messages: integrationRecord.messages || { errors: [], warnings: [] },
-                modules,
-                options: integrationClass.getOptionDetails(),
-            };
+/**
+ * Every integration one user id owns, with no organization rules: the lookup
+ * behind the app-level `friggCommands.findIntegrationsByUserId`, which has a
+ * user id and no request.
+ */
+class GetIntegrationsByUserId {
+    /** @param {ConstructorParameters<typeof GetIntegrationsForUser>[0]} params */
+    constructor(params) {
+        this.integrationRepository = params.integrationRepository;
+        this.hydrator = new GetIntegrationsForUser(params);
+    }
 
-            integrations.push(
-                mapIntegrationClassToIntegrationDTO(integrationData)
-            );
+    /** @param {string} userId */
+    async execute(userId) {
+        const records = await this.integrationRepository.findIntegrationsByUserId(
+            userId
+        );
+        const integrations = [];
+        for (const record of records) {
+            integrations.push(await this.hydrator.toDto(record));
         }
-
         return integrations;
     }
 }
 
-module.exports = { GetIntegrationsForUser };
+module.exports = { GetIntegrationsForUser, GetIntegrationsByUserId };

package/integrations/use-cases/index.js

@@ -1,4 +1,7 @@
-const { GetIntegrationsForUser } = require('./get-integrations-for-user');
+const {
+    GetIntegrationsForUser,
+    GetIntegrationsByUserId,
+} = require('./get-integrations-for-user');
 const { DeleteIntegrationForUser } = require('./delete-integration-for-user');
 const { CreateIntegration } = require('./create-integration');
 const { GetIntegration } = require('./get-integration');
@@ -9,6 +12,7 @@ const { GetProcess } = require('./get-process');
 
 module.exports = {
     GetIntegrationsForUser,
+    GetIntegrationsByUserId,
     DeleteIntegrationForUser,
     CreateIntegration,
     GetIntegration,

package/integrations/use-cases/integration-operations-for-user.js

@@ -1,11 +1,14 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+const { describeRecord } = require('../../modules/scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { isIntegrationNotFound } = require('../repositories/integration-not-found');
 
 /**
- * Management API v2 integration operations. They put an ownership check
- * (missing or foreign integration = 404) in front of the existing
- * integration use cases, and pass the record's owner id on, so the
- * organisation user model works the same as for entities.
+ * Management API v2 integration operations. They put an access check
+ * (missing or unavailable integration = 404) in front of the existing
+ * integration use cases, and pass the record's owner id on. Access follows
+ * the owner and the organization the integration was created in (ADR-056
+ * §3.6), not the owner alone.
  */
 
 const notFound = (integrationId) =>
@@ -13,10 +16,20 @@ const notFound = (integrationId) =>
         code: 'INTEGRATION_NOT_FOUND',
     });
 
-/** The integration record, or 404 when it is missing or not the caller's. */
+/**
+ * The integration record, or 404 when it is missing or the caller may not
+ * use it: not theirs or their active organization's, or created in another
+ * organization.
+ */
 class GetOwnedIntegrationRecord {
-    constructor({ integrationRepository }) {
+    constructor({ integrationRepository, scopePolicy }) {
         this.integrationRepository = integrationRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    }
+
+    /** `{ scope, owner, organizationId, access }` of a record to this caller, or null. */
+    describe(record, user) {
+        return describeRecord(record, this.scopePolicy.accessContext(user), 'integration');
     }
 
     async execute(integrationId, user) {
@@ -26,12 +39,15 @@ class GetOwnedIntegrationRecord {
                 integrationId
             );
         } catch (error) {
-            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+            if (
+                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '') ||
+                isIntegrationNotFound(error)
+            ) {
                 throw notFound(integrationId);
             }
             throw error;
         }
-        if (!record || !userOwns(user, record.userId)) {
+        if (!record || !this.describe(record, user)) {
             throw notFound(integrationId);
         }
         return record;
@@ -39,14 +55,15 @@ class GetOwnedIntegrationRecord {
 }
 
 /**
- * Creates (or reuses) an integration between entities the caller owns.
- * Unlike v1, the entities' ownership and the integration type are checked
- * before anything is written.
+ * Creates (or reuses) an integration between entities the caller may use.
+ * The entities' access, the binding scopes and the integration type are
+ * checked before anything is written, and the integration is owned and
+ * paired with an organization by `resolveIntegrationOwnership` (§3, §3.6).
  */
 class CreateIntegrationForUser {
-    constructor({ createIntegration, getEntityModuleForUser, integrationClasses }) {
+    constructor({ createIntegration, resolveIntegrationOwnership, integrationClasses }) {
         this.createIntegration = createIntegration;
-        this.getEntityModuleForUser = getEntityModuleForUser;
+        this.resolveIntegrationOwnership = resolveIntegrationOwnership;
         this.integrationClasses = integrationClasses || [];
     }
 
@@ -74,13 +91,17 @@ class CreateIntegrationForUser {
                 details: { field: 'entities' },
             });
         }
-        for (const entityId of entities) {
-            await this.getEntityModuleForUser.loadOwnedEntity(String(entityId), user);
-        }
+        const { ownerId, organizationId, adoptUnscoped } =
+            await this.resolveIntegrationOwnership.execute({
+                entityIds: entities,
+                config,
+                user,
+            });
         return this.createIntegration.execute(
             entities.map(String),
-            user.getId(),
-            config
+            ownerId,
+            config,
+            { organizationId, adoptUnscoped }
         );
     }
 }

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

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

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

@@ -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/management-api-config.js

@@ -16,6 +16,9 @@
  *     },
  * }
  * ```
+ *
+ * TODO(F6): `proxy.scopes` (ADR-056 §3.5) is not read yet; see
+ * ExecuteEntityProxyRequest.
  */
 
 // ADR-052 §7. API Gateway HTTP APIs time out at 30s and Lambda responses cap

package/management-api/openapi/components.js

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

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

@@ -34,6 +34,11 @@ const stepQuery = [
     query('step', 'Step number, 1-based (default 1)', { type: 'integer', minimum: 1 }),
     query('sessionId', 'Session from step 1; required for later steps'),
 ];
+// ADR-056 §3.4: the same two filters on every list that mixes ownership.
+const listFilters = [
+    query('scope', 'Only records of this scope', { type: 'string', enum: ['individual', 'organization'] }),
+    query('owner', 'Only the caller\'s own (`me`) or the active organization\'s (`org`)', { type: 'string', enum: ['me', 'org'] }),
+];
 const anyJson = { description: 'Defined by the integration or module' };
 
 const V2_OPERATIONS = {
@@ -41,7 +46,8 @@ const V2_OPERATIONS = {
     listIntegrations: {
         summary: "List the caller's integrations",
         description:
-            'Returns only `{ integrations }`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+            'Returns only `{ integrations }`: the caller\'s and the active organization\'s, created in that organization (ADR-056 §3.6). Each carries `scope`, `owner`, `organizationId` and `access`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+        parameters: listFilters,
         responses: { 200: ok('Integrations', ref('ListIntegrationsResponse')), ...errors('Unauthorized') },
     },
     listIntegrationOptions: {
@@ -108,14 +114,21 @@ const V2_OPERATIONS = {
     // Entities
     listEntities: {
         summary: "List the caller's connected entities",
+        description:
+            "The active organization's entities and the caller's individual ones (ADR-056 §3.6): an individual entity belongs to the organization it was connected in, unless `ownership.individualAcross` is `all`. Each carries `scope`, `owner`, `organizationId` and `access`.",
+        parameters: listFilters,
         responses: { 200: ok('Entities', ref('ListEntitiesResponse')), ...errors('Unauthorized') },
     },
     listEntityTypes: {
         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: {