@friggframework/core 2.0.0--canary.684.0da024b.0 → 2.0.0--canary.685.a13fdab.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/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

@@ -113,6 +113,9 @@ const {
     listBindingScopes,
     OwnershipConfigError,
 } = require('./modules/index');
+const {
+    ManagementApiConfigError,
+} = require('./management-api/management-api-config');
 const application = require('./application');
 const utils = require('./utils');
 
@@ -229,6 +232,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/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')),

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

@@ -10,6 +10,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');
 
 /**
@@ -34,11 +35,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-visibility.js

@@ -175,6 +175,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
@@ -234,6 +241,7 @@ module.exports = {
     matchesClause,
     scopeOf,
     describeRecord,
+    grantsUse,
     LIST_OWNERS,
     matchesListFilters,
 };

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/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.684.0da024b.0",
+    "version": "2.0.0--canary.685.a13fdab.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.684.0da024b.0",
-        "@friggframework/prettier-config": "2.0.0--canary.684.0da024b.0",
-        "@friggframework/test": "2.0.0--canary.684.0da024b.0",
+        "@friggframework/eslint-config": "2.0.0--canary.685.a13fdab.0",
+        "@friggframework/prettier-config": "2.0.0--canary.685.a13fdab.0",
+        "@friggframework/test": "2.0.0--canary.685.a13fdab.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": "0da024bd724c987e4bc839ab0c302580333466a1"
+    "gitHead": "a13fdab0900eaf5edb30f284f6b598c8e20686d8"
 }

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";
+  }
+
   /**
    * @deprecated ADR-059. Use `getEntityTypeRegistry(appDefinition)` and read
    * each entry's `definition`. Returns the registry's definitions for these