feat: add before logout hook

AdminForth/1900/image

Author: yaroslav8765

adminforth/documentation/docs/tutorial/03-Customization/12-security.md

@@ -328,6 +328,28 @@ non-existing users, so an attacker can't use it to find out whether credentials
 
 If your check needs the user record itself (like two-factor authentication does), use [auth.beforeLoginConfirmation](/docs/api/Back/type-aliases/BeforeLoginConfirmationFunction) instead: it is called after credentials are verified.
 
+## Doing cleanup on logout
+
+`auth.beforeLogout` hooks are called when user logs out, before AdminForth removes auth cookie:
+
+```ts title="./index.ts"
+export const admin = new AdminForth({
+
+  ...
+
+  auth: {
+    beforeLogout: [
+      async ({ adminUser, adminforth, extra }) => {
+        await revokeExternalSession(adminUser.pk);
+      }
+    ]
+  }
+
+  ...
+
+})
+```
+
 ## Custom user authorization hook
 
 Default user authorization checks that cookie with JWT token is valid, signed and not expired. 

adminforth/modules/configValidator.ts

@@ -1276,6 +1276,18 @@ export default class ConfigValidator implements IConfigValidator {
         newConfig.auth.beforeLoginConfirmation = blc;
       }
 
+      // normalize beforeLogout hooks
+      const blo = this.inputConfig.auth.beforeLogout;
+      if (!Array.isArray(blo)) {
+        if (blo) {
+          newConfig.auth.beforeLogout = [blo];
+        } else {
+          newConfig.auth.beforeLogout = [];
+        }
+      } else {
+        newConfig.auth.beforeLogout = blo;
+      }
+
       // normalize adminUserAuthorize hooks
       const aua = this.inputConfig.auth.adminUserAuthorize;
       if (!Array.isArray(aua)) {

adminforth/modules/restApi.ts

@@ -3,6 +3,7 @@ import {
   type IHttpServer,
   BeforeLoginAttemptFunction,
   BeforeLoginConfirmationFunction,
+  BeforeLogoutFunction,
   AdminForthResource,
   AllowedActionValue,
   AllowedActions,
@@ -773,6 +774,17 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
     }
   }
 
