@friggframework/core 2.0.0--canary.683.edb4f0b.0 → 2.0.0--canary.685.022c3c3.0

package/CLAUDE.md

@@ -502,6 +502,29 @@ The single source of the max receive count is
 devtools integration builder uses it for the queue's `RedrivePolicy` and sets
 it as `FRIGG_QUEUE_MAX_RECEIVE_COUNT` on the queue worker function.
 
+### Management API v2 notes (`/management-api`)
+
+- Handlers in `management-api/v2/handlers/` call use cases only; dependencies are wired in
+  `management-api/v2/dependencies.js`. Errors are `{ error: { code, message, details? } }`.
+- `appDefinition.managementApi` is resolved by `resolveManagementApiConfig`, which `loadAppDefinition`
+  also calls so a bad value stops the app at load. Numeric proxy limits fall back to their defaults;
+  `proxy.scopes` (ADR-056 §3.5, default `['individual']`) never does: an unknown scope, `'global'`, a
+  non-list, an empty list or a repeated scope throws `ManagementApiConfigError`
+  (`MANAGEMENT_API_CONFIG_INVALID`).
+- **Entity proxy** (`ExecuteEntityProxyRequest`): visibility in the active organization comes from
+  `GetEntityModuleForUser` (404), then `assertProxyable` reads the same `{ scope, access }` description
+  the v2 lists return: `grantsUse(access)` (`use` or `manage`, from `modules/scope-visibility.js`) or 403
+  `PROXY_NOT_ALLOWED` `reason: 'access'`, and the scope must be in `proxy.scopes` or 403 `reason: 'scope'`.
+  Do not add a second ownership rule for the proxy; change the description instead.
+- **Not visible is 404, and so is missing.** Module repositories throw `entityNotFoundError(id)`
+  (`modules/repositories/entity-not-found.js`) for a missing row and use cases match it with
+  `isEntityNotFound`. A 500 for a missing id next to a 404 for another tenant's id tells a caller which
+  ids exist. A test double that resolves `findEntityById` to `null` hides this: no adapter does that.
+- **Tenant isolation on real PostgreSQL**: `management-api/v2/tenant-isolation.postgres.test.js`, run with
+  `FRIGG_TEST_POSTGRES_URL=<a database it may wipe>`. It applies the migrations, truncates every table
+  before each test, and drives real adopter-JWT auth through the real router and Prisma repositories.
+  Without the variable it is skipped (and says so), not passed. See `docs/guides/entity-scopes.md`.
+
 ### 8. Error Handling (`/errors`)
 
 **Purpose**: Standardized error types with proper HTTP semantics.

package/credential/use-cases/credential-operations-for-user.js

@@ -1,12 +1,28 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const {
+    createScopePolicy,
+    describeRecord,
+    visibilityClauses,
+    matchesListFilters,
+    SCOPES,
+} = require('../../modules/entity-scope');
 const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
- * Management API v2 credential operations. A credential has no module name
- * of its own; its `type` and the entities that use it come from the
- * caller's entities. A missing or foreign credential is a 404.
+ * Management API v2 credential operations (ADR-056 §3.4, §3.6). A credential
+ * has no module name and no organization of its own:
+ *
+ * - its `type` and `entityIds` come from the entities that use it that the
+ *   caller may see, so the same person's account connected in two
+ *   organizations (one credential, two entities) lists in each organization
+ *   with that organization's entity only;
+ * - who it belongs to is its OWNER (`credential.userId`), never the entities:
+ *   a credential an individual entity and an organization entity both point at
+ *   (possible only through legacy data) is described by whoever owns the
+ *   credential, so the answer cannot change with the order the entities load;
+ * - a credential whose entities are all out of sight (another organization's)
+ *   is a 404, and one with no entities at all (its entity was deleted) is
+ *   visible to its owner only, as it was before scoping.
  */
 
 const credentialIdOf = (entity) => {
@@ -39,31 +55,82 @@ function withEntityUsage(credentials, entities) {
     });
 }
 
