@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/modules/repositories/authorization-session-repository-interface.js

@@ -0,0 +1,47 @@
+/**
+ * Port for persisting AuthorizationSession records (Management API v2
+ * multi-step authorization). Adapters return AuthorizationSession domain
+ * objects and never expired sessions from lookups.
+ */
+class AuthorizationSessionRepositoryInterface {
+    /**
+     * @param {import('../domain/authorization-session').AuthorizationSession} session
+     * @returns {Promise<import('../domain/authorization-session').AuthorizationSession>}
+     */
+    async create(session) {
+        throw new Error('Method create must be implemented by subclass');
+    }
+
+    /**
+     * @param {string} sessionId
+     * @returns {Promise<import('../domain/authorization-session').AuthorizationSession|null>}
+     *   null when missing or expired.
+     */
+    async findBySessionId(sessionId) {
+        throw new Error('Method findBySessionId must be implemented by subclass');
+    }
+
+    /**
+     * Saves currentStep, stepData and completed.
+     * @param {import('../domain/authorization-session').AuthorizationSession} session
+     */
+    async update(session) {
+        throw new Error('Method update must be implemented by subclass');
+    }
+
+    /** @param {string} sessionId */
+    async deleteBySessionId(sessionId) {
+        throw new Error('Method deleteBySessionId must be implemented by subclass');
+    }
+
+    /**
+     * Removes sessions that expired before `now`.
+     * @param {Date} [now]
+     * @returns {Promise<number>} how many were removed
+     */
+    async deleteExpired(now) {
+        throw new Error('Method deleteExpired must be implemented by subclass');
+    }
+}
+
+module.exports = { AuthorizationSessionRepositoryInterface };

package/modules/repositories/authorization-session-repository-prisma.js

@@ -0,0 +1,87 @@
+const { prisma } = require('../../database/prisma');
+const { AuthorizationSession } = require('../domain/authorization-session');
+const {
+    AuthorizationSessionRepositoryInterface,
+} = require('./authorization-session-repository-interface');
+
+/**
+ * AuthorizationSession persistence through the Prisma client, for PostgreSQL
+ * and MongoDB (both schemas declare the same model; the session id, not the
+ * row id, is the key, so no id conversion is needed). `stepData` is
+ * encrypted by the Prisma encryption extension (encryption-schema-registry).
+ */
+class AuthorizationSessionRepositoryPrisma extends AuthorizationSessionRepositoryInterface {
+    constructor(prismaClient = prisma) {
+        super();
+        this.prisma = prismaClient;
+    }
+
+    async create(session) {
+        const record = await this.prisma.authorizationSession.create({
+            data: {
+                sessionId: session.sessionId,
+                userId: session.userId,
+                entityType: session.entityType,
+                credentialId: session.credentialId,
+                currentStep: session.currentStep,
+                maxSteps: session.maxSteps,
+                stepData: session.stepData,
+                expiresAt: session.expiresAt,
+                completed: session.completed,
+            },
+        });
+        return toDomain(record);
+    }
+
+    async findBySessionId(sessionId) {
+        if (typeof sessionId !== 'string' || !sessionId) return null;
+        const record = await this.prisma.authorizationSession.findFirst({
+            where: { sessionId, expiresAt: { gt: new Date() } },
+        });
+        return record ? toDomain(record) : null;
+    }
+
+    async update(session) {
+        const record = await this.prisma.authorizationSession.update({
+            where: { sessionId: session.sessionId },
+            data: {
+                currentStep: session.currentStep,
+                stepData: session.stepData,
+                completed: session.completed,
+            },
+        });
+        return toDomain(record);
+    }
+
+    async deleteBySessionId(sessionId) {
+        const result = await this.prisma.authorizationSession.deleteMany({
+            where: { sessionId },
+        });
+        return result.count;
+    }
+
+    async deleteExpired(now = new Date()) {
+        const result = await this.prisma.authorizationSession.deleteMany({
+            where: { expiresAt: { lte: now } },
+        });
+        return result.count;
+    }
+}
+
+function toDomain(record) {
+    return new AuthorizationSession({
+        sessionId: record.sessionId,
+        userId: record.userId,
+        entityType: record.entityType,
+        credentialId: record.credentialId ?? null,
+        currentStep: record.currentStep,
+        maxSteps: record.maxSteps,
+        stepData: record.stepData || {},
+        expiresAt: record.expiresAt,
+        completed: record.completed,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    });
+}
+
+module.exports = { AuthorizationSessionRepositoryPrisma, toDomain };

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