+  /**
+   * Runs beforeLogout hooks. Hooks can't block logout, they are called for cleanup and logging only.
+   */
+  async processBeforeLogout(adminUser: AdminUser | null, extra: HttpExtra, tr: ITranslateFunction) {
+    const beforeLogout = this.adminforth.config.auth.beforeLogout as (BeforeLogoutFunction[] | undefined);
+
+    for (const hook of listify(beforeLogout)) {
+      await hook({ adminUser, adminforth: this.adminforth, extra, tr });
+    }
+  }
+
   checkAbortSignal(abortSignal: AbortSignal): boolean {
     if (abortSignal.aborted) {
       return true;
@@ -896,7 +908,15 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         noAuth: true,
         method: 'POST',
         path: '/logout',
-        handler: async ({ response }) => {
+        handler: async ({ body, headers, query, cookies, requestUrl, response, tr }) => {
+          // endpoint is noAuth (expired session should be able to log out as well), so user is resolved here
+          const jwt = this.adminforth.auth.getAuthCookie(cookies);
+          const adminUser = jwt ? await this.adminforth.auth.verify(jwt, 'auth') as AdminUser | null : null;
+
+          await this.processBeforeLogout(adminUser, {
+            body, headers, query, cookies, requestUrl, response
+          }, tr);
+
           this.adminforth.auth.removeAuthCookie( response );
           return { ok: true };
         },

adminforth/types/Back.ts

@@ -1328,6 +1328,30 @@ export type BeforeLoginAttemptFunction = (params: {
   tr: ITranslateFunction,
 }) => Promise<{ ok: boolean, error?: string }>;
 
+/**
+ * Called when user logs out, before AdminForth removes auth cookie.
+ * Useful for cleanup of things issued for the session (e.g. revoking tokens on external identity provider,
+ * removing custom cookies set by plugins) or for logging logout event.
+ */
+export type BeforeLogoutFunction = (params: {
+  /**
+   * User which is logging out. Is `null` when session was already expired or invalid at the moment of logout.
+   */
+  adminUser: AdminUser | null,
+  /**
+   * Adminforth instance.
+   */
+  adminforth: IAdminForth,
+  /**
+   * Extra HTTP information of logout request. Use extra.response to set custom status, headers or cookies.
+   */
+  extra: HttpExtra,
+  /**
+   * Translate function, respects language of logout request.
+   */
+  tr: ITranslateFunction,
+}) => Promise<void>;
+
 /**
  * Allow to make extra authorization
  */
@@ -1835,6 +1859,20 @@ export interface AdminForthInputConfig {
        */
       beforeLoginConfirmation?: BeforeLoginConfirmationFunction | Array<BeforeLoginConfirmationFunction>,
 
+      /**
+       * Function or functions which will be called when user logs out, before AdminForth removes auth cookie.
+       * Logout is never blocked by these hooks, so use them for cleanup or logging.
+       *
+       * Example:
+       *
+       * ```ts
+       * beforeLogout: async ({ adminUser, adminforth }) => {
+       *   await revokeExternalSession(adminUser.pk);
+       * },
+       * ```
+       */
+      beforeLogout?: BeforeLogoutFunction | Array<BeforeLogoutFunction>,
+
       /**
        * Array of functions which will be called before any request to AdminForth API.
        */

tests/jest_tests/logout_hook.test.ts

@@ -0,0 +1,73 @@
+import request from 'supertest';
+import { admin, app, closeApplication } from './authTestApp';
+
+type LogoutHook = (params: { adminUser: any, adminforth: any, extra: any, tr: any }) => Promise<void>;
+
+const hooks = admin.config.auth.beforeLogout as LogoutHook[];
+
+const logout = (cookie?: string) => {
+  const req = request(app).post('/adminapi/v1/logout');
+  return (cookie ? req.set("Cookie", cookie) : req).send({});
+};
+
+const loginCookie = async (): Promise<string> => {
+  const res = await request(app).post('/adminapi/v1/login').send({ username: 'adminforth', password: 'adminforth' });
+  return res.headers['set-cookie'][0].split(';')[0];
+};
+
+afterAll(async () => {
+  await closeApplication();
+});
+
+afterEach(() => {
+  hooks.length = 0;
+});
+
+describe('auth.beforeLogout', () => {
+  it('receives logged in user, request data and translate function', async () => {
+    const calls: { username: string, headers: Record<string, string>, translated: string }[] = [];
+    hooks.push(async ({ adminUser, extra, tr }) => {
+      calls.push({
+        username: adminUser.username,
+        headers: extra.headers,
+        translated: await tr('Invalid username or password', 'errors'),
+      });
+    });
+
+    const res = await logout(await loginCookie()).set('x-some-header', 'value');
+
+    expect(res.status).toEqual(200);
+    expect(res.body).toEqual({ ok: true });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].username).toEqual('adminforth');
+    expect(calls[0].headers['x-some-header']).toEqual('value');
+    expect(calls[0].translated).toEqual('Invalid username or password');
+  });
+
+  it('is called before auth cookie is removed and does not block logout', async () => {
+    const called: string[] = [];
+    hooks.push(
+      async () => { called.push('first'); },
+      async () => { called.push('second'); },
+    );
+
+    const res = await logout(await loginCookie());
+
+    expect(res.status).toEqual(200);
+    expect(called).toEqual(['first', 'second']);
+    expect(res.headers['set-cookie'][0]).toContain('adminforth_');
+    expect(res.headers['set-cookie'][0]).toContain('Expires=Thu, 01 Jan 1970 00:00:00 GMT');
+  });
+
+  it('passes null user when session is missing or invalid', async () => {
+    const users: (any | null)[] = [];
+    hooks.push(async ({ adminUser }) => { users.push(adminUser); });
+
+    const withoutCookie = await logout();
+    const withBrokenCookie = await logout(`adminforth_${admin.config.customization.brandNameSlug}_jwt=not-a-jwt`);
+
+    expect(withoutCookie.status).toEqual(200);
+    expect(withBrokenCookie.status).toEqual(200);
+    expect(users).toEqual([null, null]);
+  });
+});