-/** The caller's credentials with their type and entity usage. */
+/**
+ * `{scope, owner, organizationId, access}` of a credential for this caller, or
+ * null when its owner is neither the caller nor the active organization. Built
+ * by `describeRecord` over the row a connection by this owner has: the
+ * organization of a visible entity, else the one a new entity would get.
+ */
+function credentialTenancy(credential, visibleEntities, ctx) {
+    const entityOrg = visibleEntities.find(
+        (entity) => entity.organizationId !== undefined && entity.organizationId !== null
+    )?.organizationId;
+    const organizationId =
+        entityOrg ?? (ctx.individualAcross === 'all' ? null : ctx.activeOrgId);
+    return describeRecord({ userId: credential.userId, organizationId }, ctx, 'entity');
+}
+
+/** The entities of `entities` the caller may see, each with its `tenancy`. */
+function visibleOf(entities, ctx) {
+    const visible = [];
+    for (const entity of entities || []) {
+        const tenancy = describeRecord(entity, ctx, 'entity');
+        if (tenancy) visible.push({ ...entity, tenancy });
+    }
+    return visible;
+}
+
+/**
+ * The caller's credentials with their type, the entities of them they may see
+ * and `tenancy`. Credentials with no entity at all are listed too, for the
+ * person and the active organization that own them.
+ */
 class ListCredentialsForUser {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
-    async execute(user) {
-        const userId = user.getId();
-        const [credentials, entities] = await Promise.all([
-            this.credentialRepository.findCredentialsByUserId(userId),
-            this.moduleRepository.findEntitiesByUserId(userId),
+    /** @param {{scope?: string, owner?: string}} [filters] */
+    async execute(user, filters = {}) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const owners = [...new Set([ctx.callerId, ctx.activeOrgId].filter(Boolean))];
+        const [found, perOwner, owned] = await Promise.all([
+            this.moduleRepository.findEntitiesByOwnership(visibilityClauses(ctx, 'entity')),
+            Promise.all(owners.map((id) => this.credentialRepository.findCredentialsByUserId(id))),
+            // Every entity of those owners, in any organization: only to tell a credential
+            // with no entity at all from one used elsewhere.
+            Promise.all(owners.map((id) => this.moduleRepository.findEntitiesByUserId(id))),
         ]);
-        return withEntityUsage(credentials || [], entities);
+        const visible = visibleOf(found, ctx);
+        const usedAnywhere = new Set(owned.flat().map(credentialIdOf).filter(Boolean));
+        const listed = [];
+        for (const credential of perOwner.flat().filter(Boolean)) {
+            const id = String(credential.id);
+            const referencing = visible.filter((entity) => credentialIdOf(entity) === id);
+            if (referencing.length === 0 && usedAnywhere.has(id)) continue;
+            const tenancy = credentialTenancy(credential, referencing, ctx);
+            if (!tenancy || !matchesListFilters(tenancy, filters)) continue;
+            listed.push({ ...withEntityUsage([credential], referencing)[0], tenancy });
+        }
+        return listed;
     }
 }
 
-/** One credential the caller owns, with its type and entity usage. */
+/** One credential the caller may see: see the header. 404 otherwise. */
 class GetCredentialForUserV2 {
-    constructor({ credentialRepository, moduleRepository }) {
+    constructor({ credentialRepository, moduleRepository, scopePolicy }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
+        this.scopePolicy = scopePolicy || createScopePolicy();
     }
 
     async execute(credentialId, user) {
+        const notFound = () =>
+            Boom.notFound(`Credential ${credentialId} not found`, {
+                code: 'CREDENTIAL_NOT_FOUND',
+            });
         let credential = null;
         try {
             credential = await this.credentialRepository.findCredentialById(
@@ -74,26 +141,32 @@ class GetCredentialForUserV2 {
                 throw error;
             }
         }
-        if (!credential || !userOwns(user, credential.userId)) {
-            throw Boom.notFound(`Credential ${credentialId} not found`, {
-                code: 'CREDENTIAL_NOT_FOUND',
-            });
-        }
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            credential.userId
-        );
-        return withEntityUsage([credential], entities)[0];
+        if (!credential) throw notFound();
+        const ctx = this.scopePolicy.accessContext(user);
+
+        const referencing =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        const visible = visibleOf(referencing, ctx);
+        if (referencing.length > 0 && visible.length === 0) throw notFound();
+        const tenancy = credentialTenancy(credential, visible, ctx);
+        if (!tenancy) throw notFound();
+        return { ...withEntityUsage([credential], visible)[0], tenancy };
     }
 }
 
 /**
- * Deletes a credential the caller owns. The entities that used it stay, with
- * their credential unset, so they show as needing re-authorization rather
+ * Deletes a credential the caller may manage. The entities that used it stay,
+ * with their credential unset, so they show as needing re-authorization rather
  * than disappearing from integrations.
+ *
+ * Refuses with 409 `CREDENTIAL_SHARED` while an entity the caller cannot see
+ * still uses it: one credential row serves the same provider account in every
+ * organization, and deleting it from one would break the other. The message
+ * says nothing about the other connections (not even how many): remove the
+ * entities that use it, and it goes with the last one.
  */
 class DeleteCredentialForUser {
-    constructor({ credentialRepository, moduleRepository, getCredentialForUser, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    constructor({ credentialRepository, moduleRepository, getCredentialForUser }) {
         this.credentialRepository = credentialRepository;
         this.moduleRepository = moduleRepository;
         this.getCredentialForUser = getCredentialForUser;
@@ -104,11 +177,15 @@ class DeleteCredentialForUser {
             credentialId,
             user
         );
-        // A credential an organization owns: the organization's admins only.
-        // (null: not the person's or the active organization's, which the
-        // owner check above already decided.)
-        const access = this.scopePolicy.accessToOwnedBy(user, credential.userId);
-        if (access !== null) assertCanManage(access, `credential ${credential.id}`);
+        assertCanManage(credential.tenancy.access, `credential ${credential.id}`);
+        const usedBy =
+            (await this.moduleRepository.findEntities({ credentialId: credential.id })) || [];
+        if (usedBy.length > credential.entityIds.length) {
+            throw Boom.conflict(
+                `Credential ${credential.id} is still in use by other connections and cannot be deleted from here`,
+                { code: 'CREDENTIAL_SHARED' }
+            );
+        }
         for (const entityId of credential.entityIds) {
             await this.moduleRepository.unsetCredential(entityId);
         }

package/credential/use-cases/reauthorize-credential-for-user.js

@@ -1,5 +1,4 @@
 const Boom = require('@hapi/boom');
-const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
 const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
@@ -19,7 +18,9 @@ async function credentialEntityType(getCredentialForUser, credentialId, user) {
     return {
         entityType: credential.type,
         credentialId: String(credential.id),
-        ownerId: credential.userId,
+        // A re-authorization keeps the scope the connection already has.
+        fixedScope: credential.tenancy?.scope,
+        access: credential.tenancy?.access,
     };
 }
 
@@ -31,14 +32,12 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const { ownerId, ...binding } = await credentialEntityType(
-            this.getCredentialForUser,
-            credentialId,
-            user
-        );
+        const { entityType, credentialId: boundCredentialId } =
+            await credentialEntityType(this.getCredentialForUser, credentialId, user);
         return this.getAuthorizationStep.execute({
             user,
-            ...binding,
+            entityType,
+            credentialId: boundCredentialId,
             step,
             sessionId,
             state,
@@ -48,21 +47,19 @@ class GetCredentialReauthorization {
 
 /** POST /api/v2/credentials/:credentialId/reauthorize */
 class ReauthorizeCredentialForUser {
-    constructor({ getCredentialForUser, submitAuthorizationStep, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+    constructor({ getCredentialForUser, submitAuthorizationStep }) {
         this.getCredentialForUser = getCredentialForUser;
         this.submitAuthorizationStep = submitAuthorizationStep;
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const { ownerId, ...binding } = await credentialEntityType(
+        const { access, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
         );
         // A credential an organization owns: the organization's admins only.
-        const access = this.scopePolicy.accessToOwnedBy(user, ownerId);
-        if (access !== null) assertCanManage(access, `credential ${credentialId}`);
+        assertCanManage(access, `credential ${credentialId}`);
         return this.submitAuthorizationStep.execute({
             user,
             ...binding,

package/handlers/app-definition-loader.js

@@ -12,6 +12,9 @@ const {
     getEntityTypeDefinitions,
 } = require('../modules/entity-type-registry');
 const { resolveOwnershipConfig } = require('../modules/entity-scope');
+const {
+    resolveManagementApiConfig,
+} = require('../management-api/management-api-config');
 
 // Handlers without a database never load the encryption registry, so the
 // credential leaf keys are registered for redaction here too.
@@ -39,6 +42,7 @@ function registerCredentialLogKeys(appDefinition, moduleDefinitions) {
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
  * @throws {Error} Throws error if user.authModes.adopterJwt is enabled without a usable user.jwtConfig.
  * @throws {OwnershipConfigError} Throws if an ownership or scope setting is invalid (ADR-056 §3.1).
+ * @throws {ManagementApiConfigError} Throws if `managementApi.proxy.scopes` is invalid (ADR-056 §3.5).
  * @example
  * const { integrations, userConfig, telemetry } = loadAppDefinition();
  * console.log(`Found ${integrations.length} integrations`);
@@ -84,6 +88,11 @@ function loadAppDefinition() {
     // individual entity stops the app at load.
     const ownership = resolveOwnershipConfig(appDefinition, entityTypeRegistry);
 
+    // And for the Management API: `managementApi.proxy.scopes` decides whose
+    // credentials the entity proxy may act through (ADR-056 §3.5), so an
+    // unknown scope stops the app here rather than being read as a default.
+    resolveManagementApiConfig(managementApi);
+
     registerCredentialLogKeys(appDefinition, moduleDefinitions);
 
     // Degrade consistently: an invalid telemetry block must never take down a

package/index.js

@@ -112,6 +112,9 @@ const {
     listBindingScopes,
     OwnershipConfigError,
 } = require('./modules/index');
+const {
+    ManagementApiConfigError,
+} = require('./management-api/management-api-config');
 const application = require('./application');
 const utils = require('./utils');
 
@@ -226,6 +229,7 @@ module.exports = {
     resolveScope,
     listBindingScopes,
     OwnershipConfigError,
+    ManagementApiConfigError,
     // queues
     QueuerUtil,
 

package/management-api/management-api-config.js

@@ -9,6 +9,7 @@
  *         timeoutMs: 25000,   // whole upstream call, lower only
  *         maxRequestBytes: 1048576,
  *         maxResponseBytes: 5242880, // lower only
+ *         scopes: ['individual'], // entity scopes the proxy accepts (ADR-056 §3.5)
  *         modules: {          // per-module allow-list override
  *             hubspot: { allow: 'module' },
  *             erp: { allow: [{ method: 'GET', path: '/v1/customers/**' }] },
@@ -17,10 +18,36 @@
  * }
  * ```
  *
- * TODO(F6): `proxy.scopes` (ADR-056 §3.5) is not read yet; see
- * ExecuteEntityProxyRequest.
+ * Limits that are out of range fall back to their defaults. `proxy.scopes` is a
+ * security setting, so it does not fall back: a value that is not a list of
+ * known tenant scopes throws ManagementApiConfigError, and loadAppDefinition
+ * calls this so the app stops at load.
  */
 
+const { BaseError } = require('../errors/base-error');
+const { SCOPES } = require('../modules/scope-resolution');
+
+/** Raised for an invalid `appDefinition.managementApi` setting. */
+class ManagementApiConfigError extends BaseError {
+    constructor(message, options) {
+        super(message, options);
+        this.code = 'MANAGEMENT_API_CONFIG_INVALID';
+    }
+}
+
+/**
+ * The scopes `managementApi.proxy.scopes` may list. `global` is not one of
+ * them: a global entity is the app owner's and is never a tenant's to proxy.
+ */
+const PROXY_SCOPE_VALUES = Object.freeze([SCOPES.INDIVIDUAL, SCOPES.ORGANIZATION]);
+
+/**
+ * Narrowest by default (ADR-056 §3.5): proxying through a shared credential
+ * lets any member act on the organization's account, so an app opts in to
+ * `organization` explicitly.
+ */
+const DEFAULT_PROXY_SCOPES = Object.freeze([SCOPES.INDIVIDUAL]);
+
 // ADR-052 §7. API Gateway HTTP APIs time out at 30s and Lambda responses cap
 // at 6MB, so the timeout and response defaults are also ceilings: an app may
 // lower them, not raise them.
@@ -47,9 +74,41 @@ function positiveOr(value, fallback, ceiling) {
     return isPositiveNumber(value) ? Math.min(value, ceiling) : fallback;
 }
 
+const proxyScopesError = (message) =>
+    new ManagementApiConfigError(`managementApi.proxy.scopes: ${message}`);
+
+/**
+ * `managementApi.proxy.scopes`: absent means the default; anything else must be
+ * a non-empty list of PROXY_SCOPE_VALUES, each once.
+ * @returns {ReadonlyArray<string>}
+ * @throws {ManagementApiConfigError}
+ */
+function resolveProxyScopes(scopes) {
+    if (scopes === undefined) return DEFAULT_PROXY_SCOPES;
+    const allowed = PROXY_SCOPE_VALUES.join(', ');
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+        throw proxyScopesError(`must be a non-empty list drawn from ${allowed}`);
+    }
+    for (const scope of scopes) {
+        if (scope === SCOPES.GLOBAL) {
+            throw proxyScopesError(
+                "'global' is not allowed: global entities belong to the app owner and are never proxied for a tenant"
+            );
+        }
+        if (!PROXY_SCOPE_VALUES.includes(scope)) {
+            throw proxyScopesError(`unknown scope ${JSON.stringify(scope)}; use ${allowed}`);
+        }
+    }
+    if (new Set(scopes).size !== scopes.length) {
+        throw proxyScopesError('lists a scope more than once');
+    }
+    return Object.freeze([...scopes]);
+}
+
 /**
  * @param {Object} [managementApi] - `appDefinition.managementApi`
- * @returns {{ v1: boolean, proxy: { enable: boolean, timeoutMs: number, maxRequestBytes: number, maxResponseBytes: number, modules: Object } }}
+ * @returns {{ v1: boolean, proxy: { enable: boolean, timeoutMs: number, maxRequestBytes: number, maxResponseBytes: number, scopes: ReadonlyArray<string>, modules: Object } }}
+ * @throws {ManagementApiConfigError} for an invalid `proxy.scopes`
  */
 function resolveManagementApiConfig(managementApi) {
     const config =
@@ -74,6 +133,7 @@ function resolveManagementApiConfig(managementApi) {
                 proxy.maxResponseBytes,
                 DEFAULT_PROXY_LIMITS.maxResponseBytes
             ),
+            scopes: resolveProxyScopes(proxy.scopes),
             modules:
                 proxy.modules && typeof proxy.modules === 'object'
                     ? proxy.modules
@@ -82,4 +142,10 @@ function resolveManagementApiConfig(managementApi) {
     };
 }
 
-module.exports = { resolveManagementApiConfig, DEFAULT_PROXY_LIMITS };
+module.exports = {
+    resolveManagementApiConfig,
+    DEFAULT_PROXY_LIMITS,
+    DEFAULT_PROXY_SCOPES,
+    PROXY_SCOPE_VALUES,
+    ManagementApiConfigError,
+};

package/management-api/openapi/components.js

@@ -206,6 +206,7 @@ const SCHEMAS = {
             authIsValid: nullable({ type: 'boolean' }),
             entityIds: { type: 'array', items: { type: 'string' } },
             entityCount: { type: 'integer', minimum: 0 },
+            ...tenancyProperties,
             createdAt: nullable({ type: 'string', format: 'date-time' }),
             updatedAt: nullable({ type: 'string', format: 'date-time' }),
             data: {

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. 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. 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.",
         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', ref('ProxyError')),
-            404: ok('Entity not found', ref('Error')),
+            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')),
             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,6 +184,9 @@ 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,6 +124,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
         credentialRepository,
         moduleRepository,
+        scopePolicy,
     });
     const getAuthorizationRequirements = new GetAuthorizationRequirements({
         moduleDefinitions,
@@ -246,13 +247,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,
@@ -261,7 +262,6 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         reauthorizeCredentialForUser: new ReauthorizeCredentialForUser({
             getCredentialForUser,
             submitAuthorizationStep,
-            scopePolicy,
         }),
 
         // Authorization (multi-step)

package/management-api/v2/dto.js

@@ -75,6 +75,8 @@ const CREDENTIAL_METADATA = new Set([
     'type',
     'entityIds',
     'status',
+    // Added by the credential use cases (ADR-056 §3.4); never provider data.
+    'tenancy',
 ]);
 
 /**
@@ -126,6 +128,7 @@ 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,4 +1,5 @@
 const { maskCredential } = require('../dto');
+const { parseListFilters } = require('../request');
 
 /** Management API v2 credential handlers, keyed by operationId. */
 function createCredentialHandlers(useCases) {
@@ -6,8 +7,11 @@ function createCredentialHandlers(useCases) {
         useCases;
 
     return {
-        async listCredentials(_req, res, user) {
-            const credentials = await listCredentialsForUser.execute(user);
+        async listCredentials(req, res, user) {
+            const credentials = await listCredentialsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ credentials: credentials.map(maskCredential) });
         },
 

package/modules/repositories/entity-not-found.js

@@ -0,0 +1,18 @@
+/**
+ * The error `findEntityById` throws for an id with no row, and the one
+ * predicate that recognises it (as integration-not-found.js does for
+ * integrations). The adapters build the error here and use cases match it
+ * here, so a missing entity can be told from any other failure without
+ * widening a regex.
+ *
+ * Why it matters: a use case that answers 404 for another tenant's entity must
+ * answer the same 404 for an id that does not exist. Otherwise the status code
+ * says which ids exist (ADR-052 §3, ADR-056 §3.6).
+ */
+const MESSAGE = /^Entity .+ not found$/;
+
+const entityNotFoundError = (id) => new Error(`Entity ${id} not found`);
+
+const isEntityNotFound = (error) => MESSAGE.test(error?.message || '');
+
+module.exports = { entityNotFoundError, isEntityNotFound };

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

@@ -9,6 +9,7 @@ const {
     deleteOne,
 } = require('../../database/documentdb-utils');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 const { DocumentDBEncryptionService } = require('../../database/documentdb-encryption-service');
 
 /**
@@ -33,11 +34,11 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
     async findEntityById(entityId) {
         const objectId = toObjectId(entityId);
         if (!objectId) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
         const doc = await findOne(this.prisma, 'Entity', { _id: objectId });
         if (!doc) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
         const credential = await this._fetchCredential(doc.credentialId);
         return this._mapEntity(doc, credential);

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

@@ -1,6 +1,7 @@
 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
@@ -111,7 +112,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);

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

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

package/modules/repositories/module-repository.js

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

package/modules/scope-policy.js

@@ -69,6 +69,20 @@ 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;
@@ -86,6 +100,7 @@ function createScopePolicy({ ownership, entityTypeRegistry } = {}) {
         accessContext: contextFor,
         resolveScope: resolveEntityScope,
         resolveOwnership,
+        ownershipForScope,
         canUseEntity,
     });
 }

package/modules/scope-visibility.js

@@ -148,6 +148,13 @@ 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
@@ -207,6 +214,7 @@ module.exports = {
     matchesClause,
     scopeOf,
     describeRecord,
+    grantsUse,
     LIST_OWNERS,
     matchesListFilters,
 };

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

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

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

@@ -2,6 +2,8 @@ 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,
@@ -55,9 +57,11 @@ 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 ownership
- * (404), 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 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,
  * allowed or denied, writes one audit record and one usage count. Bodies,
  * headers, query values and the raw path are never logged.
  */
@@ -98,24 +102,14 @@ 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.
+            // 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.
             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' }
-                );
-            }
+            this.assertProxyable(entityId, entity, definition, user);
+
             const credentialRef = entity.credential;
             const credentialId =
                 credentialRef && typeof credentialRef === 'object'
@@ -217,6 +211,44 @@ 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,6 +1,7 @@
 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
@@ -79,8 +80,14 @@ class GetEntityModuleForUser {
         try {
             entity = await this.moduleRepository.findEntityById(entityId);
         } catch (error) {
-            // A malformed id (e.g. not an integer on Postgres) is "not found".
-            if (/Invalid ID|ObjectId|Malformed/i.test(error?.message || '')) {
+            // 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 || '')
+            ) {
                 entity = null;
             } else {
                 throw error;

package/modules/use-cases/multi-step-authorization.js

@@ -166,8 +166,10 @@ class SubmitAuthorizationStep {
      * @param {Object} params
      * @param {string} [params.scope] - the scope the caller asks for, from the
      *   deciding level's allow list (ADR-056 §3.1). Never `global`.
+     * @param {string} [params.fixedScope] - re-authorization keeps the scope the
+     *   credential already has, whatever the config says now.
      */
-    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null, scope }) {
+    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null, scope, fixedScope }) {
         if (!data || typeof data !== 'object' || Array.isArray(data)) {
             throw Boom.badRequest('data must be an object', {
                 code: 'VALIDATION_ERROR',
@@ -183,6 +185,7 @@ class SubmitAuthorizationStep {
             user,
             entityType,
             scope,
+            fixedScope,
         });
 
         if (!isMultiStep(definition)) {

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.683.edb4f0b.0",
+    "version": "2.0.0--canary.685.022c3c3.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.683.edb4f0b.0",
-        "@friggframework/prettier-config": "2.0.0--canary.683.edb4f0b.0",
-        "@friggframework/test": "2.0.0--canary.683.edb4f0b.0",
+        "@friggframework/eslint-config": "2.0.0--canary.685.022c3c3.0",
+        "@friggframework/prettier-config": "2.0.0--canary.685.022c3c3.0",
+        "@friggframework/test": "2.0.0--canary.685.022c3c3.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "edb4f0b45af2a0a70fc5c7dbe3324d9a8e088d70"
+    "gitHead": "022c3c3ae2d4e9d22046d94911fc00854416cb2a"
 }

package/types/modules/index.d.ts

@@ -68,12 +68,49 @@ declare module "@friggframework/core" {
     owner?: "derive" | "individual" | "organization";
   }
 
+  /** One operation a module or the app lets the entity proxy forward (ADR-052). */
+  export interface ProxyAllowRule {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "*";
+    /** Relative to the module's base URL. `:param` is one segment; a trailing `/**` is a subtree. */
+    path: string;
+  }
+
+  /** `appDefinition.managementApi.proxy`: the entity proxy, POST /api/v2/entities/:id/proxy (ADR-052). */
+  export interface ManagementApiProxyConfig {
+    /** Mount the route. Default false. */
+    enable?: boolean;
+    /** Upstream timeout in ms; can only be lowered from 25000. */
+    timeoutMs?: number;
+    /** Largest request body in bytes; default 1 MiB, at most 10 MiB. */
+    maxRequestBytes?: number;
+    /** Largest response body in bytes; can only be lowered from 5 MiB. */
+    maxResponseBytes?: number;
+    /**
+     * Entity scopes the proxy accepts (ADR-056 §3.5). Default `['individual']`.
+     * Add `'organization'` to let a member with use access proxy through the
+     * organization's shared credential. `global` is never accepted. An unknown,
+     * empty or repeated value throws ManagementApiConfigError at load.
+     */
+    scopes?: Array<Exclude<EntityScope, "global">>;
+    /** Per-module allow-list override; `'module'` uses the module's own list. */
+    modules?: Record<string, { allow: "module" | ProxyAllowRule[] }>;
+  }
+
+  /** `appDefinition.managementApi` (ADR-052, ADR-053). */
+  export interface ManagementApiConfig {
+    /** Serve the deprecated v1 routes. Default true. */
+    v1?: boolean;
+    proxy?: ManagementApiProxyConfig;
+  }
+
   export interface AppDefinition {
     integrations: any[];
     /** App-level entity type registry (ADR-059). */
     entities?: AppDefinitionEntities;
     /** Who owns what a person connects (ADR-056). */
     ownership?: AppOwnership;
+    /** Management API versions and the entity proxy (ADR-052, ADR-053, ADR-056 §3.5). */
+    managementApi?: ManagementApiConfig;
     [key: string]: unknown;
   }
 
@@ -138,6 +175,11 @@ declare module "@friggframework/core" {
     appDefinition?: Pick<AppDefinition, "entities" | "integrations">
   ): EntityTypeRegistry;
 
+  /** Invalid `managementApi` setting (today: `proxy.scopes`), thrown at app-definition load. */
+  export class ManagementApiConfigError extends Error {
+    code: "MANAGEMENT_API_CONFIG_INVALID";
+  }
+
   /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
   export class EntityRegistryError extends Error {
     code: "ENTITY_REGISTRY_INVALID";