Assist_Design/docs/development/auth/development-setup.md

# 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

# Skip OTP verification during login (direct login after credentials)
SKIP_OTP=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.