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

package/user/membership.js

@@ -0,0 +1,51 @@
+/**
+ * Organization membership rules that are not persistence (ADR-056 §3.6). Pure.
+ *
+ * `IndividualUser.organizationId` is the legacy single-org pointer. It is not
+ * copied into membership rows; it is read as an implicit membership here, in
+ * the domain, so the repositories stay atomic (a row or nothing). See
+ * docs/guides/organization-memberships.md for why this is a read-time
+ * fallback rather than a data migration.
+ */
+
+/** The role a membership has when nothing says otherwise. */
+const DEFAULT_ORG_ROLE = 'MEMBER';
+
+const isPresent = (value) =>
+    value !== undefined && value !== null && value !== '';
+
+const idString = (value) => (isPresent(value) ? String(value) : null);
+
+/** Ids compare as strings: stores return numbers or strings. */
+const sameId = (a, b) => isPresent(a) && isPresent(b) && String(a) === String(b);
+
+/**
+ * The membership the legacy `organizationId` pointer stands for in
+ * `organizationUserId`, or null when the person has no pointer or it names a
+ * different organization.
+ *
+ * @param {Object|null} individual The individual user as the repository returns it.
+ * @param {string|number} organizationUserId
+ * @returns {{id: null, individualUserId: string|null, organizationUserId: string, orgRole: string, createdAt: *, implicit: true}|null}
+ */
+function implicitMembership(individual, organizationUserId) {
+    if (!individual || !sameId(individual.organizationId, organizationUserId)) {
+        return null;
+    }
+    return {
+        id: null,
+        individualUserId: idString(individual.id),
+        organizationUserId: idString(individual.organizationId),
+        orgRole: DEFAULT_ORG_ROLE,
+        createdAt: individual.createdAt,
+        implicit: true,
+    };
+}
+
+module.exports = {
+    DEFAULT_ORG_ROLE,
+    isPresent,
+    idString,
+    sameId,
+    implicitMembership,
+};

package/user/repositories/organization-membership-record.js

@@ -0,0 +1,19 @@
+const { idString } = require('../membership');
+
+/**
+ * A stored membership row as the application sees it: every id a string
+ * whatever the database holds. `implicit` is always false here: only the
+ * domain (`user/membership.js`) produces an implicit membership.
+ */
+function toMembership(row) {
+    return {
+        id: idString(row.id ?? row._id),
+        individualUserId: idString(row.individualUserId),
+        organizationUserId: idString(row.organizationUserId),
+        orgRole: row.orgRole,
+        createdAt: row.createdAt,
+        implicit: false,
+    };
+}
+
+module.exports = { toMembership };

package/user/repositories/organization-membership-repository-documentdb.js

