@friggframework/core 2.0.0--canary.679.a2bcc2f.0 → 2.0.0--canary.686.219e1e7.0

package/management-api/openapi/components.js

@@ -8,6 +8,27 @@ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
 
 const nullable = (schema) => ({ ...schema, nullable: true });
 
+// Whose a record is and what the caller may do with it (ADR-056 §3.4). Added to
+// entities, credentials and integrations by the list and get use cases.
+const tenancyProperties = {
+    scope: { type: 'string', enum: ['individual', 'organization'], description: 'Whose it is. `global` records are not shown to tenants.' },
+    owner: {
+        type: 'object',
+        properties: { type: { type: 'string', enum: ['individual', 'organization'] }, id: { type: 'string' } },
+        description: "The user that owns it: the person, or the organization's user",
+    },
+    organizationId: nullable({
+        type: 'string',
+        description:
+            'The organization it belongs to. Null for an individual entity connected outside an organization, or under ownership.individualAcross "all".',
+    }),
+    access: {
+        type: 'string',
+        enum: ['manage', 'use', 'view'],
+        description: 'manage (create, reauthorize, delete), use (bind it, proxy through it) or view (metadata only)',
+    },
+};
+
 const errorBody = {
     type: 'object',
     required: ['error'],
@@ -69,6 +90,7 @@ const SCHEMAS = {
             config: { type: 'object', additionalProperties: true },
             version: nullable({ type: 'string' }),
             messages: { type: 'object', additionalProperties: true },
+            ...tenancyProperties,
         },
     },
     ListIntegrationsResponse: {
@@ -129,6 +151,7 @@ const SCHEMAS = {
             credentialId: nullable({ type: 'string' }),
             userId: nullable({ type: 'string' }),
             authIsValid: nullable({ type: 'boolean' }),
+            ...tenancyProperties,
         },
     },
     ListEntitiesResponse: {
@@ -153,6 +176,16 @@ const SCHEMAS = {
             isMultiStep: { type: 'boolean' },
             stepCount: { type: 'integer', minimum: 1 },
             capabilities: {},
+            scope: {
+                type: 'object',
+                description:
+                    'The scope a new connection of this type gets and the scopes a request may choose (ADR-056 §3.1). `global` is never offered.',
+                properties: {
+                    default: { type: 'string', enum: ['individual', 'organization', 'global'] },
+                    allow: { type: 'array', items: { type: 'string', enum: ['individual', 'organization'] } },
+                    source: { type: 'string', enum: ['binding', 'integration', 'entityType', 'app', 'default'] },
+                },
+            },
         },
     },
     ListEntityTypesResponse: {
@@ -173,6 +206,7 @@ const SCHEMAS = {
             authIsValid: nullable({ type: 'boolean' }),
             entityIds: { type: 'array', items: { type: 'string' } },
             entityCount: { type: 'integer', minimum: 0 },
+            ...tenancyProperties,
             createdAt: nullable({ type: 'string', format: 'date-time' }),
             updatedAt: nullable({ type: 'string', format: 'date-time' }),
             data: {
@@ -197,6 +231,12 @@ const SCHEMAS = {
             data: { type: 'object', additionalProperties: true, description: 'OAuth callback params or step form data' },
             step: { type: 'integer', minimum: 1, default: 1 },
             sessionId: { type: 'string', description: 'Required for step 2 and later' },
+            scope: {
+                type: 'string',
+                enum: ['individual', 'organization'],
+                description:
+                    "The scope to connect at, from the entity type's allow list (ADR-056 §3.1). Omit to take the type's default. `global` is refused (403).",
+            },
         },
     },
     ReauthorizeRequest: {

package/management-api/openapi/v2-operations.js

@@ -34,6 +34,11 @@ const stepQuery = [
     query('step', 'Step number, 1-based (default 1)', { type: 'integer', minimum: 1 }),
     query('sessionId', 'Session from step 1; required for later steps'),
 ];
+// ADR-056 §3.4: the same two filters on every list that mixes ownership.
+const listFilters = [
+    query('scope', 'Only records of this scope', { type: 'string', enum: ['individual', 'organization'] }),
+    query('owner', 'Only the caller\'s own (`me`) or the active organization\'s (`org`)', { type: 'string', enum: ['me', 'org'] }),
+];
 const anyJson = { description: 'Defined by the integration or module' };
 
 const V2_OPERATIONS = {
@@ -41,7 +46,8 @@ const V2_OPERATIONS = {
     listIntegrations: {
         summary: "List the caller's integrations",
         description:
-            'Returns only `{ integrations }`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+            'Returns only `{ integrations }`: the caller\'s and the active organization\'s, created in that organization (ADR-056 §3.6). Each carries `scope`, `owner`, `organizationId` and `access`. Integration types are at /api/v2/integrations/options and connected accounts at /api/v2/entities.',
+        parameters: listFilters,
         responses: { 200: ok('Integrations', ref('ListIntegrationsResponse')), ...errors('Unauthorized') },
     },
     listIntegrationOptions: {
@@ -108,6 +114,9 @@ const V2_OPERATIONS = {
     // Entities
     listEntities: {
         summary: "List the caller's connected entities",
+        description:
+            "The active organization's entities and the caller's individual ones (ADR-056 §3.6): an individual entity belongs to the organization it was connected in, unless `ownership.individualAcross` is `all`. Each carries `scope`, `owner`, `organizationId` and `access`.",
+        parameters: listFilters,
         responses: { 200: ok('Entities', ref('ListEntitiesResponse')), ...errors('Unauthorized') },
     },
     listEntityTypes: {
@@ -156,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')),
@@ -175,6 +184,9 @@ const V2_OPERATIONS = {
     // Credentials
     listCredentials: {
         summary: "List the caller's credentials (masked)",
+        description:
+            'A credential is listed through the entities that use it that the caller may see, so each organization lists only its own connections; one no entity uses is listed to its owner. Each carries `scope`, `owner`, `organizationId` and `access`, taken from who owns the credential.',
+        parameters: listFilters,
         responses: { 200: ok('Credentials', ref('ListCredentialsResponse')), ...errors('Unauthorized') },
     },
     getCredential: {

package/management-api/v2/dependencies.js

@@ -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,9 @@ 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 already resolved by Module.create(); defaults to the static definition.env.
      */
-    constructor({ definition, userId = null, entity: entityObj = null, state = null }) {
+    constructor({ definition, userId = null, entity: entityObj = null, state = null, resolvedEnv = null }) {
         super({ definition, userId, entity: entityObj });
 
         this.validateDefinition(definition);
@@ -54,8 +55,22 @@ 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.
+        // No resolved env (the null default; an explicit undefined takes it
+        // too) means the static definition.env applies.
+        const envValues = 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 +82,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 });
+    }
+
     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 };