7c929eb4dc
- Streamlined the README.md for clarity and conciseness. - Deleted outdated documentation files related to Freebit SIM management, SIM management API data flow, and various architectural guides to reduce clutter and improve maintainability. - Updated the last modified date in the README to reflect the latest changes.
77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# Development Authentication Setup
|
||
|
||
## Overview
|
||
|
||
The auth module now exposes a clean facade (`AuthFacade`) and a layered structure. Development conveniences (CSRF bypass, throttling disable) still exist, but code placements and service names have changed. This guide outlines how to configure the dev environment and where to look in the codebase.
|
||
|
||
## File Map
|
||
|
||
| Purpose | Location |
|
||
| --------------------- | ------------------------------------------------------------- | ------------- |
|
||
| Express cookie helper | `apps/bff/src/app/bootstrap.ts` |
|
||
| Auth controller | `modules/auth/presentation/http/auth.controller.ts` |
|
||
| Guards/interceptors | `modules/auth/presentation/http/guards | interceptors` |
|
||
| Passport strategies | `modules/auth/presentation/strategies` |
|
||
| Facade (use-cases) | `modules/auth/application/auth.facade.ts` |
|
||
| Token services | `modules/auth/infra/token` |
|
||
| Rate limiter service | `modules/auth/infra/rate-limiting/auth-rate-limit.service.ts` |
|
||
| Signup/password flows | `modules/auth/infra/workflows` |
|
||
|
||
## Development Environment Flags
|
||
|
||
Add to `.env` as needed:
|
||
|
||
```bash
|
||
# Disable CSRF protection (use only locally)
|
||
DISABLE_CSRF=true
|
||
|
||
# Disable auth rate limits / lockouts
|
||
DISABLE_RATE_LIMIT=true
|
||
DISABLE_ACCOUNT_LOCKING=true
|
||
|
||
# Show detailed validation errors in responses
|
||
EXPOSE_VALIDATION_ERRORS=true
|
||
|
||
# Allow portal origin
|
||
CORS_ORIGIN=http://localhost:3000
|
||
```
|
||
|
||
These flags are consumed in `core/config/auth-dev.config.ts` and by guards/middleware.
|
||
|
||
## CSRF in Development
|
||
|
||
- Middleware (`core/security/middleware/csrf.middleware.ts`) auto-issues stateless tokens.
|
||
- Frontend API client must forward `X-CSRF-Token`; the helper already performs this.
|
||
- To bypass entirely in dev, set `DISABLE_CSRF=true` (middleware checks `devAuthConfig.disableCsrf`).
|
||
|
||
## Rate Limiting in Development
|
||
|
||
- `AuthRateLimitService` uses Redis; if Redis isn’t running, set `DISABLE_RATE_LIMIT=true` to bypass guards.
|
||
- Login, signup, password reset, and refresh flows now go through this centralized service.
|
||
|
||
## Common Troubleshooting
|
||
|
||
1. **CSRF mismatch** – ensure `csrf-secret` cookie and header are both present. Use `/api/security/csrf/token` if you need to fetch manually.
|
||
2. **Rate limit hits** – check headers `X-RateLimit-Remaining` or disable via env flag.
|
||
3. **Redis not running** – dev scripts (`pnpm dev:start`) spin up Redis; otherwise set bypass flags.
|
||
4. **Cookie issues** – confirm `CORS_ORIGIN` matches portal dev origin and browser sends cookies (`credentials: 'include'`).
|
||
|
||
## Production Safeguards
|
||
|
||
- Remove/bypass flags (`DISABLE_*`) in staging/production.
|
||
- Ensure `CSRF_SECRET_KEY` is set in production so tokens are signed with stable key.
|
||
- Tune rate limits via env values (`LOGIN_RATE_LIMIT_LIMIT`, etc.).
|
||
|
||
## Quick Validation Steps
|
||
|
||
1. Start Redis/Postgres via `pnpm dev:start`.
|
||
2. Launch BFF and portal (`pnpm --filter @customer-portal/bff dev`, `pnpm --filter @customer-portal/portal dev`).
|
||
3. In browser, verify CSRF token is returned on first GET (check `X-CSRF-Token` response header).
|
||
4. Attempt login/signup; inspect console for clear warnings if rate limit triggers.
|
||
|
||
## Reference Documentation
|
||
|
||
- `docs/AUTH-MODULE-ARCHITECTURE.md` – full module layout.
|
||
- `docs/STRUCTURE.md` – high-level repo map.
|
||
- `docs/REDIS-TOKEN-FLOW-IMPLEMENTATION.md` – deep dive on refresh token storage.
|