@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

package/management-api/route-registry.js

@@ -50,8 +50,16 @@ const RESERVED_V2_SEGMENTS = Object.freeze(['reports']);
 const V1_MIGRATION_DOCS_URL =
     'https://docs.friggframework.org/api/migrate-v1-v2';
 
-/** Lambda functions (devtools names) that serve Management API routes. */
-const FUNCTIONS = Object.freeze({ AUTH: 'auth', HEALTH: 'health' });
+/**
+ * Functions (devtools names) that serve registered routes. `queueWorker` is
+ * the HTTP queue worker of hosts that deliver queue messages over HTTP
+ * (provider-netlify's worker-background); AWS delivers through SQS.
+ */
+const FUNCTIONS = Object.freeze({
+    AUTH: 'auth',
+    HEALTH: 'health',
+    QUEUE_WORKER: 'queueWorker',
+});
 
 const route = (version, fn) => (definition) =>
     Object.freeze({ version, function: fn, ...definition });
@@ -180,6 +188,91 @@ const AUTH_EXTRA_ROUTES = Object.freeze(
     ].map(route(null, FUNCTIONS.AUTH))
 );
 
+/**
+ * Unversioned routes the DB-free health Lambda serves next to /api/meta.
+ * GET /api/docs redirects to the current OpenAPI document; the docs
+ * themselves live under /api/meta (ADR-053).
+ */
+const DOCS_ROUTES = Object.freeze(
+    [
+        {
+            operationId: 'redirectToOpenApi',
+            method: 'GET',
+            path: '/api/docs',
+        },
+    ].map(route(null, FUNCTIONS.HEALTH))
+);
+
+/**
+ * Admin routes live under /admin (as core's /admin/db-migrate and the
+ * admin-scripts /admin/scripts do), never under the public /api prefix. A
+ * core extension (appDefinition.coreExtensions[].routes.path) mounts its admin
+ * API at /admin/<name>, served by the auth function behind the admin API key;
+ * these segments belong to other functions and cannot be taken.
+ */
+const ADMIN_ROUTE_PREFIX = '/admin/';
+const RESERVED_ADMIN_SEGMENTS = Object.freeze(['scripts', 'db-migrate', 'queue']);
+
+/**
+ * The queue delivery endpoint of hosts that deliver queue messages over HTTP
+ * (QStash posts here on Netlify). Every message must be signed: the worker
+ * verifies it before parsing anything. Not part of the public /api surface.
+ */
+const HTTP_QUEUE_ROUTES = Object.freeze(
+    [
+        {
+            operationId: 'deliverQueueMessage',
+            method: 'POST',
+            path: '/admin/queue',
+        },
+    ].map(route(null, FUNCTIONS.QUEUE_WORKER))
+);
+
+/**
+ * Why a core extension route path is not acceptable, or null when it is:
+ * `/admin/<segment>` (letters, digits, `-` and `_`, one or more segments), not
+ * a reserved segment.
+ *
+ * @param {*} path
+ * @returns {string|null}
+ */
+function coreExtensionRoutePathError(path) {
+    if (typeof path !== 'string' || !path.startsWith(ADMIN_ROUTE_PREFIX)) {
+        return `must start with ${ADMIN_ROUTE_PREFIX} (admin routes are not served under /api)`;
+    }
+    if (!/^\/admin(\/[A-Za-z0-9_-]+)+$/.test(path)) {
+        return 'must be /admin/<segment>[/<segment>...] using letters, digits, - and _';
+    }
+    const segment = path.split('/')[2];
+    if (RESERVED_ADMIN_SEGMENTS.includes(segment)) {
+        return `/admin/${segment} is reserved (${RESERVED_ADMIN_SEGMENTS.map((s) => `/admin/${s}`).join(', ')})`;
+    }
+    return null;
+}
+
+/**
+ * Route records for the core extensions' admin routes: each path and
+ * everything under it, on the auth function (core's auth router mounts the
+ * extension routes behind the admin API key).
+ *
+ * @param {Array<Object>} [coreExtensions] - appDefinition.coreExtensions (plain data;
+ *   only `routes.path` is read)
+ * @returns {Array<Object>}
+ */
+function listCoreExtensionRoutes(coreExtensions = []) {
+    if (!Array.isArray(coreExtensions)) return [];
+    const out = [];
+    for (const ext of coreExtensions) {
+        const path = ext?.routes?.path;
+        if (typeof path !== 'string' || coreExtensionRoutePathError(path)) continue;
+        out.push(
+            Object.freeze({ version: null, function: FUNCTIONS.AUTH, method: 'ANY', path, extension: ext.name }),
+            Object.freeze({ version: null, function: FUNCTIONS.AUTH, method: 'ANY', path: `${path}/{proxy+}`, extension: ext.name })
+        );
+    }
+    return out;
+}
+
 /**
  * The v2 routes an app serves. Routes tied to an opt-in capability (the entity
  * proxy, ADR-052) are left out unless the app enables it.
@@ -206,6 +299,7 @@ function listRoutes({ v1 = true, proxy = false } = {}) {
         ...listV2Routes({ proxy }),
         ...META_ROUTES,
         ...AUTH_EXTRA_ROUTES,
+        ...DOCS_ROUTES,
     ];
 }
 
@@ -225,18 +319,25 @@ function resourceRoot(record) {
 }
 
 /**
- * API Gateway HTTP API routes for the Management API, derived from the
- * registry. Each resource root gets an exact route when the root itself is
+ * Gateway routes derived from the registry: the Management API, its
+ * discovery and docs routes, the core extensions' admin routes and, for
+ * hosts that deliver queue messages over HTTP, the queue endpoint. Each
+ * Management API resource root gets an exact route when the root itself is
  * registered and a greedy `{proxy+}` route when deeper paths are. The auth
  * function uses `ANY` (as it always has, so CORS preflights reach Express);
  * the health function only serves GET.
  *
+ * devtools turns these into API Gateway HTTP API events; provider-netlify
+ * into netlify.toml redirects.
+ *
  * @param {Object} [options]
  * @param {boolean} [options.v1=true]
  * @param {boolean} [options.proxy=false]
+ * @param {Array<Object>} [options.coreExtensions=[]] - appDefinition.coreExtensions
+ * @param {boolean} [options.httpQueue=false] - include the HTTP queue route
  * @returns {Array<{function: string, method: string, path: string}>}
  */
