ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/docs/development/auth/module.md

157 lines
6.3 KiB
Markdown
Raw Permalink Normal View History

Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
# 🔐 Authentication Module Architecture (2025)
## Overview
The authentication feature in `apps/bff` now follows a layered structure that separates HTTP concerns, orchestration logic, and infrastructure details. This document explains the layout, responsibilities, and integration points so new contributors can quickly locate code and understand the data flow.
Enhance JWT handling and authentication flow - Introduced support for previous JWT secrets in the environment configuration to facilitate key rotation. - Refactored the JoseJwtService to manage multiple signing and verification keys, improving security during token validation. - Updated the AuthTokenService to include family identifiers for refresh tokens, enhancing session management and security. - Modified the PasswordWorkflowService and SignupWorkflowService to return session metadata instead of token strings, aligning with security best practices. - Improved error handling and token revocation logic in the TokenBlacklistService and AuthTokenService to prevent replay attacks. - Updated documentation to reflect changes in the authentication architecture and security model.
2025-12-12 15:29:58 +09:00
## Security Model (TL;DR)
- **Token storage**: Access/refresh token strings are stored in **httpOnly cookies** set by the BFF.
- **API responses**: Auth endpoints return **`user` + `session` (expiry metadata)** — **token strings are never returned to the browser**.
- **Access token validation**: Per-request validation is handled by `GlobalAuthGuard`:
- verifies JWT signature/claims
- rejects wrong token type (expects `type: "access"` when present)
- checks Redis blacklist (revoked access tokens)
- **Refresh token rotation**: `/api/auth/refresh` uses Redis-backed rotation with reuse detection and an **absolute refresh lifetime** (no indefinite extension).
- **CSRF**: Portal fetches token via `GET /api/security/csrf/token` and sends it as `X-CSRF-Token` on unsafe requests.
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
```
modules/auth/
├── application/
│ └── auth.facade.ts
├── presentation/
│ ├── http/
│ │ ├── auth.controller.ts
│ │ ├── guards/
│ │ └── interceptors/
│ └── strategies/
├── infra/
│ ├── token/
│ ├── rate-limiting/
│ └── workflows/
├── decorators/
├── domain/ (reserved for future policies/types)
└── utils/
```
### Layer Responsibilities
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
| Layer | Purpose |
| -------------- | --------------------------------------------------------------------------- |
| `presentation` | HTTP surface area (controllers, guards, interceptors, Passport strategies). |
| `application` | Use-case orchestration (`AuthFacade`), coordinating infra + audit logging. |
| `infra` | Technical services: token issuance, rate limiting, WHMCS/SF workflows. |
| `decorators` | Shared Nest decorators (e.g., `@Public`). |
| `domain` | (Future) domain policies, constants, pure type definitions. |
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
## Presentation Layer
### Controllers (`presentation/http/auth.controller.ts`)
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- Routes mirror previous `auth-zod.controller.ts` functionality.
- All validation still uses Zod schemas from `@customer-portal/domain` applied via `ZodValidationPipe`.
- Cookies are managed with `setSecureCookie` helper registered in `bootstrap.ts`.
### Guards
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- `GlobalAuthGuard`: wraps Passport JWT, checks blacklist via `TokenBlacklistService`.
- `AuthThrottleGuard`: Nest Throttler-based guard for general rate limits.
- `FailedLoginThrottleGuard`: uses `AuthRateLimitService` for login attempt limiting.
### Interceptors
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- `LoginResultInterceptor`: ties into `FailedLoginThrottleGuard` to clear counters on success/failure.
### Strategies (`presentation/strategies`)
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- `LocalStrategy`: delegates credential validation to `AuthFacade.validateUser`.
- `JwtStrategy`: loads user via `UsersService` and maps to public profile.
## Application Layer
### `AuthFacade`
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- Aggregates all auth flows: login/logout, signup, password flows, WHMCS link, token refresh, session logout.
- Injects infrastructure services (token, workflows, rate limiting), audit logging, config, and Prisma.
- Acts as single DI target for controllers, strategies, and guards.
## Infrastructure Layer
### Token (`infra/token`)
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- `token.service.ts`: issues/rotates access + refresh tokens, enforces Redis-backed refresh token families.
- `token-blacklist.service.ts`: stores revoked access tokens.
### Rate Limiting (`infra/rate-limiting/auth-rate-limit.service.ts`)
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- Built on `rate-limiter-flexible` with Redis storage.
- Exposes methods for login, signup, password reset, refresh token throttling.
- Handles CAPTCHA escalation via headers (config-driven, see env variables).
### Workflows (`infra/workflows`)
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
- `signup-workflow.service.ts`: orchestrates Salesforce + WHMCS checks and user creation.
- `password-workflow.service.ts`: request reset, change password, set password flows.
- `whmcs-link-workflow.service.ts`: links existing WHMCS accounts with portal users.
## Configuration & Env
Relevant env keys validated in `core/config/env.validation.ts`:
```bash
# Auth rate limits
LOGIN_RATE_LIMIT_LIMIT=5
LOGIN_RATE_LIMIT_TTL=900000
AUTH_REFRESH_RATE_LIMIT_LIMIT=10
AUTH_REFRESH_RATE_LIMIT_TTL=300000
Enhance JWT handling and authentication flow - Introduced support for previous JWT secrets in the environment configuration to facilitate key rotation. - Refactored the JoseJwtService to manage multiple signing and verification keys, improving security during token validation. - Updated the AuthTokenService to include family identifiers for refresh tokens, enhancing session management and security. - Modified the PasswordWorkflowService and SignupWorkflowService to return session metadata instead of token strings, aligning with security best practices. - Improved error handling and token revocation logic in the TokenBlacklistService and AuthTokenService to prevent replay attacks. - Updated documentation to reflect changes in the authentication architecture and security model.
2025-12-12 15:29:58 +09:00
# JWT hardening (optional but recommended in prod)
JWT_ISSUER=customer-portal
JWT_AUDIENCE=portal
JWT_SECRET_PREVIOUS=oldsecret1,oldsecret2
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
# CAPTCHA options (future integration)
AUTH_CAPTCHA_PROVIDER=none # none|turnstile|hcaptcha
AUTH_CAPTCHA_SECRET=
AUTH_CAPTCHA_THRESHOLD=0
AUTH_CAPTCHA_ALWAYS_ON=false
# CSRF
CSRF_TOKEN_EXPIRY=3600000
CSRF_SECRET_KEY=... # recommended in prod
CSRF_COOKIE_NAME=csrf-secret
CSRF_HEADER_NAME=X-CSRF-Token
Enhance JWT handling and authentication flow - Introduced support for previous JWT secrets in the environment configuration to facilitate key rotation. - Refactored the JoseJwtService to manage multiple signing and verification keys, improving security during token validation. - Updated the AuthTokenService to include family identifiers for refresh tokens, enhancing session management and security. - Modified the PasswordWorkflowService and SignupWorkflowService to return session metadata instead of token strings, aligning with security best practices. - Improved error handling and token revocation logic in the TokenBlacklistService and AuthTokenService to prevent replay attacks. - Updated documentation to reflect changes in the authentication architecture and security model.
2025-12-12 15:29:58 +09:00
# Redis failure-mode (security vs availability tradeoff)
AUTH_BLACKLIST_FAIL_CLOSED=false
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
```
Refer to `DEVELOPMENT-AUTH-SETUP.md` for dev-only overrides (`DISABLE_CSRF`, etc.).
## CSRF Summary
Enhance authentication and CSRF protection mechanisms - Introduced optional JWT issuer and audience configurations in the JoseJwtService for improved token validation. - Updated CSRF middleware to streamline token validation and enhance security measures. - Added new environment variables for JWT issuer and audience, allowing for more flexible authentication setups. - Refactored CSRF controller and middleware to improve token handling and security checks. - Cleaned up and standardized cookie paths for access and refresh tokens in the AuthController. - Enhanced error handling in the TokenBlacklistService to manage Redis availability more effectively.
2025-12-12 15:00:11 +09:00
- `core/security/controllers/csrf.controller.ts` issues stateless HMAC tokens at `GET /api/security/csrf/token`.
- Portal fetches the token once and sends it as `X-CSRF-Token` for unsafe methods.
- `core/security/middleware/csrf.middleware.ts` validates `X-CSRF-Token` for unsafe methods and skips safe methods/exempt routes.
Refactor authentication module to improve structure and maintainability. Introduce `AuthFacade` for streamlined access to authentication services, and reorganize controllers, guards, and strategies into a clearer directory structure. Remove deprecated `auth-zod.controller.ts` and consolidate token management services. Update environment variables and documentation to reflect changes in the authentication setup. Enhance validation with `Zod` integration for improved data handling across endpoints.
2025-10-02 16:33:25 +09:00
## Rate Limiting Summary
- `AuthRateLimitService` provides atomic Redis counters via `rate-limiter-flexible`.
- Guards/workflows invoke `consume*` methods and respond with rate-limit errors/headers.
## Integration Notes
- Use absolute imports (e.g., `@bff/modules/auth/application/auth.facade`) to avoid fragile relative paths.
- `AuthModule` exports `AuthFacade` and token services so other modules (e.g., admin tasks) can reuse them.
- Frontend API calls remain unchanged; payloads validated with existing Zod schemas.
## Future Work (Optional Enhancements)
- Populate `domain/` with password policy objects, role constants, etc.
- Add `application/commands/` for discrete use-case handlers if flows expand.
- Introduce MFA/session management when business requirements demand it.
---
**Last Updated:** 2025-10-02
Reference in New Issue Copy Permalink