@friggframework/core 2.0.0--canary.681.2df9ef0.0 → 2.0.0--canary.683.f45da33.0

package/modules/scope-visibility.js

@@ -0,0 +1,212 @@
+/**
+ * Which stored rows a caller may see and use (ADR-056 §3.4, §3.6).
+ *
+ * No I/O. One clause list (`ctx.clauses`) is what a repository is asked for and
+ * what `describeRecord` checks every returned row against, so a list and an
+ * access check cannot drift apart. The clauses are built once per request, when
+ * the access context is.
+ */
+
+const { isPresent, idString, sameId } = require('../user/membership');
+const { AUTH_SOURCES } = require('../user/user');
+const { SCOPES, ACCESS, DEFAULT_ORG_ADMIN_ROLES } = require('./scope-resolution');
+
+/**
+ * One owner/organization pair a repository ORs into a single query.
+ * `userId` is the owner's user id, and for an organization-owned row that is
+ * the ORGANIZATION user's id, not a person's. `organizationId: null` means "has
+ * no organization" (unset or null); otherwise the id of the organization.
+ *
+ * @typedef {Object} OwnershipClause
+ * @property {string} userId
+ * @property {(string|null)} organizationId
+ */
+
+/**
+ * Whether the caller's own rows with no organization belong to the context this
+ * request acts in: always when it acts in no organization (today's behaviour),
+ * always for an entity under `individualAcross: 'all'`, and otherwise only in
+ * the person's legacy organization.
+ */
+function unscopedRowsBelongHere(base, kind) {
+    return (
+        !base.activeOrgId ||
+        (kind === 'entity' && base.individualAcross === 'all') ||
+        sameId(base.legacyOrgId, base.activeOrgId)
+    );
+}
+
+/**
+ * What a caller may see, as owner/organization pairs:
+ *
+ *   - the active organization's own rows (owner = the organization), whether
+ *     they carry its id or, written before scoping, none;
+ *   - the caller's rows in the active organization;
+ *   - the caller's rows with no organization, when `unscopedRowsBelongHere`.
+ *
+ * `kind` is 'entity' or 'integration'; only entities may be
+ * organization-independent under 'all' (an integration always belongs to the
+ * organization it was created in).
+ *
+ * @returns {OwnershipClause[]}
+ */
+function buildClauses(base, kind) {
+    const clauses = [];
+    if (base.activeOrgId) {
+        clauses.push({ userId: base.activeOrgId, organizationId: base.activeOrgId });
+        clauses.push({ userId: base.activeOrgId, organizationId: null });
+    }
+    if (base.callerId) {
+        if (base.activeOrgId) {
+            clauses.push({ userId: base.callerId, organizationId: base.activeOrgId });
+        }
+        if (unscopedRowsBelongHere(base, kind)) {
+            clauses.push({ userId: base.callerId, organizationId: null });
+        }
+    }
+    return clauses;
+}
+
+/**
+ * Whether the caller may manage organization-level things (create, change,
+ * delete). A shared-secret caller is the app's own backend and may. A person
+ * with a token has the role the token carries, and `MEMBER` when it carries
+ * none: a missing role never means admin. An unknown source (a `User` built
+ * outside AuthenticateUser) is treated like a token.
+ *
+ * @param {{authSource: (string|null), orgRole: (string|null)}} who
+ * @param {string[]} adminRoles - `user.orgAdminRoles`, compared case-insensitively
+ */
+function canManageOrganization({ authSource, orgRole }, adminRoles = DEFAULT_ORG_ADMIN_ROLES) {
+    if (authSource === AUTH_SOURCES.SHARED_SECRET) return true;
+    const role = String(isPresent(orgRole) ? orgRole : 'MEMBER').toUpperCase();
+    return adminRoles.some((admin) => String(admin).toUpperCase() === role);
+}
+
+/**
+ * Who the caller is, for ownership and visibility: their individual user, the
+ * organization this request acts in, the legacy `organizationId` pointer,
+ * whether they may manage organization-level things, and the clauses that
+ * follow from them (computed once).
+ *
+ * @param {Object} user - the authenticated `User` (or a `{ getId }` double)
+ * @param {{individualAcross?: string, orgAdminRoles?: string[]}} [options]
+ */
+function accessContext(
+    user,
+    { individualAcross = 'organization', orgAdminRoles = DEFAULT_ORG_ADMIN_ROLES } = {}
+) {
+    const hasUserModel = typeof user?.getIndividualUser === 'function';
+    const individual = hasUserModel ? user.getIndividualUser() : null;
+    const base = {
+        callerId: hasUserModel ? idString(individual?.id) : idString(user?.getId?.()),
+        activeOrgId:
+            typeof user?.getActiveOrganizationId === 'function'
+                ? idString(user.getActiveOrganizationId())
+                : null,
+        legacyOrgId: idString(individual?.organizationId),
+        individualAcross,
+    };
+    const who = {
+        authSource:
+            typeof user?.getAuthSource === 'function' ? user.getAuthSource() : null,
+        orgRole: typeof user?.getOrgRole === 'function' ? user.getOrgRole() : null,
+    };
+    return {
+        ...base,
+        canManageOrg: canManageOrganization(who, orgAdminRoles),
+        clauses: {
+            entity: buildClauses(base, 'entity'),
+            integration: buildClauses(base, 'integration'),
+        },
+    };
+}
+
+/** The clauses for `kind` ('entity' | 'integration'): what to ask the repository. */
+const visibilityClauses = (ctx, kind) => ctx.clauses[kind];
+
+const matchesClause = (record, clause) =>
+    sameId(record.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? !isPresent(record.organizationId)
+        : sameId(record.organizationId, clause.organizationId));
+
+/** The scope a stored row has for this caller, from its owner. */
+function scopeOf(record, ctx) {
+    if (!isPresent(record?.userId)) return SCOPES.GLOBAL;
+    if (sameId(record.userId, ctx.activeOrgId)) return SCOPES.ORGANIZATION;
+    if (sameId(record.userId, ctx.callerId)) return SCOPES.INDIVIDUAL;
+    return null;
+}
+
+/** manage for the person's own; for the organization's, only an admin; use otherwise. */
+const accessFor = (scope, ctx) => {
+    if (scope === SCOPES.INDIVIDUAL) return ACCESS.MANAGE;
+    if (scope === SCOPES.ORGANIZATION) {
+        return ctx.canManageOrg ? ACCESS.MANAGE : ACCESS.USE;
+    }
+    return ACCESS.USE;
+};
+
+/**
+ * What the caller may do with a record owned by `ownerId` that carries no
+ * organization of its own (a credential): manage the person's own, manage the
+ * active organization's only as an admin, nothing otherwise. Null when the
+ * record is not theirs.
+ */
+function accessToOwner(ownerId, ctx) {
+    const scope = scopeOf({ userId: ownerId }, ctx);
+    if (scope !== SCOPES.INDIVIDUAL && scope !== SCOPES.ORGANIZATION) return null;
+    return accessFor(scope, ctx);
+}
+
+/**
+ * What a row is to this caller, or null when they may not see it.
+ * `{ scope, owner: {type, id}, organizationId, access }` (§3.4). A `global`
+ * row is never described: it is not the tenant's to see.
+ */
+function describeRecord(record, ctx, kind) {
+    if (!record) return null;
+    const scope = scopeOf(record, ctx);
+    if (scope === null || scope === SCOPES.GLOBAL) return null;
+    if (!ctx.clauses[kind].some((clause) => matchesClause(record, clause))) {
+        return null;
+    }
+    return {
+        scope,
+        owner: { type: scope, id: idString(record.userId) },
+        organizationId:
+            scope === SCOPES.ORGANIZATION
+                ? idString(record.userId)
+                : idString(record.organizationId),
+        access: accessFor(scope, ctx),
+    };
+}
+
+/** `?owner=` values and the scope each one means. */
+const LIST_OWNERS = Object.freeze({
+    me: SCOPES.INDIVIDUAL,
+    org: SCOPES.ORGANIZATION,
+});
+
+/** Whether a described row passes `?scope=` and `?owner=`. */
+function matchesListFilters(description, { scope, owner } = {}) {
+    if (scope !== undefined && description.scope !== scope) return false;
+    if (owner !== undefined && description.owner.type !== LIST_OWNERS[owner]) {
+        return false;
+    }
+    return true;
+}
+
+module.exports = {
+    canManageOrganization,
+    accessToOwner,
+    accessContext,
+    unscopedRowsBelongHere,
+    visibilityClauses,
+    matchesClause,
+    scopeOf,
+    describeRecord,
+    LIST_OWNERS,
+    matchesListFilters,
+};

