@friggframework/core 2.0.0--canary.663.8de669c.0 → 2.0.0--canary.686.821f8a3.0

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,

package/modules/use-cases/get-module.js

@@ -1,9 +1,12 @@
 const { Module } = require('../module');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
 
 class GetModule {
-    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;
     }
 
     /**
@@ -32,7 +35,7 @@ class GetModule {
         // If User object provided, use ownsUserId to check linked users
         // Otherwise fall back to simple equality check
         const isOwned = typeof userIdOrUser === 'object' && userIdOrUser?.ownsUserId
-            ? userIdOrUser.ownsUserId(entity.userId)
+            ? this.scopePolicy.canUseEntity(userIdOrUser, entity)
             : entity.userId?.toString() === userId?.toString();
 
         if (!isOwned) {
@@ -53,8 +56,11 @@ class GetModule {
             );
         }
 
-        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/manage-access.js

@@ -0,0 +1,21 @@
+const Boom = require('@hapi/boom');
+const { ACCESS } = require('../scope-resolution');
+
+/**
+ * The one check behind every "may this caller change or delete it" gate
+ * (ADR-056 §3 permissions): the caller may use it but not manage it, so 403
+ * `ORG_ADMIN_REQUIRED`. `access` comes from describeRecord (entities,
+ * integrations) or scopePolicy.accessToOwnedBy (credentials).
+ *
+ * @param {string|null} access - ACCESS value
+ * @param {string} subject - e.g. `entity 5`, for the message
+ */
+function assertCanManage(access, subject) {
+    if (access !== ACCESS.MANAGE) {
+        throw Boom.forbidden(`You may use ${subject} but not change or delete it`, {
+            code: 'ORG_ADMIN_REQUIRED',
+        });
+    }
+}
+
+module.exports = { assertCanManage };

package/modules/use-cases/multi-step-authorization.js