package/modules/repositories/module-repository-documentdb.js

@@ -3,12 +3,14 @@ const {
     toObjectId,
     fromObjectId,
     findMany,
+    findManyDrained,
     findOne,
     insertOne,
     updateOne,
     deleteOne,
 } = require('../../database/documentdb-utils');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 const { DocumentDBEncryptionService } = require('../../database/documentdb-encryption-service');
 
 /**
@@ -33,11 +35,11 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
     async findEntityById(entityId) {
         const objectId = toObjectId(entityId);
         if (!objectId) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
         const doc = await findOne(this.prisma, 'Entity', { _id: objectId });
         if (!doc) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
         const credential = await this._fetchCredential(doc.credentialId);
         return this._mapEntity(doc, credential);
@@ -76,6 +78,29 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
         return docs.map((doc) => this._mapEntity(doc, credentialMap.get(fromObjectId(doc.credentialId)) || null));
     }
 
+    /**
+     * Find entities matching any of the owner/organization pairs, in one query.
+     * `organizationId: null` matches rows with no organization (a raw MongoDB
+     * `null` also matches a missing field). The caller (a use case) decides
+     * which pairs; this only runs them.
+     *
+     * @param {Array<{userId: string, organizationId: (string|null)}>} clauses
+     * @returns {Promise<Array>}
+     */
+    async findEntitiesByOwnership(clauses) {
+        if (!Array.isArray(clauses) || clauses.length === 0) return [];
+        // Drained: a list can hold more than the first cursor batch (~101).
+        const docs = await findManyDrained(this.prisma, 'Entity', {
+            $or: clauses.map(({ userId, organizationId }) => ({
+                userId: toObjectId(userId),
+                organizationId:
+                    organizationId === null ? null : toObjectId(organizationId),
+            })),
+        });
+        const credentialMap = await this._fetchCredentialsBulk(docs.map((doc) => doc.credentialId));
+        return docs.map((doc) => this._mapEntity(doc, credentialMap.get(fromObjectId(doc.credentialId)) || null));
+    }
+
     async unsetCredential(entityId) {
         const objectId = toObjectId(entityId);
         if (!objectId) return false;
@@ -115,7 +140,14 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
         );
     }
 
