@friggframework/core 2.0.0--canary.685.022c3c3.0 → 2.0.0--canary.683.8a84ab1.0

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

@@ -165,14 +165,14 @@ const V2_OPERATIONS = {
     proxyEntityRequest: {
         summary: "Call the entity's API through Frigg (beta)",
         description:
-            "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; deny by default, only operations in the module's (or the app's) allow-list. ADR-056 §3.5: the caller needs use access to the entity in the active organization (an entity they cannot see there is 404), and the entity's scope must be in managementApi.proxy.scopes (default individual only; 403 PROXY_NOT_ALLOWED with details.reason 'scope', or 'access' for view-only access). The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
+            "ADR-052. Off unless the app sets managementApi.proxy.enable. Path-only input relative to the module's base URL; deny by default, only operations in the module's (or the app's) allow-list. The HTTP status follows the upstream status; upstream 5xx is 502 UPSTREAM_ERROR, 429 keeps Retry-After.",
         requestBody: body(ref('ProxyRequest')),
         responses: {
             200: ok('Upstream answer (the status mirrors the upstream status)', ref('ProxyResponse')),
             400: ok('INVALID_PROXY_REQUEST', ref('ProxyError')),
             401: ok('INVALID_CREDENTIALS or unauthenticated', ref('ProxyError')),
-            403: ok("PROXY_NOT_ALLOWED: not in the allow-list, or details.reason 'scope' / 'access'", ref('ProxyError')),
-            404: ok('Entity not found, or not visible in the active organization', ref('Error')),
+            403: ok('PROXY_NOT_ALLOWED', ref('ProxyError')),
+            404: ok('Entity not found', ref('Error')),
             413: ok('PAYLOAD_TOO_LARGE', ref('ProxyError')),
             415: ok('UNSUPPORTED_MEDIA_TYPE', ref('ProxyError')),
             429: ok('RATE_LIMITED (Retry-After passed through)', ref('ProxyError')),
@@ -184,9 +184,6 @@ const V2_OPERATIONS = {
     // Credentials
     listCredentials: {
         summary: "List the caller's credentials (masked)",
-        description:
-            'A credential is listed through the entities that use it that the caller may see, so each organization lists only its own connections; one no entity uses is listed to its owner. Each carries `scope`, `owner`, `organizationId` and `access`, taken from who owns the credential.',
-        parameters: listFilters,
         responses: { 200: ok('Credentials', ref('ListCredentialsResponse')), ...errors('Unauthorized') },
     },
     getCredential: {

package/management-api/v2/dependencies.js

@@ -124,7 +124,6 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
         credentialRepository,
         moduleRepository,
-        scopePolicy,
     });
     const getAuthorizationRequirements = new GetAuthorizationRequirements({
         moduleDefinitions,
@@ -247,13 +246,13 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         listCredentialsForUser: new credentialOps.ListCredentialsForUser({
             credentialRepository,
             moduleRepository,
-            scopePolicy,
         }),
         getCredentialForUser,
         deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({
             credentialRepository,
             moduleRepository,
             getCredentialForUser,
+            scopePolicy,
         }),
         getCredentialReauthorization: new GetCredentialReauthorization({
             getCredentialForUser,
@@ -262,6 +261,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         reauthorizeCredentialForUser: new ReauthorizeCredentialForUser({
             getCredentialForUser,
             submitAuthorizationStep,
+            scopePolicy,
         }),
 
         // Authorization (multi-step)

package/management-api/v2/dto.js

@@ -75,8 +75,6 @@ const CREDENTIAL_METADATA = new Set([
     'type',
     'entityIds',
     'status',
-    // Added by the credential use cases (ADR-056 §3.4); never provider data.
-    'tenancy',
 ]);
 
 /**
@@ -128,7 +126,6 @@ function maskCredential(credential) {
         entityCount: entityIds.length,
         createdAt: toIso(credential.createdAt),
         updatedAt: toIso(credential.updatedAt),
-        ...tenancyFields(credential.tenancy),
         data,
     };
 }

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

@@ -1,5 +1,4 @@
 const { maskCredential } = require('../dto');
-const { parseListFilters } = require('../request');
 
 /** Management API v2 credential handlers, keyed by operationId. */
 function createCredentialHandlers(useCases) {
@@ -7,11 +6,8 @@ function createCredentialHandlers(useCases) {
         useCases;
 
     return {
-        async listCredentials(req, res, user) {
-            const credentials = await listCredentialsForUser.execute(
-                user,
-                parseListFilters(req.query)
-            );
+        async listCredentials(_req, res, user) {
+            const credentials = await listCredentialsForUser.execute(user);
             res.json({ credentials: credentials.map(maskCredential) });
         },
 

package/modules/repositories/module-repository-documentdb.js

@@ -3,13 +3,13 @@ const {
     toObjectId,
     fromObjectId,
     findMany,
+    findManyDrained,
     findOne,
     insertOne,
     updateOne,
     deleteOne,
 } = require('../../database/documentdb-utils');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
-const { entityNotFoundError } = require('./entity-not-found');
 const { DocumentDBEncryptionService } = require('../../database/documentdb-encryption-service');
 
 /**
@@ -34,11 +34,11 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
     async findEntityById(entityId) {
         const objectId = toObjectId(entityId);
         if (!objectId) {
-            throw entityNotFoundError(entityId);
+            throw new Error(`Entity ${entityId} not found`);
         }
         const doc = await findOne(this.prisma, 'Entity', { _id: objectId });
         if (!doc) {
-            throw entityNotFoundError(entityId);
+            throw new Error(`Entity ${entityId} not found`);
         }
         const credential = await this._fetchCredential(doc.credentialId);
         return this._mapEntity(doc, credential);
@@ -88,7 +88,8 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
      */
     async findEntitiesByOwnership(clauses) {
         if (!Array.isArray(clauses) || clauses.length === 0) return [];
-        const docs = await findMany(this.prisma, 'Entity', {
+        // Drained: a list can hold more than the first cursor batch (~101).
+        const docs = await findManyDrained(this.prisma, 'Entity', {
             $or: clauses.map(({ userId, organizationId }) => ({
                 userId: toObjectId(userId),
                 organizationId:
@@ -278,8 +279,9 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
             const objectIds = ids.map(id => toObjectId(id)).filter(Boolean);
             if (objectIds.length === 0) return new Map();
 
-            // Use raw findMany to bypass Prisma encryption extension
-            const rawCredentials = await findMany(this.prisma, 'Credential', {
+            // Raw read to bypass the Prisma encryption extension. Drained:
+            // more ids than the first cursor batch must all come back.
+            const rawCredentials = await findManyDrained(this.prisma, 'Credential', {
                 _id: { $in: objectIds }
             });
 

package/modules/repositories/module-repository-mongo.js

@@ -1,7 +1,6 @@
 const { prisma } = require('../../database/prisma');
 const { organizationWhere } = require('../../database/organization-where');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
-const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * MongoDB Module Repository Adapter
@@ -112,7 +111,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw entityNotFoundError(entityId);
+            throw new Error(`Entity ${entityId} not found`);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);

package/modules/repositories/module-repository-postgres.js

@@ -1,6 +1,5 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
-const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * PostgreSQL Module Repository Adapter
@@ -145,7 +144,7 @@ class ModuleRepositoryPostgres extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw entityNotFoundError(entityId);
+            throw new Error(`Entity ${entityId} not found`);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);

package/modules/repositories/module-repository.js

@@ -1,6 +1,5 @@
 const { prisma } = require('../../database/prisma');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
-const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * Prisma-based Module Repository
@@ -38,7 +37,7 @@ class ModuleRepository extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw entityNotFoundError(entityId);
+            throw new Error(`Entity ${entityId} not found`);
         }
 
         return {

package/modules/scope-config.js

@@ -96,6 +96,20 @@ function readOrgAdminRoles(appDefinition) {
     return [...raw];
 }
 
+/**
+ * `user.orgAdminGateBearerTokens`: judge Frigg bearer-token callers by role
+ * like adopter-token callers. Default false: they keep their pre-roles
+ * behaviour and may manage the organization they act in.
+ */
+function readGateBearerTokens(appDefinition) {
+    const raw = appDefinition?.user?.orgAdminGateBearerTokens;
+    if (raw === undefined || raw === null) return false;
+    if (typeof raw !== 'boolean') {
+        throw configError('appDefinition.user.orgAdminGateBearerTokens', 'must be a boolean');
+    }
+    return raw;
+}
+
 /**
  * Every binding of every integration with its resolved scope and where it came
  * from, parsing each integration's settings once. Throws OwnershipConfigError
@@ -139,7 +153,7 @@ function listBindingScopes(appDefinition, entityTypeRegistry, primary) {
  * Validates every ownership setting in one pass and returns the app-level
  * config the runtime needs.
  *
- * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[]}}
+ * @returns {{scope: ({default: string, allow: string[]}|null), individualAcross: string, orgAdminRoles: string[], gateBearerTokens: boolean}}
  * @throws {OwnershipConfigError}
  */
 function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
@@ -165,6 +179,7 @@ function resolveOwnershipConfig(appDefinition, entityTypeRegistry) {
         scope: app.scope,
         individualAcross: app.individualAcross,
         orgAdminRoles: Object.freeze(readOrgAdminRoles(appDefinition)),
+        gateBearerTokens: readGateBearerTokens(appDefinition),
     });
 }
 

package/modules/scope-policy.js

@@ -20,7 +20,7 @@ const {
 
 /**
  * @param {Object} [params]
- * @param {{scope: *, individualAcross: string, orgAdminRoles?: string[]}} [params.ownership] - the raw
+ * @param {{scope: *, individualAcross: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [params.ownership] - the raw
  *   `appDefinition.ownership` or what resolveOwnershipConfig returned (a parsed
  *   `{ default, allow }` parses to itself)
  * @param {Map} [params.entityTypeRegistry]
@@ -39,9 +39,10 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
     }
 
     const orgAdminRoles = ownership?.orgAdminRoles ?? DEFAULT_ORG_ADMIN_ROLES;
+    const gateBearerTokens = ownership?.gateBearerTokens === true;
 
     const contextFor = (user) =>
-        accessContext(user, { individualAcross, orgAdminRoles });
+        accessContext(user, { individualAcross, orgAdminRoles, gateBearerTokens });
 
     /** The scope a new connection of `entityType` gets (levels 1, 4, 5, 6). */
     const resolveEntityScope = ({ entityType, requestScope, binding, integration, user }) =>
@@ -69,20 +70,6 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         };
     };
 
-    /**
-     * The owner and organization for a scope that is already decided: a
-     * re-authorization keeps the scope its connection has, whatever the config
-     * says now. The admin gate applies as it does on create.
-     */
-    const ownershipForScope = ({ scope, user }) => {
-        const ctx = contextFor(user);
-        return {
-            ...resolveOwnerForScope(scope, ctx),
-            legacyOrgId: ctx.legacyOrgId,
-            source: 'fixed',
-        };
-    };
-
     /** Whether `user` may load this stored entity for use (same clauses as the list). */
     const canUseEntity = (user, entity) =>
         describeRecord(entity, contextFor(user), 'entity') !== null;
@@ -100,7 +87,6 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         accessContext: contextFor,
         resolveScope: resolveEntityScope,
         resolveOwnership,
-        ownershipForScope,
         canUseEntity,
     });
 }

package/modules/scope-visibility.js

@@ -69,17 +69,34 @@ function buildClauses(base, kind) {
 
 /**
  * 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.
+ * delete), ADR-056 §3.6:
  *
- * @param {{authSource: (string|null), orgRole: (string|null)}} who
+ * - A shared-secret caller is the app's own backend and may.
+ * - A Frigg bearer token (`/user/login`) predates organization roles and
+ *   carries none. It keeps its pre-roles behaviour and may, unless the app
+ *   sets `user.orgAdminGateBearerTokens: true`; then it is judged like any
+ *   other caller below.
+ * - Otherwise the role is the one the token carries; when it carries none,
+ *   the role stored on the caller's membership of the active organization;
+ *   when there is none, `MEMBER`. A missing role never means admin. An
+ *   unknown source (a `User` built outside AuthenticateUser) is judged this
+ *   way too.
+ *
+ * @param {{authSource: (string|null), orgRole: (string|null), membershipRole: (string|null)}} who
  * @param {string[]} adminRoles - `user.orgAdminRoles`, compared case-insensitively
+ * @param {{gateBearerTokens?: boolean}} [options]
  */
-function canManageOrganization({ authSource, orgRole }, adminRoles = DEFAULT_ORG_ADMIN_ROLES) {
+function canManageOrganization(
+    { authSource, orgRole, membershipRole },
+    adminRoles = DEFAULT_ORG_ADMIN_ROLES,
+    { gateBearerTokens = false } = {}
+) {
     if (authSource === AUTH_SOURCES.SHARED_SECRET) return true;
-    const role = String(isPresent(orgRole) ? orgRole : 'MEMBER').toUpperCase();
+    if (authSource === AUTH_SOURCES.BEARER_TOKEN && !gateBearerTokens) return true;
+    let role = 'MEMBER';
+    if (isPresent(orgRole)) role = orgRole;
+    else if (isPresent(membershipRole)) role = membershipRole;
+    role = String(role).toUpperCase();
     return adminRoles.some((admin) => String(admin).toUpperCase() === role);
 }
 
@@ -90,11 +107,15 @@ function canManageOrganization({ authSource, orgRole }, adminRoles = DEFAULT_ORG
  * follow from them (computed once).
  *
  * @param {Object} user - the authenticated `User` (or a `{ getId }` double)
- * @param {{individualAcross?: string, orgAdminRoles?: string[]}} [options]
+ * @param {{individualAcross?: string, orgAdminRoles?: string[], gateBearerTokens?: boolean}} [options]
  */
 function accessContext(
     user,
-    { individualAcross = 'organization', orgAdminRoles = DEFAULT_ORG_ADMIN_ROLES } = {}
+    {
+        individualAcross = 'organization',
+        orgAdminRoles = DEFAULT_ORG_ADMIN_ROLES,
+        gateBearerTokens = false,
+    } = {}
 ) {
     const hasUserModel = typeof user?.getIndividualUser === 'function';
     const individual = hasUserModel ? user.getIndividualUser() : null;
@@ -111,10 +132,16 @@ function accessContext(
         authSource:
             typeof user?.getAuthSource === 'function' ? user.getAuthSource() : null,
         orgRole: typeof user?.getOrgRole === 'function' ? user.getOrgRole() : null,
+        membershipRole:
+            typeof user?.getMembershipRole === 'function'
+                ? user.getMembershipRole()
+                : null,
     };
     return {
         ...base,
-        canManageOrg: canManageOrganization(who, orgAdminRoles),
+        canManageOrg: canManageOrganization(who, orgAdminRoles, {
+            gateBearerTokens,
+        }),
         clauses: {
             entity: buildClauses(base, 'entity'),
             integration: buildClauses(base, 'integration'),
@@ -148,13 +175,6 @@ const accessFor = (scope, ctx) => {
     return ACCESS.USE;
 };
 
-/**
- * Whether an access level lets the caller use a record: bind it, proxy through
- * it (§3.4). `manage` includes `use`; `view` (metadata only) does not, and
- * neither does anything unrecognised.
- */
-const grantsUse = (access) => access === ACCESS.USE || access === ACCESS.MANAGE;
-
 /**
  * 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
@@ -214,7 +234,6 @@ module.exports = {
     matchesClause,
     scopeOf,
     describeRecord,
-    grantsUse,
     LIST_OWNERS,
     matchesListFilters,
 };

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

@@ -19,11 +19,9 @@ class AuthorizeEntityForUser {
      * 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, fixedScope?: string}} params
-     *   `fixedScope`: a re-authorization keeps the scope its connection has
+     * @param {{user: Object, entityType: string, scope?: string}} params
      */
-    resolveOwnership({ user, entityType, scope, fixedScope }) {
-        if (fixedScope) return this.scopePolicy.ownershipForScope({ scope: fixedScope, user });
+    resolveOwnership({ user, entityType, scope }) {
         return this.scopePolicy.resolveOwnership({
             entityType,
             requestScope: scope,

package/modules/use-cases/create-entity-from-credential.js

@@ -0,0 +1,113 @@
+const Boom = require('@hapi/boom');
+const { Module } = require('../module');
+
+const sameId = (a, b) =>
+    a !== undefined && a !== null && b !== undefined && b !== null &&
+    String(a) === String(b);
+
+/**
+ * Creates (or finds) the entity for a credential the caller already holds:
+ * the v1 `POST /api/entity`. The owner and organization follow the scope of
+ * `entityType`, exactly as an authorization does (ADR-056 §3.2, §3.6), so the
+ * owner is decided by `AuthorizeEntityForUser.resolveOwnership` and never by
+ * `user.getId()`. Whatever that resolution refuses (a missing identity, and
+ * an organization-level connection by a non-admin) is refused here too.
+ *
+ * The credential must belong to that owner: an organization entity is built
+ * on the organization's credential, an individual one on the person's own.
+ */
+class CreateEntityFromCredential {
+    /**
+     * @param {Object} params
+     * @param {import('./authorize-entity-for-user').AuthorizeEntityForUser} params.authorizeEntityForUser
+     * @param {import('./process-authorization-callback').ProcessAuthorizationCallback} params.processAuthorizationCallback
+     * @param {Object} params.credentialRepository
+     * @param {Array<Object>} params.moduleDefinitions
+     * @param {Function} [params.createModule] - builds a Module; injectable for tests
+     */
+    constructor({
+        authorizeEntityForUser,
+        processAuthorizationCallback,
+        credentialRepository,
+        moduleDefinitions,
+        createModule,
+    }) {
+        this.authorizeEntityForUser = authorizeEntityForUser;
+        this.processAuthorizationCallback = processAuthorizationCallback;
+        this.credentialRepository = credentialRepository;
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.createModule = createModule || ((params) => new Module(params));
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object} params.user - authenticated User
+     * @param {string} params.entityType
+     * @param {string} params.credentialId
+     * @returns {Promise<Object>} the persisted entity
+     */
+    async execute({ user, entityType, credentialId }) {
+        const definition = this.moduleDefinitions.find(
+            (def) =>
+                def.moduleName === entityType ||
+                (typeof def.getName === 'function' && def.getName() === entityType)
+        );
+        if (!definition) {
+            throw Boom.badRequest(`Unknown entity type ${entityType}`, {
+                code: 'ENTITY_TYPE_NOT_FOUND',
+            });
+        }
+
+        const ownership = this.authorizeEntityForUser.resolveOwnership({
+            user,
+            entityType,
+        });
+
+        const credential =
+            await this.credentialRepository.findCredentialById(credentialId);
+        // A missing credential and someone else's are the same answer, so ids
+        // cannot be probed.
+        if (!credential || !sameId(credential.userId, ownership.ownerId)) {
+            throw Boom.badRequest('Invalid credential ID', {
+                code: 'INVALID_CREDENTIAL',
+            });
+        }
+
+        // Built for the owner, with the credential loaded (the repository
+        // returns its tokens flat; a Module reads them from `data`), so the
+        // API can call the provider and a token refresh during
+        // getEntityDetails updates the owner's credential.
+        const { id, userId, externalId, authIsValid, ...data } = credential;
+        const module = this.createModule({
+            userId: ownership.ownerId,
+            definition,
+            entity: {
+                credential: { id, userId, externalId, authIsValid, data },
+            },
+        });
+        const entityDetails =
+            await definition.requiredAuthMethods.getEntityDetails(
+                module.api,
+                null,
+                null,
+                ownership.ownerId
+            );
+        Object.assign(
+            entityDetails.details,
+            module.apiParamsFromEntity(module.api)
+        );
+
+        return this.processAuthorizationCallback.findOrCreateEntity(
+            entityDetails,
+            definition.moduleName,
+            credential.id,
+            {
+                scope: ownership.scope,
+                organizationId: ownership.organizationId,
+                legacyOrgId: ownership.legacyOrgId,
+            }
+        );
+    }
+}
+
+module.exports = { CreateEntityFromCredential };

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

@@ -2,8 +2,6 @@ const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
 const { getTelemetry } = require('../../telemetry/telemetry-runtime');
 const { ProxyRequestError } = require('../proxy/proxy-errors');
-const { SCOPES } = require('../scope-resolution');
-const { grantsUse } = require('../scope-visibility');
 const { normalizeProxyPath, matchAllowRule } = require('../proxy/proxy-path');
 const {
     validateProxyRequest,
@@ -57,11 +55,9 @@ const authHeaderNamesOf = (api) =>
  * through its module with the stored credential, inside the limits the app
  * and the module set.
  *
- * Order of checks: request shape and size, path rules, entity visibility in
- * the active organization (404), `use` access (403), the entity's scope
- * against `managementApi.proxy.scopes` (403), the module's allow-list (403,
- * deny by default), credential readiness (401), then the call through
- * Requester._proxyRequest. Every call,
+ * Order of checks: request shape and size, path rules, entity ownership
+ * (404), the module's allow-list (403, deny by default), credential
+ * readiness (401), then the call through Requester._proxyRequest. Every call,
  * allowed or denied, writes one audit record and one usage count. Bodies,
  * headers, query values and the raw path are never logged.
  */
@@ -102,14 +98,24 @@ class ExecuteEntityProxyRequest {
             audit.requestBytes = validated.requestBytes;
             const path = normalizeProxyPath(validated.path);
 
-            // Visible in the active organization, or 404 (ADR-056 §3.6): the
-            // same clauses the v2 lists use, so a missing entity, another
-            // person's and one paired with another organization look alike.
+            // 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;
-            this.assertProxyable(entityId, entity, definition, user);
-
+            // 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'
@@ -211,44 +217,6 @@ class ExecuteEntityProxyRequest {
         }
     }
 
-    /**
-     * ADR-056 §3.5: the caller needs `use` access to the entity in the active
-     * organization, and the entity's scope must be one the app lets the proxy
-     * accept. `access` and `scope` come from the description the v2 lists
-     * return (GetEntityModuleForUser.describe), never from a second rule.
-     *
-     * Both refusals are 403 PROXY_NOT_ALLOWED: the caller can already see the
-     * entity, so saying it exists leaks nothing. `details.reason` tells them
-     * apart ('access' or 'scope').
-     */
-    assertProxyable(entityId, entity, definition, user) {
-        const tenancy = this.getEntityModuleForUser.describe(entity, user);
-        if (!tenancy) {
-            // Not visible after all: the same 404 as a missing entity.
-            throw Boom.notFound(`Entity ${entityId} not found`, {
-                code: 'ENTITY_NOT_FOUND',
-            });
-        }
-        if (!grantsUse(tenancy.access)) {
-            throw new ProxyRequestError(
-                'PROXY_NOT_ALLOWED',
-                'Proxying through an entity needs use access to it; you can only view this one',
-                { module: definition.moduleName, reason: 'access' }
-            );
-        }
-        // Narrowest by default (§3.5): with no setting only individual
-        // entities are proxied, because proxying through a shared credential
-        // lets any member act on the organization's account.
-        const acceptedScopes = this.proxyConfig.scopes ?? [SCOPES.INDIVIDUAL];
-        if (!acceptedScopes.includes(tenancy.scope)) {
-            throw new ProxyRequestError(
-                'PROXY_NOT_ALLOWED',
-                `The entity proxy does not accept ${tenancy.scope} entities in this app`,
-                { module: definition.moduleName, reason: 'scope', scope: tenancy.scope }
-            );
-        }
-    }
-
     /** A module may pin its proxy base URL (string, or a function of the api). */
     resolveBaseUrl(definition, api) {
         const declared = definition.proxy?.baseUrl;

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

@@ -1,7 +1,6 @@
 const Boom = require('@hapi/boom');
 const { describeRecord } = require('../scope-visibility');
 const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
-const { isEntityNotFound } = require('../repositories/entity-not-found');
 
 /**
  * True when `user` may act on records owned by `ownerId`. Uses the User
@@ -80,14 +79,8 @@ class GetEntityModuleForUser {
         try {
             entity = await this.moduleRepository.findEntityById(entityId);
         } catch (error) {
-            // Every adapter throws for a missing row, and a malformed id (e.g.
-            // not an integer on Postgres) is "not found" too. Both must be the
-            // 404 another tenant's entity gets, or the status says which ids
-            // exist. Anything else is a real failure.
-            if (
-                isEntityNotFound(error) ||
-                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '')
-            ) {
+            // A malformed id (e.g. not an integer on Postgres) is "not found".
+            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
                 entity = null;
             } else {
                 throw error;

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

@@ -60,8 +60,11 @@ class GetEntityOptionsById {
             );
         }
 
+        // Built for the entity's OWNER, not the caller: a caller may use an
+        // organization's entity, and a token refresh during this call must
+        // update the owner's credential, not create one under the caller.
         const module = new Module({
-            userId,
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });