@friggframework/core 2.0.0--canary.680.daae24e.0 → 2.0.0--canary.686.e94de4d.0

package/user/use-cases/authenticate-user.js

@@ -1,5 +1,6 @@
 const Boom = require('@hapi/boom');
 const { getLogger } = require('../../logs');
+const { AUTH_SOURCES } = require('../user');
 
 const log = getLogger('frigg.user.authentication');
 
@@ -68,10 +69,13 @@ class AuthenticateUser {
                 // Validate the API key (authentication)
                 await this.authenticateWithSharedSecret.execute(apiKey);
                 // Get user from x-frigg headers (authorization)
-                return await this.getUserFromXFriggHeaders.execute(
+                const user = await this.getUserFromXFriggHeaders.execute(
                     appUserId,
                     appOrgId
                 );
+                // The app's own backend: trusted to manage organization things.
+                user.setAuthSource(AUTH_SOURCES.SHARED_SECRET);
+                return user;
             }
             log.debug('No x-frigg-api-key header, skipping shared secret', {
                 eventName: `${log.name}.shared_secret_skipped`,
@@ -90,6 +94,7 @@ class AuthenticateUser {
             // Detect JWT format (3 parts separated by dots)
             if (token && token.split('.').length === 3) {
                 const user = await this.getUserFromAdopterJwt.execute(token);
+                user.setAuthSource(AUTH_SOURCES.ADOPTER_JWT);
                 // Validate x-frigg headers match JWT claims if present
                 if (appUserId || appOrgId) {
                     this.validateUserMatch(user, appUserId, appOrgId);
@@ -106,6 +111,7 @@ class AuthenticateUser {
             const user = await this.getUserFromBearerToken.execute(
                 req.headers.authorization
             );
+            user.setAuthSource(AUTH_SOURCES.BEARER_TOKEN);
             // Validate x-frigg headers match token user if present
             if (appUserId || appOrgId) {
                 this.validateUserMatch(user, appUserId, appOrgId);

package/user/use-cases/ensure-organization-membership.js

@@ -0,0 +1,92 @@
+const { getLogger } = require('../../logs');
+const { isPresent, implicitMembership } = require('../membership');
+
+const log = getLogger('frigg.user.membership');
+
+/**
+ * Makes sure a person is a member of the organization a request is acting in
+ * (ADR-056 §3.6). Shared by the adopter-token and x-frigg header paths.
+ *
+ * - Already a member (a stored row, or the legacy `organizationId` pointer
+ *   read as an implicit membership): nothing is written.
+ * - Not a member: a membership is added, unless the caller asks for existing
+ *   memberships only (`requireExisting`), in which case nothing is written and
+ *   `membership` is null so the caller can refuse.
+ * - The legacy `organizationId` is set when the person has none (their first
+ *   link) and never changed afterwards. It is a pointer for old readers, not
+ *   the active organization: that is whichever organization the request names.
+ *
+ * Adding is an idempotent upsert, so two first logins racing for different
+ * organizations both succeed.
+ *
+ * @class EnsureOrganizationMembership
+ */
+class EnsureOrganizationMembership {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository
+     * @param {import('../repositories/organization-membership-repository-interface').OrganizationMembershipRepositoryInterface} params.organizationMembershipRepository
+     */
+    constructor({ userRepository, organizationMembershipRepository }) {
+        this.userRepository = userRepository;
+        this.organizationMembershipRepository = organizationMembershipRepository;
+    }
+
+    /**
+     * @param {Object} params
+     * @param {Object|null} params.individual Individual user as the repository returns it.
+     * @param {Object|null} params.organization The active organization user.
+     * @param {string|null} [params.orgRole] Role to store with a new membership.
+     * @param {boolean} [params.requireExisting=false] Refuse to add.
+     * @returns {Promise<{individual: Object|null, membership: Object|null}>}
+     *   `individual` may be the updated record (legacy pointer set).
+     */
+    async execute({
+        individual,
+        organization,
+        orgRole = null,
+        requireExisting = false,
+    }) {
+        // A request that names no organization, or no person (organization-only
+        // auth), has no membership to check or add.
+        if (!individual || !organization) {
+            return { individual, membership: null };
+        }
+
+        const existing =
+            (await this.organizationMembershipRepository.findMembership(
+                individual.id,
+                organization.id
+            )) ?? implicitMembership(individual, organization.id);
+        if (existing) {
+            return { individual, membership: existing };
+        }
+        if (requireExisting) {
+            return { individual, membership: null };
+        }
+
+        const membership =
+            await this.organizationMembershipRepository.addMembership(
+                individual.id,
+                organization.id,
+                { orgRole }
+            );
+        log.debug('Organization membership added', {
+            eventName: `${log.name}.added`,
+        });
+
+        // The database repeats this condition in the update itself, so a
+        // concurrent first link by another request cannot be overwritten.
+        let updated = individual;
+        if (!isPresent(individual.organizationId)) {
+            updated =
+                (await this.userRepository.linkIndividualToOrganizationIfUnset(
+                    individual.id,
+                    organization.id
+                )) ?? individual;
+        }
+        return { individual: updated, membership };
+    }
+}
+
+module.exports = { EnsureOrganizationMembership };

package/user/use-cases/find-individual-users-by-organization.js

@@ -0,0 +1,54 @@
+const { sameId } = require('../membership');
+
+/**
+ * The individual users who belong to an organization (ADR-056 §3.6): the
+ * people with a stored membership, plus those the legacy
+ * `IndividualUser.organizationId` pointer places there, each once.
+ *
+ * Both repositories stay atomic; the union is composed here. Reading only the
+ * legacy pointer would list a person in the first organization they ever
+ * joined and in no other.
+ *
+ * @class FindIndividualUsersByOrganization
+ */
+class FindIndividualUsersByOrganization {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository
+     * @param {import('../repositories/organization-membership-repository-interface').OrganizationMembershipRepositoryInterface} params.organizationMembershipRepository
+     */
+    constructor({ userRepository, organizationMembershipRepository }) {
+        this.userRepository = userRepository;
+        this.organizationMembershipRepository = organizationMembershipRepository;
+    }
+
+    /**
+     * @param {string|number} organizationUserId
+     * @returns {Promise<Object[]>} Individual users, legacy-pointer people first.
+     */
+    async execute(organizationUserId) {
+        const [legacy, memberships] = await Promise.all([
+            this.userRepository.findIndividualUsersByOrganizationId(
+                organizationUserId
+            ),
+            this.organizationMembershipRepository.listMembershipsForOrganization(
+                organizationUserId
+            ),
+        ]);
+
+        const users = [...(legacy || [])];
+        for (const { individualUserId } of memberships) {
+            if (users.some((u) => sameId(u.id ?? u._id, individualUserId))) {
+                continue;
+            }
+            const individual = await this.userRepository.findIndividualUserById(
+                individualUserId
+            );
+            // A membership whose person was deleted is skipped, not an error.
+            if (individual) users.push(individual);
+        }
+        return users;
+    }
+}
+
+module.exports = { FindIndividualUsersByOrganization };

package/user/use-cases/get-user-from-adopter-jwt.js

@@ -1,149 +1,120 @@
-const Boom = require('@hapi/boom');
+const { getLogger } = require('../../logs');
+const { fail } = require('../adopter-jwt-errors');
+const {
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+} = require('../app-user-helpers');
+
+const log = getLogger('frigg.user.adopter_jwt');
+
+const idFromClaim = (value) => {
+    if (typeof value === 'string' && value.trim() !== '') return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return null;
+};
 
 /**
- * STUB: Use case for retrieving a user from adopter-provided JWT token.
- *
- * This is a stub implementation for future JWT authentication support.
- * When implemented, this will allow adopters to use their own JWT tokens
- * for authentication instead of Frigg's native token system.
- *
- * FUTURE IMPLEMENTATION REQUIREMENTS:
- * - Validate JWT signature using jwtConfig.secret from app definition
- * - Support configurable signing algorithms (HS256, HS384, HS512, RS256, RS384, RS512)
- * - Extract user identifiers from JWT claims based on jwtConfig.userIdClaim and jwtConfig.orgIdClaim
- * - Find or create user based on extracted claim values
- * - Handle token expiration and validation errors
- * - Support refresh tokens (optional)
- * - Validate user ID conflicts if both individual and org IDs present in JWT
+ * Authenticates a request by a token issued by the adopter's own identity
+ * system (ADR-056 §2): verifies it, then finds or creates the individual and
+ * organization users it names.
  *
- * RECOMMENDED IMPLEMENTATION:
- * - Use 'jsonwebtoken' package for JWT parsing and validation
- * - Cache JWT public keys for RS* algorithms
- * - Add comprehensive error handling for invalid tokens
- * - Log authentication attempts for security auditing
- *
- * @todo Implement JWT validation with jsonwebtoken package
- * @todo Add unit tests for JWT parsing and claim extraction
- * @todo Document adopter JWT integration guide in Frigg docs
- * @todo Add support for JWT refresh tokens
- * @todo Implement JWT public key caching for RS* algorithms
+ * The organization the token names is the request's active organization
+ * (ADR-056 §3.6). A person who is not yet a member of it becomes one; a person
+ * can belong to several, and `IndividualUser.organizationId` is never moved
+ * (see EnsureOrganizationMembership). Two first logins racing for the same new
+ * person or organization both succeed: a create that loses to a unique
+ * constraint finds the winner's row.
  *
  * @class GetUserFromAdopterJwt
  */
 class GetUserFromAdopterJwt {
     /**
-     * Creates a new GetUserFromAdopterJwt instance.
-     * @param {Object} params - Configuration parameters.
-     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {Object} params
+     * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository
      * @param {Object} params.userConfig - The user config in the app definition.
+     * @param {import('./ensure-organization-membership').EnsureOrganizationMembership} params.ensureOrganizationMembership
+     * @param {{verify: Function, claimNames: Object}} params.tokenVerifier -
+     *   from `createAdopterTokenVerifier`.
      */
-    constructor({ userRepository, userConfig }) {
+    constructor({
+        userRepository,
+        ensureOrganizationMembership,
+        userConfig,
+        tokenVerifier,
+    }) {
         this.userRepository = userRepository;
+        this.ensureOrganizationMembership = ensureOrganizationMembership;
         this.userConfig = userConfig;
+        this.tokenVerifier = tokenVerifier;
     }
 
     /**
-     * Executes the use case.
      * @async
-     * @param {string} jwtToken - The JWT token from the Authorization header.
-     * @returns {Promise<import('../user').User>} The authenticated user object.
-     * @throws {Boom} 501 Not Implemented - This feature is not yet available.
+     * @param {string} token - The JWT from the Authorization header.
+     * @returns {Promise<import('../user').User>}
+     * @throws {Boom} 401 with `data.reason` for a token the verifier refuses
+     *   (including `token_missing_user_claim`).
+     * @throws {Boom} 503 `jwks_unavailable`, 500 `jwt_config_invalid` (from the verifier).
      */
-    async execute(jwtToken) {
-        throw Boom.notImplemented(
-            'Adopter JWT authentication is not yet implemented. ' +
-                'This feature is planned for a future Frigg release. ' +
-                'Please use one of the supported authentication modes instead: ' +
-                'friggToken (native bearer token) or xFriggHeaders (backend-to-backend with x-frigg-appUserId/appOrgId headers).'
-        );
+    async execute(token) {
+        const claims = await this.tokenVerifier.verify(token);
+        const { userIdClaim, orgIdClaim, roleClaim } =
+            this.tokenVerifier.claimNames;
 
-        /* FUTURE IMPLEMENTATION PSEUDOCODE:
+        const appUserId = idFromClaim(claims[userIdClaim]);
+        if (!appUserId) throw fail('token_missing_user_claim');
 
-        const jwt = require('jsonwebtoken');
-        
-        // Validate JWT configuration exists
-        if (!this.userConfig.jwtConfig || !this.userConfig.jwtConfig.secret) {
-            throw Boom.badImplementation('JWT configuration is required when adopterJwt auth mode is enabled');
+        const rawOrgId = claims[orgIdClaim];
+        const appOrgId = idFromClaim(rawOrgId);
+        if (rawOrgId !== undefined && rawOrgId !== null && !appOrgId) {
+            throw fail('token_malformed');
         }
-        
-        try {
-            // Verify and decode JWT
-            const decoded = jwt.verify(jwtToken, this.userConfig.jwtConfig.secret, {
-                algorithms: [this.userConfig.jwtConfig.algorithm || 'HS256']
+        const role = claims[roleClaim];
+
+        const orgRole = typeof role === 'string' && role !== '' ? role : null;
+        const { user, membership } = await this._findOrCreateUser(
+            appUserId,
+            appOrgId,
+            orgRole
+        );
+        user.setOrgRole(orgRole);
+        // What the membership row says: the role when the token carries none.
+        user.setMembershipRole(membership?.orgRole ?? null);
+
+        log.debug('Adopter token accepted', {
+            eventName: `${log.name}.accepted`,
+            hasOrganization: Boolean(user.getOrganizationUser()),
+        });
+        return user;
+    }
+
+    async _findOrCreateUser(appUserId, appOrgId, orgRole) {
+        const cfg = this.userConfig;
+        const found = await findAppUsers(this.userRepository, cfg, {
+            appUserId,
+            appOrgId,
+        });
+        const created = await createMissingAppUsers(this.userRepository, cfg, {
+            appUserId,
+            appOrgId,
+            ...found,
+        });
+
+        // The token's organization is the active one whether or not this is
+        // the person's first time in it.
+        const { individual, membership } =
+            await this.ensureOrganizationMembership.execute({
+                individual: created.individual,
+                organization: created.organization,
+                orgRole,
             });
-            
-            // Extract user identifiers from claims
-            const appUserId = decoded[this.userConfig.jwtConfig.userIdClaim || 'sub'];
-            const appOrgId = decoded[this.userConfig.jwtConfig.orgIdClaim || 'org_id'];
-            
-            // At least one identifier required
-            if (!appUserId && !appOrgId) {
-                throw Boom.badRequest('JWT must contain user or organization identifier claims');
-            }
-            
-            // Find existing users
-            let individualUserData = null;
-            let organizationUserData = null;
-            
-            if (appUserId) {
-                individualUserData = await this.userRepository.findIndividualUserByAppUserId(appUserId);
-            }
-            
-            if (appOrgId) {
-                organizationUserData = await this.userRepository.findOrganizationUserByAppOrgId(appOrgId);
-            }
-            
-            // Validate no conflicts if both IDs present
-            if (appUserId && appOrgId && individualUserData && organizationUserData) {
-                const individualOrgId = individualUserData.organizationUser?.toString();
-                const expectedOrgId = organizationUserData.id?.toString();
-                
-                if (individualOrgId !== expectedOrgId) {
-                    throw Boom.badRequest(
-                        'User ID mismatch: JWT claims refer to different users. ' +
-                        'Individual and organization IDs must belong to the same user.'
-                    );
-                }
-            }
-            
-            // Auto-create if not found
-            if (!individualUserData && !organizationUserData) {
-                if (appUserId) {
-                    individualUserData = await this.userRepository.createIndividualUser({
-                        appUserId,
-                        username: `jwt-user-${appUserId}`,
-                        email: decoded.email || `${appUserId}@jwt.local`,
-                    });
-                } else {
-                    organizationUserData = await this.userRepository.createOrganizationUser({
-                        appOrgId,
-                    });
-                }
-            }
-            
-            return new User(
-                individualUserData,
-                organizationUserData,
-                this.userConfig.usePassword,
-                this.userConfig.primary,
-                this.userConfig.individualUserRequired,
-                this.userConfig.organizationUserRequired
-            );
-            
-        } catch (error) {
-            if (error.name === 'TokenExpiredError') {
-                throw Boom.unauthorized('JWT token has expired');
-            } else if (error.name === 'JsonWebTokenError') {
-                throw Boom.unauthorized('Invalid JWT token');
-            } else if (error.isBoom) {
-                throw error;
-            }
-            throw Boom.unauthorized('JWT authentication failed');
-        }
-        */
+        return {
+            user: buildUser(cfg, individual, created.organization),
+            membership,
+        };
     }
 }
 
 module.exports = { GetUserFromAdopterJwt };
-
-

package/user/use-cases/get-user-from-x-frigg-headers.js

@@ -1,10 +1,38 @@
 const Boom = require('@hapi/boom');
-const { User } = require('../user');
+const {
+    findAppUsers,
+    createMissingAppUsers,
+    buildUser,
+    wantsIndividual,
+} = require('../app-user-helpers');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.user.x_frigg_headers');
+
+const NOT_A_MEMBER_MESSAGE =
+    'Not a member: the user identified by x-frigg-appUserId is not a member of the ' +
+    'organization identified by x-frigg-appOrgId, and strict membership does not ' +
+    'allow these headers to add them.';
 
 /**
  * Use case for retrieving or creating a user from x-frigg header identifiers.
  * Supports backend-to-backend API communication using application user IDs.
  *
+ * `x-frigg-appOrgId` names the request's active organization (ADR-056 §3.6).
+ * A person the organization does not know yet is added to it as a member; the
+ * person is never moved out of another organization, and
+ * `IndividualUser.organizationId` is set only on a first link.
+ *
+ * With `user.strictMembership: true` the headers cannot make anyone a member of
+ * an organization that already existed: a person who is not already a member
+ * (a brand-new `appUserId` included) is refused with 400. The one thing strict
+ * mode still allows is naming an organization this request creates, so a first
+ * login can bootstrap its own organization. Apps that run strict add people to
+ * existing organizations themselves, through the membership repository.
+ *
+ * `strictUserValidation` is a deprecated alias for `strictMembership`; its
+ * meaning changed (it used to reject a mismatched individual/organization pair).
+ *
  * @class GetUserFromXFriggHeaders
  */
 class GetUserFromXFriggHeaders {
@@ -12,11 +40,22 @@ class GetUserFromXFriggHeaders {
      * Creates a new GetUserFromXFriggHeaders instance.
      * @param {Object} params - Configuration parameters.
      * @param {import('../repositories/user-repository-interface').UserRepositoryInterface} params.userRepository - Repository for user data operations.
+     * @param {import('./ensure-organization-membership').EnsureOrganizationMembership} params.ensureOrganizationMembership
      * @param {Object} params.userConfig - The user config in the app definition.
      */
-    constructor({ userRepository, userConfig }) {
+    constructor({ userRepository, ensureOrganizationMembership, userConfig }) {
         this.userRepository = userRepository;
+        this.ensureOrganizationMembership = ensureOrganizationMembership;
         this.userConfig = userConfig;
+
+        const { strictMembership, strictUserValidation } = userConfig ?? {};
+        if (strictUserValidation !== undefined && strictMembership === undefined) {
+            log.warn(
+                'user.strictUserValidation is deprecated and now means strictMembership; rename it',
+                { eventName: `${log.name}.strict_user_validation_deprecated` }
+            );
+        }
+        this.strict = Boolean(strictMembership ?? strictUserValidation);
     }
 
     /**
@@ -25,7 +64,7 @@ class GetUserFromXFriggHeaders {
      * @param {string} [appUserId] - The app user ID from x-frigg-appUserId header.
      * @param {string} [appOrgId] - The app organization ID from x-frigg-appOrgId header.
      * @returns {Promise<import('../user').User>} The authenticated user object.
-     * @throws {Boom} 400 Bad Request if neither ID is provided or if both IDs are provided but belong to different users.
+     * @throws {Boom} 400 Bad Request if neither ID is provided or, in strict mode, if the person is not already a member of the existing organization named.
      */
     async execute(appUserId, appOrgId) {
         // At least one header must be provided
@@ -36,96 +75,60 @@ class GetUserFromXFriggHeaders {
         }
 
         // Find users by both IDs if both are provided
-        let individualUserData = null;
-        let organizationUserData = null;
-
-        if (appUserId && this.userConfig.individualUserRequired !== false) {
-            individualUserData =
-                await this.userRepository.findIndividualUserByAppUserId(
-                    appUserId
-                );
-        }
+        let { individual: individualUserData, organization: organizationUserData } =
+            await findAppUsers(this.userRepository, this.userConfig, {
+                appUserId,
+                appOrgId,
+            });
 
-        if (appOrgId && this.userConfig.organizationUserRequired) {
-            organizationUserData =
-                await this.userRepository.findOrganizationUserByAppOrgId(
-                    appOrgId
-                );
-        }
+        // Strict mode refuses to make anyone a member of an organization that
+        // existed before this request. Only an organization created below is
+        // exempt, since it has no members to disagree with.
+        const refuseNewMembers = this.strict && Boolean(organizationUserData);
 
-        // VALIDATION/AUTO-LINKING: If both IDs provided and both users exist, handle mismatch
+        // A person who does not exist yet cannot already be a member, so refuse
+        // now, before anything is persisted: refusing after creating them would
+        // leave an orphan individual behind on every refused request.
         if (
+            refuseNewMembers &&
             appUserId &&
-            appOrgId &&
-            individualUserData &&
-            organizationUserData
+            wantsIndividual(this.userConfig) &&
+            !individualUserData
         ) {
-            // Check if individual user is linked to the org user
-            const individualOrgId =
-                individualUserData.organizationUser?.toString();
-            const expectedOrgId = organizationUserData.id?.toString();
-
-            if (individualOrgId !== expectedOrgId) {
-                // Default behavior: Auto-link disconnected users
-                // Opt-in strict mode: Throw error on mismatch
-                if (this.userConfig.strictUserValidation) {
-                    throw Boom.badRequest(
-                        'User ID mismatch: x-frigg-appUserId and x-frigg-appOrgId refer to different users. ' +
-                            'Provide only one identifier or ensure they belong to the same user.'
-                    );
-                }
-
-                // Auto-link the users
-                individualUserData = await this.userRepository.linkIndividualToOrganization(
-                    individualUserData.id,
-                    organizationUserData.id
-                );
-            }
+            throw Boom.badRequest(NOT_A_MEMBER_MESSAGE);
         }
 
         // Auto-create users independently if they don't exist and are required
-        if (
-            !individualUserData &&
-            appUserId &&
-            this.userConfig.individualUserRequired !== false
-        ) {
-            individualUserData =
-                await this.userRepository.createIndividualUser({
-                    appUserId,
-                    username: `app-user-${appUserId}`,
-                    email: `${appUserId}@app.local`,
-                });
-        }
-
-        if (
-            !organizationUserData &&
-            appOrgId &&
-            this.userConfig.organizationUserRequired
-        ) {
-            organizationUserData =
-                await this.userRepository.createOrganizationUser({
-                    appOrgId,
-                });
-
-            // Link individual user to newly created org user if individual exists
-            if (individualUserData && organizationUserData) {
-                individualUserData = await this.userRepository.linkIndividualToOrganization(
-                    individualUserData.id,
-                    organizationUserData.id
-                );
+        const created = await createMissingAppUsers(
+            this.userRepository,
+            this.userConfig,
+            {
+                appUserId,
+                appOrgId,
+                individual: individualUserData,
+                organization: organizationUserData,
             }
+        );
+        individualUserData = created.individual;
+        organizationUserData = created.organization;
+
+        // The organization named by the header is the active one: join it
+        // rather than re-linking the person's single organizationId.
+        const ensured = await this.ensureOrganizationMembership.execute({
+            individual: individualUserData,
+            organization: organizationUserData,
+            requireExisting: refuseNewMembers,
+        });
+        if (refuseNewMembers && individualUserData && !ensured.membership) {
+            throw Boom.badRequest(NOT_A_MEMBER_MESSAGE);
         }
+        individualUserData = ensured.individual;
 
-        const user = new User(
+        return buildUser(
+            this.userConfig,
             individualUserData,
-            organizationUserData,
-            this.userConfig.usePassword,
-            this.userConfig.primary,
-            this.userConfig.individualUserRequired,
-            this.userConfig.organizationUserRequired
+            organizationUserData
         );
-
-        return user;
     }
 }