@@ -0,0 +1,329 @@
+const Boom = require('@hapi/boom');
+const { FetchError } = require('../../errors/fetch-error');
+const { getLogger } = require('../../logs');
+const { AuthorizationSession } = require('../domain/authorization-session');
+const { findDefinition, getAuthStepCount } = require('./entity-types');
+const { describeRecord } = require('../scope-visibility');
+const { DEFAULT_SCOPE_POLICY } = require('../scope-policy');
+
+const log = getLogger('frigg.api.authorize');
+
+const defaultCreateModule = (params) => {
+    const { Module } = require('../module');
+    return Module.create(params);
+};
+
+const isMultiStep = (definition) =>
+    getAuthStepCount(definition) > 1 ||
+    typeof definition.processAuthorizationStep === 'function';
+
+const sessionNotFound = () =>
+    Boom.notFound('Authorization session not found or expired', {
+        code: 'AUTHORIZATION_SESSION_NOT_FOUND',
+    });
+
+/**
+ * Maps a failure from the module or the provider to a client-facing error.
+ * Boom errors pass through. A provider HTTP failure is a 502; a failed auth
+ * test or a ClientSafeError is a 400. Anything else stays a 500.
+ */
+function toAuthorizationError(error, { passMessage = false } = {}) {
+    if (error?.isBoom) return error;
+    if (error instanceof FetchError) {
+        return Boom.badGateway('The provider rejected the authorization request', {
+            code: 'UPSTREAM_ERROR',
+            expose: true,
+            details: { upstreamStatus: error.statusCode ?? null },
+        });
+    }
+    if (error?.isClientSafe || passMessage) {
+        return Boom.badRequest(error?.message || 'Authorization failed', {
+            code: 'AUTHORIZATION_FAILED',
+        });
+    }
+    if (error?.message === 'Authorization failed') {
+        return Boom.badRequest(
+            'Authorization failed: the credentials did not pass the module auth test',
+            { code: 'AUTHORIZATION_FAILED' }
+        );
+    }
+    return error;
+}
+
+/**
+ * Loads the session a caller continues, checking it belongs to them, to the
+ * entity type and (for re-authorization) to the credential.
+ */
+async function loadSession(repository, sessionId, binding) {
+    if (typeof sessionId !== 'string' || !sessionId) throw sessionNotFound();
+    const session = await repository.findBySessionId(sessionId);
+    if (!session || session.isExpired() || !session.belongsTo(binding)) {
+        throw sessionNotFound();
+    }
+    if (session.completed) {
+        throw Boom.conflict('Authorization session is already complete', {
+            code: 'AUTHORIZATION_SESSION_COMPLETED',
+        });
+    }
+    return session;
+}
+
+async function startSession(repository, binding, maxSteps) {
+    // Expired sessions are removed opportunistically; PostgreSQL has no TTL.
+    Promise.resolve()
+        .then(() => repository.deleteExpired())
+        .catch((error) =>
+        log.warn('Expired authorization sessions were not removed', {
+            eventName: `${log.name}.session_cleanup_failed`,
+            error,
+        })
+    );
+    return repository.create(AuthorizationSession.start({ ...binding, maxSteps }));
+}
+
+/**
+ * GET /api/v2/authorize (and GET /api/v2/credentials/:id/reauthorize): what
+ * the caller must submit next. A multi-step flow gets a session on step 1;
+ * later steps need that sessionId and must be the session's current step.
+ */
+class GetAuthorizationStep {
+    /**
+     * @param {Object} params
+     * @param {Array<Object>} params.moduleDefinitions
+     * @param {import('./get-authorization-requirements').GetAuthorizationRequirements} params.getAuthorizationRequirements
+     * @param {import('../repositories/authorization-session-repository-interface').AuthorizationSessionRepositoryInterface} params.authorizationSessionRepository
+     */
+    constructor({ moduleDefinitions, getAuthorizationRequirements, authorizationSessionRepository }) {
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.getAuthorizationRequirements = getAuthorizationRequirements;
+        this.sessions = authorizationSessionRepository;
+    }
+
+    async execute({ user, entityType, step = 1, sessionId, credentialId = null, state }) {
+        const definition = findDefinition(this.moduleDefinitions, entityType);
+        const userId = user.getId();
+        const requirementsFor = (n) =>
+            this.getAuthorizationRequirements.execute({ entityType, step: n, userId, state });
+
+        if (!isMultiStep(definition)) return requirementsFor(step);
+
+        const binding = { userId, entityType, credentialId };
+        let session;
+        if (sessionId) {
+            session = await loadSession(this.sessions, sessionId, binding);
+            if (step !== session.currentStep) {
+                throw Boom.conflict(
+                    `This session expects step ${session.currentStep}`,
+                    { code: 'STEP_OUT_OF_ORDER', details: { expectedStep: session.currentStep } }
+                );
+            }
+        } else {
+            if (step !== 1) {
+                throw Boom.badRequest('sessionId is required after step 1', {
+                    code: 'SESSION_REQUIRED',
+                });
+            }
+            session = await startSession(this.sessions, binding, getAuthStepCount(definition));
+        }
+        return { ...(await requirementsFor(step)), sessionId: session.sessionId };
+    }
+}
+
+/**
+ * POST /api/v2/authorize (and POST /api/v2/credentials/:id/reauthorize).
+ *
+ * Single-step modules complete at once through ProcessAuthorizationCallback
+ * (the v1 authorize logic). Multi-step modules run
+ * definition.processAuthorizationStep(api, step, data, stepData) per step;
+ * when it reports `completed`, its `authData` goes through the same
+ * callback. Returns either
+ * `{ status: 'complete', entity, credential }` (domain records; the handler
+ * masks them) or
+ * `{ status: 'pending', step, totalSteps, sessionId, requirements, message? }`.
+ */
+class SubmitAuthorizationStep {
+    constructor({
+        moduleDefinitions,
+        getAuthorizationRequirements,
+        authorizationSessionRepository,
+        authorizeEntityForUser,
+        moduleRepository,
+        credentialRepository,
+        createModule,
+        scopePolicy,
+    }) {
+        this.scopePolicy = scopePolicy || DEFAULT_SCOPE_POLICY;
+        this.moduleDefinitions = moduleDefinitions || [];
+        this.getAuthorizationRequirements = getAuthorizationRequirements;
+        this.sessions = authorizationSessionRepository;
+        this.authorizeEntityForUser = authorizeEntityForUser;
+        this.moduleRepository = moduleRepository;
+        this.credentialRepository = credentialRepository;
+        this.createModule = createModule || defaultCreateModule;
+    }
+
+    /**
+     * @param {Object} params
+     * @param {string} [params.scope] - the scope the caller asks for, from the
+     *   deciding level's allow list (ADR-056 §3.1). Never `global`.
+     * @param {string} [params.fixedScope] - re-authorization keeps the scope the
+     *   credential already has, whatever the config says now.
+     */
+    async execute({ user, entityType, data, step = 1, sessionId, credentialId = null, scope, fixedScope }) {
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            throw Boom.badRequest('data must be an object', {
+                code: 'VALIDATION_ERROR',
+                details: { field: 'data' },
+            });
+        }
+        const definition = findDefinition(this.moduleDefinitions, entityType);
+        // `userId` binds a session to the caller and is what GET /authorize
+        // computes too. The owner of the entity this creates is decided by
+        // scope (§3.2), not by user.primary, and is `ownership.ownerId`.
+        const userId = user.getId();
+        const ownership = this.authorizeEntityForUser.resolveOwnership({
+            user,
+            entityType,
+            scope,
+            fixedScope,
+        });
+
+        if (!isMultiStep(definition)) {
+            if (step !== 1) {
+                throw Boom.badRequest(`${entityType} has a single authorization step`, {
+                    code: 'INVALID_STEP',
+                });
+            }
+            return this.complete({ ownership, user, entityType, params: data, credentialId });
+        }
+
+        const totalSteps = getAuthStepCount(definition);
+        const binding = { userId, entityType, credentialId };
+        let session;
+        if (sessionId) {
+            session = await loadSession(this.sessions, sessionId, binding);
+            if (step === 1 && session.currentStep !== 1) {
+                session.restart();
+            } else if (step !== session.currentStep) {
+                throw Boom.conflict(`This session expects step ${session.currentStep}`, {
+                    code: 'STEP_OUT_OF_ORDER',
+                    details: { expectedStep: session.currentStep },
+                });
+            }
+        } else {
+            if (step !== 1) {
+                throw Boom.badRequest('sessionId is required after step 1', {
+                    code: 'SESSION_REQUIRED',
+                });
+            }
+            session = await startSession(this.sessions, binding, totalSteps);
+        }
+
+        if (typeof definition.processAuthorizationStep !== 'function') {
+            throw Boom.badImplementation(
+                `Module ${entityType} declares ${totalSteps} steps but no processAuthorizationStep`
+            );
+        }
+
+        const module = await this.createModule({ userId: ownership.ownerId, definition });
+        let result;
+        try {
+            result = await definition.processAuthorizationStep(
+                module.api,
+                step,
+                data,
+                session.stepData
+            );
+        } catch (error) {
+            // processAuthorizationStep errors are written for the end user
+            // (docs/MULTI_STEP_AUTH_MIGRATION_GUIDE.md), e.g. "Invalid code".
+            throw toAuthorizationError(error, { passMessage: true });
+        }
+
+        if (result?.completed) {
+            session.markComplete();
+            await this.sessions.update(session);
+            const outcome = await this.complete({
+                ownership,
+                user,
+                entityType,
+                params: result.authData || {},
+                credentialId,
+            });
+            // The collected data is no longer needed once the credential exists.
+            await Promise.resolve()
+                .then(() => this.sessions.deleteBySessionId(session.sessionId))
+                .catch(() => {});
+            return outcome;
+        }
+
+        const nextStep = result?.nextStep ?? step + 1;
+        try {
+            session.advanceTo(nextStep, result?.stepData);
+        } catch (error) {
+            throw Boom.badImplementation(
+                `Module ${entityType} returned an invalid next step: ${error.message}`
+            );
+        }
+        await this.sessions.update(session);
+
+        const requirements = await this.getAuthorizationRequirements.execute({
+            entityType,
+            step: nextStep,
+            userId,
+        });
+        return {
+            status: 'pending',
+            step: nextStep,
+            totalSteps,
+            sessionId: session.sessionId,
+            requirements,
+            ...(result?.message && { message: String(result.message) }),
+        };
+    }
+
+    async complete({ ownership, user, entityType, params, credentialId }) {
+        let callback;
+        try {
+            ({ result: callback } = await this.authorizeEntityForUser.execute({
+                user,
+                entityType,
+                data: params,
+                ownership,
+            }));
+        } catch (error) {
+            throw toAuthorizationError(error);
+        }
+        const [entity, credential] = await Promise.all([
+            this.moduleRepository.findEntityById(callback.entity_id),
+            this.credentialRepository.findCredentialById(callback.credential_id),
+        ]);
+        // What the new entity is to this caller (§3.4), so a client need not list again.
+        const tenancy = entity
+            ? describeRecord(entity, this.scopePolicy.accessContext(user), 'entity')
+            : null;
+        const outcome = {
+            status: 'complete',
+            entity: entity && tenancy ? { ...entity, tenancy } : entity,
+            credential: credential && {
+                ...credential,
+                type: entityType,
+                entityIds: entity ? [String(entity.id)] : [],
+                ...(tenancy && { tenancy }),
+            },
+        };
+        if (credentialId && String(callback.credential_id) !== String(credentialId)) {
+            // The provider account differs from the one being re-authorized,
+            // so a separate credential was stored.
+            outcome.previousCredentialId = String(credentialId);
+        }
+        return outcome;
+    }
+}
+
+module.exports = {
+    GetAuthorizationStep,
+    SubmitAuthorizationStep,
+    toAuthorizationError,
+    isMultiStep,
+};

