feat(auth): invite-gated signup UI (#4212)

* feat(auth): signup relays inviteToken via query + verifyInvite action

* feat(auth): signup view reveals form + prefills email on valid invite token

When signup is disabled and ?inviteToken is present, verifyInvite() is called
in created(); on valid invite the credentials form is shown and email prefilled.
The token is passed through to authStore.signup() (omitted when null to keep
existing tests exact-match on { email, password }).

* chore(auth): verify fixups for invite signup UI

Add missing verifyInvite error-path test (catch → {valid:false,email:null})
and invite-invalid view branch test to reach 100% line coverage on auth.store.js.

* refactor(auth): drop dead params write in signup; align verifyInvite test mock with contract

* fix(auth): normalize inviteToken query + suppress disabled-alert flash during invite verify

- inviteToken: normalize string | string[] | undefined to single string or null
- inviteChecking flag: true when token present, cleared after verifyInvite resolves
- Suppresses disabled-alert flash while invite is being checked
- Tests: 6 new cases (array/string/null normalization, inviteChecking lifecycle, no-flash)

Author: PierreBrisorgueil

src/modules/auth/stores/auth.store.js

@@ -203,15 +203,19 @@ export const useAuthStore = defineStore('auth', {
       const api = `${config.api.protocol}://${config.api.host}:${config.api.port}/${config.api.base}`;
       const coreStore = useCoreStore();
 
+      const { inviteToken, ...payload } = params;
+
       // Deduce firstName/lastName from email if not explicitly provided
-      if (!params.firstName && !params.lastName) {
-        const deduced = deduceNamesFromEmail(params.email);
-        if (deduced.firstName) params.firstName = deduced.firstName;
-        if (deduced.lastName) params.lastName = deduced.lastName;
+      if (!payload.firstName && !payload.lastName) {
+        const deduced = deduceNamesFromEmail(payload.email);
+        if (deduced.firstName) { payload.firstName = deduced.firstName; }
+        if (deduced.lastName) { payload.lastName = deduced.lastName; }
       }
 
+      const signupUrl = `${api}/${config.api.endPoints.auth}/signup${inviteToken ? `?inviteToken=${encodeURIComponent(inviteToken)}` : ''}`;
+
       try {
-        const res = await axios.post(`${api}/${config.api.endPoints.auth}/signup`, params);
+        const res = await axios.post(signupUrl, payload);
         localStorage.setItem(`${config.cookie.prefix}UserRoles`, res.data.user.roles);
         localStorage.setItem(`${config.cookie.prefix}CookieExpire`, res.data.tokenExpiresIn);
 
@@ -374,6 +378,22 @@ export const useAuthStore = defineStore('auth', {
       const res = await axios.post(`${api}/${config.api.endPoints.auth}/resend-verification`);
       return res.data;
     },
+
+    /**
+     * @desc Verify a signup invite token (public). Used by the signup page to
+     * reveal the form + prefill the invited email when public signup is closed.
+     * @param {string} token
+     * @returns {Promise<{valid: boolean, email: string|null}>}
+     */
+    async verifyInvite(token) {
+      const api = `${config.api.protocol}://${config.api.host}:${config.api.port}/${config.api.base}`;
+      try {
+        const res = await axios.get(`${api}/${config.api.endPoints.auth}/invitations/verify/${encodeURIComponent(token)}`);
+        return res.data.data;
+      } catch {
+        return { valid: false, email: null };
+      }
+    },
   },
 });
 

src/modules/auth/tests/auth.signup.view.unit.tests.js

@@ -7,8 +7,9 @@ const signupMock = vi.hoisted(() => vi.fn());
 const fetchServerConfigMock = vi.hoisted(() => vi.fn().mockResolvedValue(null));
 const refreshAbilitiesMock = vi.hoisted(() => vi.fn().mockResolvedValue());
 const resendVerificationMock = vi.hoisted(() => vi.fn().mockResolvedValue());
+const verifyInviteMock = vi.hoisted(() => vi.fn().mockResolvedValue({ valid: false, email: null }));
 vi.mock('../stores/auth.store', () => ({
-  useAuthStore: () => ({ auth: false, signup: signupMock, serverConfig: null, fetchServerConfig: fetchServerConfigMock, refreshAbilities: refreshAbilitiesMock, resendVerification: resendVerificationMock }),
+  useAuthStore: () => ({ auth: false, signup: signupMock, serverConfig: null, fetchServerConfig: fetchServerConfigMock, refreshAbilities: refreshAbilitiesMock, resendVerification: resendVerificationMock, verifyInvite: verifyInviteMock }),
   deduceNamesFromEmail: (email) => {
     const local = email ? email.split('@')[0] : '';
     const parts = local.split(/[._-]/);
@@ -67,6 +68,7 @@ describe('auth.signup.view', () => {
     fetchServerConfigMock.mockReset().mockResolvedValue(null);
     refreshAbilitiesMock.mockReset().mockResolvedValue();
     resendVerificationMock.mockReset().mockResolvedValue();
+    verifyInviteMock.mockReset().mockResolvedValue({ valid: false, email: null });
     createOrganizationMock.mockReset();
   });
 
@@ -420,6 +422,119 @@ describe('auth.signup.view', () => {
     });
   });
 
+  /**
+   * Extended mount helper for invite-gate scenarios.
+   * Allows configuring $route.query, fetchServerConfig return, verifyInvite return, and signup mock.
+   */
+  const mountSignup = ({ query = {}, serverConfig = null, verifyInvite = null, signup = undefined } = {}) => {
+    fetchServerConfigMock.mockResolvedValue(serverConfig);
+    verifyInviteMock.mockResolvedValue(verifyInvite);
+    if (signup) signupMock.mockImplementation(signup);
+    return mountView(makeFormStub(true), query);
+  };
+
+  describe('inviteToken normalization', () => {
+    test('when $route.query.inviteToken is an array, takes the first element', async () => {
+      const wrapper = await mountSignup({
+        query: { inviteToken: ['a', 'b'] },
+        serverConfig: { sign: { up: true } },
+        verifyInvite: { valid: true, email: null },
+      });
+      await flushPromises();
+      expect(wrapper.vm.inviteToken).toBe('a');
+    });
+
+    test('when $route.query.inviteToken is a string, uses it as-is', async () => {
+      const wrapper = await mountSignup({
+        query: { inviteToken: 'tok123' },
+        serverConfig: { sign: { up: true } },
+        verifyInvite: { valid: true, email: null },
+      });
+      await flushPromises();
+      expect(wrapper.vm.inviteToken).toBe('tok123');
+    });
+
+    test('when $route.query.inviteToken is absent, inviteToken is null', async () => {
+      const wrapper = await mountSignup({ query: {}, serverConfig: { sign: { up: true } } });
+      await flushPromises();
+      expect(wrapper.vm.inviteToken).toBeNull();
+    });
+
+    test('inviteChecking starts true when a token is present and becomes false after mount resolves', async () => {
+      const wrapper = await mountSignup({
+        query: { inviteToken: 'tok123' },
+        serverConfig: { sign: { up: false } },
+        verifyInvite: { valid: true, email: 'guest@example.com' },
+      });
+      // After flushPromises, created() has completed — inviteChecking must be false
+      await flushPromises();
+      expect(wrapper.vm.inviteChecking).toBe(false);
+    });
+
+    test('inviteChecking starts false when no token is present', async () => {
+      const wrapper = await mountSignup({ query: {}, serverConfig: { sign: { up: false } } });
+      await flushPromises();
+      expect(wrapper.vm.inviteChecking).toBe(false);
+    });
+
+    test('disabled alert is hidden while inviteChecking is true (no flash)', async () => {
+      // Simulate in-flight verify: mount without flushing promises
+      verifyInviteMock.mockResolvedValue({ valid: false, email: null });
+      fetchServerConfigMock.mockResolvedValue({ sign: { up: false } });
+      const wrapper = mountView(makeFormStub(true), { inviteToken: 'pending-tok' });
+      // Before promises flush, inviteChecking should be true → alert not shown
+      expect(wrapper.vm.inviteChecking).toBe(true);
+      await flushPromises();
+      // After resolve, inviteChecking is false
+      expect(wrapper.vm.inviteChecking).toBe(false);
+    });
+  });
+
+  describe('signup view — invited flow (signup disabled)', () => {
+    test('with a valid ?inviteToken, the credentials form is shown and email is prefilled', async () => {
+      const wrapper = await mountSignup({
+        query: { inviteToken: 'tok123' },
+        serverConfig: { sign: { up: false } },
+        verifyInvite: { valid: true, email: 'guest@example.com' },
+      });
+      await flushPromises();
+      expect(wrapper.find('input[type="password"]').exists()).toBe(true);
+      expect(wrapper.vm.email).toBe('guest@example.com');
+    });
+
+    test('with no invite and signup disabled, the disabled alert is shown and no form', async () => {
+      const wrapper = await mountSignup({ query: {}, serverConfig: { sign: { up: false } } });
+      await flushPromises();
+      expect(wrapper.text()).toContain('Registration is currently disabled');
+      expect(wrapper.find('input[type="password"]').exists()).toBe(false);
+    });
+
+    test('validate() passes inviteToken to store.signup', async () => {
+      const signupSpy = vi.fn().mockResolvedValue({});
+      const wrapper = await mountSignup({
+        query: { inviteToken: 'tok123' },
+        serverConfig: { sign: { up: false } },
+        verifyInvite: { valid: true, email: 'guest@example.com' },
+        signup: signupSpy,
+      });
+      await flushPromises();
+      wrapper.vm.password = 'Sup3rStr0ng!';
+      await wrapper.vm.validate();
+      expect(signupSpy).toHaveBeenCalledWith(expect.objectContaining({ inviteToken: 'tok123', email: 'guest@example.com' }));
+    });
+
+    test('with an invalid invite (valid: false) and signup disabled, the disabled alert is shown and no form', async () => {
+      const wrapper = await mountSignup({
+        query: { inviteToken: 'expired-token' },
+        serverConfig: { sign: { up: false } },
+        verifyInvite: { valid: false, email: null },
+      });
+      await flushPromises();
+      expect(wrapper.text()).toContain('Registration is currently disabled');
+      expect(wrapper.find('input[type="password"]').exists()).toBe(false);
+    });
+  });
+
   describe('email verification flow', () => {
     it('shows email verification step when emailVerificationRequired is returned', async () => {
       signupMock.mockResolvedValueOnce({

src/modules/auth/tests/auth.store.unit.tests.js

@@ -639,11 +639,12 @@ describe('Auth Store', () => {
       };
 
       axios.post.mockResolvedValueOnce(mockResponse);
-      const params = { email: 'jane.smith@test.com', password: 'password123' };
-      await authStore.signup(params);
+      await authStore.signup({ email: 'jane.smith@test.com', password: 'password123' });
 
-      expect(params.firstName).toBe('Jane');
-      expect(params.lastName).toBe('Smith');
+      // Assert the meaningful thing: the POSTed body contains the deduced names
+      const body = axios.post.mock.calls[0][1];
+      expect(body.firstName).toBe('Jane');
+      expect(body.lastName).toBe('Smith');
     });
   });
 
@@ -880,6 +881,39 @@ describe('Auth Store', () => {
     });
   });
 
+  describe('auth store — invite token relay', () => {
+    it('signup appends inviteToken as a query param and omits it from the body', async () => {
+      const authStore = useAuthStore();
+      axios.post.mockResolvedValueOnce({ data: { user: { id: '1', roles: ['user'], email: 'a@b.co' }, tokenExpiresIn: 10 } });
+      await authStore.signup({ email: 'a@b.co', password: 'x', inviteToken: 'tok123' });
+      const [url, body] = axios.post.mock.calls[0];
+      expect(url).toContain('/signup?inviteToken=tok123');
+      expect(body).not.toHaveProperty('inviteToken');
+    });
+
+    it('signup without inviteToken posts to a plain /signup URL', async () => {
+      const authStore = useAuthStore();
+      axios.post.mockResolvedValueOnce({ data: { user: { id: '1', roles: ['user'], email: 'a@b.co' }, tokenExpiresIn: 10 } });
+      await authStore.signup({ email: 'a@b.co', password: 'x' });
+      expect(axios.post.mock.calls[0][0]).toMatch(/\/signup$/);
+    });
+
+    it('verifyInvite returns { valid, email } from the API', async () => {
+      const authStore = useAuthStore();
+      axios.get.mockResolvedValueOnce({ data: { data: { valid: true, email: 'a@b.co' } } });
+      const r = await authStore.verifyInvite('tok123');
+      expect(axios.get.mock.calls[0][0]).toContain('/invitations/verify/tok123');
+      expect(r).toEqual({ valid: true, email: 'a@b.co' });
+    });
+
+    it('verifyInvite returns { valid: false, email: null } when the API rejects', async () => {
+      const authStore = useAuthStore();
+      axios.get.mockRejectedValueOnce(new Error('Not found'));
+      const r = await authStore.verifyInvite('bad-token');
+      expect(r).toEqual({ valid: false, email: null });
+    });
+  });
+
   describe('PostHog analytics', () => {
     it('should call identify helper on signin with user data', async () => {
       const authStore = useAuthStore();

src/modules/auth/views/signup.view.vue

@@ -62,7 +62,7 @@
       </div>
 
       <!-- Registration disabled -->
-      <v-alert v-if="serverConfig?.sign?.up === false" type="warning" variant="tonal" class="mb-4" :class="config.vuetify.theme.rounded">
+      <v-alert v-if="serverConfig?.sign?.up === false && !invite?.valid && !inviteChecking" type="warning" variant="tonal" class="mb-4" :class="config.vuetify.theme.rounded">
         <span class="text-body-medium">Registration is currently disabled.</span>
       </v-alert>
 
@@ -103,7 +103,10 @@
       </template>
 
       <!-- Credentials form -->
-      <template v-else-if="serverConfig === null || serverConfig?.sign?.up === true">
+      <template v-else-if="serverConfig === null || serverConfig?.sign?.up === true || invite?.valid">
+        <v-alert v-if="invite?.valid" type="success" variant="tonal" class="mb-4" :class="config.vuetify.theme.rounded">
+          <span class="text-body-medium">You've been invited. Create your account below.</span>
+        </v-alert>
         <v-alert
           v-if="signupError"
           type="error"
@@ -185,6 +188,9 @@ export default {
       theme,
       valid: false,
       serverConfig: undefined,
+      inviteToken: (() => { const q = this.$route.query.inviteToken; return (Array.isArray(q) ? q[0] : q) || null; })(),
+      inviteChecking: !!((() => { const q = this.$route.query.inviteToken; return (Array.isArray(q) ? q[0] : q) || null; })()),
+      invite: null, // { valid, email } once verified
       signupStep: 'form',
       organizationWelcomeMessage: '',
       suggestedOrganization: null,
@@ -268,6 +274,11 @@ export default {
   async created() {
     const authStore = useAuthStore();
     this.serverConfig = await authStore.fetchServerConfig();
+    if (this.inviteToken) {
+      this.invite = await authStore.verifyInvite(this.inviteToken);
+      if (this.invite?.valid && this.invite.email) this.email = this.invite.email;
+      this.inviteChecking = false;
+    }
     // If already logged in (e.g. page refresh after signup), redirect appropriately
     if (authStore.isLoggedIn) {
       if (authStore.user?.currentOrganization) {
@@ -303,6 +314,7 @@ export default {
           const result = await authStore.signup({
             email: this.email,
             password: this.password,
+            ...(this.inviteToken ? { inviteToken: this.inviteToken } : {}),
           });
 
           if (!result) return;