@flink-app/generic-auth-plugin 0.12.1-alpha.30 → 0.12.1-alpha.34

package/readme.md

@@ -1,338 +1,422 @@
-# Generic Auth Plugin Docs
+# Generic Auth Plugin
 
-A FLINK plugin that provides a generic and easy to use user system.
+A comprehensive Flink plugin that provides a complete user authentication system with user management, password reset, SMS authentication, and push notification token management. This plugin builds on top of the JWT Auth Plugin to provide ready-to-use authentication endpoints and functions.
 
-This plugin is dependent on other flink plugins:
+## Features
 
-- [jwt-auth-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/jwt-auth-plugin)
-- [email-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/email-plugin)
-
-This plugin enables the following functionalities:
-
-- User creation
-- User login
-- Change user password
-- Password reset routine (with email)
-- User profile
+- User registration and login
+- Password-based and SMS-based authentication
+- BankID authentication support
+- Password reset flow with email verification
+- User profile management
 - Push notification token management
+- Customizable password hashing
+- Pre-built API endpoints (optional)
+- Management API integration for admin interfaces
+- Lifecycle hooks (onSuccessfulLogin, onUserCreated)
 
-Plugin can both be used by accessing core functions by calling them directly from your code, or by using the embedded API endpoints.
+## Dependencies
 
-## Installation
+This plugin requires:
+- [@flink-app/jwt-auth-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/jwt-auth-plugin) - For JWT token management
+- [@flink-app/email-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/email-plugin) - For password reset emails
+- [@flink-app/sms-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/sms-plugin) - For SMS authentication (optional)
 
-Install plugin to your flink app project:
+## Installation
 
+```bash
+npm install @flink-app/generic-auth-plugin @flink-app/jwt-auth-plugin @flink-app/email-plugin
 ```
-npm i -S @flink-app/generic-auth-plugin
+
+For SMS authentication:
+```bash
+npm install @flink-app/sms-plugin
 ```
 
 ## Setup
 
-The setup of this plugin contains a few different steps. Please follow each steps before trying to use the plugin.
+### Step 1: Create User Repository
 
-### Step 1 - Adding a user repo
+Create a user repository in your project:
 
-The plugin needs a repo to store the users in.
-
-Add this repo to your project by first adding `src/repos/UserRepo.ts`:
-
-```
+**`src/repos/UserRepo.ts`:**
+```typescript
 import { FlinkRepo } from "@flink-app/flink";
+import { User } from "@flink-app/generic-auth-plugin";
 import { Ctx } from "../Ctx";
-import { User } from "@flink-app/generic-auth-plugin"
+
 class UserRepo extends FlinkRepo<Ctx, User> {}
 
 export default UserRepo;
 ```
 
-And add the repo to your ApplicationContext `src/Ctx.ts`:
-
-```
+**`src/Ctx.ts`:**
+```typescript
 import { FlinkContext } from "@flink-app/flink";
 import UserRepo from "./repos/UserRepo";
 
 export interface Ctx extends FlinkContext {
   repos: {
-    userRepo : UserRepo
+    userRepo: UserRepo;
   };
 }
 ```
 
-### Step 2 - Configure auth to your app
+### Step 2: Configure Authentication
 
-Create a configured instance of JwtAuthPlugin by using the helper function `getJtwTokenPlugin()` and configure auth property of the FlinkApp in `index.ts`
-
-```
+**`index.ts`:**
+```typescript
 import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { genericAuthPlugin } from "@flink-app/generic-auth-plugin";
+import { emailPlugin } from "@flink-app/email-plugin";
 import { Ctx } from "./Ctx";
 
