◆ Auth Microservice Docs

A production-grade authentication & authorization microservice built on Node.js/Express with TypeScript strict mode. It implements industry-standard security patterns including JWT RS256 asymmetric signing, Argon2id password hashing, TOTP-based MFA, refresh token rotation with family-based reuse detection, Redis-backed sliding window rate limiting, and a comprehensive audit trail.

The system uses a dual-token architecture with RS256 asymmetric JWTs:

Follows a modular monolith pattern with feature-based organization. Each module has its own controller, service, routes, validation schemas, and tests.

Complete Authentication Lifecycle

Entity Relationship

Key Design Decisions

• Token hashing: Never store raw tokens. All tokens (refresh, email verify, password reset) stored as SHA-256 hashes. If the DB is breached, tokens are useless.
• Refresh token families: Each login session creates a family UUID. All rotated tokens share it. If a revoked token is replayed, the entire family gets nuked.
• Soft deletes: Users have deletedAt instead of hard deletes. Preserves audit trail integrity.
• MFA secret encryption: TOTP secrets encrypted at rest with AES-256-GCM using a dedicated MFA_ENCRYPTION_KEY. Format: iv:authTag:ciphertext (all hex).
• Backup codes: 8 codes generated per MFA enrollment, each SHA-256 hashed. One-time use (usedAt timestamp marks consumption).

1. Password Security: Argon2id

// OWASP 2023 recommended parameters
const ARGON2_OPTIONS = {
  type: argon2.argon2id,     // Hybrid: resists GPU + side-channel attacks
  memoryCost: 65536,        // 64 MiB per hash
  timeCost: 3,              // 3 iterations
  parallelism: 4,           // 4 threads
};

Each hash includes a random salt. The output is self-describing: $argon2id$v=19$m=65536,t=3,p=4$SALT$HASH. Verification is constant-time to prevent timing attacks.

2. JWT Architecture: RS256

// Asymmetric signing: private key signs, public key verifies
// This means microservices only need the PUBLIC key to verify tokens
const signOptions: SignOptions = {
  algorithm: 'RS256',
  expiresIn: '15m',        // Short-lived access tokens
  subject: payload.userId,
  jwtid: crypto.randomUUID(),  // Unique per token (prevents same-second collisions)
};

// Access token payload
{ userId, email, role, type: 'access', iat, exp, sub, jti }

// Refresh token payload (adds family for rotation tracking)
{ userId, email, role, type: 'refresh', family: 'uuid', iat, exp, sub, jti }

3. Sliding Window Rate Limiter

// Redis Sorted Set algorithm (per-IP, per-endpoint)
// Key: rl:auth:{ip}:{normalized_path}

pipeline.zremrangebyscore(key, '-inf', windowStart);  // 1. Prune old entries
pipeline.zcard(key);                                    // 2. Count remaining
pipeline.zadd(key, now, uuid);                          // 3. Add this request
pipeline.pexpire(key, windowMs);                        // 4. Auto-expire key

// Global: 100 req / 60s per IP
// Auth endpoints: 5 req / 60s per IP (brute-force protection)
// Path normalization: /users/abc-123 → /users/:id (prevents key explosion)

4. Token Blacklist (Logout)

// On logout, add access token to Redis with TTL = remaining lifetime
const remainingSeconds = payload.exp - Math.floor(Date.now() / 1000);
await redis.set(`bl:${accessToken}`, '1', 'EX', remainingSeconds);

// authenticate middleware checks EVERY request:
const isBlacklisted = await redis.get(`bl:${token}`);
if (isBlacklisted) throw new AuthenticationError('Token has been revoked');

5. MFA: TOTP + AES-256-GCM

// TOTP secret encrypted at rest
// encrypt(): iv (12 bytes) + AES-256-GCM + authTag (16 bytes)
// Storage format: "hex(iv):hex(authTag):hex(ciphertext)"
// Key: MFA_ENCRYPTION_KEY env var (256-bit / 64 hex chars)

// Verification allows ±30s window (standard TOTP tolerance)
authenticator.check(userCode, decryptedSecret); // true/false

Execution Order (app.ts)

// ─── Global (applied to ALL routes) ────────────────
app.use(securityHeaders);       // 1. Helmet: CSP, HSTS, X-Frame-Options, nosniff
app.use(corsMiddleware);         // 2. CORS whitelist from CORS_ORIGINS env
app.use(compression());           // 3. Gzip responses
app.use(express.json({limit: '10kb'}));  // 4. Body parser (DoS protection)
app.use(cookieParser());          // 5. Parse Cookie header
app.use(requestLogger);          // 6. X-Request-ID, duration, field redaction
app.use(metricsMiddleware);       // 7. Prometheus counters & histograms
app.use(globalRateLimiter);       // 8. 100 req/60s per IP (Redis sorted set)
app.use(passport.initialize());   // 9. OAuth strategy registration

// ─── Route-specific (applied per-route) ────────────
// authRateLimiter               // 5 req/60s (on /login, /register, /forgot-password)
// authenticate                  // JWT verify + Redis blacklist check
// authorize('ADMIN')            // Role-based access control
// validateRequest(schema)       // Zod validation on body/params/query

// ─── Global catch-all ──────────────────────────────
app.use(errorHandler);           // Normalizes ALL errors to standard envelope

