@zola_do/authorization 0.2.5 → 0.2.6

package/README.md

@@ -1,6 +1,23 @@
 # @zola_do/authorization
 
-JWT authentication, API key validation, guards, and strategies for NestJS.
+[![npm version](https://img.shields.io/npm/v/@zola_do/authorization.svg)](https://www.npmjs.com/package/@zola_do/authorization)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/authorization.svg)](https://www.npmjs.com/package/@zola_do/authorization)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+JWT authentication, API key validation, guards, and strategies for NestJS applications.
+
+## Overview
+
+`@zola_do/authorization` provides a complete authentication and authorization solution:
+
+- **JWT Guards** — Bearer token authentication
+- **Permission Guards** — Role-based access control (RBAC)
+- **API Key Guard** — External API authentication
+- **Strategies** — Passport JWT strategies (access + refresh tokens)
+- **Decorators** — `@CurrentUser()`, `@AllowAnonymous()`
+- **Auth Helper** — Token generation, password hashing, OTP
+
+By default, `JwtGuard` is registered as a global guard, protecting all routes.
 
 ## Installation
 
@@ -12,31 +29,36 @@ npm install @zola_do/authorization
 npm install @zola_do/nestjs-shared
 ```
 
-## Recommended Imports
-
-`@zola_do/authorization` root imports remain fully supported for backward compatibility.
-For new code, prefer focused subpath imports:
+### Dependencies
 
-```typescript
-import { AuthorizationModule } from '@zola_do/authorization/module';
-import { JwtGuard, PermissionsGuard } from '@zola_do/authorization/guards';
-import { AllowAnonymous, CurrentUser } from '@zola_do/authorization/decorators';
-import { AuthHelper } from '@zola_do/authorization/helper';
+```bash
+npm install @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt jsonwebtoken
 ```
 
-Optional throttler guard stays available at:
+### Optional Dependencies
 
-```typescript
-import { ThrottlerBehindProxyGuard } from '@zola_do/authorization/optional/throttler';
+```bash
+# For ThrottlerBehindProxyGuard
+npm install @nestjs/throttler
 ```
 
-## Usage
+## Quick Start
 
-### Module Setup
+### 1. Configure Environment
+
+```bash
+# .env
+JWT_ACCESS_TOKEN_SECRET=your-access-token-secret-min-32-chars
+JWT_ACCESS_TOKEN_EXPIRES=15m
+JWT_REFRESH_TOKEN_SECRET=your-refresh-token-secret-min-32-chars
+JWT_REFRESH_TOKEN_EXPIRES=7d
+```
+
+### 2. Register Module
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { AuthorizationModule } from '@zola_do/authorization';
+import { Module } from "@nestjs/common";
+import { AuthorizationModule } from "@zola_do/authorization";
 
 @Module({
   imports: [AuthorizationModule],
@@ -44,147 +66,526 @@ import { AuthorizationModule } from '@zola_do/authorization';
 export class AppModule {}
 ```
 
-By default, `JwtGuard` is registered as a global guard. Protect routes automatically; use `@AllowAnonymous()` for public routes.
+### 3. Access User in Controller
+
+```typescript
+import { Controller, Get } from "@nestjs/common";
+import { CurrentUser, JwtGuard, UseGuards } from "@zola_do/authorization";
+
+@Controller("profile")
+export class ProfileController {
+  @Get()
+  @UseGuards(JwtGuard) // Optional - global guard is active by default
+  getProfile(@CurrentUser() user: any) {
+    return {
+      id: user.id,
+      email: user.email,
+      organization: user.organization,
+    };
+  }
+}
+```
+
+## JWT Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Login Flow                                  │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Client          Backend                    JWT Payload              │
+│    │                │                            │                   │
+│    │  POST /login   │                            │                   │
+│    │  {email,pass}  │                            │                   │
+│    │───────────────>│                            │                   │
+│    │                │                            │                   │
+│    │         ┌─────▼─────┐                      │                   │
+│    │         │ Validate   │                      │                   │
+│    │         │ credentials│                      │                   │
+│    │         └─────┬─────┘                      │                   │
+│    │               │                             │                   │
+│    │         ┌─────▼───────────────┐             │                   │
+│    │         │ Generate tokens:    │             │                   │
+│    │         │ - accessToken       │─────────────┼─────────────────>│
+│    │         │ - refreshToken      │             │ {                 │
+│    │         └────────────────────┘             │   sub: userId,    │
+│    │                │                            │   email,          │
+│    │                │                            │   organization,  │
+│    │                │                            │   permissions     │
+│    │<───────────────│                            │ }                 │
+│    │  { accessToken,│                                               │
+│    │    refreshToken│                                               │
+│    │  }             │                                               │
+│    │                │                                               │
+└────┼────────────────┼───────────────────────────────────────────────┘
+     │                │
+     │                │
+     ▼                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Authenticated Request                            │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Client          Backend                    JwtGuard                 │
+│    │                │                            │                   │
+│    │  GET /profile  │                            │                   │
+│    │  Authorization:│                            │                   │
+│    │  Bearer <token>│                            │                   │
+│    │───────────────>│                            │                   │
+│    │                │                            │                   │
+│    │                │  ┌────▼─────┐              │                   │
+│    │                │  │ Extract  │              │                   │
+│    │                │  │ token    │              │                   │
+│    │                │  └────┬─────┘              │                   │
+│    │                │       │                    │                   │
+│    │                │  ┌────▼────────────┐       │                   │
+│    │                │  │ Verify with     │       │                   │
+│    │                │  │ JWT_ACCESS_     │       │                   │
+│    │                │  │ TOKEN_SECRET    │       │                   │
+│    │                │  └────┬────────────┘       │                   │
+│    │                │       │                    │                   │
+│    │                │       │ set request.user   │                   │
+│    │                │       ▼                    │                   │
+│    │                │  req.user = payload        │                   │
+│    │                │                            │                   │
+│    │<───────────────│  Controller runs           │                   │
+│    │  { user data } │  @CurrentUser() = user    │                   │
+│    │                │                            │                   │
+└────┴────────────────┴───────────────────────────────────────────────┘
+```
+
+## Guards
+
+### JwtGuard
+
+Default global guard that validates Bearer tokens:
+
+```typescript
+@UseGuards(JwtGuard)
+@Controller("protected")
+export class ProtectedController {}
+```
+
+### OptionalJwtGuard
+
+Allows anonymous access but extracts user if token is present:
+
+```typescript
+@UseGuards(OptionalJwtGuard)
+@Controller("optional")
+export class OptionalController {
+  @Get()
+  getData(@CurrentUser() user?: any) {
+    if (user) {
+      return { message: "Authenticated", user };
+    }
+    return { message: "Anonymous" };
+  }
+}
+```
+
+### PermissionsGuard
+
+Requires specific permissions. Supports pipe-separated OR logic:
+
+```typescript
+@UseGuards(JwtGuard, PermissionsGuard("product:create"))
+@Controller("products")
+export class ProductsController {
+  @Post()
+  createProduct() {
+    // Requires 'product:create' permission
+  }
+
+  @Patch(":id")
+  @UseGuards(PermissionsGuard("product:update|product:manage"))
+  updateProduct() {
+    // Requires 'product:update' OR 'product:manage'
+  }
+}
+```
+
+### ApiKeyGuard
+
+Validates `X-API-Key` header against `process.env.API_KEY`:
 
-### Override JwtGuard In AppModule
+```typescript
+@UseGuards(ApiKeyGuard)
+@Controller("external")
+export class ExternalController {}
+```
 
-If your app uses a different token payload shape or custom validation logic, override `JwtGuard` in `AppModule`.
-When `request.user` is already set by your guard, library `JwtGuard`/`OptionalJwtGuard` now skip token parsing and do not overwrite it.
+### VendorGuard
+
+Checks vendor registration status (custom implementation required):
 
 ```typescript
-import { Injectable, ExecutionContext } from '@nestjs/common';
-import { JwtGuard } from '@zola_do/authorization';
+@UseGuards(JwtGuard, VendorGuard())
+@Controller("vendor")
+export class VendorController {}
+```
+
+## Decorators
+
+### @CurrentUser()
+
+Extract user from request:
+
+```typescript
+@Get('profile')
+getProfile(@CurrentUser() user: UserPayload) {
+  return user;
+}
+
+// With property extraction
+@Get('profile')
+getProfile(@CurrentUser('email') email: string) {
+  return { email };
+}
+```
+
+### @AllowAnonymous()
+
+Skip authentication for specific routes:
+
+```typescript
+@Get('public')
+@AllowAnonymous()
+getPublicData() {
+  return { message: 'Public data' };
+}
+```
+
+## JWT Payload
+
+Default payload structure:
+
+```typescript
+interface JwtPayload {
+  sub: string; // User ID
+  email: string; // User email
+  organization?: {
+    // Organization context
+    organizationId: string;
+    organizationName: string;
+  };
+  permissions?: string[]; // User permissions
+  iat?: number; // Issued at
+  exp?: number; // Expiration
+}
+```
+
+## AuthHelper
+
+Utility service for token operations:
+
+```typescript
+import { AuthHelper } from "@zola_do/authorization";
+
+@Injectable()
+export class AuthService {
+  constructor(private readonly authHelper: AuthHelper) {}
+
+  async login(user: User) {
+    // Generate tokens
+    const tokens = this.authHelper.generateTokens(user);
+
+    // Hash password
+    const hashedPassword = await this.authHelper.hashPassword(plainPassword);
+
+    // Verify password
+    const isValid = await this.authHelper.verifyPassword(
+      plainPassword,
+      hashedPassword,
+    );
+
+    // Generate OTP
+    const otp = this.authHelper.generateOtp();
+
+    return { tokens, hashedPassword, isValid, otp };
+  }
+
+  async refreshTokens(refreshToken: string) {
+    return this.authHelper.refreshTokens(refreshToken);
+  }
+}
+```
+
+### AuthHelper Methods
+
+| Method                           | Description                    | Returns                         |
+| -------------------------------- | ------------------------------ | ------------------------------- |
+| `generateTokens(user)`           | Create access + refresh tokens | `{ accessToken, refreshToken }` |
+| `refreshTokens(refreshToken)`    | Refresh using refresh token    | `{ accessToken, refreshToken }` |
+| `hashPassword(password)`         | bcrypt hash                    | `string`                        |
+| `verifyPassword(password, hash)` | Compare password to hash       | `boolean`                       |
+| `generateOtp(length)`            | Generate numeric OTP           | `string`                        |
+| `decodeToken(token)`             | Decode without verification    | `JwtPayload`                    |
+
+## Token Generation Example
+
+```typescript
+import { AuthHelper } from "@zola_do/authorization";
+import { JwtPayload } from "@zola_do/authorization/helper";
+
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly authHelper: AuthHelper) {}
+
+  @Post("login")
+  async login(@Body() dto: LoginDto) {
+    const user = await this.userService.validateUser(dto);
+
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      organization: {
+        organizationId: user.organizationId,
+        organizationName: user.organization.name,
+      },
+      permissions: user.permissions,
+    };
+
+    return this.authHelper.generateTokens(payload);
+  }
+
+  @Post("refresh")
+  async refresh(@Body("refreshToken") refreshToken: string) {
+    return this.authHelper.refreshTokens(refreshToken);
+  }
+}
+```
+
+## Custom JwtGuard Override
+
+Override the default JWT validation logic:
+
+```typescript
+import { Injectable, ExecutionContext } from "@nestjs/common";
+import { JwtGuard } from "@zola_do/authorization";
 
 @Injectable()
 export class AppJwtGuard extends JwtGuard {
   async canActivate(context: ExecutionContext): Promise<boolean> {
-    // Add app-specific token parsing/validation logic here.
+    // Run default validation
+    const canActivate = await super.canActivate(context);
+    if (!canActivate) return false;
+
+    // Add custom logic
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    // Check additional conditions
+    if (user.status === "suspended") {
+      throw new ForbiddenException("Account suspended");
+    }
+
     return true;
   }
 }
 ```
 
+Register in module:
+
 ```typescript