-import { getJtwTokenPlugin } from "@flink-app/generic-auth-plugin"
-const authPlugin = getJtwTokenPlugin("secret");
-
 function start() {
-  var app = new FlinkApp<Ctx>({
-    name: "My flink app",
+  const app = new FlinkApp<Ctx>({
+    name: "My Flink App",
     debug: true,
-    auth : authPlugin,
+    auth: jwtAuthPlugin({
+      secret: process.env.JWT_SECRET!,
+      getUser: async (tokenData) => {
+        const user = await app.ctx.repos.userRepo.findById(tokenData.userId);
+        if (!user) throw new Error("User not found");
+        return {
+          id: user._id,
+          username: user.username,
+          roles: user.roles,
+        };
+      },
+      rolePermissions: {
+        admin: ["read", "write", "delete", "manage_users"],
+        user: ["read", "write"],
+      },
+      passwordPolicy: /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/,
+    }),
     db: {
-      uri: "mongodb://localhost:27017/my-flink-app",
+      uri: process.env.MONGODB_URI!,
     },
     plugins: [
-
+      emailPlugin({
+        // Email configuration for password resets
+        provider: "sendgrid",
+        apiKey: process.env.SENDGRID_API_KEY!,
+      }),
+      genericAuthPlugin({
+        repoName: "userRepo",
+        enableRoutes: true, // Enable built-in API endpoints
+        enablePasswordReset: true,
+        enablePushNotificationTokens: true,
+        usernameFormat: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, // Email format
+        passwordResetSettings: {
+          email: {
+            from_address: "noreply@example.com",
+            subject: "Password Reset Code",
+            html: "Your password reset code is: {{code}}",
+          },
+          code: {
+            numberOfDigits: 6,
+            lifeTime: "1h", // Uses ms package format
+            jwtSecret: process.env.PASSWORD_RESET_SECRET!,
+          },
+        },
+      }),
     ],
-  })
+  });
+
   app.start();
 }
 
 start();
 ```
 
-Se details and configuration for getJtwTokenPlugin() below.
-
-### Step 3 - Initiate the plugin
-
+## Configuration Options
+
+### `GenericAuthPluginOptions`
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `repoName` | `string` | Yes | - | Name of the user repository in your context |
+| `enableRoutes` | `boolean` | No | `true` | Enable built-in HTTP endpoints |
+| `enablePasswordReset` | `boolean` | No | `false` | Enable password reset functionality |
+| `passwordResetReusableTokens` | `boolean` | No | `false` | Allow password reset tokens to be reused |
+| `enablePushNotificationTokens` | `boolean` | No | `false` | Enable push notification token management |
+| `enableUserCreation` | `boolean` | No | `true` | Enable user creation endpoint |
+| `enableProfileUpdate` | `boolean` | No | `true` | Enable profile update endpoint |
+| `enablePasswordUpdate` | `boolean` | No | `true` | Enable password update endpoint |
+| `enableUserLogin` | `boolean` | No | `true` | Enable user login endpoint |
+| `passwordResetSettings` | `UserPasswordResetSettings` | No | - | Password reset configuration |
+| `baseUrl` | `string` | No | - | Base URL for email links |
+| `pluginId` | `string` | No | `"genericAuthPlugin"` | Plugin identifier |
+| `usernameFormat` | `RegExp` | No | `/.{1,}$/` | Regex to validate username format |
+| `sms` | `GenericAuthsmsOptions` | No | - | SMS authentication configuration |
+| `createPasswordHashAndSaltMethod` | `Function` | No | - | Custom password hashing function |
+| `validatePasswordMethod` | `Function` | No | - | Custom password validation function |
+| `onSuccessfulLogin` | `Function` | No | - | Callback after successful login |
+| `onUserCreated` | `Function` | No | - | Callback after user creation |
+| `deregisterOtherDevices` | `boolean` | No | `false` | Deregister other devices when new device is registered |
+| `allowMultipleDevices` | `boolean` | No | `true` | Allow multiple devices with same deviceId |
+
+### Password Reset Settings
+
+```typescript
+interface UserPasswordResetSettings {
+  email: {
+    from_address: string;
+    subject: string; // Handlebars template
+    html: string;    // Handlebars template
+  };
+  code: {
+    numberOfDigits: number;  // Length of reset code
+    lifeTime: string;        // e.g., "1h", "30m", "1d" (ms package format)
+    jwtSecret: string;       // Secret for reset token JWT
+  };
+}
 ```
-import { FlinkApp } from "@flink-app/flink";
-import { Ctx } from "./Ctx";
 
-import { getJtwTokenPlugin, genericAuthPlugin } from "@flink-app/generic-auth-plugin"
+**Handlebars Context:**
+- `{{username}}` - User's username
+- `{{code}}` - Password reset code
+- `{{profile}}` - User profile object
 
-const authPlugin = getJtwTokenPlugin("secret");
+### SMS Authentication Options
 
-function start() {
-  var app = new FlinkApp<Ctx>({
-    name: "My flink app",
-    debug: true,
-    auth : authPlugin,
-    db: {
-      uri: "mongodb://localhost:27017/my-flink-app",
-    },
-    plugins: [
-      genericAuthPlugin({
-        repoName : "userRepo",
-        usernameFormat : /.{1,}$/, //Regex to validate username
-        enableRoutes : true, //Set true to enable API-endpoints
-        enablePasswordReset : true,
-        enablePushNotificationTokens : true,
-        passwordResetSettings : {
-          email : {
-              from_address : "from@host.xxx",
-              subject : "Your password reset code",
-              html : "To reset your password use the code {{code}}",
-          },
-          code : {
-             numberOfDigits : 8,
-             lifeTime : "1h", //npm package
-             jwtSecret : "Secret used by password reset"
-           }
-        }
-      }),
-    ],
-  })
-  app.start();
+```typescript
+interface GenericAuthsmsOptions {
+  smsClient: smsClient;      // SMS client instance
+  smsFrom: string;           // Sender name/number
+  smsMessage: string;        // Message template with {{code}}
+  jwtToken: string;          // Secret for SMS JWT tokens
+  codeType: "numeric" | "alphanumeric";
+  codeLength: number;        // Length of SMS code
 }
