@flink-app/jwt-auth-plugin 0.12.1-alpha.3 → 0.12.1-alpha.33

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@flink-app/jwt-auth-plugin",
-    "version": "0.12.1-alpha.3",
+    "version": "0.12.1-alpha.33",
     "description": "Flink plugin for JWT auth",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
         "test:watch": "nodemon --ext ts --exec 'jasmine-ts  --config=./spec/support/jasmine.json'",
-        "prepublish": "tsc --project tsconfig.dist.json",
+        "prepare": "tsc --project tsconfig.dist.json",
         "watch": "tsc-watch --project tsconfig.dist.json"
     },
     "author": "joel@frost.se",
@@ -20,7 +20,7 @@
         "jwt-simple": "^0.5.6"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.3",
+        "@flink-app/flink": "^0.12.1-alpha.23",
         "@types/bcrypt": "^5.0.0",
         "@types/jasmine": "^3.7.1",
         "@types/node": "22.13.10",
@@ -31,5 +31,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "51b6524e233acb2430953ffaed6382909f34db8e"
+    "gitHead": "eec3a22c21db0e7fec84190bf7a74c1e430e5ec4"
 }

package/readme.md

@@ -1,33 +1,619 @@
-# Flink API Docs
+# JWT Authentication Plugin
 
-**WORK IN PROGRESS 👷‍♀️👷🏻‍♂️**
+A Flink authentication plugin that provides JWT (JSON Web Token) based authentication with role-based permissions, password hashing, and token management.
 
-A FLINK plugin that generates a VERY simple documentation based on the apps
-registered routes and schemas.
+## Features
 
-## Usage
+- JWT token generation and validation
+- Password hashing using bcrypt
+- Role-based access control with permissions
+- Configurable password policies
+- Token expiration support
+- Bearer token authentication
 
-Install plugin to your flink app project:
+## Installation
 