-import { Module } from '@nestjs/common';
-import { APP_GUARD } from '@nestjs/core';
-import { AuthorizationModule, JwtGuard } from '@zola_do/authorization';
-import { AppJwtGuard } from './guards/app-jwt.guard';
+import { APP_GUARD } from "@nestjs/core";
+import { AuthorizationModule, JwtGuard } from "@zola_do/authorization";
 
 @Module({
   imports: [AuthorizationModule],
   providers: [
     AppJwtGuard,
-    // Used by controllers that reference @UseGuards(JwtGuard)
     { provide: JwtGuard, useExisting: AppJwtGuard },
-    // Used as global guard
     { provide: APP_GUARD, useExisting: AppJwtGuard },
   ],
 })
 export class AppModule {}
 ```
 
-### Protected Routes
+## Strategies
+
+### JwtStrategy
+
+Passport strategy for access token validation:
 
 ```typescript
-import { Controller, Get } from '@nestjs/common';
-import { CurrentUser, JwtGuard, UseGuards } from '@zola_do/authorization';
+import { JwtStrategy } from "@zola_do/authorization";
 
-@Controller('profile')
-@UseGuards(JwtGuard)
-export class ProfileController {
-  @Get()
-  getProfile(@CurrentUser() user: any) {
-    return user; // Contains JWT payload (id, email, organization, etc.)
-  }
-}
+// Already registered by AuthorizationModule
+// Customization via override (see above)
 ```
 
-### Anonymous Routes
+### JwtRefreshTokenStrategy
+
+Passport strategy for refresh token validation:
 
 ```typescript