-start();
 ```
 
-| Parameter      | Description                                                                                      |
-| -------------- | ------------------------------------------------------------------------------------------------ |
-| lifeTime       | expressed in seconds or a string describing a time span [zeit/ms](https://github.com/vercel/ms). |
-| subject / html | expressed in [handlebars](https://handlebarsjs.com/)                                             |
+## Context API
 
-#### Handlebars context
+The plugin exposes the following functions via `ctx.plugins.genericAuthPlugin`:
 
-Context used when processing the handlebars template for subject and html is:
+### `loginUser()`
 
-```
-{
-    username, //Username of user
-    code, //The code for the password reset
-    profile, //Profile of the user
-}
+Authenticate a user with username and password or initiate SMS authentication.
+
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.loginUser(
+  repo,
+  auth,
+  username,
+  password,
+  validatePasswordMethod?,
+  smsOptions?,
+  onSuccessfulLogin?,
+  req?
+);
 ```
 
-### getJtwTokenPlugin()
+**Returns:** `UserLoginRes`
 
-The function have the following definition:
+### `loginByToken()`
 
-```
-getJtwTokenPlugin(secret: string, rolePermissions?: { [role: string]: string[]; } | undefined, passwordPolicy?: RegExp | undefined): JwtAuthPlugin
+Complete SMS authentication using the validation token and code.
+
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.loginByToken(
+  repo,
+  auth,
+  token,
+  code,
+  jwtSecret
+);
 ```
 
-| Parameter       | Description                                                     |
-| --------------- | --------------------------------------------------------------- |
-| secret          | A secret string that will be used to encrypt the jwt-token      |
-| rolePermissions | An object with roles as key and arrays of permissions as values |
-| passwordPolicy  | Regex used to validate password                                 |
+**Returns:** `UserLoginRes`
 
-#### rolePermissions
+### `createUser()`
 
-The rolePermissions parameter specifies which roles have which permissions. Example:
+Create a new user with password, SMS, or BankID authentication.
 
-```
-{
-  "normal_user" : ["read", "list"],
-  "admin" : ["read", "list", "write"]
-}
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.createUser(
+  repo,
+  auth,
+  username,
+  password,
+  authentificationMethod, // "password" | "sms" | "bankid"
+  roles,
+  profile,
+  createPasswordHashAndSaltMethod?,
+  onUserCreated?,
+  personalNumber?
+);
 ```
 
-In this plugin the role `user` with the permission `authenticated` is added automatically. This permission is used to require authenticated user to access a route.
+**Returns:** `UserCreateRes`
 
-## Making authenticated requests
+### `changePassword()`
 
-After logging in by calling `user/login` any subsequent calls should contain the Bearer Authentification token header like this:
+Change a user's password.
 
-```
-Authorization: Bearer <token>
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.changePassword(
+  repo,
+  auth,
+  userId,
+  newPassword,
+  createPasswordHashAndSaltMethod?
+);
 ```
 
-## Limit access to your own handlers
+**Returns:** `UserPasswordChangeRes`
 
-To limit the access to your own handler, specify the "permission" property of the RouteProps of your handler.
+### `passwordResetStart()`
 
-To limit access to your handler to any user, modify the Route like this:
+Initiate password reset process and send email with code.
 
-```
-export const Route: RouteProps = {
-  path: "/sample/url",
-  permission : "authenticated"
-};
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.passwordResetStart(
+  repo,
+  auth,
+  jwtSecret,
+  username,
+  numberOfDigits?,
+  lifeTime?,
+  passwordResetReusableTokens?
+);
 ```
 
-To limit access to your handler to a specific permission, specify that permission to the Route like this:
+**Returns:** `UserPasswordResetStartRes`
 
-```
-export const Route: RouteProps = {
-  path: "/sample/url",
-  permission : "my_permission"
-};
+### `passwordResetComplete()`
+
+Complete password reset with token, code, and new password.
+
+```typescript
+const result = await ctx.plugins.genericAuthPlugin.passwordResetComplete(
+  repo,
+  auth,
+  jwtSecret,
+  passwordResetToken,
+  code,
+  newPassword,
+  createPasswordHashAndSaltMethod?,
+  passwordResetReusableTokens?
+);
 ```
 
-## Using API-endpoints
+**Returns:** `UserPasswordResetCompleteRes`
 
-### POST /user/create
+## Built-in API Endpoints
 
-Creates a new user.
+When `enableRoutes: true` (default), the following endpoints are automatically registered:
 
-#### Request data:
+### POST /user/create
 
