feat(auth): add POST /api/auth/signout to clear TOKEN cookie (#3508)

* feat(auth): add POST /api/auth/signout endpoint to clear TOKEN cookie

Before: signout was client-side only — the Vue client dropped its in-memory
user state but the httpOnly TOKEN cookie stayed in the browser and the
user was silently re-logged in on the next /api/auth/token call.

Now: POST /api/auth/signout clears the cookie server-side with options
(httpOnly, secure, sameSite) mirroring tokenCookieOptions so the browser
actually discards it. No JWT middleware — works even if the token is
expired, invalid, or missing. Rate-limited via authLimiter.

Integration tests cover:
- 200 + success body without prior JWT
- Set-Cookie header with Max-Age=0/Expires-in-past + HttpOnly
- Follow-up /api/auth/token returns 401 on the same agent (cookie killed)

Closes #3502

* style(auth): use block-body arrow for signout handler

Codacy's shell-syntax rule SC2288 mis-fires on the chained arrow
expression-body (`res.status().clearCookie().json()`) and flags it as
"Non-serializable expression must be wrapped with $(...)" — a false
positive for JS but still shows up as ACTION_REQUIRED on the PR.

Split the chain across two explicit statements inside a block body to
dodge the parser confusion. Purely cosmetic — same 200 response, same
Set-Cookie header (expired TOKEN with HttpOnly/secure/sameSite from
tokenCookieOptions). Integration tests unchanged and still pass.

* test(auth): add signout controller unit test to satisfy codecov/patch threshold

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -4,6 +4,38 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## Auth signout endpoint (2026-04-23)
+
+New `POST /api/auth/signout` endpoint that clears the httpOnly `TOKEN` cookie on the client.
+
+### Why
+
+Before: signout was purely client-side — the Vue client dropped its in-memory user state but the httpOnly `TOKEN` cookie remained in the browser. On the next page load the cookie was replayed to `/api/auth/token`, the user was silently re-logged in, and the signout button was effectively a no-op.
+
+Now: the route calls `res.clearCookie('TOKEN', { httpOnly, secure, sameSite })` with options mirroring `tokenCookieOptions`. Browsers only delete cookies whose `secure`/`sameSite`/`path`/`domain` attributes match the original `Set-Cookie`, so the options must match exactly.
+
+### Contract
+
+- `POST /api/auth/signout` → `200 { type: 'success', message: 'Signed out' }`
+- `Set-Cookie: TOKEN=; Max-Age=0; HttpOnly; …` (expired cookie — browser discards it)
+- No JWT middleware: signout works even if the token is expired, invalid, or missing
+- Rate-limited via the standard `authLimiter`
+
+### Non-breaking
+
+Additive endpoint. No existing contract changes. Downstream projects can adopt it at their own pace:
+
+- Vue: call `POST /api/auth/signout` from the signout action, then clear the Vuex/Pinia user state
+- No env var changes
+- No Mongo migration
+
+### Action for downstream
+
+1. Run `/update-stack` to pull the endpoint.
+2. (Vue side, separately) wire the signout action to call `POST /api/auth/signout` before resetting client state.
+
+---
+
 ## OAuth account linking + Express 5 callback fix (2026-04-23)
 
 Two related auth fixes that ship together.

modules/auth/controllers/auth.controller.js

@@ -474,6 +474,21 @@ const oauthCallback = async (req, res, next) => {
   })(req, res, next);
 };
 