package/modules/use-cases/process-authorization-callback.js

@@ -1,5 +1,16 @@
 const { Module } = require('../module');
 const { ModuleConstants } = require('../ModuleConstants');
+const { pickExistingEntity } = require('../scope-resolution');
+
+/**
+ * What an entity belongs to when the caller says nothing: the person's own,
+ * outside any organization.
+ */
+const DEFAULT_TENANCY = Object.freeze({
+    scope: 'individual',
+    organizationId: null,
+    legacyOrgId: null,
+});
 const { getLogger } = require('../../logs');
 
 const log = getLogger('frigg.modules.authorization_callback');
@@ -30,7 +41,17 @@ class ProcessAuthorizationCallback {
         this.integrationRepository = integrationRepository;
     }
 
-    async execute(userId, entityType, params) {
+    /**
+     * @param {string} userId - the OWNER of what this creates (ADR-056 §3.2): the
+     *   person for `individual`, the organization's user for `organization`.
+     *   Not necessarily the caller; callers resolve it from the scope.
+     * @param {string} entityType
+     * @param {Object} params - what the module's authorization needs
+     * @param {{scope: string, organizationId: (string|null), legacyOrgId: (string|null)}} [tenancy]
+     *   the entity's scope and organization (§3.6); default: the person's own,
+     *   with no organization
+     */
+    async execute(userId, entityType, params, tenancy = DEFAULT_TENANCY) {
         log.debug('Authorization callback started', {
             eventName: `${log.name}.started`,
             userId,
@@ -57,10 +78,7 @@ class ProcessAuthorizationCallback {
                 userId,
                 entityType
             );
-        const existingEntity =
-            existingEntities && existingEntities.length > 0
-                ? existingEntities[0]
-                : null;
+        const existingEntity = pickExistingEntity(existingEntities, tenancy);
 
         if (existingEntity) {
             log.debug('Existing entity found', {
@@ -70,7 +88,7 @@ class ProcessAuthorizationCallback {
             });
         }
 
-        const module = new Module({
+        const module = await Module.create({
             userId,
             entity: existingEntity,
             definition: moduleDefinition,
@@ -156,7 +174,8 @@ class ProcessAuthorizationCallback {
         const persistedEntity = await this.findOrCreateEntity(
             entityDetails,
             entityType,
-            module.credential.id
+            module.credential.id,
+            tenancy
         );
         log.debug('Authorization callback completed', {
             eventName: `${log.name}.completed`,
@@ -233,7 +252,12 @@ class ProcessAuthorizationCallback {
         module.credential = persisted;
     }
 
-    async findOrCreateEntity(entityDetails, moduleName, credentialId) {
+    async findOrCreateEntity(
+        entityDetails,
+        moduleName,
+        credentialId,
+        tenancy = DEFAULT_TENANCY
+    ) {
         const { identifiers, details } = entityDetails;
 
         // Support both 'user' and 'userId' field names from module definitions
@@ -247,11 +271,16 @@ class ProcessAuthorizationCallback {
             );
         }
 
-        const existingEntity = await this.moduleRepository.findEntity({
-            externalId: identifiers.externalId,
-            user: userId,
-            moduleName: moduleName,
-        });
+        // The same provider account in two organizations is two entities
+        // (ADR-056 §3.6), so the match is per organization.
+        const existingEntity = pickExistingEntity(
+            await this.moduleRepository.findEntities({
+                externalId: identifiers.externalId,
+                user: userId,
+                moduleName: moduleName,
+            }),
+            tenancy
+        );
 
         if (existingEntity) {
             // Repoint the entity's credentialId when re-auth produced a
@@ -282,12 +311,17 @@ class ProcessAuthorizationCallback {
             return existingEntity;
         }
 
-        return await this.moduleRepository.createEntity({
-            ...identifiers,
-            ...details,
-            moduleName: moduleName,
-            credential: credentialId,
-        });
+        // `organizationId` is not part of the entity data: that carries provider
+        // fields, and one that happens to be called organizationId is theirs.
+        return await this.moduleRepository.createEntity(
+            {
+                ...identifiers,
+                ...details,
+                moduleName: moduleName,
+                credential: credentialId,
+            },
+            { organizationId: tenancy.organizationId ?? null }
+        );
     }
 }