fix(organizations): address CodeRabbit + Copilot review findings

- domain: reject multiple-@ malformed emails in normalizeEmailDomain
- service: JSDoc for buildResult @param/@returns (CR+Copilot)
- service: update @returns to reflect null org/membership on mailer path
- e2e: add explicit suggestedJoin assertion on domain-match signup path
- e2e: fix stale A2b comment (now shipped in this PR)
- unit: remove stale "RED" test-driven header comment
- unit: cover multiple-@ rejection in domain tests

Author: PierreBrisorgueil

modules/organizations/services/organizations.domain.js

@@ -18,7 +18,7 @@ export const PUBLIC_DOMAINS = new Set([
 export function normalizeEmailDomain(email) {
   if (typeof email !== 'string') return null;
   const at = email.indexOf('@');
-  if (at === -1) return null;
+  if (at === -1 || at !== email.lastIndexOf('@')) return null;
   const domain = email.slice(at + 1).trim().toLowerCase();
   return domain.length > 0 && domain.includes('.') ? domain : null;
 }

modules/organizations/services/organizations.service.js

@@ -127,8 +127,9 @@ const createOrganizationForUser = async ({ name, slug, domain, user, slugGenerat
  * exactly once per real new org — no double-credit possible.
  *
  * @param {Object} user - The user object returned by UserService.create (with id, email, firstName, lastName).
- * @returns {Promise<{organization: Object, membership: Object, abilities: Array, emailVerificationRequired?: boolean, suggestedJoin?: {orgId: string, orgName: string}}>}
+ * @returns {Promise<{organization: Object|null, membership: Object|null, abilities: Array, emailVerificationRequired?: boolean, suggestedJoin?: {orgId: string, orgName: string}}>}
  *   An object containing the organization context for the signup response.
+ *   `organization` and `membership` are null when `emailVerificationRequired` is true (mailer path).
  *   NEVER returns `organizationSetupRequired` or `pendingJoin`.
  */
 const handleSignupOrganization = async (user) => {
@@ -155,6 +156,12 @@ const handleSignupOrganization = async (user) => {
   // MembershipRepository.defaultPopulate includes organizationId, so membership.organizationId
   // is the full org document after the query.
   // Shared result builder — all three signup exit-paths return the same {organization,membership,abilities} shape.
+  /**
+   * Build the signup organization payload with serialized abilities.
+   * @param {Object} organization - Organization document.
+   * @param {Object} membership - Membership document.
+   * @returns {Promise<{organization: Object, membership: Object, abilities: Array}>}
+   */
   const buildResult = async (organization, membership) => ({
     organization,
     membership,

modules/organizations/tests/organizations.domain.unit.tests.js

@@ -15,6 +15,9 @@ describe('organizations.domain', () => {
       expect(normalizeEmailDomain('')).toBeNull();
       expect(normalizeEmailDomain(null)).toBeNull();
     });
+    it('returns null for multiple-@ addresses', () => {
+      expect(normalizeEmailDomain('a@b@acme.com')).toBeNull();
+    });
   });
   describe('isPublicDomain', () => {
     it('flags common public providers', () => {

modules/organizations/tests/organizations.domainJoin.e2e.tests.js

@@ -152,10 +152,16 @@ describe('Organizations domain join E2E tests:', () => {
         expect(activeMemberships).toHaveLength(1);
         expect(activeMemberships[0].role).toBe('owner');
 
-        // suggestedJoin hint returned (name-only) pointing to owner's org
-        // controller still emits suggestedOrganization (always null post-footgun-removal);
-        // suggestedJoin is wired to the response in a follow-up (A2b).
+        // suggestedJoin hint (name-only shape) pointing to owner's org — wired in A2b
+        // controller still emits suggestedOrganization (always null post-footgun-removal)
         expect(result.body.suggestedOrganization).toBeNull();
+        expect(result.body.suggestedJoin).toBeDefined();
+        expect(result.body.suggestedJoin).toEqual(
+          expect.objectContaining({
+            orgId: String(org._id),
+            orgName: org.name,
+          }),
+        );
       } catch (err) {
         console.log(err);
         expect(err).toBeFalsy();

modules/organizations/tests/organizations.service.signup.unit.tests.js

@@ -10,7 +10,7 @@
  *  - signupGrant credited exactly once per real new org creation (via BillingSignupGrantService.grantOnSignup);
  *    not double-credited on any path.
  *
- * RED: written before A2 implementation — current code fails these assertions.
+ * All assertions pass with the A2 implementation shipped in this PR.
  */
 import mongoose from 'mongoose';
 import { jest, describe, test, expect, beforeEach } from '@jest/globals';