@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/queues/queue-message-auth.js

@@ -0,0 +1,193 @@
+/**
+ * Queue message authentication for HTTP-delivered queues.
+ *
+ * An SQS-triggered Lambda is invoked by AWS itself, so its events are trusted
+ * by the transport. An HTTP-delivered queue (a Netlify Background Function,
+ * a QStash destination) is a public URL: anyone who can reach it can post a
+ * message. These helpers let the sending adapter prove a message came from
+ * Frigg and let the receiving adapter check that proof before anything runs.
+ *
+ * Scheme (Frigg-signed messages):
+ *   timestamp = whole seconds since the epoch, as a decimal string
+ *   signature = 'v1=' + hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`))
+ * sent as the `x-frigg-queue-timestamp` and `x-frigg-queue-signature`
+ * headers. The receiver recomputes the HMAC over the raw body it was given,
+ * compares in constant time, and refuses a timestamp more than
+ * MAX_MESSAGE_AGE_SECONDS away from its own clock (replay window).
+ *
+ * Fail closed: with no secret configured, a message is accepted unsigned only
+ * when FRIGG_QUEUE_ALLOW_UNSIGNED=true AND the environment is not production
+ * (isProductionEnvironment; a deployed function always is). Anything else is
+ * refused.
+ */
+const crypto = require('crypto');
+const { isDeployedRuntime } = require('../providers/runtime-detection');
+
+const SIGNING_SECRET_ENV = 'FRIGG_QUEUE_SIGNING_SECRET';
+const ALLOW_UNSIGNED_ENV = 'FRIGG_QUEUE_ALLOW_UNSIGNED';
+const SIGNATURE_HEADER = 'x-frigg-queue-signature';
+const TIMESTAMP_HEADER = 'x-frigg-queue-timestamp';
+const SIGNATURE_VERSION = 'v1';
+const MAX_MESSAGE_AGE_SECONDS = 5 * 60;
+
+// Stages core already treats as non-production (database/prisma.js bypasses
+// encryption for the same list).
+const NON_PRODUCTION_STAGES = ['dev', 'test', 'local'];
+const NON_PRODUCTION_NODE_ENVS = ['development', 'test'];
+
+/**
+ * Production unless the environment says otherwise: an unset STAGE and
+ * NODE_ENV count as production, so a missing setting never opens the door.
+ * A deployed function (AWS Lambda, or the active provider's platform such as
+ * a Netlify Function: providers/runtime-detection) is production whatever
+ * STAGE says, so a deployed `dev` stage cannot opt out of signatures.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function isProductionEnvironment(env = process.env) {
+    if (isDeployedRuntime(env)) return true;
+    if (NON_PRODUCTION_STAGES.includes(env.STAGE)) return false;
+    if (NON_PRODUCTION_NODE_ENVS.includes(env.NODE_ENV)) return false;
+    if (env.NETLIFY_DEV === 'true') return false;
+    return true;
+}
+
+/**
+ * Unsigned messages are allowed only by an explicit opt-in outside production.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function allowsUnsignedMessages(env = process.env) {
+    return env[ALLOW_UNSIGNED_ENV] === 'true' && !isProductionEnvironment(env);
+}
+
+/**
+ * @param {Object} [env=process.env]
+ * @returns {string|undefined} the configured signing secret, if non-empty
+ */
+function readSigningSecret(env = process.env) {
+    const secret = env[SIGNING_SECRET_ENV];
+    return typeof secret === 'string' && secret.length > 0 ? secret : undefined;
+}
+
+function computeSignature(secret, timestamp, rawBody) {
+    const mac = crypto
+        .createHmac('sha256', secret)
+        .update(`${timestamp}.${rawBody}`)
+        .digest('hex');
+    return `${SIGNATURE_VERSION}=${mac}`;
+}
+
+/**
+ * Sign a raw message body.
+ *
+ * @param {Object} params
+ * @param {string} params.body - the exact string that will be sent
+ * @param {string} params.secret
+ * @param {number} [params.now] - milliseconds since the epoch (default Date.now())
+ * @returns {{ [header: string]: string }} headers to add to the request
+ */
+function signQueueMessage({ body, secret, now = Date.now() }) {
+    if (!secret) {
+        throw new Error('A signing secret is required to sign a queue message');
+    }
+    const timestamp = String(Math.floor(now / 1000));
+    return {
+        [TIMESTAMP_HEADER]: timestamp,
+        [SIGNATURE_HEADER]: computeSignature(secret, timestamp, body),
+    };
+}
+
+function constantTimeEqual(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    // timingSafeEqual throws on unequal lengths; the length of a v1 signature
+    // is fixed, so comparing lengths first leaks nothing secret.
+    if (left.length !== right.length) return false;
+    return crypto.timingSafeEqual(left, right);
+}
+
+/**
+ * Verify a Frigg-signed message.
+ *
+ * @param {Object} params
+ * @param {string|null|undefined} params.body - raw body as received
+ * @param {string|undefined} params.timestamp - x-frigg-queue-timestamp
+ * @param {string|undefined} params.signature - x-frigg-queue-signature
+ * @param {string} params.secret
+ * @param {number} [params.now] - milliseconds since the epoch
+ * @param {number} [params.maxAgeSeconds]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function verifyQueueMessage({
+    body,
+    timestamp,
+    signature,
+    secret,
+    now = Date.now(),
+    maxAgeSeconds = MAX_MESSAGE_AGE_SECONDS,
+}) {
+    if (!secret) return { ok: false, reason: 'signing_secret_not_configured' };
+    if (!signature || !timestamp) return { ok: false, reason: 'missing_signature' };
+    if (typeof body !== 'string') return { ok: false, reason: 'missing_body' };
+    if (!/^\d{1,15}$/.test(timestamp)) return { ok: false, reason: 'invalid_timestamp' };
+
+    const ageSeconds = Math.abs(Math.floor(now / 1000) - Number(timestamp));
+    if (ageSeconds > maxAgeSeconds) return { ok: false, reason: 'stale_timestamp' };
+
+    const expected = computeSignature(secret, timestamp, body);
+    if (!constantTimeEqual(expected, signature)) {
+        return { ok: false, reason: 'invalid_signature' };
+    }
+    return { ok: true };
+}
+
+/**
+ * Case-insensitive header lookup over a Lambda/Netlify v1 event's headers.
+ *
+ * @param {Object} event
+ * @param {string} name - lower-case header name
+ * @returns {string|undefined}
+ */
+function readHeader(event, name) {
+    const headers = event?.headers || {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name) {
+            return Array.isArray(value) ? value[0] : value;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * The raw request body exactly as signed: a string body as is, a base64
+ * body decoded to its UTF-8 text. An already-parsed object body cannot be
+ * verified (its bytes are gone), so it reads as absent.
+ *
+ * @param {Object} event
+ * @returns {string|null}
+ */
+function readRawBody(event) {
+    if (typeof event?.body !== 'string') return null;
+    if (event.isBase64Encoded) {
+        return Buffer.from(event.body, 'base64').toString('utf8');
+    }
+    return event.body;
+}
+
+module.exports = {
+    SIGNING_SECRET_ENV,
+    ALLOW_UNSIGNED_ENV,
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    MAX_MESSAGE_AGE_SECONDS,
+    isProductionEnvironment,
+    allowsUnsignedMessages,
+    readSigningSecret,
+    signQueueMessage,
+    verifyQueueMessage,
+    readHeader,
+    readRawBody,
+};

package/queues/queue-provider-factory.js

@@ -0,0 +1,101 @@
+/**
+ * Queue Provider Factory
+ *
+ * Creates a QueueProvider (send / batchSend / parseEvent) for the active
+ * platform. From friggframework/frigg#545, adapted: #545 resolved every
+ * provider through resolveProvider(), so an AWS app had to install
+ * @friggframework/provider-aws. In this stack the AWS SDK is a core
+ * dependency, so the built-in queues are created here and only an unknown
+ * name goes through the provider plugin system.
+ *
+ * Priority order for determining the provider:
+ * 1. Explicit `provider` option
+ * 2. `appDefinition.queue.provider`
+ * 3. `QUEUE_PROVIDER` environment variable
+ * 4. Default: SQS
+ *
+ * Built-in names:
+ * - 'sqs' | 'aws'                     -> SqsQueueProvider
+ * - 'netlify-background' | 'netlify'  -> NetlifyBackgroundProvider
+ * - 'qstash'                          -> QStashQueueProvider
+ * Any other name -> require('@friggframework/provider-<name>').QueueProvider
+ */
+
+const QUEUE_PROVIDERS = {
+    SQS: 'sqs',
+    NETLIFY_BACKGROUND: 'netlify-background',
+    QSTASH: 'qstash',
+};
+
+// Platform provider names (appDefinition.provider) that map to a built-in queue.
+const PLATFORM_ALIASES = {
+    aws: QUEUE_PROVIDERS.SQS,
+    netlify: QUEUE_PROVIDERS.NETLIFY_BACKGROUND,
+};
+
+/**
+ * Determine the queue provider from the config hierarchy.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider]
+ * @param {Object} [options.appDefinition]
+ * @returns {string|undefined}
+ */
+function determineProvider(options = {}) {
+    if (options.provider) {
+        return options.provider;
+    }
+    if (options.appDefinition?.queue?.provider) {
+        return options.appDefinition.queue.provider;
+    }
+    if (process.env.QUEUE_PROVIDER) {
+        return process.env.QUEUE_PROVIDER;
+    }
+    return undefined;
+}
+
+/**
+ * Create a queue provider instance.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.provider] - Queue provider name
+ * @param {Object} [options.appDefinition] - reads `queue.provider`
+ * @param {Object} [options.providerOptions] - passed to the provider constructor
+ * @returns {import('./queue-provider').QueueProvider}
+ */
+function createQueueProvider(options = {}) {
+    const explicit = determineProvider(options);
+    const name = PLATFORM_ALIASES[explicit] || explicit || QUEUE_PROVIDERS.SQS;
+    const providerOptions = options.providerOptions || {};
+
+    switch (name) {
+        case QUEUE_PROVIDERS.SQS: {
+            const { SqsQueueProvider } = require('./providers/sqs-queue-provider');
+            return new SqsQueueProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.NETLIFY_BACKGROUND: {
+            const {
+                NetlifyBackgroundProvider,
+            } = require('./providers/netlify-background-provider');
+            return new NetlifyBackgroundProvider(providerOptions);
+        }
+        case QUEUE_PROVIDERS.QSTASH: {
+            const { QStashQueueProvider } = require('./providers/qstash-queue-provider');
+            return new QStashQueueProvider(providerOptions);
+        }
+        default: {
+            const { resolveProvider } = require('../providers/resolve-provider');
+            const provider = resolveProvider(null, { provider: name });
+            if (!provider.QueueProvider) {
+                throw new Error(`Provider '${provider.name || name}' does not export a QueueProvider`);
+            }
+            return new provider.QueueProvider(providerOptions);
+        }
+    }
+}
+
+module.exports = {
+    createQueueProvider,
+    determineProvider,
+    QUEUE_PROVIDERS,
+};

package/queues/queue-provider.js

@@ -0,0 +1,65 @@
+/**
+ * Queue Provider Interface (Port)
+ *
+ * Defines the contract for queue message sending.
+ * All queue adapters must extend this interface.
+ *
+ * Following Frigg's hexagonal architecture pattern:
+ * - Port defines WHAT the service does (contract)
+ * - Adapters implement HOW (AWS SQS, Netlify Background Functions, QStash, etc.)
+ */
+class QueueProvider {
+    /**
+     * Send a single message to a queue
+     *
+     * @param {Object} message - Message payload (will be JSON-serialized)
+     * @param {string} queueId - Queue identifier (URL, name, or endpoint depending on provider)
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async send(message, queueId) {
+        throw new Error('Method send must be implemented by subclass');
+    }
+
+    /**
+     * Send a batch of messages to a queue
+     *
+     * @param {Object[]} entries - Array of message payloads
+     * @param {string} queueId - Queue identifier
+     * @returns {Promise<Object>} Provider-specific response
+     */
+    async batchSend(entries, queueId) {
+        throw new Error('Method batchSend must be implemented by subclass');
+    }
+
+    /**
+     * Parse an incoming event into an array of message payloads.
+     * Each provider has its own event shape (SQS Records, HTTP body, etc.)
+     *
+     * @param {Object} event - Raw event from the runtime (Lambda event, HTTP request, etc.)
+     * @returns {Object[]} Array of parsed message payloads
+     */
+    parseEvent(event) {
+        throw new Error('Method parseEvent must be implemented by subclass');
+    }
+
+    /**
+     * Prove an incoming event was sent by Frigg before anything is parsed or
+     * dispatched. HTTP-delivered queues (Netlify Background Functions,
+     * QStash) are public URLs, so their adapters check a signature here.
+     *
+     * The default refuses: an adapter that does not know how to verify its
+     * events must not have them run. An adapter whose transport already
+     * authenticates the caller (SQS triggering a Lambda) overrides this, and
+     * must not set `verifiesHttpDelivery`: an HTTP entry point (Netlify's
+     * worker-background) consults only adapters that set it to true, since
+     * a transport-trust answer says nothing about an HTTP caller.
+     *
+     * @param {Object} event - Raw event from the runtime
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        return { ok: false, reason: 'verification_not_implemented' };
+    }
+}
+
+module.exports = { QueueProvider };

package/queues/sqs-queue-client.js

@@ -0,0 +1,81 @@
+/**
+ * SQS Queue Client (Adapter)
+ *
+ * AWS SQS implementation of QueueClientInterface, used by Worker.
+ *
+ * In friggframework/frigg#545 this adapter moved to
+ * @friggframework/provider-aws and Worker required it to be injected. In
+ * this stack the AWS SDK stays a core dependency, so the adapter lives here,
+ * Worker defaults to it, and provider-aws re-exports it. The SDK is
+ * required on first use, not at module load.
+ */
+const { QueueClientInterface } = require('./queue-client-interface');
+
+let sqsModule = null;
+function getSqsModule() {
+    if (!sqsModule) {
+        sqsModule = require('@aws-sdk/client-sqs');
+    }
+    return sqsModule;
+}
+
+/**
+ * Client config #545's adapter used: IS_OFFLINE credentials, AWS_REGION and
+ * AWS_ENDPOINT.
+ */
+function defaultSqsClientConfig() {
+    const config = {};
+    if (process.env.IS_OFFLINE) {
+        config.credentials = {
+            accessKeyId: 'test-aws-key',
+            secretAccessKey: 'test-aws-secret',
+        };
+        config.region = 'us-east-1';
+    }
+    if (!config.region && process.env.AWS_REGION) {
+        config.region = process.env.AWS_REGION;
+    }
+    if (process.env.AWS_ENDPOINT) {
+        config.endpoint = process.env.AWS_ENDPOINT;
+    }
+    return config;
+}
+
+class SqsQueueClient extends QueueClientInterface {
+    /**
+     * @param {Object} [options]
+     * @param {Object} [options.clientConfig] - SQSClient config; defaults to
+     *   defaultSqsClientConfig().
+     */
+    constructor({ clientConfig } = {}) {
+        super();
+        this._clientConfig = clientConfig;
+        this._sqs = null;
+    }
+
+    _client() {
+        if (!this._sqs) {
+            const { SQSClient } = getSqsModule();
+            this._sqs = new SQSClient(this._clientConfig || defaultSqsClientConfig());
+        }
+        return this._sqs;
+    }
+
+    async sendMessage(params) {
+        const { SendMessageCommand } = getSqsModule();
+        return this._client().send(new SendMessageCommand(params));
+    }
+
+    async sendMessageBatch(params) {
+        const { SendMessageBatchCommand } = getSqsModule();
+        return this._client().send(new SendMessageBatchCommand(params));
+    }
+
+    async getQueueUrl(params) {
+        const { GetQueueUrlCommand } = getSqsModule();
+        const data = await this._client().send(new GetQueueUrlCommand(params));
+        return data.QueueUrl;
+    }
+}
+
+module.exports = { SqsQueueClient, defaultSqsClientConfig };

package/types/index.d.ts

@@ -12,3 +12,5 @@
 /// <reference path="./eslint-config/index.d.ts" />
 /// <reference path="./associations/index.d.ts" />
 /// <reference path="./syncs/index.d.ts" />
+/// <reference path="./user/index.d.ts" />
+/// <reference path="./modules/index.d.ts" />

package/types/modules/index.d.ts

@@ -0,0 +1,197 @@
+declare module "@friggframework/core" {
+  /** Where an entity type comes from: the app's `entities` map or an integration binding it. */
+  export type EntityTypeSource =
+    | { kind: "app" }
+    | { kind: "integration"; name: string };
+
+  export type EntityScope = "individual" | "organization" | "global";
+
+  /** App-level settings carried from the `entities` entry; empty for an inferred-only type. */
+  export interface EntityTypeSettings {
+    scope?: EntityScope | { default?: EntityScope; allow?: EntityScope[] };
+    proxy?: Record<string, unknown>;
+    display?: Record<string, unknown>;
+  }
+
+  export interface EntityTypeEntry {
+    /** The API module definition. */
+    definition: any;
+    /** Frozen. `{ kind: 'app' }` first when registered, then each binding integration. */
+    sources: readonly EntityTypeSource[];
+    /** Frozen. */
+    settings: Readonly<EntityTypeSettings>;
+  }
+
+  /** Entity type name (the definition's moduleName) to its entry. */
+  export type EntityTypeRegistry = Map<string, EntityTypeEntry>;
+
+  /** One `appDefinition.entities` entry. The key must equal the definition's moduleName (and getName() when defined). */
+  export interface EntityRegistration extends EntityTypeSettings {
+    definition: any;
+  }
+
+  export interface AppDefinitionEntities {
+    /** false turns inference off: every module an integration binds must be registered. Default true. */
+    $infer?: boolean;
+    [entityType: string]: EntityRegistration | boolean | undefined;
+  }
+
+  /**
+   * One level's setting: a scope, or a default plus the scopes a request may
+   * choose from (ADR-056 §3.1). `global` is never chosen by a tenant request.
+   */
+  export type ScopeSetting =
+    | EntityScope
+    | { default?: EntityScope; allow?: EntityScope[] };
+
+  /**
+   * `appDefinition.ownership` (ADR-056 §3, §3.6). Resolution order for a new
+   * connection: request, binding, integration, entity type (`entities[name].scope`),
+   * this `scope`, then `organization` for an organization-primary app and
+   * `individual` otherwise.
+   */
+  export interface AppOwnership {
+    scope?: ScopeSetting;
+    /**
+     * `'organization'` (default): an individual entity belongs to the organization
+     * it was connected in. `'all'`: one connection per person across every
+     * organization, stored with no `organizationId`.
+     */
+    individualAcross?: "organization" | "all";
+  }
+
+  /** `Definition.ownership` on an integration (ADR-056 §3.1, §3.3). */
+  export interface IntegrationOwnership {
+    /** Scope every binding of this integration accepts unless it sets its own. */
+    scope?: ScopeSetting;
+    /** `'derive'` (default): organization when every entity it uses is organization-scoped. */
+    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;
+  }
+
+  /** Whose a record is and what the caller may do with it (ADR-056 §3.4). */
+  export interface RecordTenancy {
+    scope: Exclude<EntityScope, "global">;
+    owner: { type: Exclude<EntityScope, "global">; id: string };
+    /** Null for an individual entity connected outside an organization, or under `individualAcross: 'all'`. */
+    organizationId: string | null;
+    /** `manage`: create, reauthorize, delete. `use`: bind it, proxy through it. `view`: metadata only. */
+    access: "manage" | "use" | "view";
+  }
+
+  /** Which scope a connection gets, and from which level of the order (ADR-056 §3.1). */
+  export interface ResolvedScope {
+    scope: EntityScope;
+    /** Where `scope` came from. `request` when the request chose within the allowed list. */
+    source: "request" | "binding" | "integration" | "entityType" | "app" | "default";
+    /** The level that decided what a request may choose from. */
+    decidedBy: "binding" | "integration" | "entityType" | "app" | "default";
+    allow: EntityScope[];
+  }
+
+  /**
+   * First match wins, each level overriding the ones below it. A request may
+   * choose only from the deciding level's `allow`; `global` never comes from a
+   * tenant request. Throws a Boom 400/403 for a request scope that is not allowed.
+   */
+  export function resolveScope(levels: {
+    request?: EntityScope;
+    binding?: ScopeSetting;
+    integration?: ScopeSetting;
+    entityType?: ScopeSetting;
+    app?: ScopeSetting;
+    primary?: "individual" | "organization";
+  }): ResolvedScope;
+
+  /** Every binding of every integration with its resolved scope (for tooling that wants to show the chain). */
+  export function listBindingScopes(
+    appDefinition: Pick<AppDefinition, "integrations" | "ownership">,
+    entityTypeRegistry: EntityTypeRegistry,
+    primary?: "individual" | "organization"
+  ): Array<{
+    integration: string;
+    binding: string;
+    moduleName: string | null;
+    scope: EntityScope;
+    source: ResolvedScope["source"];
+    owner: "derive" | "individual" | "organization";
+  }>;
+
+  /** Invalid ownership or scope setting, thrown at app-definition load. `code` is always `OWNERSHIP_CONFIG_INVALID`. */
+  export class OwnershipConfigError extends Error {
+    code: "OWNERSHIP_CONFIG_INVALID";
+  }
+
+  /**
+   * Builds the registry from `entities` plus the modules integrations bind.
+   * Throws EntityRegistryError on an invalid registry.
+   */
+  export function getEntityTypeRegistry(
+    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
+   * integrations (plus registry-only types when `entities` is passed).
+   */
+  export function getModulesDefinitionFromIntegrationClasses(
+    integrationClasses: any[],
+    entities?: AppDefinitionEntities
+  ): any[];
+
+  /** Invalid `entities` registry. `code` is always `ENTITY_REGISTRY_INVALID`. */
+  export class EntityRegistryError extends Error {
+    code: "ENTITY_REGISTRY_INVALID";
+  }
+}