@hazeljs/auth 0.2.0-beta.8 → 0.2.0-beta.81

package/README.md

@@ -1,22 +1,23 @@
 # @hazeljs/auth
 
-**Authentication and JWT Module for HazelJS**
+**JWT authentication, role-based access control, and tenant isolation — in one line of decorators.**
 
-Secure your HazelJS applications with JWT-based authentication, guards, and decorators.
+No Passport config, no middleware soup. `@UseGuards(JwtAuthGuard)` on a controller and you're done.
 
 [![npm version](https://img.shields.io/npm/v/@hazeljs/auth.svg)](https://www.npmjs.com/package/@hazeljs/auth)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/@hazeljs/auth)](https://www.npmjs.com/package/@hazeljs/auth)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 ## Features
 
-- 🔐 **JWT Authentication** - Secure token-based authentication
-- 🛡️ **Auth Guards** - Protect routes with decorators
-- 👤 **User Extraction** - Get current user from request
-- 🔑 **Token Management** - Generate, verify, and refresh tokens
-- ⏰ **Token Expiration** - Configurable expiration times
-- 🎯 **Role-Based Access** - Role and permission guards
-- 🔄 **Refresh Tokens** - Long-lived refresh token support
-- 📊 **Token Blacklisting** - Revoke tokens when needed
+- **JWT signing & verification** via `JwtService` (backed by `jsonwebtoken`)
+- **`JwtAuthGuard`** — `@UseGuards`-compatible guard that verifies Bearer tokens and attaches `req.user`
+- **`RoleGuard`** — configurable role check with **inherited role hierarchy** (admin satisfies manager checks automatically)
+- **`TenantGuard`** — tenant-level isolation; compares the tenant ID on the JWT against a URL param, header, or query string
+- **`@CurrentUser()`** — parameter decorator that injects the authenticated user into controller methods
+- **`@Auth()`** — all-in-one method decorator for JWT + optional role check without `@UseGuards`
+
+---
 
 ## Installation
 
@@ -24,460 +25,475 @@ Secure your HazelJS applications with JWT-based authentication, guards, and deco
 npm install @hazeljs/auth
 ```
 
-## Quick Start
+---
+
+## Setup
 
-### 1. Configure Auth Module
+### 1. Register `JwtModule`
+
+Configure the JWT secret once in your root module. Picks up `JWT_SECRET` and `JWT_EXPIRES_IN` env vars automatically when no options are passed.
 
 ```typescript
 import { HazelModule } from '@hazeljs/core';
-import { AuthModule } from '@hazeljs/auth';
+import { JwtModule } from '@hazeljs/auth';
 
 @HazelModule({
   imports: [
-    AuthModule.forRoot({
-      secret: process.env.JWT_SECRET || 'your-secret-key',
-      expiresIn: '1h',
-      refreshExpiresIn: '7d',
+    JwtModule.forRoot({
+      secret: process.env.JWT_SECRET,   // or set JWT_SECRET env var
+      expiresIn: '1h',                  // or set JWT_EXPIRES_IN env var
+      issuer: 'my-app',                 // optional
+      audience: 'my-users',             // optional
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### 2. Create Auth Service
-
-```typescript
-import { Injectable } from '@hazeljs/core';
-import { AuthService } from '@hazeljs/auth';
+```env
+JWT_SECRET=change-me-in-production
+JWT_EXPIRES_IN=1h
+```
 
-@Injectable()
-export class UserAuthService {
-  constructor(private authService: AuthService) {}
-
-  async login(email: string, password: string) {
-    // Validate credentials
-    const user = await this.validateUser(email, password);
-    
-    if (!user) {
-      throw new Error('Invalid credentials');
-    }
-
-    // Generate tokens
-    const accessToken = await this.authService.generateToken({
-      sub: user.id,
-      email: user.email,
-      roles: user.roles,
-    });
+### 2. Issue tokens at login
 
-    const refreshToken = await this.authService.generateRefreshToken({
-      sub: user.id,
+```typescript
+import { Service } from '@hazeljs/core';
+import { JwtService } from '@hazeljs/auth';
+
+@Service()
+export class AuthLoginService {
+  constructor(private readonly jwt: JwtService) {}
+
+  async login(userId: string, role: string, tenantId?: string) {
+    const token = this.jwt.sign({
+      sub: userId,
+      role,
+      tenantId,           // include for TenantGuard
     });
 
-    return {
-      accessToken,
-      refreshToken,
-      user,
-    };
-  }
-
-  async validateUser(email: string, password: string) {
-    // Your user validation logic
-    const user = await this.userService.findByEmail(email);
-    
-    if (user && await this.comparePasswords(password, user.password)) {
-      return user;
-    }
-    
-    return null;
+    return { accessToken: token };
   }
 }
 ```
 
-### 3. Protect Routes with Guards
+---
 
-```typescript
-import { Controller, Get, Post, Body } from '@hazeljs/core';
-import { UseGuard, AuthGuard, CurrentUser } from '@hazeljs/auth';
-
-@Controller('/api')
-export class ApiController {
-  @Post('/login')
-  async login(@Body() credentials: LoginDto) {
-    return this.authService.login(credentials.email, credentials.password);
-  }
+## Guards
 
-  @Get('/profile')
-  @UseGuard(AuthGuard)
-  getProfile(@CurrentUser() user: any) {
-    return { user };
-  }
+All guards are resolved from the DI container, so they can inject services.
+
+### `JwtAuthGuard`
 
-  @Get('/admin')
-  @UseGuard(AuthGuard)
-  @UseGuard(RoleGuard(['admin']))
-  getAdminData(@CurrentUser() user: any) {
-    return { message: 'Admin only data', user };
+Verifies the `Authorization: Bearer <token>` header. On success it attaches the decoded payload to `req.user` so downstream guards and `@CurrentUser()` can read it.
+
+```typescript
+import { Controller, Get } from '@hazeljs/core';
+import { UseGuards } from '@hazeljs/core';
+import { JwtAuthGuard, CurrentUser, AuthUser } from '@hazeljs/auth';
+
+@UseGuards(JwtAuthGuard)          // protects every route in this controller
+@Controller('/profile')
+export class ProfileController {
+  @Get('/')
+  getProfile(@CurrentUser() user: AuthUser) {
+    return user;
   }
 }
 ```
 
-## Authentication Flow
+Errors thrown:
 
-### Login
+| Condition | Status |
+|---|---|
+| No `Authorization` header | 400 |
+| Header not in `Bearer <token>` format | 400 |
+| Token invalid or expired | 401 |
+
+---
+
+### `RoleGuard`
+
+Checks the authenticated user's `role` against a list of allowed roles. Uses the **role hierarchy** so higher roles automatically satisfy lower-level checks.
 
 ```typescript
-@Post('/auth/login')
-async login(@Body() loginDto: LoginDto) {
-  const user = await this.authService.validateUser(
-    loginDto.email,
-    loginDto.password
-  );
-
-  if (!user) {
-    throw new UnauthorizedException('Invalid credentials');
-  }
+import { UseGuards } from '@hazeljs/core';
+import { JwtAuthGuard, RoleGuard } from '@hazeljs/auth';
 
-  const payload = {
-    sub: user.id,
-    email: user.email,
-    roles: user.roles,
-  };
+@UseGuards(JwtAuthGuard, RoleGuard('manager'))   // manager, admin, superadmin can access
+@Controller('/reports')
+export class ReportsController {}
+```
+
+#### Role hierarchy
+
+The default hierarchy is `superadmin → admin → manager → user`.
 
-  return {
-    accessToken: await this.authService.generateToken(payload),
-    refreshToken: await this.authService.generateRefreshToken(payload),
-  };
-}
+```
+superadmin
+  └─ admin
+       └─ manager
+            └─ user
 ```
 
-### Refresh Token
+So `RoleGuard('user')` passes for **every** role, and `RoleGuard('admin')` only passes for `admin` and `superadmin`.
 
 ```typescript
-@Post('/auth/refresh')
-async refresh(@Body() refreshDto: RefreshDto) {
-  const payload = await this.authService.verifyRefreshToken(
-    refreshDto.refreshToken
-  );
-
-  return {
-    accessToken: await this.authService.generateToken({
-      sub: payload.sub,
-      email: payload.email,
-      roles: payload.roles,
-    }),
-  };
-}
+// Only superadmin and admin can call this:
+@UseGuards(JwtAuthGuard, RoleGuard('admin'))
+
+// Everyone authenticated can call this:
+@UseGuards(JwtAuthGuard, RoleGuard('user'))
+
+// Either role (admin OR moderator, each with their inherited roles):
+@UseGuards(JwtAuthGuard, RoleGuard('admin', 'moderator'))
 ```
 
-### Logout
+#### Custom hierarchy
 
 ```typescript
-@Post('/auth/logout')
-@UseGuard(AuthGuard)
-async logout(@CurrentUser() user: any, @Headers('authorization') token: string) {
-  // Extract token from "Bearer <token>"
-  const jwt = token.split(' ')[1];
-  
-  // Blacklist the token
-  await this.authService.blacklistToken(jwt);
-  
-  return { message: 'Logged out successfully' };
-}
+import { RoleGuard, RoleHierarchy } from '@hazeljs/auth';
+
+const hierarchy = new RoleHierarchy({
+  owner:  ['editor'],
+  editor: ['viewer'],
+  viewer: [],
+});
+
+@UseGuards(JwtAuthGuard, RoleGuard('editor', { hierarchy }))
+// owner and editor pass; viewer does not
 ```
 
-## Guards
+#### Disable hierarchy
+
+```typescript
+@UseGuards(JwtAuthGuard, RoleGuard('admin', { hierarchy: {} }))
+// Only exact 'admin' role passes — no inheritance
+```
+
+Errors thrown:
+
+| Condition | Status |
+|---|---|
+| No `req.user` (guard order wrong) | 401 |
+| User role not in allowed set | 403 |
+
+---
 
-### Auth Guard
+### `TenantGuard`
+
+Enforces tenant-level isolation. Compares `req.user.tenantId` (from the JWT) against the tenant ID found in the request.
+
+**Requires `JwtAuthGuard` to run first** so `req.user` is populated.
+
+#### URL param (default)
 
 ```typescript
-import { AuthGuard } from '@hazeljs/auth';
-
-@Controller('/protected')
-export class ProtectedController {
-  @Get()
-  @UseGuard(AuthGuard)
-  getData(@CurrentUser() user: any) {
-    return { data: 'protected', user };
-  }
-}
+import { JwtAuthGuard, TenantGuard } from '@hazeljs/auth';
+
+// Route: GET /orgs/:tenantId/invoices
+@UseGuards(JwtAuthGuard, TenantGuard())
+@Controller('/orgs/:tenantId/invoices')
+export class InvoicesController {}
 ```
 
-### Role Guard
+#### HTTP header
 
 ```typescript
-import { RoleGuard } from '@hazeljs/auth';
+// Client sends: X-Org-ID: acme
+@UseGuards(JwtAuthGuard, TenantGuard({ source: 'header', key: 'x-org-id' }))
+@Controller('/invoices')
+export class InvoicesController {}
+```
 
-@Controller('/admin')
-export class AdminController {
-  @Get('/users')
-  @UseGuard(AuthGuard)
-  @UseGuard(RoleGuard(['admin']))
-  getAllUsers() {
-    return { users: [] };
-  }
+#### Query string
 
-  @Get('/settings')
-  @UseGuard(AuthGuard)
-  @UseGuard(RoleGuard(['admin', 'superadmin']))
-  getSettings() {
-    return { settings: {} };
-  }
-}
+```typescript
+// Client sends: GET /invoices?org=acme
+@UseGuards(JwtAuthGuard, TenantGuard({ source: 'query', key: 'org' }))
+@Controller('/invoices')
+export class InvoicesController {}
 ```
 
-### Permission Guard
+#### Bypass for privileged roles
+
+Superadmins often need to manage any tenant. Use `bypassRoles` to skip the check for them:
 
 ```typescript
-import { PermissionGuard } from '@hazeljs/auth';
-
-@Controller('/posts')
-export class PostController {
-  @Post()
-  @UseGuard(AuthGuard)
-  @UseGuard(PermissionGuard(['posts:create']))
-  createPost(@Body() createPostDto: CreatePostDto) {
-    return this.postService.create(createPostDto);
-  }
+@UseGuards(
+  JwtAuthGuard,
+  TenantGuard({ bypassRoles: ['superadmin'] })
+)
+@Controller('/orgs/:tenantId/settings')
+export class OrgSettingsController {}
+```
 
-  @Delete('/:id')
-  @UseGuard(AuthGuard)
-  @UseGuard(PermissionGuard(['posts:delete']))
-  deletePost(@Param('id') id: string) {
-    return this.postService.delete(id);
-  }
-}
+#### Custom user field
+
+```typescript
+// JWT payload uses 'orgId' instead of 'tenantId'
+@UseGuards(JwtAuthGuard, TenantGuard({ userField: 'orgId' }))
 ```
 
-## Decorators
+All options:
 
-### @CurrentUser()
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `source` | `'param' \| 'header' \| 'query'` | `'param'` | Where to read the tenant ID from the request |
+| `key` | `string` | `'tenantId'` | Param name / header name / query key |
+| `userField` | `string` | `'tenantId'` | Field on `req.user` holding the user's tenant |
+| `bypassRoles` | `string[]` | `[]` | Roles that skip the check entirely |
 
-Extract the authenticated user from the request:
+Errors thrown:
 
-```typescript
-@Get('/me')
-@UseGuard(AuthGuard)
-getMe(@CurrentUser() user: any) {
-  return user;
-}
+| Condition | Status |
+|---|---|
+| No `req.user` | 401 |
+| `req.user` has no tenant field | 403 |
+| Tenant ID absent from request | 400 |
+| Tenant IDs do not match | 403 |
 
-// With specific property
-@Get('/email')
-@UseGuard(AuthGuard)
-getEmail(@CurrentUser('email') email: string) {
-  return { email };
-}
-```
+---
 
-### @Public()
+### Database-level tenant isolation
 
-Mark routes as public (skip authentication):
+`TenantGuard` blocks cross-tenant HTTP requests, but that alone isn't enough — a bug in service code could still return another tenant's rows. `TenantContext` closes that gap by enforcing isolation at the **query level** using Node.js `AsyncLocalStorage`.
+
+After `TenantGuard` validates the request it calls `TenantContext.enterWith(tenantId)`, which seeds the tenant ID into the current async execution chain. Every service and repository downstream can then call `tenantCtx.requireId()` to get the current tenant without it being passed through every function signature.
 
 ```typescript
-import { Public } from '@hazeljs/auth';
-
-@Controller('/api')
-@UseGuard(AuthGuard) // Applied to all routes
-export class ApiController {
-  @Get('/public')
-  @Public() // This route skips authentication
-  getPublicData() {
-    return { data: 'public' };
+// src/orders/orders.repository.ts
+import { Service } from '@hazeljs/core';
+import { TenantContext } from '@hazeljs/auth';
+
+@Service()
+export class OrdersRepository {
+  constructor(private readonly tenantCtx: TenantContext) {}
+
+  findAll() {
+    const tenantId = this.tenantCtx.requireId();
+    // Scoped automatically — no tenantId parameter needed
+    return db.query('SELECT * FROM orders WHERE tenant_id = $1', [tenantId]);
   }
 
-  @Get('/private')
-  getPrivateData(@CurrentUser() user: any) {
-    return { data: 'private', user };
+  findById(id: string) {
+    const tenantId = this.tenantCtx.requireId();
+    // Even direct ID lookup is tenant-scoped — prevents IDOR attacks
+    return db.query(
+      'SELECT * FROM orders WHERE id = $1 AND tenant_id = $2',
+      [id, tenantId]
+    );
   }
 }
 ```
 
-### @Roles()
-
-Shorthand for role-based access:
+The route setup:
 
 ```typescript
-import { Roles } from '@hazeljs/auth';
-
-@Controller('/admin')
-export class AdminController {
-  @Get('/dashboard')
-  @Roles('admin', 'superadmin')
-  getDashboard() {
-    return { dashboard: 'data' };
+@UseGuards(JwtAuthGuard, TenantGuard())
+@Controller('/orgs/:tenantId/orders')
+export class OrdersController {
+  constructor(private readonly repo: OrdersRepository) {}
+
+  @Get('/')
+  list() {
+    // TenantContext is already seeded by TenantGuard — no need to pass tenantId
+    return this.repo.findAll();
   }
 }
 ```
 
-## Token Management
+The two layers together:
 
-### Generate Token
+| Layer | What it does | What it catches |
+|---|---|---|
+| `TenantGuard` | Rejects requests where `req.user.tenantId !== :tenantId` | Unauthenticated cross-tenant requests |
+| `TenantContext` | Scopes every DB query via AsyncLocalStorage | Bugs, missing guard on a route, IDOR attempts |
+
+For background jobs or tests, you can run code in a specific tenant context explicitly:
 
 ```typescript
-const token = await authService.generateToken({
-  sub: user.id,
-  email: user.email,
-  roles: ['user'],
-  customClaim: 'value',
+// Background job — no HTTP request involved
+await TenantContext.run('acme', async () => {
+  await ordersService.processPendingOrders();
 });
 ```
 
-### Verify Token
+`requireId()` throws with a 500 if called outside any tenant context (guard missing), giving you a clear error instead of silently querying all tenants.
+
+---
+
+### Combining guards
+
+Guards run left-to-right. Always put `JwtAuthGuard` first.
 
 ```typescript
-try {
-  const payload = await authService.verifyToken(token);
-  console.log(payload.sub); // user.id
-  console.log(payload.email);
-} catch (error) {
-  console.error('Invalid token:', error.message);
+@UseGuards(JwtAuthGuard, RoleGuard('manager'), TenantGuard())
+@Controller('/orgs/:tenantId/orders')
+export class OrdersController {
+
+  @Get('/')
+  listOrders(@CurrentUser() user: AuthUser) {
+    return this.ordersService.findAll(user.tenantId!);
+  }
+
+  // Stricter restriction on a single route — only admin (and above) can delete:
+  @UseGuards(RoleGuard('admin'))
+  @Delete('/:id')
+  deleteOrder(@Param('id') id: string) {
+    return this.ordersService.remove(id);
+  }
 }
 ```
 
-### Decode Token (without verification)
+---
 
-```typescript
-const payload = authService.decodeToken(token);
-console.log(payload);
-```
+## `@CurrentUser()` decorator
 
-### Blacklist Token
+Injects the authenticated user (or a specific field from it) directly into the controller parameter.
 
 ```typescript
-await authService.blacklistToken(token);
+import { CurrentUser, AuthUser } from '@hazeljs/auth';
+
+@UseGuards(JwtAuthGuard)
+@Get('/me')
+getMe(@CurrentUser() user: AuthUser) {
+  return user;
+  // { id: 'u1', username: 'alice', role: 'admin', tenantId: 'acme' }
+}
+
+@Get('/role')
+getRole(@CurrentUser('role') role: string) {
+  return { role };
+}
 
-// Check if blacklisted
-const isBlacklisted = await authService.isTokenBlacklisted(token);
+@Get('/tenant')
+getTenant(@CurrentUser('tenantId') tenantId: string) {
+  return { tenantId };
+}
 ```
 
-## Configuration
+---
+
+## `@Auth()` decorator (method-level shorthand)
 
-### Module Configuration
+A lower-level alternative that wraps the handler directly instead of using the `@UseGuards` metadata system. Useful for one-off routes or when you prefer explicit colocation.
 
 ```typescript
-AuthModule.forRoot({
-  // JWT secret key
-  secret: process.env.JWT_SECRET,
-  
-  // Access token expiration
-  expiresIn: '15m',
-  
-  // Refresh token expiration
-  refreshExpiresIn: '7d',
-  
-  // Token issuer
-  issuer: 'hazeljs-app',
-  
-  // Token audience
-  audience: 'hazeljs-users',
-  
-  // Algorithm
-  algorithm: 'HS256',
-  
-  // Token blacklist (requires Redis)
-  blacklist: {
-    enabled: true,
-    redis: redisClient,
-  },
-})
-```
+import { Auth } from '@hazeljs/auth';
 
-### Environment Variables
+@Controller('/admin')
+export class AdminController {
+  @Auth()                         // JWT check only
+  @Get('/dashboard')
+  getDashboard() { ... }
 
-```env
-JWT_SECRET=your-super-secret-key-change-in-production
-JWT_EXPIRES_IN=1h
-JWT_REFRESH_EXPIRES_IN=7d
+  @Auth({ roles: ['admin'] })     // JWT + role check (no hierarchy)
+  @Delete('/user/:id')
+  deleteUser(@Param('id') id: string) { ... }
+}
 ```
 
-## Password Hashing
+> **Note:** `@Auth()` does not use the role hierarchy. Use `@UseGuards(JwtAuthGuard, RoleGuard('admin'))` when hierarchy matters.
+
+---
+
+## `JwtService` API
 
 ```typescript
-import { hash, compare } from '@hazeljs/auth';
+import { JwtService } from '@hazeljs/auth';
 
-// Hash password
-const hashedPassword = await hash('user-password', 10);
+// Sign a token
+const token = jwtService.sign({ sub: userId, role: 'admin', tenantId: 'acme' });
+const token = jwtService.sign({ sub: userId }, { expiresIn: '15m' }); // custom expiry
 
-// Compare password
-const isValid = await compare('user-password', hashedPassword);
+// Verify and decode
+const payload = jwtService.verify(token);   // throws on invalid/expired
+payload.sub       // string
+payload.role      // string
+payload.tenantId  // string | undefined
+
+// Decode without verification (e.g. to read exp before refreshing)
+const payload = jwtService.decode(token);   // returns null on malformed
 ```
 
-## Custom Guards
+---
 
-```typescript
-import { Guard, GuardContext } from '@hazeljs/core';
-import { Injectable } from '@hazeljs/core';
+## `AuthService` API
 
-@Injectable()
-export class CustomAuthGuard implements Guard {
-  async canActivate(context: GuardContext): Promise<boolean> {
-    const request = context.request;
-    const token = request.headers.authorization?.split(' ')[1];
-    
-    if (!token) {
-      return false;
-    }
-
-    try {
-      const payload = await this.authService.verifyToken(token);
-      request.user = payload;
-      return true;
-    } catch {
-      return false;
-    }
-  }
+`AuthService` wraps `JwtService` and returns a typed `AuthUser` object:
+
+```typescript
+interface AuthUser {
+  id: string;
+  username?: string;
+  role: string;
+  [key: string]: unknown;   // all other JWT claims pass through
 }
+
+const user = await authService.verifyToken(token);
+// Returns AuthUser | null (null when token is invalid — never throws)
 ```
 
-## API Reference
+---
 
-### AuthService
+## `RoleHierarchy` API
 
 ```typescript
-class AuthService {
-  generateToken(payload: any, options?: SignOptions): Promise<string>;
-  generateRefreshToken(payload: any): Promise<string>;
-  verifyToken(token: string): Promise<any>;
-  verifyRefreshToken(token: string): Promise<any>;
-  decodeToken(token: string): any;
-  blacklistToken(token: string): Promise<void>;
-  isTokenBlacklisted(token: string): Promise<boolean>;
-}
-```
+import { RoleHierarchy, DEFAULT_ROLE_HIERARCHY } from '@hazeljs/auth';
 
-### Guards
+const h = new RoleHierarchy(DEFAULT_ROLE_HIERARCHY);
 
-- `AuthGuard` - Validates JWT token
-- `RoleGuard(roles: string[])` - Checks user roles
-- `PermissionGuard(permissions: string[])` - Checks user permissions
+h.satisfies('superadmin', 'user')  // true  — full chain
+h.satisfies('manager', 'admin')    // false — no upward inheritance
+h.resolve('admin')                 // Set { 'admin', 'manager', 'user' }
+```
 
-### Decorators
+---
 
-- `@CurrentUser(property?: string)` - Extract user from request
-- `@Public()` - Skip authentication
-- `@Roles(...roles: string[])` - Require specific roles
+## Custom guards
 
-## Examples
+Implement `CanActivate` from `@hazeljs/core` for fully custom logic:
 
-See the [examples](../../example/src/auth) directory for complete working examples.
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@hazeljs/core';
 
-## Testing
+@Injectable()
+export class ApiKeyGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest() as { headers: Record<string, string> };
+    return req.headers['x-api-key'] === process.env.API_KEY;
+  }
+}
+```
 
-```bash
-npm test
+The `ExecutionContext` also exposes the fully parsed `RequestContext` (params, query, headers, body, user):
+
+```typescript
+canActivate(context: ExecutionContext): boolean {
+  const ctx = context.switchToHttp().getContext();
+  const orgId = ctx.params['orgId'];
+  const user  = ctx.user;
+  // ...
+}
 ```
 
-## Contributing
+---
 
-Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+## Environment variables
 
-## License
+| Variable | Default | Description |
+|---|---|---|
+| `JWT_SECRET` | *(required)* | Secret used to sign and verify tokens |
+| `JWT_EXPIRES_IN` | `1h` | Default token lifetime |
+| `JWT_ISSUER` | — | Optional `iss` claim |
+| `JWT_AUDIENCE` | — | Optional `aud` claim |
 
-MIT © [HazelJS](https://hazeljs.com)
+---
 
 ## Links
 
 - [Documentation](https://hazeljs.com/docs/packages/auth)
 - [GitHub](https://github.com/hazel-js/hazeljs)
-- [Issues](https://github.com/hazeljs/hazel-js/issues)
-- [Discord](https://discord.gg/hazeljs)
+- [Issues](https://github.com/hazel-js/hazeljs/issues)
+- [Discord](https://discord.com/channels/1448263814238965833/1448263814859456575)