@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.690.3fe2b27.0

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

@@ -0,0 +1,331 @@
+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

@@ -0,0 +1,100 @@
+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-entities-for-user.js

@@ -1,8 +1,11 @@
 const { Module } = require('../module');
 const { mapModuleClassToModuleDTO } = require('../utils/map-module-dto');
+const { describeRecord, visibilityClauses } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntitiesForUser {
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
         this.moduleRepository = moduleRepository;
 
         this.definitionMap = new Map();
@@ -11,21 +14,31 @@ class GetEntitiesForUser {
         }
     }
 
-    async execute(userId) {
-        const entities = await this.moduleRepository.findEntitiesByUserId(
-            userId
+    /**
+     * The entities a `User` may see in the active organization (ADR-056 §3.6).
+     * @param {Object} user - authenticated User
+     */
+    async execute(user) {
+        const ctx = this.scopePolicy.accessContext(user);
+        const found = await this.moduleRepository.findEntitiesByOwnership(
+            visibilityClauses(ctx, 'entity')
+        );
+        const entities = (found || []).filter((entity) =>
+            describeRecord(entity, ctx, 'entity')
         );
 
-        return entities.map((entity) => {
-            const definition = this.definitionMap.get(entity.moduleName);
+        return Promise.all(
+            entities.map(async (entity) => {
+                const definition = this.definitionMap.get(entity.moduleName);
 
-            const moduleInstance = new Module({
-                userId,
-                definition: definition,
-                entity: entity,
-            });
-            return mapModuleClassToModuleDTO(moduleInstance);
-        });
+                const moduleInstance = await Module.create({
+                    userId: entity.userId,
+                    definition: definition,
+                    entity: entity,
+                });
+                return mapModuleClassToModuleDTO(moduleInstance);
+            })
+        );
     }
 }
 

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

@@ -0,0 +1,113 @@
+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 };

package/modules/use-cases/get-entity-options-by-id.js

@@ -1,4 +1,5 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetEntityOptionsById {
     /**
@@ -6,9 +7,11 @@ class GetEntityOptionsById {
      * @param {import('../repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository
      * @param {} params.moduleDefinitions
      */
-    constructor({ moduleRepository, moduleDefinitions }) {
+    constructor({ moduleRepository, moduleDefinitions, scopePolicy }) {
         this.moduleRepository = moduleRepository;
         this.moduleDefinitions = moduleDefinitions;
+        // Who may load an entity follows its scope (ADR-056 §3.6).
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
     }
 
     /**
@@ -35,7 +38,7 @@ class GetEntityOptionsById {
 
         // Validate entity ownership
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
@@ -57,8 +60,11 @@ class GetEntityOptionsById {
             );
         }
 
-        const module = new Module({
-            userId,
+        // Built for the entity's OWNER, not the caller: a caller may use an
+        // organization's entity, and a token refresh during this call must
+        // update the owner's credential, not create one under the caller.
+        const module = await Module.create({
+            userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-entity-options-by-type.js

@@ -21,7 +21,7 @@ class GetEntityOptionsByType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        const moduleInstance = new Module({
+        const moduleInstance = await Module.create({
             userId,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-module-instance-from-type.js

@@ -23,7 +23,7 @@ class GetModuleInstanceFromType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        return new Module({
+        return Module.create({
             userId,
             definition: moduleDefinition,
             state: options.state,