-import { AllowAnonymous } from '@zola_do/authorization';
+import { JwtRefreshTokenStrategy } from "@zola_do/authorization";
 
-@Get('public')
-@AllowAnonymous()
-getPublicData() {
-  return { message: 'No auth required' };
-}
+// Used for token refresh endpoints
+// Validates against JWT_REFRESH_TOKEN_SECRET
 ```
 
-### Permission Guards
+## Environment Variables
 
-Require specific permissions on routes:
+| Variable                    | Description                  | Default  |
+| --------------------------- | ---------------------------- | -------- |
+| `JWT_ACCESS_TOKEN_SECRET`   | Access token signing secret  | Required |
+| `JWT_ACCESS_TOKEN_EXPIRES`  | Access token TTL             | `15m`    |
+| `JWT_REFRESH_TOKEN_SECRET`  | Refresh token signing secret | Required |
+| `JWT_REFRESH_TOKEN_EXPIRES` | Refresh token TTL            | `7d`     |
+| `API_KEY`                   | API key for ApiKeyGuard      | Optional |
 
-```typescript
-import { PermissionsGuard } from '@zola_do/authorization';
+### Token Expiration Format
 
-@Post()
-@UseGuards(JwtGuard, PermissionsGuard('product:create'))
-createProduct(@Body() dto: CreateProductDto) {}
+```
+15m    - 15 minutes
+1h     - 1 hour
+7d     - 7 days
+30d    - 30 days
 ```
 