+Install the plugin in your Flink app project:
+
+```bash
+npm install @flink-app/jwt-auth-plugin
+```
+
+## Basic Setup
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { Ctx } from "./Ctx";
+
+function start() {
+  const app = new FlinkApp<Ctx>({
+    name: "My Flink App",
+    auth: jwtAuthPlugin({
+      secret: process.env.JWT_SECRET || "your-secret-key",
+      getUser: async (tokenData) => {
+        // Retrieve user from database using token data
+        const user = await ctx.repos.userRepo.findById(tokenData.userId);
+        return {
+          id: user._id,
+          username: user.username,
+          roles: user.roles,
+        };
+      },
+      rolePermissions: {
+        admin: ["read", "write", "delete", "manage_users"],
+        user: ["read", "write"],
+        guest: ["read"],
+      },
+    }),
+    db: {
+      uri: "mongodb://localhost:27017/my-app",
+    },
+  });
+
+  app.start();
+}
+
+start();
+```
+
+## Configuration Options
+
+### `JwtAuthPluginOptions`
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `secret` | `string` | Yes | - | Secret key used to sign and verify JWT tokens. Keep this secure! |
+| `getUser` | `(tokenData: any) => Promise<FlinkAuthUser>` | Yes | - | Async function that retrieves user data from token payload |
+| `rolePermissions` | `{ [role: string]: string[] }` | Yes | - | Maps roles to their allowed permissions |
+| `algo` | `jwtSimple.TAlgorithm` | No | `"HS256"` | JWT signing algorithm |
+| `passwordPolicy` | `RegExp` | No | `/^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/` | Regex to validate password strength |
+| `tokenTTL` | `number` | No | `1000 * 60 * 60 * 24 * 365 * 100` (100 years) | Token time-to-live in milliseconds |
+
+### Default Password Policy
+
+The default password policy requires:
+- Minimum 8 characters
+- At least one letter (A-Z or a-z)
+- At least one number (0-9)
+
+You can customize this by providing your own regex:
+
+```typescript
+jwtAuthPlugin({
+  secret: "your-secret",
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  passwordPolicy: /^(?=.*[A-Za-z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]{12,}$/,
+  // Requires: 12+ chars, 1 letter, 1 number, 1 special character
+})
+```
+
+## Context API
+
+Once configured, the plugin provides the following methods via the `auth` context:
+
+### `createToken(payload: any, roles: string[]): Promise<string>`
+
+Creates a JWT token with the provided payload and roles.
+
+```typescript
+const token = await ctx.auth.createToken(
+  { userId: user._id, username: user.username },
+  ["user"]
+);
+```
+
+**Parameters:**
+- `payload`: Any data to encode in the token (typically user ID and username)
+- `roles`: Array of role names assigned to the user
+
+**Returns:** JWT token string
+
+**Example:**
+```typescript
+// In a login handler
+const handler: Handler<Ctx, LoginReq, LoginRes> = async ({ ctx, req }) => {
+  const user = await ctx.repos.userRepo.findOne({ username: req.body.username });
+
+  if (!user) {
+    return { status: 401, error: { code: "invalid_credentials" } };
+  }
+
+  const token = await ctx.auth.createToken(
+    { userId: user._id, username: user.username },
+    user.roles
+  );
+
+  return {
+    data: {
+      token,
+      user: {
+        id: user._id,
+        username: user.username,
+      },
+    },
+  };
+};
+```
+
+### `createPasswordHashAndSalt(password: string): Promise<{ hash: string; salt: string } | null>`
+
+Generates a secure password hash and salt using bcrypt.
+
+```typescript
+const result = await ctx.auth.createPasswordHashAndSalt("mypassword123");
+if (result) {
+  const { hash, salt } = result;
+  // Save hash and salt to database
+}
+```
+
+**Parameters:**
+- `password`: The plain text password to hash
+
+**Returns:**
+- Object with `hash` and `salt` if password meets policy
+- `null` if password doesn't meet the configured password policy
+
+**Security Note:** Both hash and salt must be stored in your database to validate passwords later.
+
+**Example:**
+```typescript
+// Creating a new user
+const handler: Handler<Ctx, CreateUserReq, CreateUserRes> = async ({ ctx, req }) => {
+  const passwordData = await ctx.auth.createPasswordHashAndSalt(req.body.password);
+
+  if (!passwordData) {
+    return {
+      status: 400,
+      error: {
+        code: "weak_password",
+        message: "Password does not meet security requirements",
+      },
+    };
+  }
+
+  const user = await ctx.repos.userRepo.create({
+    username: req.body.username,
+    password: passwordData.hash,
+    salt: passwordData.salt,
+    roles: ["user"],
+  });
+
+  return { data: { userId: user._id } };
+};
 ```
-npm i -S @flink-app/api-docs-plugin
+
+### `validatePassword(password: string, passwordHash: string, salt: string): Promise<boolean>`
+
+Validates a password against a stored hash and salt.
+
+```typescript
+const isValid = await ctx.auth.validatePassword(
+  "mypassword123",
+  user.password,
+  user.salt
+);
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+**Parameters:**
+- `password`: Plain text password to validate
+- `passwordHash`: Stored password hash from database
+- `salt`: Stored salt from database
+
+**Returns:** `true` if password matches, `false` otherwise
 
+**Example:**
+```typescript
+// In a login handler
+const handler: Handler<Ctx, LoginReq, LoginRes> = async ({ ctx, req }) => {
+  const user = await ctx.repos.userRepo.findOne({ username: req.body.username });
+
+  if (!user) {
+    return { status: 401, error: { code: "invalid_credentials" } };
+  }
+
+  const isValidPassword = await ctx.auth.validatePassword(
+    req.body.password,
+    user.password,
+    user.salt
+  );
+
+  if (!isValidPassword) {
+    return { status: 401, error: { code: "invalid_credentials" } };
+  }
+
+  const token = await ctx.auth.createToken(
+    { userId: user._id, username: user.username },
+    user.roles
+  );
+
+  return {
+    data: {
+      token,
+      user: { id: user._id, username: user.username },
+    },
+  };
+};
 ```
-import { apiDocPlugin } from "@flink-app/api-docs-plugin";
+
+### `authenticateRequest(req: FlinkRequest, permissions: string | string[]): Promise<boolean>`
+
+Automatically called by Flink framework to authenticate requests. You typically don't call this directly.
+
+## Role-Based Access Control
+
+### Defining Roles and Permissions
+
+```typescript
+jwtAuthPlugin({
+  secret: "your-secret",
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: {
+    // Admin role can do everything
+    admin: ["read", "write", "delete", "manage_users", "view_analytics"],
+
+    // Regular user has limited permissions
+    user: ["read", "write"],
+
+    // Guest can only read
+    guest: ["read"],
+  },
+})
+```
+
+### Protecting Routes with Permissions
+
+Use the `permission` property in your route configuration to restrict access:
+
+```typescript
+// Only authenticated users (any role)
+export const Route: RouteProps = {
+  path: "/api/profile",
+  permission: "read", // Must have "read" permission
+};
+
+// Only admins
+export const Route: RouteProps = {
+  path: "/api/admin/users",
+  permission: "manage_users", // Must have "manage_users" permission
+};
+
+// Multiple permissions (user must have at least one)
+export const Route: RouteProps = {
+  path: "/api/content",
+  permission: ["read", "write"], // Must have either "read" OR "write"
+};
+```
+
+### Accessing User in Handlers
+
+Once authenticated, the user object is available in `req.user`:
+
+```typescript
+const handler: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  // Access authenticated user
+  const userId = req.user?.id;
+  const username = req.user?.username;
+  const roles = req.user?.roles;
+
+  // Use user data in your logic
+  const data = await ctx.repos.dataRepo.findByUserId(userId);
+
+  return { data };
+};
+```
+
+## Making Authenticated Requests
+
+Clients must include the JWT token in the `Authorization` header:
+
+```
+Authorization: Bearer <your-jwt-token>
+```
+
+### Example with fetch
+
+```javascript
+const response = await fetch('https://api.example.com/profile', {
+  method: 'GET',
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  },
+});
+```
+
+### Example with axios
+
+```javascript
+const response = await axios.get('https://api.example.com/profile', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+  },
+});
+```
+
+## Complete Example
+
+```typescript
+// index.ts
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { Ctx } from "./Ctx";
 
 function start() {
-  new FlinkApp<AppContext>({
-    name: "My app",
-    plugins: [
-        // Register plugin, customize options if needed to
-        apiDocPlugin({
-            title: "API Docs: My app"
-        })
-    ],
-  }).start();
+  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);
+        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 * 7, // 7 days
+    }),
+    db: {
+      uri: process.env.MONGODB_URI!,
+    },
+  });
+
+  app.start();
 }
 
+start();
+
+// handlers/auth/PostLogin.ts
+import { Handler, RouteProps } from "@flink-app/flink";
+import { Ctx } from "../../Ctx";
+import LoginReq from "../../schemas/LoginReq";
+import LoginRes from "../../schemas/LoginRes";
+
+export const Route: RouteProps = {
+  path: "/auth/login",
+};
+
+const PostLogin: Handler<Ctx, LoginReq, LoginRes> = async ({ ctx, req }) => {
+  const { username, password } = req.body;
+
+  // Find user
+  const user = await ctx.repos.userRepo.findOne({ username });
+  if (!user) {
+    return {
+      status: 401,
+      error: { code: "invalid_credentials", message: "Invalid username or password" },
+    };
+  }
+
+  // Validate password
+  const isValid = await ctx.auth.validatePassword(password, user.password, user.salt);
+  if (!isValid) {
+    return {
+      status: 401,
+      error: { code: "invalid_credentials", message: "Invalid username or password" },
+    };
+  }
+
+  // Create token
+  const token = await ctx.auth.createToken(
+    { userId: user._id, username: user.username },
+    user.roles
+  );
+
+  return {
+    data: {
+      token,
+      user: {
+        id: user._id,
+        username: user.username,
+        roles: user.roles,
+      },
+    },
+  };
+};
+
+export default PostLogin;
+
+// handlers/users/PostUser.ts
+import { Handler, RouteProps } from "@flink-app/flink";
+import { Ctx } from "../../Ctx";
+import CreateUserReq from "../../schemas/CreateUserReq";
+import CreateUserRes from "../../schemas/CreateUserRes";
+
+export const Route: RouteProps = {
+  path: "/users",
+  permission: "manage_users", // Only admins can create users
+};
+
+const PostUser: Handler<Ctx, CreateUserReq, CreateUserRes> = async ({ ctx, req }) => {
+  const { username, password, roles } = req.body;
+
+  // Check if user exists
+  const existingUser = await ctx.repos.userRepo.findOne({ username });
+  if (existingUser) {
+    return {
+      status: 409,
+      error: { code: "user_exists", message: "Username already taken" },
+    };
+  }
+
+  // Hash password
+  const passwordData = await ctx.auth.createPasswordHashAndSalt(password);
+  if (!passwordData) {
+    return {
+      status: 400,
+      error: {
+        code: "weak_password",
+        message: "Password does not meet security requirements",
+      },
+    };
+  }
+
+  // Create user
+  const user = await ctx.repos.userRepo.create({
+    username,
+    password: passwordData.hash,
+    salt: passwordData.salt,
+    roles: roles || ["user"],
+    createdAt: new Date(),
+  });
+
+  return {
+    data: {
+      id: user._id,
+      username: user.username,
+      roles: user.roles,
+    },
+  };
+};
+
+export default PostUser;
 ```
+
+## Security Best Practices
+
+### 1. Secret Key Management
+
+Never hardcode your JWT secret. Use environment variables:
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  // ...
+})
+```
+
+Generate a strong secret:
+```bash
+node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+```
+
+### 2. Token Expiration
+
+Set an appropriate TTL for your use case:
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  tokenTTL: 1000 * 60 * 60 * 24 * 7, // 7 days
+  // ...
+})
+```
+
+### 3. Password Policies
+
+Enforce strong password requirements:
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  // Require: 12+ chars, uppercase, lowercase, number, special char
+  passwordPolicy: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{12,}$/,
+  // ...
+})
+```
+
+### 4. HTTPS Only
+
+Always use HTTPS in production to prevent token interception.
+
+### 5. Token Storage (Client-Side)
+
+- Avoid `localStorage` (vulnerable to XSS)
+- Prefer `httpOnly` cookies or secure session storage
+- Implement token refresh mechanisms for long-lived sessions
+
+### 6. Rate Limiting
+
+Implement rate limiting on authentication endpoints to prevent brute force attacks.
+
+## TypeScript Types
+
+```typescript
+import { JwtAuthPlugin, JwtAuthPluginOptions } from "@flink-app/jwt-auth-plugin";
+
+// Plugin options
+interface JwtAuthPluginOptions {
+  secret: string;
+  algo?: jwtSimple.TAlgorithm;
+  getUser: (tokenData: any) => Promise<FlinkAuthUser>;
+  passwordPolicy?: RegExp;
+  tokenTTL?: number;
+  rolePermissions: {
+    [role: string]: string[];
+  };
+}
+
+// Plugin interface
+interface JwtAuthPlugin extends FlinkAuthPlugin {
+  createToken: (payload: any, roles: string[]) => Promise<string>;
+  createPasswordHashAndSalt: (
+    password: string
+  ) => Promise<{ hash: string; salt: string } | null>;
+  validatePassword: (
+    password: string,
+    passwordHash: string,
+    salt: string
+  ) => Promise<boolean>;
+}
+
+// Authenticated user (from Flink framework)
+interface FlinkAuthUser {
+  id: string;
+  username?: string;
+  roles?: string[];
+  [key: string]: any;
+}
+```
+
+## Troubleshooting
+
+### Token Validation Fails
+
+**Issue:** Requests return 401 Unauthorized
+
+**Solutions:**
+- Verify the token is being sent in the `Authorization` header
+- Check the header format: `Authorization: Bearer <token>`
+- Ensure the secret used to sign matches the secret used to verify
+- Check if the token has expired (if TTL is configured)
+
+### Password Creation Returns Null
+
+**Issue:** `createPasswordHashAndSalt` returns `null`
+
+**Solution:** Password doesn't meet the configured `passwordPolicy`. Update the password or adjust the policy.
+
+### getUser Function Errors
+
+**Issue:** Authentication fails with error from `getUser`
+
+**Solution:** Ensure your `getUser` function properly handles missing users:
+
+```typescript
+getUser: async (tokenData) => {
+  const user = await ctx.repos.userRepo.findById(tokenData.userId);
+  if (!user) {
+    throw new Error("User not found");
+  }
+  return {
+    id: user._id,
+    username: user.username,
+    roles: user.roles,
+  };
+}
+```
+
+## License
+
+MIT