+/**
+ * @desc Endpoint to clear the JWT TOKEN cookie on the client.
+ * No JWT middleware is required — signout must work even when the token is
+ * expired, invalid, or missing. clearCookie options mirror tokenCookieOptions
+ * because browsers only delete cookies whose secure/sameSite/path attributes
+ * match the Set-Cookie used at login.
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {void} Sends a 200 JSON response and clears the TOKEN cookie
+ */
+const signout = (req, res) => {
+  res.clearCookie('TOKEN', tokenCookieOptions);
+  return res.status(200).json({ type: 'success', message: 'Signed out' });
+};
+
 /**
  * @desc Endpoint to expose public auth configuration (sign flags and organizations settings)
  * @param {Object} req - Express request object
@@ -567,6 +582,7 @@ export default {
   signup,
   signinAuthenticate,
   signin,
+  signout,
   token,
   oauthCall,
   oauthCallback,

modules/auth/routes/auth.routes.js

@@ -41,6 +41,9 @@ export default (app) => {
   // Setting up the users authentication api
   app.route('/api/auth/signup').post(authLimiter, model.isValid(UsersSchema.User), auth.signup);
   app.route('/api/auth/signin').post(authLimiter, auth.signinAuthenticate, auth.signin);
+  // Signout: intentionally no JWT middleware — must clear the cookie even if the
+  // token is expired/invalid/missing so the client cannot get silently re-logged in.
+  app.route('/api/auth/signout').post(authLimiter, auth.signout);
 
   // Email verification
   app.route('/api/auth/verify-email/:token').post(authLimiter, auth.verifyEmail);

modules/auth/tests/auth.integration.tests.js

@@ -18,6 +18,7 @@ import logger from '../../../lib/services/logger.js';
 describe('Auth integration tests:', () => {
   let UserService = null;
   let AuthService = null;
+  let app; // Express app instance for fresh agents inside Signout block (#3502)
   let agent;
   let credentials;
   let user;
@@ -31,7 +32,8 @@ describe('Auth integration tests:', () => {
       const init = await bootstrap();
       UserService = (await import(path.resolve('./modules/users/services/users.service.js'))).default;
       AuthService = (await import(path.resolve('./modules/auth/services/auth.service.js'))).default;
-      agent = request.agent(init.app);
+      app = init.app;
+      agent = request.agent(app);
     } catch (err) {
       console.log(err);
       expect(err).toBeFalsy();
@@ -1225,6 +1227,71 @@ describe('Auth integration tests:', () => {
     });
   });
 
+  describe('Signout', () => {
+    const outEmail = 'signout@test.com';
+    const outPassword = 'W@os.jsI$Aw3$0m3';
+    let outUser;
+
+    beforeEach(async () => {
+      // Clean up stale user from previous runs on shared databases
+      try {
+        const existing = await UserService.getBrut({ email: outEmail });
+        if (existing) await UserService.remove(existing);
+      } catch (_) { /* cleanup – ignore errors */ }
+      try {
+        const signoutAgent = request.agent(app);
+        const result = await signoutAgent.post('/api/auth/signup').send({
+          firstName: 'Signout',
+          lastName: 'Test',
+          email: outEmail,
+          password: outPassword,
+          provider: 'local',
+        }).expect(200);
+        outUser = result.body.user;
+      } catch (err) {
+        console.log(err);
+        expect(err).toBeFalsy();
+      }
+    });
+
+    test('should return 200 with success message even without prior JWT cookie', async () => {
+      const result = await request(app).post('/api/auth/signout').expect(200);
+      expect(result.body.type).toBe('success');
+      expect(result.body.message).toBe('Signed out');
+    });
+
+    test('should set an expired TOKEN cookie so the browser discards it', async () => {
+      const result = await request(app).post('/api/auth/signout').expect(200);
+      const tokenCookie = result.headers['set-cookie']?.find((c) => c.startsWith('TOKEN='));
+      expect(tokenCookie).toBeDefined();
+      // Cleared cookie: value is empty and either Max-Age=0 or Expires is in the past
+      expect(tokenCookie).toMatch(/^TOKEN=;/);
+      const hasMaxAgeZero = /Max-Age=0/i.test(tokenCookie);
+      const expiresMatch = tokenCookie.match(/Expires=([^;]+)/i);
+      const expiresInPast = expiresMatch ? new Date(expiresMatch[1]).getTime() < Date.now() : false;
+      expect(hasMaxAgeZero || expiresInPast).toBe(true);
+      // Must mirror login cookie attributes (httpOnly) so the browser deletes it
+      expect(tokenCookie).toMatch(/HttpOnly/i);
+    });
+
+    test('should invalidate the session so subsequent JWT-guarded calls return 401', async () => {
+      // Use a dedicated agent with a clean cookie jar so the signin cookie is the only state
+      const signoutAgent = request.agent(app);
+      await signoutAgent.post('/api/auth/signin').send({ email: outEmail, password: outPassword }).expect(200);
+      // Cookie present → token endpoint works
+      await signoutAgent.get('/api/auth/token').expect(200);
+      // Signout clears the cookie on the agent's jar
+      await signoutAgent.post('/api/auth/signout').expect(200);
+      // Next JWT-guarded call with the same agent must be 401 (cookie gone)
+      await signoutAgent.get('/api/auth/token').expect(401);
+    });
+
+    afterEach(async () => {
+      try { if (outUser) await UserService.remove(outUser); } catch (_) { /* cleanup */ }
+      outUser = null;
+    });
+  });
+
   describe('Error paths', () => {
     test('should redirect to invalid when validateResetToken getBrut throws', async () => {
       jest.spyOn(UserService, 'getBrut').mockRejectedValueOnce(new Error('DB error'));

modules/auth/tests/auth.signout.controller.unit.tests.js

@@ -0,0 +1,94 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+describe('auth.controller signout:', () => {
+  beforeEach(() => {
+    jest.resetModules();
+
+    jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+      default: { warn: jest.fn(), error: jest.fn(), info: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../config/index.js', () => ({
+      default: {
+        sign: { up: true, in: true },
+        jwt: { secret: 's', expiresIn: 3600 },
+        cookie: { secure: true, sameSite: 'lax' },
+        organizations: { enabled: false },
+        app: { title: 'Test', contact: 'a@b.com' },
+      },
+    }));
+    jest.unstable_mockModule('../../../modules/users/services/users.service.js', () => ({
+      default: { create: jest.fn(), getBrut: jest.fn(), update: jest.fn(), remove: jest.fn(), search: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../modules/users/repositories/users.repository.js', () => ({
+      default: { update: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../modules/organizations/services/organizations.service.js', () => ({
+      default: { handleSignupOrganization: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../modules/organizations/services/organizations.crud.service.js', () => ({
+      default: { autoSetCurrentOrganization: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../modules/organizations/services/organizations.membership.service.js', () => ({
+      default: { findByUserAndOrganization: jest.fn(), listPendingByUser: jest.fn().mockResolvedValue([]) },
+    }));
+    jest.unstable_mockModule('../../../modules/users/models/users.schema.js', () => ({
+      default: { User: {} },
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/model.js', () => ({
+      default: { getResultFromZod: jest.fn(), checkError: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/policy.js', () => ({
+      default: { defineAbilityFor: jest.fn().mockResolvedValue({}) },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/mailer/index.js', () => ({
+      default: { isConfigured: jest.fn().mockReturnValue(false), sendMail: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/responses.js', () => ({
+      default: {
+        success: jest.fn().mockReturnValue(jest.fn()),
+        error: jest.fn().mockReturnValue(jest.fn()),
+      },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/errors.js', () => ({
+      default: { getMessage: jest.fn().mockReturnValue('error') },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/AppError.js', () => ({
+      default: class AppError extends Error {
+        constructor(msg, opts) {
+          super(msg);
+          this.code = opts?.code;
+          this.details = opts?.details;
+        }
+      },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/abilities.js', () => ({
+      default: jest.fn().mockReturnValue([]),
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/getBaseUrl.js', () => ({
+      default: jest.fn().mockReturnValue('http://localhost:3000'),
+    }));
+    jest.unstable_mockModule('../../../lib/services/analytics.js', () => ({
+      default: { identify: jest.fn(), groupIdentify: jest.fn() },
+    }));
+  });
+
+  test('clears TOKEN cookie with options mirroring tokenCookieOptions and returns success', async () => {
+    const { default: AuthController } = await import('../../../modules/auth/controllers/auth.controller.js');
+
+    const cleared = [];
+    const res = {
+      clearCookie: (name, opts) => { cleared.push({ name, opts }); return res; },
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    };
+
+    AuthController.signout({}, res);
+
+    expect(cleared).toEqual([{ name: 'TOKEN', opts: { httpOnly: true, secure: true, sameSite: 'lax' } }]);
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ type: 'success', message: 'Signed out' });
+  });
+});