-### API Key Guard
+## Permission System
 
-Protect routes with API key validation:
+Permissions use pipe-separated OR logic:
 
 ```typescript
-import { ApiKeyGuard } from '@zola_do/authorization';
+// Require any of these permissions
+@UseGuards(PermissionsGuard('admin:write|manager:write|product:create'))
+```
 
-@UseGuards(ApiKeyGuard)
-@Get('api-data')
-getApiData() {}
+### Common Permission Patterns
+
+| Pattern           | Description                               |
+| ----------------- | ----------------------------------------- |
+| `resource:action` | Basic CRUD (product:create, product:read) |
+| `resource:*`      | All actions on resource                   |
+| `*:read`          | Read all resources                        |
+| `admin:*`         | Admin access                              |
+
+## Recommended Imports
+
+Subpath imports are recommended for tree-shaking:
+
+```typescript
+import { AuthorizationModule } from "@zola_do/authorization/module";
+import {
+  JwtGuard,
+  PermissionsGuard,
+  ApiKeyGuard,
+} from "@zola_do/authorization/guards";
+import { AllowAnonymous, CurrentUser } from "@zola_do/authorization/decorators";
+import { AuthHelper } from "@zola_do/authorization/helper";
+import {
+  JwtStrategy,
+  JwtRefreshTokenStrategy,
+} from "@zola_do/authorization/strategy";
 ```
 
-### AuthHelper
+Root import is supported for backward compatibility:
+
+```typescript
+import {
+  AuthorizationModule,
+  JwtGuard,
+  AllowAnonymous,
+  AuthHelper,
+} from "@zola_do/authorization";
+```
+
+## Optional Features
 
-Generate and verify tokens:
+### ThrottlerBehindProxyGuard
+
+Rate limiting guard for applications behind a reverse proxy:
 
 ```typescript
-import { AuthHelper } from '@zola_do/authorization';
+import { ThrottlerBehindProxyGuard } from "@zola_do/authorization/optional/throttler";
 
-@Injectable()
-export class AuthService {
-  constructor(private readonly authHelper: AuthHelper) {}
+@UseGuards(ThrottlerBehindProxyGuard)
+@Controller("api")
+export class ApiController {}
+```
 
