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:

# 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.