@@ -0,0 +1,106 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findOne,
+    findManyDrained,
+    updateOne,
+} = require('../../database/documentdb-utils');
+const { DUPLICATE_KEY_CODE } = require('../../database/unique-violation');
+const {
+    OrganizationMembershipRepositoryInterface,
+} = require('./organization-membership-repository-interface');
+const { toMembership } = require('./organization-membership-record');
+const { DEFAULT_ORG_ROLE } = require('../membership');
+
+const COLLECTION = 'OrganizationMembership';
+
+const parseDate = (value) => {
+    if (!value) return undefined;
+    const date = new Date(value.$date ?? value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
+/**
+ * Organization membership persistence for DocumentDB through raw commands.
+ * Nothing in a membership is encrypted.
+ */
+class OrganizationMembershipRepositoryDocumentDB extends OrganizationMembershipRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async findMembership(individualUserId, organizationUserId) {
+        const doc = await this._findDoc(individualUserId, organizationUserId);
+        return doc ? this._toMembership(doc) : null;
+    }
+
+    async addMembership(individualUserId, organizationUserId, options = {}) {
+        // $setOnInsert: an existing membership is left exactly as it is.
+        const result = await updateOne(
+            this.prisma,
+            COLLECTION,
+            this._pair(individualUserId, organizationUserId),
+            {
+                $setOnInsert: {
+                    orgRole: options.orgRole ?? DEFAULT_ORG_ROLE,
+                    createdAt: new Date(),
+                },
+            },
+            { upsert: true }
+        );
+        // The loser of a first-login race can hit the unique pair; the row
+        // exists then, so only other write errors are failures.
+        const writeError = result?.writeErrors?.[0];
+        if (writeError && writeError.code !== DUPLICATE_KEY_CODE) {
+            throw new Error(
+                `Adding organization membership failed: ${writeError.errmsg} (code: ${writeError.code})`
+            );
+        }
+        const doc = await this._findDoc(individualUserId, organizationUserId);
+        if (!doc) {
+            throw new Error('Organization membership was not stored');
+        }
+        return this._toMembership(doc);
+    }
+
+    async listMembershipsForOrganization(organizationUserId) {
+        // Drained: findMany returns only the first cursor batch (~101 documents),
+        // which would silently drop members of a large organization.
+        const docs = await findManyDrained(
+            this.prisma,
+            COLLECTION,
+            { organizationUserId: toObjectId(organizationUserId) },
+            { sort: { createdAt: 1 } }
+        );
+        return docs.map((doc) => this._toMembership(doc));
+    }
+
+    _pair(individualUserId, organizationUserId) {
+        return {
+            individualUserId: toObjectId(individualUserId),
+            organizationUserId: toObjectId(organizationUserId),
+        };
+    }
+
+    async _findDoc(individualUserId, organizationUserId) {
+        return findOne(
+            this.prisma,
+            COLLECTION,
+            this._pair(individualUserId, organizationUserId)
+        );
+    }
+
+    _toMembership(doc) {
+        return toMembership({
+            id: fromObjectId(doc._id),
+            individualUserId: fromObjectId(doc.individualUserId),
+            organizationUserId: fromObjectId(doc.organizationUserId),
+            orgRole: doc.orgRole ?? DEFAULT_ORG_ROLE,
+            createdAt: parseDate(doc.createdAt),
+        });
+    }
+}
+
+module.exports = { OrganizationMembershipRepositoryDocumentDB };

package/user/repositories/organization-membership-repository-factory.js

@@ -0,0 +1,42 @@
+const databaseConfig = require('../../database/config');
+const {
+    OrganizationMembershipRepositoryMongo,
+} = require('./organization-membership-repository-mongo');
+const {
+    OrganizationMembershipRepositoryPrisma,
+} = require('./organization-membership-repository-prisma');
+const {
+    OrganizationMembershipRepositoryPostgres,
+} = require('./organization-membership-repository-postgres');
+const {
+    OrganizationMembershipRepositoryDocumentDB,
+} = require('./organization-membership-repository-documentdb');
+
+/**
+ * Membership repository for the configured database. Every method returns
+ * String ids whatever the database stores.
+ *
+ * @returns {import('./organization-membership-repository-interface').OrganizationMembershipRepositoryInterface}
+ */
+function createOrganizationMembershipRepository() {
+    switch (databaseConfig.DB_TYPE) {
+        case 'mongodb':
+            return new OrganizationMembershipRepositoryMongo();
+        case 'postgresql':
+            return new OrganizationMembershipRepositoryPostgres();
+        case 'documentdb':
+            return new OrganizationMembershipRepositoryDocumentDB();
+        default:
+            throw new Error(
+                `Unsupported DB_TYPE: ${databaseConfig.DB_TYPE}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createOrganizationMembershipRepository,
+    OrganizationMembershipRepositoryPrisma,
+    OrganizationMembershipRepositoryMongo,
+    OrganizationMembershipRepositoryPostgres,
+    OrganizationMembershipRepositoryDocumentDB,
+};

package/user/repositories/organization-membership-repository-interface.js

@@ -0,0 +1,57 @@
+/**
+ * Organization Membership Repository Interface (ADR-056 §3.6).
+ *
+ * Atomic persistence of "this person belongs to that organization": a row or
+ * nothing. No policy and no reading of `IndividualUser.organizationId`: the
+ * legacy pointer counts as an implicit membership, and that rule lives in the
+ * domain (`user/membership.js`), applied by the use cases.
+ *
+ * Every method returns String ids whatever the database stores.
+ *
+ * @abstract
+ */
+class OrganizationMembershipRepositoryInterface {
+    /**
+     * @param {string|number} individualUserId
+     * @param {string|number} organizationUserId
+     * @returns {Promise<Object|null>} The stored membership, or null.
+     * @abstract
+     */
+    async findMembership(individualUserId, organizationUserId) {
+        throw new Error('Method findMembership must be implemented by subclass');
+    }
+
+    /**
+     * Adds a membership if there is none; never changes an existing one.
+     * Idempotent, and safe against a concurrent identical call: both resolve
+     * to the same row.
+     *
+     * @param {string|number} individualUserId
+     * @param {string|number} organizationUserId
+     * @param {Object} [options]
+     * @param {string|null} [options.orgRole] Stored only when the row is
+     *   created; defaults to `MEMBER`.
+     * @returns {Promise<Object>} The stored membership.
+     * @abstract
+     */
+    async addMembership(individualUserId, organizationUserId, options) {
+        throw new Error('Method addMembership must be implemented by subclass');
+    }
+
+    /**
+     * Stored memberships of an organization, oldest first. Rows only: people
+     * who are in the organization through the legacy pointer alone are not
+     * here.
+     *
+     * @param {string|number} organizationUserId
+     * @returns {Promise<Object[]>}
+     * @abstract
+     */
+    async listMembershipsForOrganization(organizationUserId) {
+        throw new Error(
+            'Method listMembershipsForOrganization must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { OrganizationMembershipRepositoryInterface };

package/user/repositories/organization-membership-repository-mongo.js

@@ -0,0 +1,13 @@
+const {
+    OrganizationMembershipRepositoryPrisma,
+} = require('./organization-membership-repository-prisma');
+
+/** Organization membership persistence for MongoDB: ids are ObjectId strings, used as they are. */
+class OrganizationMembershipRepositoryMongo extends OrganizationMembershipRepositoryPrisma {
+    /** @protected */
+    _toDbId(id) {
+        return id;
+    }
+}
+
+module.exports = { OrganizationMembershipRepositoryMongo };

package/user/repositories/organization-membership-repository-postgres.js

@@ -0,0 +1,29 @@
+const {
+    OrganizationMembershipRepositoryPrisma,
+} = require('./organization-membership-repository-prisma');
+
+/**
+ * Organization membership persistence for PostgreSQL. The database keys are
+ * Int, the application's are strings, so ids are converted in and the record
+ * mapper stringifies them out.
+ */
+class OrganizationMembershipRepositoryPostgres extends OrganizationMembershipRepositoryPrisma {
+    /**
+     * Strict: digits only. `parseInt` would turn '12abc' into 12 and query
+     * the wrong person.
+     * @protected
+     */
+    _toDbId(id) {
+        const text = typeof id === 'number' ? String(id) : id;
+        if (typeof text !== 'string' || !/^\d+$/.test(text)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        const parsed = Number(text);
+        if (!Number.isSafeInteger(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+}
+
+module.exports = { OrganizationMembershipRepositoryPostgres };

package/user/repositories/organization-membership-repository-prisma.js

@@ -0,0 +1,81 @@
+const { prisma } = require('../../database/prisma');
+const { isUniqueViolation } = require('../../database/unique-violation');
+const {
+    OrganizationMembershipRepositoryInterface,
+} = require('./organization-membership-repository-interface');
+const { toMembership } = require('./organization-membership-record');
+
+/**
+ * Organization membership persistence through the Prisma client. Both schemas
+ * declare the same model; they differ only in the id type, which the subclass
+ * supplies through `_toDbId` (MongoDB: ObjectId strings, PostgreSQL: Int).
+ *
+ * @abstract
+ */
+class OrganizationMembershipRepositoryPrisma extends OrganizationMembershipRepositoryInterface {
+    constructor(prismaClient = prisma) {
+        super();
+        this.prisma = prismaClient;
+    }
+
+    /**
+     * @protected
+     * @abstract
+     */
+    _toDbId(id) {
+        throw new Error('Method _toDbId must be implemented by subclass');
+    }
+
+    async findMembership(individualUserId, organizationUserId) {
+        const row = await this._findRow(individualUserId, organizationUserId);
+        return row ? toMembership(row) : null;
+    }
+
+    async addMembership(individualUserId, organizationUserId, options = {}) {
+        const pair = this._pair(individualUserId, organizationUserId);
+        try {
+            const row = await this.prisma.organizationMembership.upsert({
+                where: { individualUserId_organizationUserId: pair },
+                // `undefined` lets the column default (MEMBER) apply.
+                create: { ...pair, orgRole: options.orgRole ?? undefined },
+                update: {},
+            });
+            return toMembership(row);
+        } catch (error) {
+            // Two first logins can both miss the row and both try to create it.
+            // The loser's insert hits the unique pair; the row is there now.
+            if (!isUniqueViolation(error)) throw error;
+            const row = await this._findRow(individualUserId, organizationUserId);
+            if (!row) throw error;
+            return toMembership(row);
+        }
+    }
+
+    async listMembershipsForOrganization(organizationUserId) {
+        const rows = await this.prisma.organizationMembership.findMany({
+            where: { organizationUserId: this._toDbId(organizationUserId) },
+            orderBy: { createdAt: 'asc' },
+        });
+        return rows.map(toMembership);
+    }
+
+    _pair(individualUserId, organizationUserId) {
+        return {
+            individualUserId: this._toDbId(individualUserId),
+            organizationUserId: this._toDbId(organizationUserId),
+        };
+    }
+
+    async _findRow(individualUserId, organizationUserId) {
+        return this.prisma.organizationMembership.findUnique({
+            where: {
+                individualUserId_organizationUserId: this._pair(
+                    individualUserId,
+                    organizationUserId
+                ),
+            },
+        });
+    }
+}
+
+module.exports = { OrganizationMembershipRepositoryPrisma };

package/user/repositories/user-repository-documentdb.js

@@ -4,7 +4,7 @@ const {
     toObjectId,
     fromObjectId,
     findOne,
-    findMany,
+    findManyDrained,
     insertOne,
     updateOne,
     deleteOne,
@@ -72,7 +72,9 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
     }
 
     async findIndividualUsersByOrganizationId(organizationUserId) {
-        const docs = await findMany(this.prisma, 'User', {
+        // Drained: findMany returns only the first cursor batch, which would
+        // drop people from a large organization.
+        const docs = await findManyDrained(this.prisma, 'User', {
             organizationId: toObjectId(organizationUserId),
             type: 'INDIVIDUAL',
         });
@@ -421,6 +423,29 @@ class UserRepositoryDocumentDB extends UserRepositoryInterface {
         );
         return this._mapUser(decrypted);
     }
+
+    /**
+     * Set the legacy organizationId only if it is still null or absent (see the
+     * interface): the filter carries the condition, so it is one atomic update.
+     * @param {string} individualUserId
+     * @param {string} organizationUserId
+     * @returns {Promise<Object|null>} The individual user as stored afterwards
+     */
+    async linkIndividualToOrganizationIfUnset(individualUserId, organizationUserId) {
+        await updateOne(
+            this.prisma,
+            'User',
+            {
+                _id: toObjectId(individualUserId),
+                type: 'INDIVIDUAL',
+                // Raw MongoDB query (not Prisma): `{ field: null }` matches both a
+                // null value and a missing field, so no `$exists` branch is needed.
+                organizationId: null,
+            },
+            { $set: { organizationId: toObjectId(organizationUserId) } }
+        );
+        return this.findIndividualUserById(individualUserId);
+    }
 }
 
 module.exports = { UserRepositoryDocumentDB };

package/user/repositories/user-repository-interface.js

@@ -209,6 +209,24 @@ class UserRepositoryInterface {
             'Method linkIndividualToOrganization must be implemented by subclass'
         );
     }
+
+    /**
+     * Set an individual user's legacy `organizationId` pointer only if it is
+     * not set yet (their first link), decided by the database in the same
+     * statement so two concurrent first logins cannot overwrite each other.
+     * Never changes an existing pointer (ADR-056 §3.6).
+     *
+     * @param {string|number} individualUserId - Individual user ID
+     * @param {string|number} organizationUserId - Organization user ID
+     * @returns {Promise<Object|null>} The individual user as stored afterwards
+     *   (null if there is no such individual)
+     * @abstract
+     */
+    async linkIndividualToOrganizationIfUnset(individualUserId, organizationUserId) {
+        throw new Error(
+            'Method linkIndividualToOrganizationIfUnset must be implemented by subclass'
+        );
+    }
 }
 
 module.exports = { UserRepositoryInterface };

package/user/repositories/user-repository-mongo.js

@@ -318,6 +318,30 @@ class UserRepositoryMongo extends UserRepositoryInterface {
             },
         });
     }
+
+    /**
+     * Set the legacy organizationId only if it is still null (see the interface).
+     * @param {string} individualUserId
+     * @param {string} organizationUserId
+     * @returns {Promise<Object|null>} The individual user as stored afterwards
+     */
+    async linkIndividualToOrganizationIfUnset(individualUserId, organizationUserId) {
+        await this.prisma.user.updateMany({
+            where: {
+                id: individualUserId,
+                type: 'INDIVIDUAL',
+                // Prisma on MongoDB: `null` matches only an explicit null, and
+                // `isSet: false` only a missing field. An individual created
+                // without the field is the common case, so match both.
+                OR: [
+                    { organizationId: null },
+                    { organizationId: { isSet: false } },
+                ],
+            },
+            data: { organizationId: organizationUserId },
+        });
+        return this.findIndividualUserById(individualUserId);
+    }
 }
 
 module.exports = { UserRepositoryMongo };

package/user/repositories/user-repository-postgres.js

@@ -372,6 +372,24 @@ class UserRepositoryPostgres extends UserRepositoryInterface {
         });
         return this._convertUserIds(user);
     }
+
+    /**
+     * Set the legacy organizationId only if it is still null (see the interface).
+     * @param {string} individualUserId - Individual user ID (string from application layer)
+     * @param {string} organizationUserId - Organization user ID (string from application layer)
+     * @returns {Promise<Object|null>} The individual user as stored afterwards, with string IDs
+     */
+    async linkIndividualToOrganizationIfUnset(individualUserId, organizationUserId) {
+        await this.prisma.user.updateMany({
+            where: {
+                id: this._convertId(individualUserId),
+                type: 'INDIVIDUAL',
+                organizationId: null,
+            },
+            data: { organizationId: this._convertId(organizationUserId) },
+        });
+        return this.findIndividualUserById(individualUserId);
+    }
 }
 
 module.exports = { UserRepositoryPostgres };