-```
+Create a new user account.
+
+**Request:**
+```json
 {
-  "username" : "demo@test.com",
-  "password" : "12345678",
-  "profile" : {
-      "age" : 20
+  "username": "user@example.com",
+  "password": "mypassword123",
+  "authentificationMethod": "password",
+  "profile": {
+    "name": "John Doe",
+    "age": 30
   }
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
-    "status": "success"
+    "status": "success",
     "user": {
-      "_id": "id...",
-      "token": "token...",
-      "username": "demo@test.com"
+      "_id": "507f1f77bcf86cd799439011",
+      "username": "user@example.com",
+      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }
 }
 ```
 
-#### Errors
-
-| Code          | Description                                       |
-| ------------- | ------------------------------------------------- |
-| error         | Internal unknown error                            |
-| userExists    | User already exists                               |
-| passwordError | Password not accepted / not meeting requirements  |
-| usernameError |  Username not accepted / not meeting requirements |
+**Error Codes:**
+- `userExists` - Username already taken
+- `passwordError` - Password doesn't meet requirements
+- `usernameError` - Username doesn't meet format requirements
 
 ### POST /user/login
 
-Logs a user in.
-
-#### Request data:
+Login with username and password.
 
-```
+**Request:**
+```json
 {
-  "username" : "demo@test.com",
-  "password" : "12345678"
+  "username": "user@example.com",
+  "password": "mypassword123"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
-    "status": "success"
+    "status": "success",
     "user": {
-      "_id": "id...",
-      "username": "demo@test.com",
-      "token": "token...",
+      "_id": "507f1f77bcf86cd799439011",
+      "username": "user@example.com",
+      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
       "profile": {
-        "age": 20
+        "name": "John Doe",
+        "age": 30
       }
     }
   }
 }
 ```
 
-#### Errors
-
-| Code   | Description                  |
-| ------ | ---------------------------- |
-| failed | Invalid username or password |
+**Error Codes:**
+- `failed` - Invalid username or password
 
 ### POST /user/password/reset
 
-Initiates a password reset. Username must be in form of an e-mail for the password reset to work.
-
-#### Request data:
+Initiate password reset (sends email with code).
 
-```
+**Request:**
+```json
 {
-  "username" : "demo@test.com"
+  "username": "user@example.com"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
-    "status": "success"
-    "passwordResetToken": "token to use later"
+    "status": "success",
+    "passwordResetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
 }
 ```
 
-#### Errors
-
-| Code         | Description    |
-| ------------ | -------------- |
-| userNotFound | User not found |
+**Error Codes:**
+- `userNotFound` - User doesn't exist
 
 ### POST /user/password/reset/complete
 
-Completes a password reset by supplying the passwordRestToken received from step 1, the code from the email sent to the user and the new password.
+Complete password reset with code from email.
 
-#### Request data:
-
-```
+**Request:**
+```json
 {
-  "passwordResetToken" : "token to use later",
-  "code" : "12345678",
-  "password" : "new password"
+  "passwordResetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "code": "123456",
+  "password": "mynewpassword123"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
     "status": "success"
@@ -340,29 +424,26 @@ Completes a password reset by supplying the passwordRestToken received from step
 }
 ```
 
-#### Errors
-
-| Code          | Description                                        |
-| ------------- | -------------------------------------------------- |
-| invalidCode   | Invalid validation code                            |
-| passwordError | Password not accepted / does not meet requirements |
-| userNotFound  | User not found                                     |
+**Error Codes:**
+- `invalidCode` - Code is wrong or expired
+- `passwordError` - Password doesn't meet requirements
+- `userNotFound` - User not found
 
 ### PUT /user/password
 
-Updates password of the current user. Request needs authentication.
+Change password for authenticated user.
 
-#### Request data:
+**Authentication:** Required
 
-```
+**Request:**
+```json
 {
-  "password" : "12345678"
+  "password": "mynewpassword123"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
     "status": "success"
@@ -370,46 +451,47 @@ Updates password of the current user. Request needs authentication.
 }
 ```
 
-#### Errors
-
-| Code          | Description                                        |
-| ------------- | -------------------------------------------------- |
-| failed        | Internal unknown error                             |
-| passwordError | Password not accepted / does not meet requirements |
+**Error Codes:**
+- `passwordError` - Password doesn't meet requirements
+- `failed` - Internal error
 
 ### GET /user/profile
 
-Gets the user profile of the current user. Request needs authentication.
+Get current user's profile.
 
-#### Response example
+**Authentication:** Required
 
-```
+**Response:**
+```json
 {
   "data": {
-    "age": 20
+    "name": "John Doe",
+    "age": 30
   }
 }
 ```
 
 ### PUT /user/profile
 
-Updates profile of the current user. Request needs authentication.
+Update current user's profile.
 
-#### Request data:
+**Authentication:** Required
 
-```
+**Request:**
+```json
 {
-  "age" : "21",
-  "city" : "Stockholm"
+  "name": "Jane Doe",
+  "age": 31,
+  "city": "Stockholm"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
-    "age": "21",
+    "name": "Jane Doe",
+    "age": 31,
     "city": "Stockholm"
   }
 }
@@ -417,20 +499,20 @@ Updates profile of the current user. Request needs authentication.
 
 ### POST /user/push
 
-Adds a push notification token to the user. Request needs authentication.
+Register push notification token.
 
-#### Request data:
+**Authentication:** Required
 
