Merge branch 'main' of github.com:devforth/adminforth into next

AdminForth/1731/security-audit

AdminForth/1731/security-audit

Author: yaroslav8765

adminforth/commands/createApp/templates/.env.prod.hbs

@@ -1,4 +1,7 @@
 # Add only non-sensitive production environment variables here so deployed applications can use them
 # Deliver sensitive production environment variables via your deployment platform's process environment
 
-NODE_ENV=production
+NODE_ENV=production
+DEBUG_LEVEL=info
+AF_DEBUG_LEVEL=info
+DB_DEBUG_LEVEL=info

adminforth/commands/createApp/templates/index.ts.hbs

@@ -16,6 +16,7 @@ export const admin = new AdminForth({
     usernameField: 'email',
     passwordHashField: 'password_hash',
     rememberMeDuration: '30d', 
+    rateLimit: ['500/5m', '5000/1h', '10000/1d'],
     loginBackgroundImage: 'https://images.unsplash.com/photo-1534239697798-120952b76f2b?q=80&w=3389&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
     loginBackgroundPosition: '1/2',
     loginPromptHTML: async () => { 

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

@@ -30,6 +30,31 @@ new AdminForth({
 In this case users who will check "Remember me" checkbox will be logged in for 7 days instead of 24 hours.
 
 
+## Login rate limits
+
+AdminForth rate-limits login attempts by client IP using `auth.rateLimit`. Password login, OAuth login, and passkey login use the same configured limits, but each login method has its own independent rate-limit bucket.
+
+By default AdminForth uses:
+
+```ts
+['500/5m', '5000/1h', '10000/1d']
+```
+
+You can override it in the app config:
+
+```ts ./index.ts
+new AdminForth({
+  ...
+  auth: {
+    rateLimit: ['10/5m', '100/1h', '500/1d']
+  }
+})
+```
+
+The format is `requests/period`, where period can use `s`, `m`, `h`, or `d`.
+Because rate limits are keyed by client IP, configure `auth.clientIpHeader` when AdminForth runs behind a trusted CDN or reverse proxy. See [Trusting client IP addresses](#trusting-client-ip-addresses).
+
+
 ## Password strength
 
 AdminForth allows to set validation RegExp based rules for any field. This can be reused for password strength validation.
@@ -284,4 +309,4 @@ This means that a user is allowed to make up to 20 requests within one day, and
 - h → hours (1h)
 - d → days (1d)
 
-> ☝ Сonsume(key) is used to check whether a specific key such as a userId, IP address, or any other identifier has exceeded its allowed request limit. If the limit has not been reached, it returns true, meaning the request is allowed to proceed.
+> ☝ Сonsume(key) is used to check whether a specific key such as a userId, IP address, or any other identifier has exceeded its allowed request limit. If the limit has not been reached, it returns true, meaning the request is allowed to proceed.

adminforth/documentation/docs/tutorial/06-Adapters/04-storage-adapters.md

@@ -56,8 +56,9 @@ R2_BUCKET_REGION=auto
     region: process.env.R2_BUCKET_REGION as string,
     s3ACL: "private",
     cleanupKeyValueAdapter: new LevelDBKeyValueAdapter({
-      dbPath: './stores/cloudflare_r2_storage_keys',
-    }),
+      // ensure /stores/ folder is a persisted/backed up point, if you running in docker ensure ensure you mount /stores/ as volume
+      dbPath: process.env.NODE_ENV === production ? '/stores/cloudflare_r2_storage_keys' : './cloudflare_r2_storage_keys',
+    });,
     forcePathStyle: true,
     cleanupCheckInterval: '30m',
     cleanupGracePeriod: '5d'
@@ -88,7 +89,8 @@ R2_BUCKET_REGION=auto
     region: 'us-east-1',
     s3ACL: 'private',
     cleanupKeyValueAdapter: new LevelDBKeyValueAdapter({
-      dbPath: './stores/minio_storage_keys',
+      // ensure /stores/ folder is a persisted/backed up point, if you running in docker ensure ensure you mount /stores/ as volume
+      dbPath: process.env.NODE_ENV === production ? '/stores/minio_storage_keys' : './minio_storage_keys',
     }),
     forcePathStyle: true,
     cleanupCheckInterval: '30m',

adminforth/documentation/docs/tutorial/06-Adapters/07-key-value-adapters.md

@@ -36,7 +36,7 @@ Redis uses in-memory storage with $O(1)$ get complexity. It is a great fit for l
 import RedisKeyValueAdapter from '@adminforth/key-value-adapter-redis';
 
 const adapter = new RedisKeyValueAdapter({
-  redisUrl: '127.0.0.1:6379',
+  redisUrl: 'redis://localhost:6379',
 });
 
 adapter.set('test-key', 'test-value', 120);

adminforth/documentation/docs/tutorial/09-Plugins/07-email-password-reset.md

@@ -16,10 +16,13 @@ Plugin allows to reset password for admin users who forgot their password by sen
 Installation:
 
 ```bash
-pnpm install @adminforth/email-password-reset --save
-pnpm install @adminforth/email-adapter-aws-ses --save
+pnpm add @adminforth/email-password-reset
+pnpm add @adminforth/email-adapter-aws-ses
+pnpm add @adminforth/key-value-adapter-ram
 ```
 
+>⚠️Note: we use key/value adapter to store used password reset token for validity period and we recomend to use stateful adapter like Redis in production, because stateless adapter (like key/value RAM) is cleared after server restart and password reset token could be re-used for the second time 
+
 Import plugin:
 
 ```typescript
@@ -42,6 +45,8 @@ Add plugin to user resource:
 ```typescript ./resources/adminuser.ts
 import EmailResetPasswordPlugin from '@adminforth/email-password-reset';
 import EmailAdapterAwsSes from '@adminforth/email-adapter-aws-ses';
+import KeyValueAdapterRam from '@adminforth/key-value-adapter-ram';
+
 ...
 plugins: [
   ...
@@ -56,12 +61,12 @@ plugins: [
     sendFrom: 'no-reply@devforth.io',
 
     adapter: new EmailAdapterAwsSes({
-        // region where SES is setup
-        region: "eu-central-1",
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
-      }),
-
+      // region where SES is setup
+      region: "eu-central-1",
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
+    }),
+    userResetTokensKeyValueAdapter: new KeyValueAdapterRam(),
   }),
 ]
 ```
@@ -102,12 +107,12 @@ plugins: [
     sendFrom: 'no-reply@devforth.io',
 
     adapter: new EmailAdapterMailgun({
-        apiKey: process.env.MAILGUN_API_KEY as string,
-        domain: process.env.MAILGUN_DOMAIN as string,
-        //baseUrl is optional, if not provided, will default to "https://api.mailgun.net" but if you are using Mailgun EU, you should use "https://api.eu.mailgun.net" instead
-        baseUrl: process.env.MAILGUN_REGION_URL as string,
-      }),
-
+      apiKey: process.env.MAILGUN_API_KEY as string,
+      domain: process.env.MAILGUN_DOMAIN as string,
+      //baseUrl is optional, if not provided, will default to "https://api.mailgun.net" but if you are using Mailgun EU, you should use "https://api.eu.mailgun.net" instead
+      baseUrl: process.env.MAILGUN_REGION_URL as string,
+    }),
+    userResetTokensKeyValueAdapter: new KeyValueAdapterRam(),
   }),
 ]
 ```

adminforth/documentation/docs/tutorial/09-Plugins/23-background-jobs.md

@@ -9,7 +9,7 @@ BackgroundJobsPlugin adds a durable background job system to AdminForth. Jobs ar
 
 
 ## Setup
-
+> ‼️ Note, that before deploying this plugin, you should create volume for the level db and pass is as `levelDbPath` param, so background jobs will be saved between redeploys
 First, install the plugin:
 ```bash
 pnpm i @adminforth/background-jobs
@@ -124,6 +124,7 @@ export default {
       statusField: 'status',
       nameField: 'name',
       jobHandlerField: 'job_handler_name',
+      levelDbPath: process.env.NODE_ENV === production ? '/stores/background_job_plugin' : './background_jobs',
     })
   ]
 } as AdminForthResourceInput;