fix(auth,organizations): soft-refresh (token) at onboarding sites to prevent silent sign-out (#4431)

* fix(auth,organizations): soft-refresh (token) at onboarding sites to prevent silent sign-out

refreshAbilities() signs the user out AND rethrows on any failure — correct for
the axios 401 interceptor and router guard (session expiry), but a footgun at
onboarding touchpoints where a transient network/5xx error silently ejects a
brand-new user (worst at the final "Get Started" click). acceptInvitation already
uses the safe token() soft-refresh for this reason; apply the same pattern to the
remaining onboarding sites:

- signup proceedToApp (final Get Started click)
- verifyEmail post-verification redirect
- organization.create (first / additional org create)
- organizations.required refresh ("Check status") + requestToJoin

token() refreshes abilities + user + nav via the same /token endpoint without
signing out or throwing. The interceptor and router guard keep refreshAbilities()
(signout-on-failure is intended there).

Tests updated to mock/assert token(). Suite 145 files / 2454 tests + build green.

Claude-Session: https://claude.ai/code/session_01XioM62H2iEMLsr686minjn

* docs(organizations,auth): jsdoc on modified onboarding methods (coderabbit)

Add/repair JSDoc headers per the coding guideline (every function documents
@param + @returns; async returns Promise<void>):
- signup proceedToApp @returns void -> Promise<void>
- organizations.required refresh() + requestToJoin() headers
- organization.create create() header

Claude-Session: https://claude.ai/code/session_01XioM62H2iEMLsr686minjn

Author: PierreBrisorgueil

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

@@ -5,11 +5,11 @@ import { createVuetify } from 'vuetify';
 
 const signupMock = vi.hoisted(() => vi.fn());
 const fetchServerConfigMock = vi.hoisted(() => vi.fn().mockResolvedValue(null));
-const refreshAbilitiesMock = vi.hoisted(() => vi.fn().mockResolvedValue());
+const tokenMock = 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, verifyInvite: verifyInviteMock }),
+  useAuthStore: () => ({ auth: false, signup: signupMock, serverConfig: null, fetchServerConfig: fetchServerConfigMock, token: tokenMock, resendVerification: resendVerificationMock, verifyInvite: verifyInviteMock }),
   deduceNamesFromEmail: (email) => {
     const local = email ? email.split('@')[0] : '';
     const parts = local.split(/[._-]/);
@@ -66,7 +66,7 @@ describe('auth.signup.view', () => {
     setActivePinia(createPinia());
     signupMock.mockReset();
     fetchServerConfigMock.mockReset().mockResolvedValue(null);
-    refreshAbilitiesMock.mockReset().mockResolvedValue();
+    tokenMock.mockReset().mockResolvedValue();
     resendVerificationMock.mockReset().mockResolvedValue();
     verifyInviteMock.mockReset().mockResolvedValue({ valid: false, email: null });
     createOrganizationMock.mockReset();
@@ -343,7 +343,7 @@ describe('auth.signup.view', () => {
 
       await wrapper.vm.proceedToApp();
 
-      expect(refreshAbilitiesMock).toHaveBeenCalled();
+      expect(tokenMock).toHaveBeenCalled();
       expect(wrapper.vm.$router.push).toHaveBeenCalledWith('/tasks');
     });
 
@@ -423,7 +423,7 @@ describe('auth.signup.view', () => {
       await wrapper.vm.proceedToApp();
       await flushPromises();
 
-      expect(refreshAbilitiesMock).toHaveBeenCalled();
+      expect(tokenMock).toHaveBeenCalled();
       // useAuthStore mock has currentOrganization undefined → proceedToApp checks authStore.user.currentOrganization;
       // since orgs.enabled is true AND user has no currentOrganization, it goes to /organization-required, NOT redirect.
       // For this test, we assert the redirect-honor branch fires when user DOES have an org.

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

@@ -4,11 +4,11 @@ import { createPinia, setActivePinia } from 'pinia';
 import { createVuetify } from 'vuetify';
 
 const verifyEmailMock = vi.hoisted(() => vi.fn());
-const refreshAbilitiesMock = vi.hoisted(() => vi.fn().mockResolvedValue());
+const tokenMock = vi.hoisted(() => vi.fn().mockResolvedValue());
 const fetchServerConfigMock = vi.hoisted(() => vi.fn().mockResolvedValue(null));
 const storeMock = vi.hoisted(() => ({
   verifyEmail: verifyEmailMock,
-  refreshAbilities: refreshAbilitiesMock,
+  token: tokenMock,
   fetchServerConfig: fetchServerConfigMock,
   isLoggedIn: false,
   user: null,
@@ -48,7 +48,7 @@ describe('auth.verifyEmail.view', () => {
   beforeEach(() => {
     setActivePinia(createPinia());
     verifyEmailMock.mockReset();
-    refreshAbilitiesMock.mockReset().mockResolvedValue();
+    tokenMock.mockReset().mockResolvedValue();
     fetchServerConfigMock.mockReset().mockResolvedValue(null);
     storeMock.isLoggedIn = false;
     storeMock.user = null;

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

@@ -395,12 +395,14 @@ export default {
     },
     /**
      * @desc Navigate to the main application after signup and org setup.
-     * @returns {void}
+     * @returns {Promise<void>}
      */
     async proceedToApp() {
-      // Refresh token/abilities after org setup to pick up new org context
+      // Soft-refresh (token(), never throws) to pick up the new org context.
+      // refreshAbilities() signs out + rethrows on any failure — at this final
+      // onboarding click a transient error would silently eject a brand-new user.
       const authStore = useAuthStore();
-      await authStore.refreshAbilities();
+      await authStore.token();
       // If user has no org yet (pending join), go to organization-required page
       if (!authStore.user?.currentOrganization && this.serverConfig?.organizations?.enabled) {
         this.$router.push('/organization-required');

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

@@ -103,13 +103,10 @@ export default {
      */
     async handlePostVerificationRedirect(authStore) {
       if (authStore.isLoggedIn) {
-        // Refresh user data to pick up emailVerified = true
-        try {
-          await authStore.refreshAbilities();
-        } catch {
-          // If refresh fails (e.g. expired token), stay on page
-          return;
-        }
+        // Soft-refresh (token(), never throws) to pick up emailVerified = true.
+        // refreshAbilities() signs out + rethrows on failure, which would eject
+        // the user who just verified their email.
+        await authStore.token();
         this.redirecting = true;
         const serverConfig = authStore.serverConfig || (await authStore.fetchServerConfig());
         if (!authStore.user?.currentOrganization && serverConfig?.organizations?.enabled) {

src/modules/organizations/tests/organization.create.view.unit.tests.js

@@ -3,9 +3,9 @@ import { mount, flushPromises } from '@vue/test-utils';
 import { createPinia, setActivePinia } from 'pinia';
 import { createVuetify } from 'vuetify';
 
-const refreshAbilitiesMock = vi.hoisted(() => vi.fn().mockResolvedValue());
+const tokenMock = vi.hoisted(() => vi.fn().mockResolvedValue());
 const createOrganizationMock = vi.hoisted(() => vi.fn().mockResolvedValue({ id: 'org-9' }));
-const authStoreMock = vi.hoisted(() => ({ user: null, refreshAbilities: refreshAbilitiesMock }));
+const authStoreMock = vi.hoisted(() => ({ user: null, token: tokenMock }));
 
 vi.mock('../../auth/stores/auth.store', () => ({
   useAuthStore: () => authStoreMock,
@@ -50,7 +50,7 @@ describe('organization.create.view — first-org redirect (#4422)', () => {
   beforeEach(() => {
     setActivePinia(createPinia());
     push.mockReset();
-    refreshAbilitiesMock.mockReset().mockResolvedValue();
+    tokenMock.mockReset().mockResolvedValue();
     createOrganizationMock.mockReset().mockResolvedValue({ id: 'org-9' });
     authStoreMock.user = null;
   });
@@ -62,7 +62,7 @@ describe('organization.create.view — first-org redirect (#4422)', () => {
     await wrapper.vm.create();
     await flushPromises();
     expect(createOrganizationMock).toHaveBeenCalledWith({ name: 'Acme', description: '' });
-    expect(refreshAbilitiesMock).toHaveBeenCalled();
+    expect(tokenMock).toHaveBeenCalled();
     expect(push).toHaveBeenCalledWith('/tasks');
   });
 

src/modules/organizations/views/organization.create.view.vue

@@ -64,6 +64,12 @@ export default {
     };
   },
   methods: {
+    /**
+     * @desc Validate the form and create the organization, then route the user:
+     *       a first org (no current org yet) lands in the app via sign.route; an
+     *       additional org created while one is active goes to its detail page.
+     * @returns {Promise<void>}
+     */
     async create() {
       if (this.loading) return;
       const form = await this.$refs.form.validate();
@@ -83,7 +89,10 @@ export default {
             description: this.description,
           });
           if (org) {
-            await authStore.refreshAbilities();
+            // Soft-refresh (token(), never throws) to pick up the new org context.
+            // refreshAbilities() signs out + rethrows on failure, which would eject
+            // a user who just created their org.
+            await authStore.token();
             this.$router.push(
               isFirstOrg ? this.config.sign.route : `/users/organizations/${org.id || org._id}`,
             );

src/modules/organizations/views/organizations.required.view.vue

@@ -249,21 +249,36 @@ export default {
         this.acceptingId = null;
       }
     },
+    /**
+     * @desc Soft-refresh the session ("Check status") and, if the user now has an
+     *       organization, forward them into the app.
+     * @returns {Promise<void>}
+     */
     async refresh() {
       const authStore = useAuthStore();
-      await authStore.refreshAbilities();
+      // Soft-refresh (token(), never throws) — refreshAbilities() signs out +
+      // rethrows on failure, so a hiccup on "Check status" would eject the user.
+      await authStore.token();
       if (authStore.user?.currentOrganization) {
         this.$router.push(this.config.sign.route);
       }
     },
+    /**
+     * @desc Send a join request for the given organization, then soft-refresh the
+     *       session so any resulting membership/pending state is reflected.
+     * @param {Object} org - The organization to request to join.
+     * @returns {Promise<void>}
+     */
     async requestToJoin(org) {
       const orgId = org.id || org._id;
       this.requestingOrgId = orgId;
       const organizationsStore = useOrganizationsStore();
       try {
         await organizationsStore.createJoinRequest(orgId);
         const authStore = useAuthStore();
-        await authStore.refreshAbilities();
+        // Soft-refresh (token(), never throws). refreshAbilities() would sign the
+        // user out before this try/catch could swallow the throw.
+        await authStore.token();
       } catch {
         // interceptor handles snackbar
       } finally {