@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.693.d8859c2.0

package/modules/use-cases/entity-types.js

@@ -1,139 +0,0 @@
-const Boom = require('@hapi/boom');
-const { ModuleConstants } = require('../ModuleConstants');
-const { usedByOf } = require('../entity-type-registry');
-
-const AUTH_TYPE_BY_REQUESTER = {
-    [ModuleConstants.authType.oauth2]: 'oauth2',
-    [ModuleConstants.authType.oauth1]: 'oauth1',
-    [ModuleConstants.authType.apiKey]: 'api-key',
-    [ModuleConstants.authType.basic]: 'basic',
-};
-
-const callIfFunction = (target, name) =>
-    typeof target?.[name] === 'function' ? target[name]() : undefined;
-
-/** Number of authorization steps a module declares (1 unless multi-step). */
-function getAuthStepCount(definition) {
-    const count = callIfFunction(definition, 'getAuthStepCount');
-    return Number.isInteger(count) && count > 0 ? count : 1;
-}
-
-/**
- * Public description of an API module (an "entity type"). Reads only the
- * definition: display metadata, auth type and step count. Never credentials
- * or env values.
- */
-function describeEntityType(definition, typeName = definition.moduleName) {
-    const stepCount = getAuthStepCount(definition);
-    const display = definition.display || {};
-    const description = {
-        type: typeName,
-        name:
-            callIfFunction(definition, 'getDisplayName') ??
-            display.label ??
-            display.name ??
-            typeName,
-        authType:
-            callIfFunction(definition, 'getAuthType') ??
-            AUTH_TYPE_BY_REQUESTER[definition.API?.requesterType] ??
-            'custom',
-        isMultiStep: stepCount > 1,
-        stepCount,
-    };
-    const text = callIfFunction(definition, 'getDescription') ?? display.description;
-    if (text) description.description = text;
-    const capabilities = callIfFunction(definition, 'getCapabilities');
-    if (capabilities !== undefined) description.capabilities = capabilities;
-    return description;
-}
-
-function findDefinition(moduleDefinitions, entityType) {
-    const definition = moduleDefinitions.find(
-        (def) => def.moduleName === entityType
-    );
-    if (!definition) {
-        throw Boom.notFound(`Entity type '${entityType}' not found`, {
-            code: 'ENTITY_TYPE_NOT_FOUND',
-        });
-    }
-    return definition;
-}
-
-/**
- * With a scope policy the entry also says which scope a new connection gets
- * and which a request may choose (ADR-056 §3.1), so a UI can offer the choice.
- * `global` is never offered: a tenant request cannot create one.
- */
-const scopeOf = (scopePolicy, name, user) => {
-    if (!scopePolicy) return {};
-    const { scope, source, allow } = scopePolicy.resolveScope({
-        entityType: name,
-        user,
-    });
-    return {
-        scope: {
-            default: scope,
-            allow: allow.filter((value) => value !== 'global'),
-            source,
-        },
-    };
-};
-
-const describeEntry = (name, entry, scopePolicy, user) => ({
-    // The registry key is the name the API uses, whatever the definition spells.
-    ...describeEntityType(entry.definition, name),
-    usedBy: usedByOf(entry),
-    ...scopeOf(scopePolicy, name, user),
-});
-
-function requireRegistry(entityTypeRegistry) {
-    if (!(entityTypeRegistry instanceof Map)) {
-        throw new TypeError('entityTypeRegistry is required (see getEntityTypeRegistry)');
-    }
-    return entityTypeRegistry;
-}
-
-/**
- * Lists the entity types this app can authorize: registry entries plus every
- * module an integration binds (ADR-059). `usedBy` names the integrations that
- * bind each type; it is empty for a registry-only type.
- */
-class ListEntityTypes {
-    constructor({ entityTypeRegistry, scopePolicy }) {
-        this.registry = requireRegistry(entityTypeRegistry);
-        this.scopePolicy = scopePolicy;
-    }
-
-    /** @param {{user?: Object}} [params] - the caller, for the level-6 scope default */
-    async execute({ user } = {}) {
-        return [...this.registry]
-            .map(([name, entry]) => describeEntry(name, entry, this.scopePolicy, user))
-            .sort((a, b) => a.name.localeCompare(b.name));
-    }
-}
-
-/** Describes one entity type, looked up by its registry key; 404 when absent. */
-class GetEntityType {
-    constructor({ entityTypeRegistry, scopePolicy }) {
-        this.registry = requireRegistry(entityTypeRegistry);
-        this.scopePolicy = scopePolicy;
-    }
-
-    async execute(entityType, { user } = {}) {
-        const entry = this.registry.get(entityType);
-        if (!entry) {
-            throw Boom.notFound(`Entity type '${entityType}' not found`, {
-                code: 'ENTITY_TYPE_NOT_FOUND',
-            });
-        }
-        return describeEntry(entityType, entry, this.scopePolicy, user);
-    }
-}
-
-module.exports = {
-    ListEntityTypes,
-    GetEntityType,
-    describeEntityType,
-    getAuthStepCount,
-    findDefinition,
-};

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