-  async login(user: User) {
-    return this.authHelper.generateTokens(user);
-  }
+Requires `@nestjs/throttler` peer dependency.
+
+## API Reference
+
+### Guards
+
+| Guard                           | Description             | Auth Required        |
+| ------------------------------- | ----------------------- | -------------------- |
+| `JwtGuard`                      | Bearer token validation | Yes (global default) |
+| `OptionalJwtGuard`              | Bearer token if present | No                   |
+| `PermissionsGuard(permissions)` | Permission check        | Yes                  |
+| `ApiKeyGuard`                   | API key validation      | Yes                  |
+| `VendorGuard()`                 | Vendor status check     | Yes                  |
+| `ThrottlerBehindProxyGuard`     | Rate limiting           | Configurable         |
+
+### Decorators
+
+| Decorator                | Description                   |
+| ------------------------ | ----------------------------- |
+| `@CurrentUser()`         | Get current user from request |
+| `@CurrentUser(property)` | Get specific property         |
+| `@AllowAnonymous()`      | Skip authentication           |
+
+### Strategies
+
+| Strategy                  | Token Type | Secret                     |
+| ------------------------- | ---------- | -------------------------- |
+| `JwtStrategy`             | Access     | `JWT_ACCESS_TOKEN_SECRET`  |
+| `JwtRefreshTokenStrategy` | Refresh    | `JWT_REFRESH_TOKEN_SECRET` |
+
+### AuthHelper
+
+```typescript
+class AuthHelper {
+  generateTokens(payload: JwtPayload): {
+    accessToken: string;
+    refreshToken: string;
+  };
+  refreshTokens(
+    refreshToken: string,
+  ): Promise<{ accessToken: string; refreshToken: string }>;
+  hashPassword(password: string): Promise<string>;
+  verifyPassword(password: string, hashedPassword: string): Promise<boolean>;
+  generateOtp(length?: number): string;
+  decodeToken(token: string): JwtPayload;
 }
 ```
 
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `JWT_ACCESS_TOKEN_SECRET` | Secret for access token signing |
-| `JWT_REFRESH_TOKEN_SECRET` | Secret for refresh token signing |
-| `JWT_ACCESS_TOKEN_EXPIRES` | Access token TTL (e.g. `15m`) |
-| `JWT_REFRESH_TOKEN_EXPIRES` | Refresh token TTL (e.g. `7d`) |
-| `API_KEY` | API key for `ApiKeyGuard` validation |
+## Troubleshooting
 
-## Exports
+### Q: Token expired errors?
 
-- **Guards:** `JwtGuard`, `JwtRefreshGuard`, `PermissionsGuard`, `ApiKeyGuard`, `VendorGuard`, `OptionalJwtGuard`
-- **Decorators:** `@CurrentUser()`, `@AllowAnonymous()`
-- **Strategies:** `JwtStrategy`, `JwtRefreshTokenStrategy`
-- **Helpers:** `AuthHelper`
-- **Subpath entrypoints:** `@zola_do/authorization/module`, `@zola_do/authorization/decorators`, `@zola_do/authorization/guards`, `@zola_do/authorization/strategy`, `@zola_do/authorization/helper`, `@zola_do/authorization/models`
-- **Root entrypoint:** `@zola_do/authorization` (supported for backward compatibility)
+Check `JWT_ACCESS_TOKEN_EXPIRES` environment variable and ensure clocks are synchronized.
 
-### Optional Features
+### Q: User is undefined in @CurrentUser()?
 
-`ThrottlerBehindProxyGuard` is available as an optional export:
+Ensure `JwtGuard` is active and token is valid:
 
 ```typescript
-import { ThrottlerBehindProxyGuard } from '@zola_do/authorization/optional/throttler';
+@UseGuards(JwtGuard) // Add explicit guard if global is not configured
 ```
 
-When using this guard, install `@nestjs/throttler` in your app.
+### Q: Custom token payload?
+
+Override `JwtStrategy` and `JwtGuard` to implement custom validation.
+
+### Q: Skip guard for specific routes?
+
+```typescript
+@AllowAnonymous() // Works even with global JwtGuard
+```
 
 ## Related Packages
 
 - [@zola_do/crud](../crud) — Uses JwtGuard and PermissionsGuard
 
+## License
+
+ISC
+
 ## Community
 
 - [Contributing](../../CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/authorization",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "JWT auth, guards, strategies for NestJS",
   "author": "zolaDO",
   "license": "ISC",