@friggframework/core 2.0.0--canary.682.3c8b68a.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/README.md

@@ -393,7 +393,7 @@ value that is not a three-part JWT is not offered to the verifier at all; it fal
 | `clockToleranceSec` | `30` | Skew allowed on `exp` and `nbf`. |
 | `userIdClaim` | `sub` | App user id (required in the token). |
 | `orgIdClaim` | `org_id` | App organization id (optional). |
-| `roleClaim` | `org_role` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). |
+| `roleClaim` | `org_role` | Exposed as `user.getOrgRole()` for the request, and stored as the `orgRole` of a person's membership the first time they join that organization (`MEMBER` when the token names none). A token with no role is a member for permissions too: it cannot create or change organization-level entities or integrations; `user.orgAdminRoles` (default `['ADMIN']`) names the roles that can. |
 
 Rules worth knowing:
 

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

@@ -1,10 +1,28 @@
 const Boom = require('@hapi/boom');
-const { userOwns } = require('../../modules/use-cases/get-entity-module-for-user');
+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) => {
@@ -37,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(
@@ -72,22 +141,29 @@ 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 }) {
@@ -101,6 +177,15 @@ class DeleteCredentialForUser {
             credentialId,
             user
         );
+        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,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 
 /**
  * Re-authorization of a credential the caller owns (Management API v2). It
@@ -14,7 +15,13 @@ async function credentialEntityType(getCredentialForUser, credentialId, user) {
             { code: 'CREDENTIAL_TYPE_UNKNOWN' }
         );
     }
-    return { entityType: credential.type, credentialId: String(credential.id) };
+    return {
+        entityType: credential.type,
+        credentialId: String(credential.id),
+        // A re-authorization keeps the scope the connection already has.
+        fixedScope: credential.tenancy?.scope,
+        access: credential.tenancy?.access,
+    };
 }
 
 /** GET /api/v2/credentials/:credentialId/reauthorize */
@@ -25,14 +32,12 @@ class GetCredentialReauthorization {
     }
 
     async execute(credentialId, user, { step = 1, sessionId, state } = {}) {
-        const 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,11 +53,13 @@ class ReauthorizeCredentialForUser {
     }
 
     async execute(credentialId, user, { data, step = 1, sessionId } = {}) {
-        const binding = await credentialEntityType(
+        const { access, ...binding } = await credentialEntityType(
             this.getCredentialForUser,
             credentialId,
             user
         );
+        // A credential an organization owns: the organization's admins only.
+        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/integrations/integration-router.js

@@ -279,9 +279,11 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
     } = useCases;
 
     // The owner of an integration the caller may reach (404 otherwise), which is
-    // what the id-and-owner use cases below expect.
-    const ownerOf = async (integrationId, user) =>
-        (await getOwnedIntegrationRecord.execute(integrationId, user)).userId;
+    // what the id-and-owner use cases below expect. `manage: true` is for
+    // changing or deleting: an organization's integration needs an admin (403).
+    const ownerOf = async (integrationId, user, options) =>
+        (await getOwnedIntegrationRecord.execute(integrationId, user, options))
+            .userId;
 
     router.route('/api/integrations').get(
         catchAsyncError(async (req, res) => {
@@ -333,7 +335,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
 
             const integration = await updateIntegration.execute(
                 req.params.integrationId,
-                await ownerOf(req.params.integrationId, user),
+                await ownerOf(req.params.integrationId, user, { manage: true }),
                 params.config
             );
             res.json(integration);
@@ -346,7 +348,7 @@ function setIntegrationRoutes(router, authenticateUser, useCases) {
             const params = checkRequiredParams(req.params, ['integrationId']);
             await deleteIntegrationForUser.execute(
                 params.integrationId,
-                await ownerOf(params.integrationId, user)
+                await ownerOf(params.integrationId, user, { manage: true })
             );
             res.status(204).json({});
         })

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

@@ -1,6 +1,7 @@
 const Boom = require('@hapi/boom');
 const { describeRecord } = require('../../modules/scope-visibility');
 const { DEFAULT_SCOPE_POLICY } = require('../../modules/scope-policy');
+const { assertCanManage } = require('../../modules/use-cases/manage-access');
 const { isIntegrationNotFound } = require('../repositories/integration-not-found');
 
 /**
@@ -32,7 +33,14 @@ class GetOwnedIntegrationRecord {
         return describeRecord(record, this.scopePolicy.accessContext(user), 'integration');
     }
 
-    async execute(integrationId, user) {
+    /**
+     * @param {string} integrationId
+     * @param {Object} user - authenticated User
+     * @param {{manage?: boolean}} [options] - `manage: true` for changing or
+     *   deleting: a person may use an organization's integration but only an
+     *   admin may change it (403 ORG_ADMIN_REQUIRED)
+     */
+    async execute(integrationId, user, { manage = false } = {}) {
         let record = null;
         try {
             record = await this.integrationRepository.findIntegrationById(
@@ -47,9 +55,9 @@ class GetOwnedIntegrationRecord {
             }
             throw error;
         }
-        if (!record || !this.describe(record, user)) {
-            throw notFound(integrationId);
-        }
+        const tenancy = record && this.describe(record, user);
+        if (!tenancy) throw notFound(integrationId);
+        if (manage) assertCanManage(tenancy.access, `integration ${integrationId}`);
         return record;
     }
 }
@@ -138,7 +146,8 @@ class UpdateIntegrationForUser {
         }
         const record = await this.getOwnedIntegrationRecord.execute(
             integrationId,
-            user
+            user,
+            { manage: true }
         );
         return this.updateIntegration.execute(record.id, record.userId, config);
     }
@@ -154,7 +163,8 @@ class RemoveIntegrationForUser {
     async execute(integrationId, user) {
         const record = await this.getOwnedIntegrationRecord.execute(
             integrationId,
-            user
+            user,
+            { manage: true }
         );
         await this.deleteIntegrationForUser.execute(record.id, record.userId);
     }

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,6 +247,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         listCredentialsForUser: new credentialOps.ListCredentialsForUser({
             credentialRepository,
             moduleRepository,
+            scopePolicy,
         }),
         getCredentialForUser,
         deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({

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 };