@@ -1,331 +0,0 @@
-const Boom = require('@hapi/boom');
-const { getLogger } = require('../../logs');
-const { getTelemetry } = require('../../telemetry/telemetry-runtime');
-const { ProxyRequestError, ProxyConfigError } = require('../proxy/proxy-errors');
-const { SCOPES } = require('../scope-resolution');
-const { grantsUse } = require('../scope-visibility');
-const { normalizeProxyPath, matchAllowRule } = require('../proxy/proxy-path');
-const { DEFAULT_BASE, resolveModuleBases } = require('../proxy/proxy-bases');
-const {
-    validateProxyRequest,
-    resolveAllowRules,
-    filterRequestHeaders,
-    filterResponseHeaders,
-    decodeResponseBody,
-} = require('../proxy/proxy-policy');
-
-const log = getLogger('frigg.api.proxy');
-
-/** HTTP status and audit outcome for each proxy error code (ADR-052 §10). */
-const ERROR_MAP = {
-    INVALID_PROXY_REQUEST: { status: 400, outcome: 'denied' },
-    PROXY_UNKNOWN_BASE: { status: 400, outcome: 'denied' },
-    PROXY_NOT_ALLOWED: { status: 403, outcome: 'denied' },
-    PAYLOAD_TOO_LARGE: { status: 413, outcome: 'too_large' },
-    UNSUPPORTED_MEDIA_TYPE: { status: 415, outcome: 'denied' },
-    PROXY_NOT_CONFIGURED: { status: 501, outcome: 'denied' },
-    INVALID_CREDENTIALS: { status: 401, outcome: 'upstream_error' },
-    RATE_LIMITED: { status: 429, outcome: 'upstream_error' },
-    UPSTREAM_ERROR: { status: 502, outcome: 'upstream_error' },
-    NETWORK_ERROR: { status: 502, outcome: 'upstream_error' },
-    RESPONSE_TOO_LARGE: { status: 502, outcome: 'too_large' },
-    TIMEOUT: { status: 504, outcome: 'timeout' },
-};
-
-function toBoom(error, extra = {}) {
-    const mapping = ERROR_MAP[error.code] || { status: 502 };
-    const boom = new Boom.Boom(error.message, {
-        statusCode: mapping.status,
-        data: {
-            code: error.code,
-            details: error.details,
-            // Every proxy message is written for the caller (no URLs, no
-            // credential material), including the 5xx ones.
-            expose: true,
-            proxy: true,
-            ...extra,
-        },
-    });
-    return boom;
-}
-
-const authHeaderNamesOf = (api) =>
-    [api?.api_key_name, api?.API_KEY_NAME].filter(
-        (name) => typeof name === 'string' && name
-    );
-
-/**
- * POST /api/v2/entities/:entityId/proxy (ADR-052): calls the entity's API
- * through its module with the stored credential, inside the limits the app
- * and the module set.
- *
- * Order of checks: request shape and size, path rules, entity visibility in
- * the active organization (404), `use` access (403), the entity's scope
- * against `managementApi.proxy.scopes` (403), the module's allow-list (403,
- * deny by default), credential readiness (401), then the call through
- * Requester._proxyRequest. Every call,
- * allowed or denied, writes one audit record and one usage count. Bodies,
- * headers, query values and the raw path are never logged.
- */
-class ExecuteEntityProxyRequest {
-    /**
-     * @param {Object} params
-     * @param {import('./get-entity-module-for-user').GetEntityModuleForUser} params.getEntityModuleForUser
-     * @param {ReturnType<import('../../management-api/management-api-config').resolveManagementApiConfig>['proxy']} params.proxyConfig
-     * @param {Object} [params.telemetry]
-     * @param {() => number} [params.now]
-     */
-    constructor({ getEntityModuleForUser, proxyConfig, telemetry, now }) {
-        this.getEntityModuleForUser = getEntityModuleForUser;
-        this.proxyConfig = proxyConfig;
-        this.telemetry = telemetry;
-        this.now = now || Date.now;
-    }
-
-    /**
-     * @param {string} entityId
-     * @param {Object} user - authenticated User
-     * @param {Object} request - { method, path, query?, headers?, body? }
-     * @returns {Promise<{ status: number, body: { success: boolean, status: number, headers: Object, data: unknown, dataEncoding?: string } }>}
-     */
-    async execute(entityId, user, request) {
-        const started = this.now();
-        const audit = {
-            userId: user?.getId?.(),
-            organizationId: user?.getOrganizationUser?.()?.id,
-            entityId: String(entityId),
-            method: typeof request?.method === 'string' ? request.method.toUpperCase() : undefined,
-            requestBytes: 0,
-        };
-
-        try {
-            const validated = validateProxyRequest(request, this.proxyConfig);
-            audit.method = validated.method;
-            audit.requestBytes = validated.requestBytes;
-            const path = normalizeProxyPath(validated.path);
-
-            // Visible in the active organization, or 404 (ADR-056 §3.6): the
-            // same clauses the v2 lists use, so a missing entity, another
-            // person's and one paired with another organization look alike.
-            const { entity, definition, module } =
-                await this.getEntityModuleForUser.execute(entityId, user);
-            audit.module = definition.moduleName;
-            this.assertProxyable(entityId, entity, definition, user);
-
-            // The base is a name the module declared; the host comes from the
-            // module's declaration, never from the request.
-            const base = validated.base ?? DEFAULT_BASE;
-            audit.base = base;
-            const bases = this.basesOf(definition);
-            if (!bases.names.includes(base)) {
-                throw new ProxyRequestError(
-                    'PROXY_UNKNOWN_BASE',
-                    `Module ${definition.moduleName} has no base named ${base}; use one of: ${bases.names.join(', ')}`,
-                    { module: definition.moduleName, base, bases: bases.names }
-                );
-            }
-
-            const credentialRef = entity.credential;
-            const credentialId =
-                credentialRef && typeof credentialRef === 'object'
-                    ? credentialRef.id ?? credentialRef._id
-                    : credentialRef;
-            if (credentialId !== undefined && credentialId !== null) {
-                audit.credentialId = String(credentialId);
-            }
-
-            const { rules } = resolveAllowRules(definition, this.proxyConfig.modules);
-            const rule = matchAllowRule(rules, validated.method, path, base);
-            if (!rule) {
-                throw new ProxyRequestError(
-                    'PROXY_NOT_ALLOWED',
-                    `Module ${definition.moduleName} does not allow ${validated.method} on this path` +
-                        // Single-base modules keep the message they always had.
-                        (bases.names.length > 1 ? ` of base ${base}` : ''),
-                    { module: definition.moduleName, method: validated.method, base }
-                );
-            }
-            audit.pattern = rule.path;
-
-            const credential = entity.credential;
-            if (!credential || (typeof credential === 'object' && credential.authIsValid === false)) {
-                throw new ProxyRequestError(
-                    'INVALID_CREDENTIALS',
-                    'The entity has no usable credential; re-authorize it'
-                );
-            }
-
-            const authHeaderNames = authHeaderNamesOf(module.api);
-            const headers = filterRequestHeaders(validated.headers, {
-                moduleHeaders: Array.isArray(definition.proxy?.headers) ? definition.proxy.headers : [],
-                authHeaderNames,
-            });
-            if (validated.body !== undefined && !headers['content-type']) {
-                headers['content-type'] = validated.bodyIsJson ? 'application/json' : 'text/plain';
-            }
-
-            const upstream = await module.api._proxyRequest({
-                method: validated.method,
-                path,
-                query: validated.query,
-                headers,
-                body: validated.body,
-                baseUrl: this.resolveBaseUrl(bases, module.api, base),
-                timeoutMs: this.proxyConfig.timeoutMs,
-                maxResponseBytes: this.proxyConfig.maxResponseBytes,
-                isAllowedRedirect: (nextPath, nextMethod) =>
-                    Boolean(matchAllowRule(rules, nextMethod, nextPath, base)),
-            });
-            audit.upstreamStatus = upstream.status;
-            audit.responseBytes = upstream.body?.length ?? 0;
-
-            if (upstream.status === 429) {
-                throw Object.assign(
-                    new ProxyRequestError('RATE_LIMITED', 'The upstream API is rate limiting this account', {
-                        upstreamStatus: 429,
-                    }),
-                    { retryAfter: upstream.headers['retry-after'] }
-                );
-            }
-            if (upstream.status >= 500) {
-                throw new ProxyRequestError('UPSTREAM_ERROR', 'The upstream API returned an error', {
-                    upstreamStatus: upstream.status,
-                });
-            }
-
-            const decoded = decodeResponseBody(upstream.body, upstream.contentType, {
-                binary: definition.proxy?.binary === true,
-            });
-            const result = {
-                status: upstream.status,
-                body: {
-                    success: upstream.status < 400,
-                    status: upstream.status,
-                    headers: filterResponseHeaders(upstream.headers, {
-                        redirectBlocked: upstream.redirectBlocked,
-                        authHeaderNames,
-                    }),
-                    data: decoded.data,
-                    ...(decoded.encoding && { dataEncoding: decoded.encoding }),
-                },
-            };
-            this.record(audit, upstream.status < 400 ? 'ok' : 'upstream_error', started);
-            return result;
-        } catch (error) {
-            if (error instanceof ProxyRequestError) {
-                const { outcome = 'upstream_error' } = ERROR_MAP[error.code] || {};
-                this.record(audit, outcome, started, error.code);
-                throw toBoom(error, error.retryAfter ? { retryAfter: error.retryAfter } : {});
-            }
-            const notFound = error?.isBoom && error.output.statusCode === 404;
-            this.record(
-                audit,
-                notFound ? 'denied' : 'error',
-                started,
-                error?.data?.code || (error?.isBoom ? undefined : 'INTERNAL_ERROR')
-            );
-            throw error;
-        }
-    }
-
-    /**
-     * 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 }
-            );
-        }
-    }
-
-    /**
-     * The module's bases. Load already validated the definition
-     * (assertProxyConfig), so this only fails for a definition that skipped
-     * load; that is a configuration fault (501), never an unmapped 500.
-     */
-    basesOf(definition) {
-        try {
-            return resolveModuleBases(definition);
-        } catch (error) {
-            if (!(error instanceof ProxyConfigError)) throw error;
-            throw new ProxyRequestError(
-                'PROXY_NOT_CONFIGURED',
-                `Module ${definition.moduleName} has invalid proxy settings`
-            );
-        }
-    }
-
-    /**
-     * The URL of the named base. A base the module declared never falls back
-     * to the requester's own host (that would send the module's token to a
-     * host the module did not name); only a module that declares nothing at
-     * all uses the requester's base URL, signalled by undefined.
-     */
-    resolveBaseUrl(bases, api, name) {
-        const declared = bases.values.get(name);
-        if (!bases.declared) return undefined;
-        const url = typeof declared === 'function' ? declared(api) : declared;
-        if (typeof url !== 'string' || url === '') {
-            throw new ProxyRequestError(
-                'PROXY_NOT_CONFIGURED',
-                `The module declares no usable URL for base ${name}`
-            );
-        }
-        return url;
-    }
-
-    /** One audit record (ADR-048) and one usage count (ADR-011) per call. */
-    record(audit, outcome, started, reason) {
-        const fields = {
-            eventName: 'frigg.api.proxy.request',
-            ...audit,
-            outcome,
-            durationMs: this.now() - started,
-            ...(reason && { reason }),
-        };
-        if (outcome === 'ok' || outcome === 'upstream_error') {
-            log.info('Entity proxy request', fields);
-        } else {
-            log.warn('Entity proxy request refused', fields);
-        }
-        try {
-            (this.telemetry || getTelemetry()).count('frigg.api.proxy.requests', 1, {
-                module: audit.module || 'unknown',
-                method: audit.method || 'unknown',
-                outcome,
-            });
-        } catch {
-            // Telemetry must never break a request.
-        }
-    }
-}
-
-module.exports = { ExecuteEntityProxyRequest, ERROR_MAP };