-```
+**Request:**
+```json
 {
-  "deviceId" : "xxx",
-  "token" : "token..."
+  "deviceId": "device-123",
+  "token": "firebase-token-xyz"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
     "status": "success"
@@ -440,20 +522,20 @@ Adds a push notification token to the user. Request needs authentication.
 
 ### DELETE /user/push
 
-Removes a push notification token from the user. Request needs authentication.
+Remove push notification token.
 
-#### Request data:
+**Authentication:** Required
 
-```
+**Request:**
+```json
 {
-  "deviceId" : "xxx",
-  "token" : "token..."
+  "deviceId": "device-123",
+  "token": "firebase-token-xyz"
 }
 ```
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
     "status": "success"
@@ -463,429 +545,409 @@ Removes a push notification token from the user. Request needs authentication.
 
 ### GET /user/token
 
-Get a refreshed token for the current user. Request needs authentication.
+Refresh JWT token for current user (useful after role changes).
 
-User need to refresh his token if roles or username have been changed.
+**Authentication:** Required
 
-#### Response example
-
-```
+**Response:**
+```json
 {
   "data": {
-    "token": "token..."
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
 }
 ```
 
-## Using plugin functions
+## SMS Authentication
 
-As an alternative to use the included API-endpoints you might use the supplied core functions from this plugin to manage some basic tasks.
-
-After initilizing this plugin, these functions are exposed in the app context:
-
-```
-ctx.plugins.genericAuthPlugin.loginUser( repo : FlinkRepo<any, User>, auth : JwtAuthPlugin, username : string, password? : string) : Promise<UserLoginRes>
-```
-
-```
-ctx.plugins.genericAuthPlugin.createUser( repo : FlinkRepo<any, User>, auth : JwtAuthPlugin, username : string, password : string, authentificationMethod : "password" | "sms",  roles : string[], profile : UserProfile ) : Promise<UserCreateRes>
-```
-
-```
-ctx.plugins.genericAuthPlugin.changePassword( repo : FlinkRepo<any, User>, auth : JwtAuthPlugin, userId : string, newPassword : string) : Promise<UserPasswordChangeRes>
-```
+### Setup
 
-```
-ctx.plugins.genericAuthPlugin.passwordResetStart( repo : FlinkRepo<any, User>, auth : JwtAuthPlugin, jwtSecret : string, username : string, numberOfDigits? : number, lifeTime? : string) : Promise<UserPasswordResetStartRes>
-```
+Install and configure SMS plugin:
 
+```bash
+npm install @flink-app/sms-plugin
 ```
-ctx.plugins.genericAuthPlugin.passwordResetComplete( repo : FlinkRepo<any, User>, auth : JwtAuthPlugin, jwtSecret : string, passwordResetToken : string, code : string, newPassword : string) : Promise<UserPasswordResetCompleteRes>
-```
-
-## Deleting users, changing roles and more..
-
-You can always interact directly with the userRepo to modify you users.
-
-Please remember to refresh the users token after changing vital parts of a user.
 
-## Using alternativ password and hash functions
-
-You can specify your own methods to generate hash and salt or to verify a password.
-
-To do this, simply specify the `createPasswordHashAndSaltMethod` and/or `validatePasswordMethod` options on plugin initilizing. Like this:
-
-```
-//This is just a dummy on storing password in plain text. STRONGLY NOT RECOMMENDED.
+```typescript
+import { sms46elksClient } from "@flink-app/sms-plugin";
 
 genericAuthPlugin({
-  createPasswordHashAndSaltMethod : (password) => {
-      return new Promise((resolve) => {
-        resolve({ hash : password, salt : "" });
-      })
+  repoName: "userRepo",
+  sms: {
+    smsClient: new sms46elksClient({
+      username: process.env.SMS_USERNAME!,
+      password: process.env.SMS_PASSWORD!,
+    }),
+    smsFrom: "MyApp",
+    smsMessage: "Your verification code is {{code}}",
+    jwtToken: process.env.SMS_JWT_SECRET!,
+    codeType: "numeric",
+    codeLength: 6,
   },
-  validatePasswordMethod : (password, hash, salt) => {
-      return new Promise((resolve) => {
-        resolve(password == hash);
-      })
-  }
 })
 ```
 
-When `validatePasswordMethod` is specified, that method will be used to validate the password. If that method returns false, the default validation will try as well. This will make it possible to use both default password hashes and alternative ones.
-
-### How to validate old Aquro / Aplexa passwords?
-
-If you are using this plugin to verify old Aquro / Aplexa passwords, you can simply do this by specifying `validatePasswordMethod` and use the same hash-function as Aquro Platform.
-
-#### Install required plugin
+### Create SMS User
 
-```
-npm install --save password-hash
-npm install --save-dev @types/password-hash
+**POST /user/create:**
+```json
+{
+  "username": "+46701234567",
+  "authentificationMethod": "sms"
+}
 ```
 
-#### Update plugin initialization
+### Login with SMS (Two-Step Process)
 
+**Step 1: Initiate** - POST /user/login
+```json
+{
+  "username": "+46701234567"
+}
 ```
-import passwordHash from "password-hash";
 
-genericAuthPlugin({
-  validatePasswordMethod : (password, hash, salt) => {
-      return new Promise((resolve) => {
-        resolve(passwordHash.verify(password, hash));
-      })
-    }
-})
+Response:
+```json
+{
+  "data": {
+    "status": "success",
+    "validationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
 ```
 
-## Enabling management-api functions
-
-This plugin supports the [management-api-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/management-api-plugin) structure to expose management apis.
-
-The management API is used by [flink-admin](https://github.com/FrostDigital/flink-admin). So to enable managing of app users in flink-admin, you need to exponse this plugins management api functions.
-
-To do this, first install the managemnet-api-plugin and then get the management module from this plugin.
-
+**Step 2: Complete** - POST /user/login-by-token
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "code": "123456"
+}
 ```
-import { GetManagementModule  } from "@flink-app/generic-auth-plugin"
 
-const genericAuthManagementModule =  GetManagementModule(
-  {
-    ui : true, //Enable UI for this module in flink-admin-portal
-    uiSettings : {
-       title : "App users", //Title of this module
-       enableUserEdit, : true //Make it possible to edit the user
-       enableUserCreate, : true //Make it possible to create new users
-       enableUserDelete, : true //Make it possible to delete the user
-       enableUserView, : true //Make it possible to view a user
+Response:
+```json
+{
+  "data": {
+    "status": "success",
+    "user": {
+      "_id": "507f1f77bcf86cd799439011",
+      "username": "+46701234567",
+      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+      "profile": {}
     }
   }
-)
-```
-
-Finally add the management module to the list of modules in the managementApiPlugin config:
-
-```
-
-function start() {
-  new FlinkApp<Ctx>({
-    name: "My flink app",
-    debug: true,
-    auth : authPlugin,
-    loader: (file: any) => import(file),
-    db: {
-      uri: "mongodb://localhost:27017/my-flink-app",
-    },
-    plugins: [
-      genericAuthPlugin({
-        repoName : "userRepo",
-      }),
-      managementApiPlugin({
-        token : "TOKEN",
-        jwtSecret : "SECRET",
-        modules : [
-          genericAuthManagementModule
-        ]
-      })
-    ],
-  }).start();
 }
 ```
 
-### Enable user viewing
+## Custom Password Hashing
 
-To make it possible to view data for a user, you will need to first enable the `enableUserView` flag. 
+You can provide custom password hashing functions to support legacy systems:
 
-You can also provide a function that returns the data that should be shown of the user. 
-This function can also be extended to return a list of buttons that will be added to the toolbar. 
-
-
-```
-import { GetManagementModule  } from "@flink-app/generic-auth-plugin"
+```typescript
+import passwordHash from "password-hash";
 
-const genericAuthManagementModule =  GetManagementModule(
-  {
-    ui : true, //Enable UI for this module in flink-admin-portal
-    uiSettings : {
-       title : "App users", //Title of this module
-       enableUserEdit, : true //Make it possible to edit the user
-       enableUserCreate, : true //Make it possible to create new users
-       enableUserDelete, : true //Make it possible to delete the user
-       enableUserView, : true //Make it possible to view a user
-    },
-    userView: {
-        getData(user: User) {
-     
-            let data: {
-                [key: string]: string
-            } = {
-                'E-mail': user.username,
-                'Profile property' : user.profile.Property.toString()
-            }
-
-            let buttons: {
-                text: string
-                url: string
-            }[] = []
-
-            buttons.push({
-                    text: 'Visit google',
-                    url: 'https://www.google.com',
-              })
-
-
-            return {
-                buttons,
-                data,
-            }
-        },
-    },    
-  }
-)
+genericAuthPlugin({
+  repoName: "userRepo",
+  createPasswordHashAndSaltMethod: async (password) => {
+    // Custom hash creation
+    return {
+      hash: passwordHash.generate(password),
+      salt: "",
+    };
+  },
+  validatePasswordMethod: async (password, hash, salt) => {
+    // Custom validation
+    return passwordHash.verify(password, hash);
+  },
+})
 ```
 
+This allows validating both new and legacy password formats.
 
+## User Model
 
-### Make it possible to edit profile properites
-
-To make it possible to edit profile properties when editing users, you must expose the JSON-schema of the profile.
-
-To do this, follow these steps:
-
-#### Step 1:
-
-Create a Schema file for your profile properties, eg. schemas/ProfileProperties.ts
-
-#### Step 2:
-
-Configure flink to generate schema files by editing package.json file and replace
-
-```
-    "flink:generate": "flink generate"
-```
+```typescript
+interface User {
+  _id: string;
+  username: string;
+  personalNumber?: string;
+  password?: string;
+  salt?: string;
+  pwdResetStartedAt?: string | null;
+  roles: string[];
+  authentificationMethod: "password" | "sms" | "bankid";
+  profile: UserProfile;
+  pushNotificationTokens: PushNotificationToken[];
+}
 
-to:
+interface UserProfile {
+  [key: string]: any; // Custom profile fields
+}
 
-```
-    "flink:generate": "flink generate && flink generate-schema"
+interface PushNotificationToken {
+  deviceId: string;
+  token: string;
+  registeredAt: Date;
+}
 ```
 
-#### Step 3:
+## Management API Integration
 
-Restart your flink app (to generate the JSON-schemeas)
+Integrate with [@flink-app/management-api-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/management-api-plugin) for admin interfaces:
 
-#### Step 4:
+```typescript
+import { managementApiPlugin } from "@flink-app/management-api-plugin";
+import { GetManagementModule } from "@flink-app/generic-auth-plugin";
+import schemas from "./.flink/schemas.json"; // Generated schemas
 
-Import the JSON-schema and pass it to the `GetManagementModule` function.
+const genericAuthManagementModule = GetManagementModule({
+  ui: true,
+  profileSchema: schemas.UserProfile, // Enable profile editing
+  uiSettings: {
+    title: "App Users",
+    enableUserEdit: true,
+    enableUserCreate: true,
+    enableUserDelete: true,
+    enableUserView: true,
+  },
+  userView: {
+    getData(user) {
+      return {
+        data: {
+          "Email": user.username,
+          "Name": user.profile.name,
+          "Status": user.roles.join(", "),
+        },
+        buttons: [
+          {
+            text: "Send Email",
+            url: `mailto:${user.username}`,
+          },
+        ],
+      };
+    },
+  },
+});
 
+// Add to plugins
+plugins: [
+  genericAuthPlugin({ /* ... */ }),
+  managementApiPlugin({
+    token: process.env.ADMIN_TOKEN!,
+    jwtSecret: process.env.ADMIN_JWT_SECRET!,
+    modules: [genericAuthManagementModule],
+  }),
+]
 ```
-import { GetManagementModule  } from "@flink-app/generic-auth-plugin"
-import schemas from "../.flink/schemas.json";
 
-const genericAuthManagementModule =  GetManagementModule(
-  {
-    ui : true, //Enable UI for this module in flink-admin-portal
-    profileSchema : schemas.ProfileProperties,
-    uiSettings : {
-       title : "App users", //Title of this module
-       enableUserEdit, : true //Make it possible to edit the user
-       enableUserCreate, : true //Make it possible to create new users
-       enableUserDelete, : true //Make it possible to delete the user
-    }
-  }
-)
-```
+## Lifecycle Hooks
 
-Please note that only string and enum property types can be edited from the flink-admin interface.
+### onSuccessfulLogin
 
-✅ Do:
+Called after successful authentication:
 
-```
-export interface ProfileProperties{
-    name : string;
-    city : string;
-    gender : "male" | "female" | "any";
-}
+```typescript
+genericAuthPlugin({
+  repoName: "userRepo",
+  onSuccessfulLogin: async (user, req) => {
+    // Track login
+    await ctx.repos.auditLogRepo.create({
+      userId: user._id,
+      action: "login",
+      ip: req?.ip,
+      timestamp: new Date(),
+    });
+  },
+})
 ```
 
-❌ Dont:
+### onUserCreated
 
-```
-type myType = {
-    hello : string,
-    world : string
-}
+Called after user creation:
 
-export interface Profile{
-    name : string;
-    type : myType
-}
+```typescript
+genericAuthPlugin({
+  repoName: "userRepo",
+  onUserCreated: async (user) => {
+    // Send welcome email
+    await ctx.plugins.email.send({
+      to: user.username,
+      subject: "Welcome!",
+      html: `<p>Welcome to our app, ${user.profile.name}!</p>`,
+    });
+  },
+})
 ```
 
+## Protecting Your Routes
 
+Use permissions from jwt-auth-plugin to protect routes:
 
-## Using SMS login
-
-
-### prerequisites
-- A SMS client must be setup using the [sms-plugin](https://github.com/FrostDigital/flink-framework/tree/main/packages/sms-plugin)
-
+```typescript
+// Only authenticated users
+export const Route: RouteProps = {
+  path: "/api/data",
+  permission: "read",
+};
 
-### Setup
-- Configure this plugin by setting the sms option:
+// Only admins
+export const Route: RouteProps = {
+  path: "/api/admin/users",
+  permission: "manage_users",
+};
+```
 
+## Complete Example
 
-```
+```typescript
+// index.ts
 import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { genericAuthPlugin } from "@flink-app/generic-auth-plugin";
+import { emailPlugin } from "@flink-app/email-plugin";
 import { Ctx } from "./Ctx";
 
-import { getJtwTokenPlugin, genericAuthPlugin } from "@flink-app/generic-auth-plugin"
-
-const authPlugin = getJtwTokenPlugin("secret");
-
 function start() {
-  var app = new FlinkApp<Ctx>({
-    name: "My flink app",
-    debug: true,
-    auth : authPlugin,
+  const app = new FlinkApp<Ctx>({
+    name: "My App",
+    auth: jwtAuthPlugin({
+      secret: process.env.JWT_SECRET!,
+      getUser: async (tokenData) => {
+        const user = await app.ctx.repos.userRepo.findById(tokenData.userId);
+        if (!user) throw new Error("User not found");
+        return {
+          id: user._id,
+          username: user.username,
+          roles: user.roles,
+        };
+      },
+      rolePermissions: {
+        admin: ["read", "write", "delete", "manage_users"],
+        user: ["read", "write"],
+      },
+      passwordPolicy: /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d@$!%*?&]{10,}$/,
+      tokenTTL: 1000 * 60 * 60 * 24 * 30, // 30 days
+    }),
     db: {
-      uri: "mongodb://localhost:27017/my-flink-app",
+      uri: process.env.MONGODB_URI!,
     },
     plugins: [
+      emailPlugin({
+        provider: "sendgrid",
+        apiKey: process.env.SENDGRID_API_KEY!,
+      }),
       genericAuthPlugin({
-        ...
-
-
-          sms : {
-            smsClient: new sms46elksClient({
-              username: "XXX",
-              password: "YYY",
-            }),
-            smsFrom: "AUTHMSG",
-            smsMessage: "Your code is {{code}}",
-            jwtToken: "secret-to-sign-jwt-tokens",
-            codeType: "numeric",
-            codeLength: 6
-          }
-
-
-        ...
-
-        }
+        repoName: "userRepo",
+        enableRoutes: true,
+        enablePasswordReset: true,
+        enablePushNotificationTokens: true,
+        usernameFormat: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+        passwordResetSettings: {
+          email: {
+            from_address: "noreply@example.com",
+            subject: "Password Reset - {{username}}",
+            html: `
+              <h2>Password Reset Request</h2>
+              <p>Your password reset code is: <strong>{{code}}</strong></p>
+              <p>This code expires in 1 hour.</p>
+            `,
+          },
+          code: {
+            numberOfDigits: 6,
+            lifeTime: "1h",
+            jwtSecret: process.env.PASSWORD_RESET_SECRET!,
+          },
+        },
+        onSuccessfulLogin: async (user) => {
+          console.log(`User ${user.username} logged in`);
+        },
+        onUserCreated: async (user) => {
+          console.log(`New user created: ${user.username}`);
+        },
       }),
     ],
-  })
+  });
+
   app.start();
 }
+
 start();
 ```
 
+## Security Best Practices
 
+### 1. Username Validation
 
-### Register users with SMS-login
-To use SMS-login on a user, the user must be created with the `authentificationMethod` option set to sms.
-Username also have to be the users phone number in the "+4671234567" format.
+Validate username format to prevent injection attacks:
 
-### POST /user/create
+```typescript
+usernameFormat: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
+```
 
-Create a user that can login via SMS
+### 2. Password Reset Security
 
-#### Request data:
+- Use short-lived tokens (1 hour or less)
+- Use single-use tokens (set `passwordResetReusableTokens: false`)
+- Use separate JWT secret for password resets
+- Include rate limiting on reset endpoints
 
-```
-{
-  "username" : "+4671234567",
- "authentificationMethod" : "sms" 
-}
-```
+### 3. Push Token Management
 
-#### Response example
+Enable `deregisterOtherDevices` to prevent token duplication:
 
-```
-{
-  "data": {
-    "status": "success",
-  },
+```typescript
+deregisterOtherDevices: true
 ```
 
+### 4. Environment Variables
 
+Never commit secrets to version control:
 
-### Initiate login
-Initiate a user login by sending a SMS with the code to the user.
-Please note that the user HAVE to be created with the  `authentificationMethod` option set to sms.
+```bash
+JWT_SECRET=xxx
+PASSWORD_RESET_SECRET=yyy
+SENDGRID_API_KEY=zzz
+```
 
-### POST /user/login
+### 5. HTTPS Only
 
+Always use HTTPS in production to prevent credential interception.
 
-#### Request data:
+## TypeScript Types
 
-```
-{
-  "username" : "+4671234567",
-}
+```typescript
+import {
+  User,
+  UserProfile,
+  UserLoginRes,
+  UserCreateRes,
+  UserPasswordResetStartRes,
+  UserPasswordResetCompleteRes,
+  GenericAuthPluginOptions,
+} from "@flink-app/generic-auth-plugin";
 ```
 
-#### Response example
+## Troubleshooting
 
-```
-{
-  "data": {
-    "status": "success",
-    "validationToken": "TOKEN"
-  },
-}
+### Password Reset Emails Not Sending
 
+**Solution:** Verify email plugin is configured and test email settings:
+```typescript
+await ctx.plugins.email.send({
+  to: "test@example.com",
+  subject: "Test",
+  html: "<p>Test email</p>",
+});
 ```
 
-### Login
-Finalize the login by sending the token received above, and the code received via SMS.
-
-### POST /user/login-by-token
+### Users Cannot Login After Creation
 
+**Solution:** Check password policy matches between jwt-auth-plugin and user creation.
 
-#### Request data:
+### SMS Code Not Received
 
-```
-{
-  "token" : "TOKEN",
-  "code" : "code"
- }
-```
+**Solution:** Verify SMS plugin configuration and check SMS provider logs.
 
-#### Response example
+## License
 
-```
-{
-  "data": {
-    "status": "success",
-    "user": {
-      "_id": "1234...",
-      "username": "+4671234567",
-      "token": "Token",
-      "profile": {}
-    }
-  },
-  "status": 200
-}
-```
+MIT