See the Authentication Lifecycle section for the full registration flow diagram. Key implementation details:

• Email verification token: crypto.randomBytes(32).toString('hex') → 64 hex chars
• Stored as SHA-256 hash (if DB is breached, raw tokens are useless)
• Email sent via void emailService.sendVerificationEmail() (fire-and-forget, errors logged but don't break registration)
• ConflictError (409) on duplicate email, not generic 400

Account Lockout Implementation

// Redis-backed counter with TTL (survives server restarts)
const key = `failed_login:${userId}`;
const attempts = await redis.incr(key);     // Atomic increment
await redis.expire(key, 900);               // 15 min TTL

if (attempts >= 5) {
  await prisma.user.update({
    where: { id: user.id },
    data: { lockedUntil: new Date(Date.now() + 15 * 60 * 1000) },
  });
}

MFA Challenge Flow

When user.mfaEnabled === true, login returns a short-lived MFA challenge token (type: mfa_challenge, 15min expiry) instead of full tokens. The client must then call POST /mfa/verify-login with this token + a valid TOTP code to receive full access/refresh tokens.

TOTP secrets stored encrypted: AES-256-GCM(secret, MFA_ENCRYPTION_KEY) → iv:authTag:ciphertext. Decrypted only during verification.

Token Lifecycle State Machine

Token Cleanup Job

// Runs hourly via setInterval (unref'd so it won't prevent process exit)
await prisma.refreshToken.deleteMany({
  where: { OR: [
    { expiresAt: { lt: now } },                      // Expired tokens
    { revokedAt: { not: null, lt: revokedCutoff } },  // Revoked >24h ago
  ]},
});

Two-step process: POST /auth/forgot-password (generates token) → POST /auth/reset-password/:token (consumes token). The reset token is a 32-byte random hex string, stored as SHA-256. Expiry: 1 hour (PASSWORD_RESET_EXPIRY_MS = 60 * 60 * 1000). After reset, all user's refresh tokens are revoked with revokedAt = now() to force re-authentication on every device.

Implemented via Passport.js strategies. Each strategy is conditionally loaded. If the client ID env var is not set, the strategy is skipped with a warning log. Account resolution logic: (1) find by OAuthAccount(provider, providerId), (2) find by email match, (3) create new user with emailVerified: true.

All admin routes are guarded by authenticate + authorize('ADMIN') middleware. The authorize middleware checks req.userRole (set by authenticate). The admin service supports paginated queries with Zod-validated params: page, limit (max 100), role filter, status filter (active/locked/deleted), dateFrom/dateTo, search (email fuzzy match), sortBy/sortOrder.

Error Class Hierarchy

AppError (base)
  ├── AuthenticationError  // 401 - invalid token, wrong password
  ├── AuthorizationError   // 403 - insufficient role
  ├── ValidationError      // 400 - Zod schema failures (includes field errors[])
  ├── NotFoundError        // 404 - user/resource not found
  ├── ConflictError        // 409 - duplicate email
  ├── RateLimitError       // 429 - too many requests
  └── InternalError        // 500 - isOperational=false (masked in prod)

The global errorHandler middleware catches all errors, maps Prisma errors (P2002 → 409, P2025 → 404), Zod errors to ValidationError, and masks non-operational errors in production (returns generic "An unexpected error occurred" while logging full stack trace).

Multi-Stage Dockerfile

# Stage 1: Build (full Node, all devDeps)
FROM node:20-alpine AS builder
RUN npm ci                    # Deterministic install
RUN npx prisma generate        # Generate typed client
RUN npm run build              # tsc → dist/

# Stage 2: Production (minimal image)
FROM node:20-alpine
RUN apk add --no-cache dumb-init openssl
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/public ./public
USER node                      # Non-root user
CMD ["dumb-init", "node", "dist/server.js"]  # PID 1 handler

docker-compose.yml

5 services on a shared bridge network (auth-network). App depends on postgres/redis health checks. Postgres uses pg_isready, Redis uses redis-cli ping. Data persisted via named volumes. Docker entrypoint generates RSA keys if missing, runs Prisma migrations, and seeds in dev.

Prometheus Metrics Collected

Logging via Pino (JSON in production, pretty-printed in dev). Automatic field redaction for passwords, tokens, and secrets. Every log entry includes requestId for distributed tracing.

Test Architecture

// Coverage thresholds (jest.config.js)
coverageThreshold: {
  global: { branches: 70, functions: 80, lines: 80, statements: 80 }
}

// Test commands
npm run test:unit        // src/**/*.test.ts (86 tests)
npm run test:integration // tests/integration/ (40 tests, real DB)
npm run test:e2e         // tests/e2e/ (10 steps, sequential flow)

Key Testing Patterns

• Unit tests: Pure function testing (argon2 roundtrip, JWT sign/verify, crypto encrypt/decrypt, Zod schema edge cases). No DB or network calls.
• Integration tests: Supertest against real Express app with real Prisma (test DB) and real Redis. afterEach cleans all tables.
• E2E tests: Sequential 10-step journey using setup-e2e.ts (no afterEach cleanup, only afterAll) so state persists between steps.
• Test helpers: factories.ts provides createTestUser() and createTestApp() with TestAgent for cookie/header persistence.
• TypeScript config: tsconfig.test.json extends base with noUnusedLocals: false to allow test-scoped variables.