package/modules/use-cases/get-authorization-requirements.js

@@ -1,100 +0,0 @@
-const Boom = require('@hapi/boom');
-const { findDefinition, getAuthStepCount } = require('./entity-types');
-
-const defaultCreateModule = (params) => {
-    const { Module } = require('../module');
-    return Module.create(params);
-};
-
-/**
- * Normalises what a module returns for a step into the v2 requirements
- * shape: `{ type, data }`. Modules either return `{ type, data }` already
- * (multi-step, JSON-schema forms) or a flat object such as the OAuth2
- * requester's `{ type: 'oauth2', url }`.
- */
-function normalizeRequirements(raw) {
-    if (!raw || typeof raw !== 'object') return { type: 'custom', data: {} };
-    if (raw.data && typeof raw.data === 'object') {
-        return { ...raw, type: raw.type || 'custom' };
-    }
-    const { type, ...data } = raw;
-    return { type: type || 'custom', data };
-}
-
-/**
- * Single-step requirements, from wherever the module declares them: a
- * requiredAuthMethods.getAuthorizationRequirements(api) (the form-based
- * API-key convention `frigg auth` uses), or the Api's own
- * getAuthorizationRequirements() (OAuth2Requester builds the authorize URL).
- */
-async function singleStepRequirements(definition, module) {
-    const declared = definition.requiredAuthMethods?.getAuthorizationRequirements;
-    if (typeof declared === 'function') return declared(module.api);
-    if (typeof module.api?.getAuthorizationRequirements === 'function') {
-        return module.api.getAuthorizationRequirements();
-    }
-    throw Boom.notImplemented(
-        `Module ${definition.moduleName} declares no authorization requirements (add requiredAuthMethods.getAuthorizationRequirements)`,
-        { code: 'REQUIREMENTS_NOT_DECLARED', expose: true }
-    );
-}
-
-/**
- * What the caller must submit for one authorization step of an entity type
- * (Management API v2). Single-step modules use their Api's
- * getAuthorizationRequirements(); multi-step modules declare
- * getAuthStepCount() and getAuthRequirementsForStep(step) on their
- * definition (docs/MULTI_STEP_AUTH_MIGRATION_GUIDE.md).
- */
-class GetAuthorizationRequirements {
-    /**
-     * @param {Object} params
-     * @param {Array<Object>} params.moduleDefinitions
-     * @param {Function} [params.createModule]
-     */
-    constructor({ moduleDefinitions, createModule }) {
-        this.moduleDefinitions = moduleDefinitions || [];
-        this.createModule = createModule || defaultCreateModule;
-    }
-
-    /**
-     * @param {Object} params
-     * @param {string} params.entityType
-     * @param {number} [params.step=1]
-     * @param {string} [params.userId]
-     * @param {string} [params.state] - OAuth state forwarded to the Api.
-     * @returns {Promise<{type: string, data: Object, step: number, totalSteps: number, isMultiStep: boolean}>}
-     */
-    async execute({ entityType, step = 1, userId = null, state } = {}) {
-        const definition = findDefinition(this.moduleDefinitions, entityType);
-        const totalSteps = getAuthStepCount(definition);
-
-        if (!Number.isInteger(step) || step < 1 || step > totalSteps) {
-            throw Boom.badRequest(
-                `step must be between 1 and ${totalSteps} for ${entityType}`,
-                { code: 'INVALID_STEP' }
-            );
-        }
-
-        let raw;
-        if (typeof definition.getAuthRequirementsForStep === 'function') {
-            raw = await definition.getAuthRequirementsForStep(step);
-        } else {
-            const module = await this.createModule({
-                userId,
-                definition,
-                ...(state ? { state } : {}),
-            });
-            raw = await singleStepRequirements(definition, module);
-        }
-
-        return {
-            ...normalizeRequirements(raw),
-            step,
-            totalSteps,
-            isMultiStep: totalSteps > 1,
-        };
-    }
-}
-
-module.exports = { GetAuthorizationRequirements, normalizeRequirements };

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

