feat: enhance login attempt handling with translation support and failed attempts tracking

AdminForth/1817/login-captcha-plugin-does-not-

Author: yaroslav8765

adminforth/documentation/docs/tutorial/03-Customization/08-pageInjections.md

@@ -235,6 +235,26 @@ Now create file `CustomLoginHeader.vue` in the `custom` folder of your project:
 
 
 
+### Reacting to rejected login attempts
+
+Components injected into `underInputs` and `underLoginButton` get a `failedLoginAttempts` prop, which is incremented every time
+the login endpoint answers with an error. Use it when your injection has to be refreshed for the next attempt, e.g. a captcha widget
+has to issue a new token. Such injections can also disable the login button until they are ready, by emitting `update:disableLoginButton`:
+
+```html title="./custom/CustomLoginFooter.vue"
+<script setup lang="ts">
+import { watch } from 'vue';
+
+const props = defineProps<{ failedLoginAttempts?: number }>();
+const emit = defineEmits(['update:disableLoginButton']);
+
+watch(() => props.failedLoginAttempts, () => {
+  emit('update:disableLoginButton', true);
+  // prepare the injection for the next attempt, then enable the button back
+});
+</script>
+```
+
 ## List view page injections shrinking: thin enough to shrink?
 
 

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

@@ -308,9 +308,9 @@ export const admin = new AdminForth({
 
   auth: {
     beforeLoginAttempt: [
-      async ({ username, adminforth, extra }) => {
+      async ({ username, adminforth, extra, tr }) => {
         if (!await captchaIsValid(extra)) {
-          return { ok: false, error: "Captcha verification failed" };
+          return { ok: false, error: await tr("Captcha verification failed", "errors") };
         }
         return { ok: true };
       }

adminforth/documentation/docs/tutorial/09-Plugins/19-login-captcha.md

@@ -48,7 +48,7 @@ plugins: [
 
 ## Preventing token reuse
 
-A captcha token stays valid at the provider for a short period, which means the same token could be replayed for several logins. To prevent this, pass an optional [key-value adapter](/docs/tutorial/Adapters/key-value-adapters) via `keyValueAdapter`. Each token is recorded once it has been used for a successful login, and any later attempt with the same token is rejected.
+A captcha token stays valid at the provider for a short period, which means the same token could be replayed for several login attempts. To prevent this, pass an optional [key-value adapter](/docs/tutorial/Adapters/key-value-adapters) via `keyValueAdapter`. Each token is recorded once it has been used for a login attempt, and any later attempt with the same token is rejected.
 
 ```bash
 pnpm add @adminforth/key-value-adapter-ram
@@ -68,9 +68,9 @@ plugins: [
         siteKey: "YOUR_SITE_KEY", // Replace with your site key
         secretKey: "YOUR_SECRET_KEY", // Replace with your secret key
       }),
-      // Store used tokens to prevent them from being replayed
+      // Store spent tokens to prevent them from being replayed
       keyValueAdapter: new RamKeyValueAdapter(),
-      // Optional: how long (in seconds) a used token is remembered. Should be at least as long
+      // Optional: how long (in seconds) a spent token is remembered. Should be at least as long
       // as the captcha provider keeps the token valid. Defaults to 300 (5 minutes).
       tokenTimeToLiveSeconds: 300,
     }),

adminforth/modules/restApi.ts

@@ -9,6 +9,7 @@ import {
   AfterDataSourceResponseFunction,
   BeforeDataSourceRequestFunction,
   IAdminForthEndpointHandlerInput,
+  ITranslateFunction,
   IAdminForthRestAPI,
   IAdminForthSort,
   HttpExtra,
@@ -737,11 +738,11 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
   /**
    * Runs beforeLoginAttempt hooks. Returns error to answer with, or null if login attempt is allowed to proceed.
    */
-  async processBeforeLoginAttempt(username: string, extra: HttpExtra): Promise<{ error: string } | null> {
+  async processBeforeLoginAttempt(username: string, extra: HttpExtra, tr: ITranslateFunction): Promise<{ error: string } | null> {
     const beforeLoginAttempt = this.adminforth.config.auth.beforeLoginAttempt as (BeforeLoginAttemptFunction[] | undefined);
 
     for (const hook of listify(beforeLoginAttempt)) {
-      const hookRespError = hookResponseError(await hook({ username, adminforth: this.adminforth, extra }), 'beforeLoginAttempt');
+      const hookRespError = hookResponseError(await hook({ username, adminforth: this.adminforth, extra, tr }), 'beforeLoginAttempt');
       if (hookRespError) {
         return hookRespError;
       }
@@ -811,7 +812,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         // for existing and non-existing users (e.g. captcha check should not leak valid credentials)
         const loginAttemptError = await this.processBeforeLoginAttempt(normalizedUsername, {
           body, headers, query, cookies, requestUrl, response
-        });
+        }, tr);
         if (loginAttemptError) {
           response.setStatus(401);
           return loginAttemptError;

adminforth/spa/src/views/LoginView.vue

@@ -97,6 +97,7 @@
                           :key="`under-inputs-${index}`"
                           :is="getCustomComponent(formatComponent(c))"
                           :meta="formatComponent(c).meta"
+                          :failedLoginAttempts="failedLoginAttempts"
                           @update:disableLoginButton="setDisableLoginButton($event)"
                         />
 
@@ -117,6 +118,7 @@
                           :key="`under-login-button-${index}`"
                           :is="getCustomComponent(formatComponent(c))"
                           :meta="formatComponent(c).meta"
+                          :failedLoginAttempts="failedLoginAttempts"
                           @update:disableLoginButton="setDisableLoginButton($event)"
                           @update:oauthRedirecting="oauthRedirecting = $event"
                         />
@@ -161,6 +163,8 @@ const showPw = ref(false);
 
 const error = ref(null);
 const disableLoginButton = ref(false);
+// login page injections (e.g. captcha widget) use it to know that attempt was rejected and they have to refresh themselves
+const failedLoginAttempts = ref(0);
 
 const backgroundPosition = computed(() => {
   return coreStore.config?.loginBackgroundPosition || '1/2';
@@ -194,6 +198,7 @@ async function login() {
   });
   if (resp.error) {
       error.value = resp.error;
+      failedLoginAttempts.value++;
   } else if (resp.redirectTo) {
     error.value = null;
     isSuccess.value = true;

adminforth/types/Back.ts

@@ -1285,6 +1285,10 @@ export type BeforeLoginAttemptFunction = (params: {
    * Extra HTTP information of login request. Use extra.response to set custom status or headers.
    */
   extra: HttpExtra,
+  /**
+   * Translate function, respects language of login request.
+   */
+  tr: ITranslateFunction,
 }) => Promise<{ ok: boolean, error?: string }>;
 
 /**

tests/jest_tests/login_attempt_hook.test.ts

@@ -2,7 +2,7 @@ import { jest } from '@jest/globals';
 import request from 'supertest';
 import { admin, app, closeApplication } from './authTestApp';
 
-type LoginAttemptHook = (params: { username: string, adminforth: any, extra: any }) => Promise<{ ok: boolean, error?: string }>;
+type LoginAttemptHook = (params: { username: string, adminforth: any, extra: any, tr: any }) => Promise<{ ok: boolean, error?: string }>;
 
 const hooks = admin.config.auth.beforeLoginAttempt as LoginAttemptHook[];
 
@@ -45,10 +45,10 @@ describe('auth.beforeLoginAttempt', () => {
     getData.mockRestore();
   });
 
-  it('receives normalized username and request data', async () => {
-    const calls: { username: string, headers: Record<string, string> }[] = [];
-    hooks.push(async ({ username, extra }) => {
-      calls.push({ username, headers: extra.headers });
+  it('receives normalized username, request data and translate function', async () => {
+    const calls: { username: string, headers: Record<string, string>, translated: string }[] = [];
+    hooks.push(async ({ username, extra, tr }) => {
+      calls.push({ username, headers: extra.headers, translated: await tr('Captcha verification failed', 'errors') });
       return { ok: true };
     });
 
@@ -62,6 +62,7 @@ describe('auth.beforeLoginAttempt', () => {
     expect(calls).toHaveLength(1);
     expect(calls[0].username).toEqual('adminforth');
     expect(calls[0].headers['x-captcha-token']).toEqual('token');
+    expect(calls[0].translated).toEqual('Captcha verification failed');
   });
 
   it('stops on first rejecting hook and lets login pass when all hooks allow it', async () => {