-function getGatewayRoutes({ v1 = true, proxy = false } = {}) {
+function getGatewayRoutes({ v1 = true, proxy = false, coreExtensions = [], httpQueue = false } = {}) {
     const out = [];
     const seen = new Set();
     const add = (fn, method, path) => {
@@ -265,7 +366,7 @@ function getGatewayRoutes({ v1 = true, proxy = false } = {}) {
 
     // Extra routes get an exact route unless a greedy route on the same
     // function already covers them.
-    for (const record of AUTH_EXTRA_ROUTES) {
+    for (const record of [...AUTH_EXTRA_ROUTES, ...DOCS_ROUTES]) {
         const covered = greedyRoots.has(
             `${record.function} ${resourceRoot(record)}`
         );
@@ -274,6 +375,16 @@ function getGatewayRoutes({ v1 = true, proxy = false } = {}) {
         }
     }
 
+    for (const record of listCoreExtensionRoutes(coreExtensions)) {
+        add(record.function, record.method, record.path);
+    }
+
+    if (httpQueue) {
+        for (const record of HTTP_QUEUE_ROUTES) {
+            add(record.function, record.method, record.path);
+        }
+    }
+
     return out;
 }
 
@@ -287,6 +398,12 @@ module.exports = {
     V2_ROUTES,
     META_ROUTES,
     AUTH_EXTRA_ROUTES,
+    DOCS_ROUTES,
+    HTTP_QUEUE_ROUTES,
+    ADMIN_ROUTE_PREFIX,
+    RESERVED_ADMIN_SEGMENTS,
+    coreExtensionRoutePathError,
+    listCoreExtensionRoutes,
     listRoutes,
     listV2Routes,
     getGatewayRoutes,

package/management-api/v2/dependencies.js

@@ -29,13 +29,18 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         getEntityTypeRegistry,
         getEntityTypeDefinitions,
     } = require('../../modules/entity-type-registry');
-    const { GetUserFromBearerToken } = require('../../user/use-cases/get-user-from-bearer-token');
-    const { GetUserFromXFriggHeaders } = require('../../user/use-cases/get-user-from-x-frigg-headers');
-    const { GetUserFromAdopterJwt } = require('../../user/use-cases/get-user-from-adopter-jwt');
+    const { createScopePolicy } = require('../../modules/scope-policy');
+    const {
+        AuthorizeEntityForUser,
+    } = require('../../modules/use-cases/authorize-entity-for-user');
+    const {
+        ResolveIntegrationOwnership,
+    } = require('../../integrations/use-cases/resolve-integration-ownership');
     const {
         AuthenticateWithSharedSecret,
     } = require('../../user/use-cases/authenticate-with-shared-secret');
     const { AuthenticateUser } = require('../../user/use-cases/authenticate-user');
+    const { buildUserAuthentication } = require('../../user/create-user-authentication');
     const { CreateIntegration } = require('../../integrations/use-cases/create-integration');
     const { UpdateIntegration } = require('../../integrations/use-cases/update-integration');
     const {
@@ -87,6 +92,11 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         appDefinition.entityTypeRegistry ??
         getEntityTypeRegistry(appDefinition);
     const moduleDefinitions = getEntityTypeDefinitions(registry);
+    // Ownership by scope (ADR-056 §3): one object every use case asks.
+    const scopePolicy = createScopePolicy({
+        ownership: appDefinition.ownership,
+        entityTypeRegistry: registry,
+    });
 
     const moduleRepository = createModuleRepository();
     const integrationRepository = createIntegrationRepository();
@@ -95,9 +105,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     const authorizationSessionRepository = createAuthorizationSessionRepository();
 
     const authenticateUser = new AuthenticateUser({
-        getUserFromBearerToken: new GetUserFromBearerToken({ userRepository, userConfig }),
-        getUserFromXFriggHeaders: new GetUserFromXFriggHeaders({ userRepository, userConfig }),
-        getUserFromAdopterJwt: new GetUserFromAdopterJwt({ userRepository, userConfig }),
+        ...buildUserAuthentication({ userConfig, userRepository }),
         authenticateWithSharedSecret: new AuthenticateWithSharedSecret(),
         userConfig,
     });
@@ -111,10 +119,12 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     const getEntityModuleForUser = new GetEntityModuleForUser({
         moduleRepository,
         moduleDefinitions,
+        scopePolicy,
     });
     const getCredentialForUser = new credentialOps.GetCredentialForUserV2({
         credentialRepository,
         moduleRepository,
+        scopePolicy,
     });
     const getAuthorizationRequirements = new GetAuthorizationRequirements({
         moduleDefinitions,
@@ -128,17 +138,22 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         moduleDefinitions,
         getAuthorizationRequirements,
         authorizationSessionRepository,
-        processAuthorizationCallback: new ProcessAuthorizationCallback({
-            moduleRepository,
-            credentialRepository,
-            integrationRepository,
-            moduleDefinitions,
+        authorizeEntityForUser: new AuthorizeEntityForUser({
+            scopePolicy,
+            processAuthorizationCallback: new ProcessAuthorizationCallback({
+                moduleRepository,
+                credentialRepository,
+                integrationRepository,
+                moduleDefinitions,
+            }),
         }),
         moduleRepository,
         credentialRepository,
+        scopePolicy,
     });
     const getOwnedIntegrationRecord = new integrationOps.GetOwnedIntegrationRecord({
         integrationRepository,
+        scopePolicy,
     });
     const getIntegrationInstanceForUser = new integrationOps.GetIntegrationInstanceForUser({
         getOwnedIntegrationRecord,
@@ -148,6 +163,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
     return {
         config,
         moduleDefinitions,
+        scopePolicy,
         repositories: {
             moduleRepository,
             integrationRepository,
@@ -163,6 +179,7 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
             integrationClasses,
             moduleFactory,
             moduleRepository,
+            scopePolicy,
         }),
         getPossibleIntegrations: new GetPossibleIntegrations({ integrationClasses }),
         createIntegrationForUser: new integrationOps.CreateIntegrationForUser({
@@ -171,7 +188,11 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
                 integrationClasses,
                 moduleFactory,
             }),
-            getEntityModuleForUser,
+            resolveIntegrationOwnership: new ResolveIntegrationOwnership({
+                moduleRepository,
+                integrationClasses,
+                scopePolicy,
+            }),
             integrationClasses,
         }),
         getIntegrationInstanceForUser,
@@ -203,7 +224,10 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
 
         // Entities
         getEntityModuleForUser,
-        listEntitiesForUser: new entityOps.ListEntitiesForUser({ moduleRepository }),
+        listEntitiesForUser: new entityOps.ListEntitiesForUser({
+            moduleRepository,
+            scopePolicy,
+        }),
         getEntityForUser: new entityOps.GetEntityForUser({ getEntityModuleForUser }),
         deleteEntityForUser: new entityOps.DeleteEntityForUser({
             getEntityModuleForUser,
@@ -215,14 +239,15 @@ function buildV2Dependencies({ appDefinition, config, entityTypeRegistry }) {
         refreshEntityOptionsForUser: new entityOps.RefreshEntityOptionsForUser({
             getEntityModuleForUser,
         }),
-        listEntityTypes: new ListEntityTypes({ entityTypeRegistry: registry }),
-        getEntityType: new GetEntityType({ entityTypeRegistry: registry }),
+        listEntityTypes: new ListEntityTypes({ entityTypeRegistry: registry, scopePolicy }),
+        getEntityType: new GetEntityType({ entityTypeRegistry: registry, scopePolicy }),
         getAuthorizationRequirements,
 
         // Credentials
         listCredentialsForUser: new credentialOps.ListCredentialsForUser({
             credentialRepository,
             moduleRepository,
+            scopePolicy,
         }),
         getCredentialForUser,
         deleteCredentialForUser: new credentialOps.DeleteCredentialForUser({

package/management-api/v2/dto.js

@@ -13,6 +13,20 @@ const idOf = (value) => {
     return String(value);
 };
 
+/**
+ * `{ scope, owner, organizationId, access }` (ADR-056 §3.4): whose a record is
+ * and what the caller may do with it. Empty when the use case did not say.
+ */
+function tenancyFields(tenancy) {
+    if (!tenancy) return {};
+    return {
+        scope: tenancy.scope,
+        owner: tenancy.owner,
+        organizationId: tenancy.organizationId ?? null,
+        access: tenancy.access,
+    };
+}
+
 /** An entity (connected account). */
 function toEntityDto(entity) {
     const credential =
@@ -30,6 +44,7 @@ function toEntityDto(entity) {
             typeof credential?.authIsValid === 'boolean'
                 ? credential.authIsValid
                 : null,
+        ...tenancyFields(entity.tenancy),
     };
 }
 
@@ -42,6 +57,7 @@ function toIntegrationDto(integration) {
         config: integration.config ?? {},
         version: integration.version ?? null,
         messages: integration.messages ?? {},
+        ...tenancyFields(integration.tenancy),
     };
 }
 
@@ -59,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',
 ]);
 
 /**
@@ -110,11 +128,13 @@ function maskCredential(credential) {
         entityCount: entityIds.length,
         createdAt: toIso(credential.createdAt),
         updatedAt: toIso(credential.updatedAt),
+        ...tenancyFields(credential.tenancy),
         data,
     };
 }
 
 module.exports = {
+    tenancyFields,
     toEntityDto,
     toIntegrationDto,
     maskCredential,

package/management-api/v2/handlers/authorization.js

@@ -63,6 +63,7 @@ function createAuthorizationHandlers(useCases) {
                 data: body.data,
                 step,
                 sessionId,
+                scope: optionalString(body.scope, 'scope'),
             });
             res.json(toAuthorizationResponse(result));
         },

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/management-api/v2/handlers/entities.js

@@ -1,5 +1,5 @@
 const { toEntityDto } = require('../dto');
-const { objectBody, parseStep } = require('../request');
+const { objectBody, parseStep, parseListFilters } = require('../request');
 
 /** Management API v2 entity and entity-type handlers, keyed by operationId. */
 function createEntityHandlers(useCases) {
@@ -16,17 +16,20 @@ function createEntityHandlers(useCases) {
     } = useCases;
 
     return {
-        async listEntities(_req, res, user) {
-            const entities = await listEntitiesForUser.execute(user);
+        async listEntities(req, res, user) {
+            const entities = await listEntitiesForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ entities: entities.map(toEntityDto) });
         },
 
-        async listEntityTypes(_req, res) {
-            res.json({ types: await listEntityTypes.execute() });
+        async listEntityTypes(_req, res, user) {
+            res.json({ types: await listEntityTypes.execute({ user }) });
         },
 
-        async getEntityType(req, res) {
-            res.json(await getEntityType.execute(req.params.entityType));
+        async getEntityType(req, res, user) {
+            res.json(await getEntityType.execute(req.params.entityType, { user }));
         },
 
         // Describes a step's requirements without starting an authorization

package/management-api/v2/handlers/integrations.js

@@ -1,5 +1,5 @@
 const { toIntegrationDto } = require('../dto');
-const { objectBody, optionalString } = require('../request');
+const { objectBody, optionalString, parseListFilters } = require('../request');
 
 /**
  * Management API v2 integration handlers, keyed by registry operationId.
@@ -27,8 +27,11 @@ function createIntegrationHandlers(useCases) {
         );
 
     return {
-        async listIntegrations(_req, res, user) {
-            const integrations = await getIntegrationsForUser.execute(user.getId());
+        async listIntegrations(req, res, user) {
+            const integrations = await getIntegrationsForUser.execute(
+                user,
+                parseListFilters(req.query)
+            );
             res.json({ integrations: integrations.map(toIntegrationDto) });
         },
 

package/management-api/v2/request.js

@@ -1,4 +1,5 @@
 const Boom = require('@hapi/boom');
+const { LIST_OWNERS } = require('../../modules/scope-visibility');
 
 /** The JSON body as an object, or a 400 VALIDATION_ERROR. */
 function objectBody(req) {
@@ -51,4 +52,34 @@ function optionalString(value, name) {
     return value;
 }
 
-module.exports = { objectBody, requireFields, parseStep, optionalString };
+const LIST_SCOPES = ['individual', 'organization'];
+
+/**
+ * `?scope=individual|organization` and `?owner=me|org` on a list (ADR-056
+ * §3.4). Anything else is a 400.
+ */
+function parseListFilters(query = {}) {
+    const scope = optionalString(query.scope, 'scope');
+    const owner = optionalString(query.owner, 'owner');
+    if (scope !== undefined && !LIST_SCOPES.includes(scope)) {
+        throw Boom.badRequest(`scope must be one of ${LIST_SCOPES.join(', ')}`, {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'scope' },
+        });
+    }
+    if (owner !== undefined && !Object.hasOwn(LIST_OWNERS, owner)) {
+        throw Boom.badRequest('owner must be me or org', {
+            code: 'VALIDATION_ERROR',
+            details: { field: 'owner' },
+        });
+    }
+    return { scope, owner };
+}
+
+module.exports = {
+    objectBody,
+    requireFields,
+    parseStep,
+    optionalString,
+    parseListFilters,
+};

package/modules/entity-scope.js

@@ -0,0 +1,15 @@
+/**
+ * Entity scopes and ownership (ADR-056 §3), re-exported from the four files it
+ * is split into:
+ *
+ *   scope-resolution  constants, scope resolution, ownership on create
+ *   scope-config      reading and validating app-definition settings
+ *   scope-visibility  who may see which stored row
+ *   scope-policy      the object a use case asks
+ */
+module.exports = {
+    ...require('./scope-resolution'),
+    ...require('./scope-config'),
+    ...require('./scope-visibility'),
+    ...require('./scope-policy'),
+};

package/modules/index.js

@@ -8,6 +8,11 @@ const {
     getEntityTypeRegistry,
     EntityRegistryError,
 } = require('./entity-type-registry');
+const {
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
+} = require('./entity-scope');
 
 module.exports = {
     ApiKeyRequester,
@@ -18,4 +23,7 @@ module.exports = {
     ModuleFactory,
     getEntityTypeRegistry,
     EntityRegistryError,
+    resolveScope,
+    listBindingScopes,
+    OwnershipConfigError,
 };

package/modules/module-factory.js

@@ -45,6 +45,18 @@ class ModuleFactory {
             );
         }
 
+        // definition.env may be an async function (e.g. the db-credentials
+        // extension's bootstrap loads OAuth app credentials from the
+        // database); resolve it first. A static env keeps the plain
+        // constructor, exactly as before.
+        if (typeof moduleDefinition.env === 'function') {
+            return await Module.create({
+                userId,
+                entity,
+                definition: moduleDefinition,
+            });
+        }
+
         return new Module({
             userId,
             entity,

package/modules/module.js

@@ -21,8 +21,17 @@ class Module extends Delegate {
      * @param {string} params.userId The user id
      * @param {Object} params.entity The entity record from the database
      * @param {string} [params.state] Optional OAuth state value forwarded to the API client (round-trips through the OAuth provider).
+     * @param {Object} [params.resolvedEnv] definition.env as Module.create() resolved it (may be undefined).
+     * @param {boolean} [params.envResolved=false] true when resolvedEnv carries the resolved env, even an undefined one; otherwise the static definition.env is used.
      */
-    constructor({ definition, userId = null, entity: entityObj = null, state = null }) {
+    constructor({
+        definition,
+        userId = null,
+        entity: entityObj = null,
+        state = null,
+        resolvedEnv,
+        envResolved = false,
+    }) {
         super({ definition, userId, entity: entityObj });
 
         this.validateDefinition(definition);
@@ -54,8 +63,23 @@ class Module extends Delegate {
 
         Object.assign(this, this.definition.requiredAuthMethods);
 
+        // A pre-resolved env (Module.create()) supports definition.env as an
+        // async function, e.g. OAuth app credentials loaded from the database
+        // by the db-credentials extension; otherwise the static object.
+        // "Resolved" is an explicit flag, not a non-null value: a function env
+        // may legitimately resolve to undefined (no static env, no DB row),
+        // and falling back to definition.env would then read the function.
+        const envValues = envResolved ? resolvedEnv : this.definition.env;
+        if (typeof envValues === 'function') {
+            // Spreading a function yields no keys, so the API client would
+            // silently get no client_id / client_secret.
+            throw new TypeError(
+                `Module ${this.name}: definition.env is a function; build the module with await Module.create(...)`
+            );
+        }
+
         const apiParams = {
-            ...this.definition.env,
+            ...envValues,
             delegate: this,
             logger: this.logger,
             ...(state ? { state } : {}),
@@ -67,6 +91,33 @@ class Module extends Delegate {
         this.api = new this.apiClass(apiParams);
     }
 
+    /**
+     * Resolves definition.env, supporting both a static object and a
+     * (possibly async) function.
+     *
+     * @param {Object} definition - Module definition
+     * @returns {Promise<Object|undefined>} Resolved env values
+     */
+    static async resolveEnv(definition) {
+        if (typeof definition.env === 'function') {
+            return await definition.env();
+        }
+        return definition.env;
+    }
+
+    /**
+     * Async factory that resolves definition.env first, so a module whose
+     * env is a function gets its values. Prefer it over `new Module(...)`
+     * wherever the call site can await.
+     *
+     * @param {Object} params - same as the constructor, minus resolvedEnv
+     * @returns {Promise<Module>}
+     */
+    static async create({ definition, userId = null, entity = null, state = null }) {
+        const resolvedEnv = await Module.resolveEnv(definition);
+        return new Module({ definition, userId, entity, state, resolvedEnv, envResolved: true });
+    }
+
     getName() {
         return this.name;
     }

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