@@ -1,113 +0,0 @@
-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
- * domain object's rule (individual or organisation user model) when present.
- * This is the owner-only rule: it ignores the organization a record belongs
- * to, so it no longer decides access to an entity or an integration
- * (modules/scope-visibility.js does). Credentials still use it.
- * @param {Object} user - authenticated User (or a plain { getId } double)
- * @param {string|number} ownerId
- */
-function userOwns(user, ownerId) {
-    if (ownerId === undefined || ownerId === null || !user) return false;
-    if (typeof user.ownsUserId === 'function') return user.ownsUserId(ownerId);
-    return String(user.getId()) === String(ownerId);
-}
-
-const defaultCreateModule = (params) => {
-    const { Module } = require('../module');
-    return Module.create(params);
-};
-
-/**
- * Loads an entity the caller owns and builds its Module (API client
- * hydrated from the persisted entity and credential). Management API v2.
- *
- * A missing entity and one owned by someone else are the same 404, so ids
- * cannot be probed (ADR-052 §3).
- */
-class GetEntityModuleForUser {
-    /**
-     * @param {Object} params
-     * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
-     * @param {Array<Object>} params.moduleDefinitions
-     * @param {Function} [params.createModule] - builds a Module; injectable for tests.
-     * @param {Object} [params.scopePolicy] - from createScopePolicy; with none the
-     *   app configures nothing (ADR-056 §3.1).
-     */
-    constructor({ moduleRepository, moduleDefinitions, createModule, scopePolicy }) {
-        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
-        this.moduleRepository = moduleRepository;
-        this.moduleDefinitions = moduleDefinitions || [];
-        this.createModule = createModule || defaultCreateModule;
-    }
-
-    /**
-     * @param {string} entityId
-     * @param {Object} user - authenticated User
-     * @returns {Promise<{ entity: Object, definition: Object, module: Object }>}
-     */
-    async execute(entityId, user) {
-        const entity = await this.loadOwnedEntity(entityId, user);
-        const definition = this.moduleDefinitions.find(
-            (def) => def.moduleName === entity.moduleName
-        );
-        if (!definition) {
-            throw Boom.notFound(
-                `Entity type ${entity.moduleName} is not configured in this app`,
-                { code: 'ENTITY_TYPE_NOT_FOUND' }
-            );
-        }
-        const module = await this.createModule({
-            userId: entity.userId,
-            entity,
-            definition,
-        });
-        return { entity, definition, module };
-    }
-
-    /**
-     * The entity record, or a 404 when it is missing or the caller may not use
-     * it: not theirs, or paired with another organization (ADR-056 §3.6). A
-     * `global` entity is never the tenant's to load.
-     */
-    async loadOwnedEntity(entityId, user) {
-        let entity = null;
-        try {
-            entity = await this.moduleRepository.findEntityById(entityId);
-        } catch (error) {
-            // Every adapter throws for a missing row, and a malformed id (e.g.
-            // not an integer on Postgres) is "not found" too. Both must be the
-            // 404 another tenant's entity gets, or the status says which ids
-            // exist. Anything else is a real failure.
-            if (
-                isEntityNotFound(error) ||
-                /Invalid ID|ObjectId|Malformed/i.test(error?.message || '')
-            ) {
-                entity = null;
-            } else {
-                throw error;
-            }
-        }
-        if (!entity || !this.describe(entity, user)) {
-            throw Boom.notFound(`Entity ${entityId} not found`, {
-                code: 'ENTITY_NOT_FOUND',
-            });
-        }
-        return entity;
-    }
-
-    /**
-     * `{ scope, owner, organizationId, access }` of an entity to this caller,
-     * or null when they may not see it (§3.4).
-     */
-    describe(entity, user) {
-        return describeRecord(entity, this.scopePolicy.accessContext(user), 'entity');
-    }
-}
-
-module.exports = { GetEntityModuleForUser, userOwns };