-    async createEntity(entityData) {
+    /**
+     * @param {Object} entityData
+     * @param {{organizationId?: (string|null)}} [tenancy] - the organization the entity
+     *   belongs to (ADR-056 §3.6). A separate argument, not a field of `entityData`,
+     *   because `entityData` carries provider fields and one named `organizationId`
+     *   must not be taken for ours.
+     */
+    async createEntity(entityData, tenancy = {}) {
         const {
             user,
             userId,
@@ -133,6 +165,7 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
             name: name ?? null,
             moduleName: moduleName ?? null,
             externalId: externalId ?? null,
+            organizationId: toObjectId(tenancy.organizationId) || null,
             data: dynamicData,
         };
         const insertedId = await insertOne(this.prisma, 'Entity', document);
@@ -247,8 +280,9 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
             const objectIds = ids.map(id => toObjectId(id)).filter(Boolean);
             if (objectIds.length === 0) return new Map();
 
-            // Use raw findMany to bypass Prisma encryption extension
-            const rawCredentials = await findMany(this.prisma, 'Credential', {
+            // Raw read to bypass the Prisma encryption extension. Drained:
+            // more ids than the first cursor batch must all come back.
+            const rawCredentials = await findManyDrained(this.prisma, 'Credential', {
                 _id: { $in: objectIds }
             });
 
@@ -329,19 +363,30 @@ class ModuleRepositoryDocumentDB extends ModuleRepositoryInterface {
         if (filter.name) query.name = filter.name;
         if (filter.moduleName) query.moduleName = filter.moduleName;
         if (filter.externalId) query.externalId = filter.externalId;
+        // `null` means "no organization"; absent means "any". A raw MongoDB
+        // `{ field: null }` matches both a null value and a missing field.
+        if (filter.organizationId !== undefined) {
+            query.organizationId =
+                filter.organizationId === null
+                    ? null
+                    : toObjectId(filter.organizationId);
+        }
         return query;
     }
 
     _mapEntity(doc, credential) {
         const dynamicData = doc?.data || {};
         return {
+            // First, so no stored provider field can replace a column below
+            // (identity, owner or organization decide who sees the entity).
+            ...dynamicData,
             id: fromObjectId(doc?._id),
             credential,
             userId: fromObjectId(doc?.userId),
             name: doc?.name ?? null,
             externalId: doc?.externalId ?? null,
             moduleName: doc?.moduleName ?? null,
-            ...dynamicData,
+            organizationId: fromObjectId(doc?.organizationId) ?? null,
         };
     }
 }

package/modules/repositories/module-repository-interface.js

@@ -67,6 +67,21 @@ class ModuleRepositoryInterface {
         );
     }
 
+    /**
+     * Find entities matching any of the owner/organization pairs, in one query
+     * (ADR-056 §3.6). `organizationId: null` matches rows with no organization.
+     * Which pairs is decided by the caller (modules/entity-scope.js), not here.
+     *
+     * @param {Array<{userId: string|number, organizationId: (string|number|null)}>} clauses
+     * @returns {Promise<Array>} Array of entity objects
+     * @abstract
+     */
+    async findEntitiesByOwnership(clauses) {
+        throw new Error(
+            'Method findEntitiesByOwnership must be implemented by subclass'
+        );
+    }
+
     /**
      * Unset credential from entity
      *
@@ -110,11 +125,13 @@ class ModuleRepositoryInterface {
     /**
      * Create a new entity
      *
-     * @param {Object} entityData - Entity data
+     * @param {Object} entityData - Entity data (provider fields included)
+     * @param {{organizationId?: (string|number|null)}} [tenancy] - the organization
+     *   the entity belongs to (ADR-056 §3.6), kept apart from `entityData`
      * @returns {Promise<Object>} Created entity object
      * @abstract
      */
-    async createEntity(entityData) {
+    async createEntity(entityData, tenancy) {
         throw new Error('Method createEntity must be implemented by subclass');
     }
 

package/modules/repositories/module-repository-mongo.js

@@ -1,5 +1,7 @@
 const { prisma } = require('../../database/prisma');
+const { organizationWhere } = require('../../database/organization-where');
 const { ModuleRepositoryInterface } = require('./module-repository-interface');
+const { entityNotFoundError } = require('./entity-not-found');
 
 /**
  * MongoDB Module Repository Adapter
@@ -76,6 +78,26 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         return credentialMap;
     }
 
+    /**
+     * The one place a stored entity row becomes the entity the application sees.
+     * The provider's `data` is spread FIRST and every column is pinned after it:
+     * a stored `id`, `userId` or `organizationId` in `data` must not decide who
+     * owns the entity or who sees it.
+     * @private
+     */
+    _mapEntity(row, credential) {
+        return {
+            ...(row.data || {}),
+            id: row.id,
+            credential,
+            userId: row.userId,
+            name: row.name,
+            externalId: row.externalId,
+            moduleName: row.moduleName,
+            organizationId: row.organizationId ?? null,
+        };
+    }
+
     /**
      * Find entity by ID with credential
      * Replaces: Entity.findById(entityId).populate('credential')
@@ -90,20 +112,12 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         });
 
         if (!entity) {
-            throw new Error(`Entity ${entityId} not found`);
+            throw entityNotFoundError(entityId);
         }
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id,
-            credential,
-            userId: entity.userId,
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -121,15 +135,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id,
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId,
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -147,15 +153,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id,
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId,
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -177,15 +175,32 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id,
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId,
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
+    }
+
+    /**
+     * Find entities matching any of the owner/organization pairs, in one query.
+     * `organizationId: null` matches rows with no organization. The caller
+     * (a use case) decides which pairs; this only runs them.
+     *
+     * @param {Array<{userId: string, organizationId: (string|null)}>} clauses
+     * @returns {Promise<Array>} Array of entity objects with string IDs
+     */
+    async findEntitiesByOwnership(clauses) {
+        if (!Array.isArray(clauses) || clauses.length === 0) return [];
+        const entities = await this.prisma.entity.findMany({
+            where: {
+                OR: clauses.map(({ userId, organizationId }) => ({
+                    userId,
+                    ...organizationWhere(organizationId),
+                })),
+            },
+        });
+
+        const credentialIds = entities.map(e => e.credentialId).filter(Boolean);
+        const credentialMap = await this._fetchCredentialsBulk(credentialIds);
+
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -223,15 +238,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
 
         const credential = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id,
-            credential,
-            userId: entity.userId,
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credential);
     }
 
     /**
@@ -251,15 +258,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
             .filter(Boolean);
         const credentialMap = await this._fetchCredentialsBulk(credentialIds);
 
-        return entities.map((e) => ({
-            id: e.id,
-            credential: credentialMap.get(e.credentialId) || null,
-            userId: e.userId,
-            name: e.name,
-            externalId: e.externalId,
-            moduleName: e.moduleName,
-            ...(e.data || {}),
-        }));
+        return entities.map((e) => (this._mapEntity(e, credentialMap.get(e.credentialId) || null)));
     }
 
     /**
@@ -267,9 +266,13 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
      * Replaces: Entity.create(entityData)
      *
      * @param {Object} entityData - Entity data
+     * @param {{organizationId?: (string|null)}} [tenancy] - the organization the entity
+     *   belongs to (ADR-056 §3.6). A separate argument, not a field of `entityData`,
+     *   because `entityData` carries provider fields and one named `organizationId`
+     *   must not be taken for ours.
      * @returns {Promise<Object>} Created entity object with string IDs
      */
-    async createEntity(entityData) {
+    async createEntity(entityData, tenancy = {}) {
         const {
             user,
             userId,
@@ -287,6 +290,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
             name,
             moduleName,
             externalId,
+            organizationId: tenancy.organizationId ?? null,
             data: dynamicData,
         };
 
@@ -296,15 +300,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
 
         const credentialObj = await this._fetchCredential(entity.credentialId);
 
-        return {
-            id: entity.id,
-            credential: credentialObj,
-            userId: entity.userId,
-            name: entity.name,
-            externalId: entity.externalId,
-            moduleName: entity.moduleName,
-            ...(entity.data || {}),
-        };
+        return this._mapEntity(entity, credentialObj);
     }
 
     /**
@@ -358,15 +354,7 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
 
             const credentialObj = await this._fetchCredential(entity.credentialId);
 
-            return {
-                id: entity.id,
-                credential: credentialObj,
-                userId: entity.userId,
-                name: entity.name,
-                externalId: entity.externalId,
-                moduleName: entity.moduleName,
-                ...(entity.data || {}),
-            };
+            return this._mapEntity(entity, credentialObj);
         } catch (error) {
             if (error.code === 'P2025') {
                 return null;
@@ -429,6 +417,11 @@ class ModuleRepositoryMongo extends ModuleRepositoryInterface {
         if (filter.moduleName) where.moduleName = filter.moduleName;
         if (filter.externalId) where.externalId = this._toString(filter.externalId);
 
+        // `null` means "no organization"; absent means "any".
+        if (filter.organizationId !== undefined) {
+            Object.assign(where, organizationWhere(filter.organizationId));
+        }
+
         return where;
     }
 }