package/modules/tests/doubles/ownership-matching.js

@@ -0,0 +1,18 @@
+/**
+ * Test double helper: answers an owner/organization clause the way a database
+ * does, so in-memory repositories run the clauses a use case hands them.
+ * `clause.organizationId === null` matches a row with no organization (unset
+ * or null).
+ */
+const same = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b);
+
+const matchesClause = (row, clause) =>
+    same(row.userId, clause.userId) &&
+    (clause.organizationId === null
+        ? row.organizationId === null || row.organizationId === undefined
+        : same(row.organizationId, clause.organizationId));
+
+const matchesAnyClause = (row, clauses) => clauses.some((clause) => matchesClause(row, clause));
+
+module.exports = { same, matchesClause, matchesAnyClause };

package/modules/use-cases/authorize-entity-for-user.js

@@ -0,0 +1,59 @@
+/**
+ * Authorizes an entity for a caller: decides who will own it and in which
+ * organization (ADR-056 §3.2, §3.6), then runs the module's authorization.
+ * Shared by the v1 `POST /api/authorize` and the v2 authorize flow, so the
+ * owner is decided in one place and never by `user.primary`.
+ */
+class AuthorizeEntityForUser {
+    /**
+     * @param {Object} params
+     * @param {Object} params.scopePolicy - from createScopePolicy
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     */
+    constructor({ scopePolicy, processAuthorizationCallback }) {
+        this.scopePolicy = scopePolicy;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+    }
+
+    /**
+     * The scope, owner and organization a new entity of `entityType` gets for
+     * this caller. Throws a 400/403 when the request cannot have one.
+     *
+     * @param {{user: Object, entityType: string, scope?: string}} params
+     */
+    resolveOwnership({ user, entityType, scope }) {
+        return this.scopePolicy.resolveOwnership({
+            entityType,
+            requestScope: scope,
+            user,
+        });
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {Object} params.data - what the module's authorization needs
+     * @param {string} [params.scope] - the scope the request asks for
+     * @param {Object} [params.ownership] - from `resolveOwnership`, when the
+     *   caller needed it earlier (a multi-step flow does)
+     * @returns {Promise<{result: Object, ownership: Object}>} the callback's
+     *   `{ credential_id, entity_id, type }` and the ownership it ran with
+     */
+    async execute({ user, entityType, data, scope, ownership }) {
+        const resolved = ownership ?? this.resolveOwnership({ user, entityType, scope });
+        const result = await this.processAuthorizationCallback.execute(
+            resolved.ownerId,
+            entityType,
+            data,
+            {
+                scope: resolved.scope,
+                organizationId: resolved.organizationId,
+                legacyOrgId: resolved.legacyOrgId,
+            }
+        );
+        return { result, ownership: resolved };
+    }
+}
+
+module.exports = { AuthorizeEntityForUser };

package/modules/use-cases/entity-operations-for-user.js

@@ -1,4 +1,11 @@
 const Boom = require('@hapi/boom');
+const {
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+} = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
+const { assertCanManage } = require('./manage-access');
 
 /**
  * Management API v2 entity operations. Each one starts from
@@ -6,29 +13,55 @@ const Boom = require('@hapi/boom');
  * (missing or foreign entity = 404).
  */
 
-/** The caller's connected entities. */
+/**
+ * The entities the caller may see in the active organization (ADR-056 §3.4,
+ * §3.6): the organization's own, and the caller's individual ones by the
+ * visibility rule. Each carries `tenancy` ({scope, owner, organizationId,
+ * access}); the stored entity is otherwise untouched.
+ */
 class ListEntitiesForUser {
-    constructor({ moduleRepository }) {
+    constructor({ moduleRepository, scopePolicy }) {
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
-    /** @param {Object} user - authenticated User */
-    async execute(user) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            user.getId()
+    /**
+     * @param {Object} user - authenticated User
+     * @param {{scope?: string, owner?: string}} [filters] - `?scope=` and `?owner=`
+     */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const entities = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
         );
-        return Array.isArray(entities) ? entities : [];
+        const listed = [];
+        for (const entity of Array.isArray(entities) ? entities : []) {
+            // The query is the filter; this is the same rule applied again,
+            // so a repository that returns too much cannot widen the list.
+            const tenancy = describeRecord(entity, ctx, 'entity');
+            if (tenancy && matchesListFilters(tenancy, filters)) {
+                listed.push({ ...entity, tenancy });
+            }
+        }
+        return listed;
     }
 }
 
-/** One entity the caller owns. */
+/** One entity the caller may use, with its `tenancy`. */
 class GetEntityForUser {
     constructor({ getEntityModuleForUser }) {
         this.getEntityModuleForUser = getEntityModuleForUser;
     }
 
     async execute(entityId, user) {
-        return this.getEntityModuleForUser.loadOwnedEntity(entityId, user);
+        const entity = await this.getEntityModuleForUser.loadOwnedEntity(
+            entityId,
+            user
+        );
+        return {
+            ...entity,
+            tenancy: this.getEntityModuleForUser.describe(entity, user),
+        };
     }
 }
 
@@ -79,10 +112,10 @@ class RefreshEntityOptionsForUser {
 }
 
 /**
- * Deletes an entity the caller owns. Refuses with 409 while integrations
- * still use it, so an integration never points at a missing entity. The
- * credential is left alone (others may share it); delete it through
- * /api/v2/credentials.
+ * Deletes an entity the caller may manage (the owner; for an organization
+ * entity, an organization admin). Refuses with 409 while integrations still
+ * use it, so an integration never points at a missing entity. The credential
+ * is left alone (others may share it); delete it through /api/v2/credentials.
  */
 class DeleteEntityForUser {
     constructor({ getEntityModuleForUser, moduleRepository, integrationRepository }) {
@@ -96,6 +129,10 @@ class DeleteEntityForUser {
             entityId,
             user
         );
+        assertCanManage(
+            this.getEntityModuleForUser.describe(entity, user)?.access,
+            `entity ${entity.id}`
+        );
         const integrations =
             (await this.integrationRepository.findIntegrationsByEntityId(
                 entity.id

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,74 @@ function findDefinition(moduleDefinitions, entityType) {
     return definition;
 }
 
-/** Lists the entity types (API modules) this app can authorize. */
+/**
+ * With a scope policy the entry also says which scope a new connection gets
+ * and which a request may choose (ADR-056 §3.1), so a UI can offer the choice.
+ * `global` is never offered: a tenant request cannot create one.
+ */
+const scopeOf = (scopePolicy, name, user) => {
+    if (!scopePolicy) return {};
+    const { scope, source, allow } = scopePolicy.resolveScope({
+        entityType: name,
+        user,
+    });
+    return {
+        scope: {
+            default: scope,
+            allow: allow.filter((value) => value !== 'global'),
+            source,
+        },
+    };
+};
+
+const describeEntry = (name, entry, scopePolicy, user) => ({
+    // The registry key is the name the API uses, whatever the definition spells.
+    ...describeEntityType(entry.definition, name),
+    usedBy: usedByOf(entry),
+    ...scopeOf(scopePolicy, name, user),
+});
+
+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, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute() {
-        return this.moduleDefinitions
-            .map(describeEntityType)
+    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
+    async execute({ user } = {}) {
+        return [...this.registry]
+            .map(([name, entry]) => describeEntry(name, entry, this.scopePolicy, user))
             .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, scopePolicy }) {
+        this.registry = requireRegistry(entityTypeRegistry);
+        this.scopePolicy = scopePolicy;
     }
 
-    async execute(entityType) {
-        return describeEntityType(findDefinition(this.moduleDefinitions, entityType));
+    async execute(entityType, { user } = {}) {
+        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, this.scopePolicy, user);
     }
 }
 

package/modules/use-cases/execute-entity-proxy-request.js

@@ -98,9 +98,24 @@ class ExecuteEntityProxyRequest {
             audit.requestBytes = validated.requestBytes;
             const path = normalizeProxyPath(validated.path);
 
+            // Access is `use` in the active organization (ADR-056 §3.5, §3.6): the
+            // owner's entity there, or the organization's. A `global` entity is
+            // never the tenant's.
             const { entity, definition, module } =
                 await this.getEntityModuleForUser.execute(entityId, user);
             audit.module = definition.moduleName;
+            // Narrowest by default (§3.5): proxying through a shared credential
+            // lets any member act on the organization's account, so only an
+            // individual entity may be proxied until `managementApi.proxy.scopes`
+            // lets an app opt in to `organization`.
+            // TODO(F6): read proxy.scopes here instead of refusing outright.
+            if (this.getEntityModuleForUser.describe(entity, user)?.scope !== 'individual') {
+                throw new ProxyRequestError(
+                    'PROXY_NOT_ALLOWED',
+                    'The entity proxy only accepts individual entities; organization-level entities are not proxied',
+                    { module: definition.moduleName, reason: 'scope' }
+                );
+            }
             const credentialRef = entity.credential;
             const credentialId =
                 credentialRef && typeof credentialRef === 'object'

package/modules/use-cases/get-entities-for-user.js

@@ -1,8 +1,11 @@
 const { Module } = require('../module');
 const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+const { describeRecord, visibilityClauses } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntitiesForUser {
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
 
         this.definitionMap = new Map();
@@ -11,16 +14,24 @@ class GetEntitiesForUser {
         }
     }
 
-    async execute(userId) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            userId
+    /**
+     * The entities a `User` may see in the active organization (ADR-056 §3.6).
+     * @param {Object} user - authenticated User
+     */
+    async execute(user) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const found = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
+        );
+        const entities = (found || []).filter((entity) =>
+            describeRecord(entity, ctx, 'entity')
         );
 
         return entities.map((entity) => {
             const definition = this.definitionMap.get(entity.moduleName);
 
             const moduleInstance = new Module({
-                userId,
+                userId: entity.userId,
                 definition: definition,
                 entity: entity,
             });

package/modules/use-cases/get-entity-module-for-user.js

@@ -1,8 +1,13 @@
 const Boom = require('@hapi/boom');
+const { describeRecord } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 /**
  * True when `user` may act on records owned by `ownerId`. Uses the User
  * domain object's rule (individual or organisation user model) when present.
+ * This is the owner-only rule: it ignores the organization a record belongs
+ * to, so it no longer decides access to an entity or an integration
+ * (modules/scope-visibility.js does). Credentials still use it.
  * @param {Object} user - authenticated User (or a plain { getId } double)
  * @param {string|number} ownerId
  */
@@ -30,8 +35,11 @@ class GetEntityModuleForUser {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {Array<Object>} params.moduleDefinitions
      * @param {Function} [params.createModule] - builds a Module; injectable for tests.
+     * @param {Object} [params.scopePolicy] - from createScopePolicy; with none the
+     *   app configures nothing (ADR-056 §3.1).
      */
-    constructor({ moduleRepository, moduleDefinitions, createModule }) {
+    constructor({ moduleRepository, moduleDefinitions, createModule, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions || [];
         this.createModule = createModule || defaultCreateModule;
@@ -61,7 +69,11 @@ class GetEntityModuleForUser {
         return { entity, definition, module };
     }
 
-    /** The entity record, or a 404 when it is missing or not the caller's. */
+    /**
+     * The entity record, or a 404 when it is missing or the caller may not use
+     * it: not theirs, or paired with another organization (ADR-056 §3.6). A
+     * `global` entity is never the tenant's to load.
+     */
     async loadOwnedEntity(entityId, user) {
         let entity = null;
         try {
@@ -74,13 +86,21 @@ class GetEntityModuleForUser {
                 throw error;
             }
         }
-        if (!entity || !userOwns(user, entity.userId)) {
+        if (!entity || !this.describe(entity, user)) {
             throw Boom.notFound(`Entity ${entityId} not found`, {
                 code: 'ENTITY_NOT_FOUND',
             });
         }
         return entity;
     }
+
+    /**
+     * `{ scope, owner, organizationId, access }` of an entity to this caller,
+     * or null when they may not see it (§3.4).
+     */
+    describe(entity, user) {
+        return describeRecord(entity, this.scopePolicy.accessContext(user), 'entity');
+    }
 }
 
 module.exports = { GetEntityModuleForUser, userOwns };

package/modules/use-cases/get-entity-options-by-id.js

@@ -1,4 +1,5 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntityOptionsById {
     /**
@@ -6,9 +7,11 @@ class GetEntityOptionsById {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {} params.moduleDefinitions
      */
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -35,7 +38,7 @@ class GetEntityOptionsById {
 
         // Validate entity ownership
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {