How to Write Tickets for Azure DevOps (dev.azure.com)

Title: [EPIC] [Auth] Implement Multi-Factor Authentication (MFA) Across Enterprise Portals
Area Path: Identity\Auth
Iteration Path: Release 2026.Q3
Risk: 1 - High | Priority: 1
Tags: security, compliance, epic

Description:
To comply with updated SOC2 requirements and reduce account takeover risks, our core web platform must enforce mandatory Multi-Factor Authentication (MFA) for all administrative and end-user accounts by end of Q3.

Business Value:
- Achieves SOC2 compliance certification.
- Reduces credential stuffing vulnerability by 99%.

Success Criteria (Definition of Done):
- SMS OTP and Authenticator App (TOTP) supported as secondary verification factors.
- 100% of admin users mandated to enroll upon next login.
- Zero downtime deployment across all web and mobile client applications.
- Audit logging enabled for all MFA state changes and failed verification attempts.

Title: [FEATURE] [Auth] Authenticator App (TOTP) Verification & Setup Flow
Parent Link: Epic 10402: Implement Multi-Factor Authentication (MFA)
Area Path: Identity\Auth
Iteration Path: Sprint 42
Story Points: 13 | Risk: 2 - Medium | Priority: 1
Tags: auth, backend, frontend

Description:
Provide users with the ability to pair a time-based one-time password (TOTP) authenticator application (e.g., Google Authenticator, 1Password) with their account, store encrypted secrets, and verify TOTP tokens during login.

Scope Boundaries:
- In Scope: QR code generation, secret key display, TOTP code validation, 10 single-use recovery backup codes.
- Out of Scope: Hardware key support (YubiKey/WebAuthn - handled in separate Feature).

Acceptance Criteria:
- Users can navigate to /settings/mfa and initiate QR code pairing.
- Secret keys are stored in database encrypted at rest using AES-256.
- Login endpoint accepts and validates 6-digit TOTP codes with a 30-second clock skew tolerance window.
- User is issued 10 single-use recovery codes upon successful pairing.

Title: [ISSUE] [API] Implement Redis Sliding-Window Rate Limiting on TOTP Verification Endpoint
Parent Link: Feature 10515: Authenticator App (TOTP) Verification & Setup Flow
Area Path: Identity\Auth
Iteration Path: Sprint 42
Story Points: 3 | Risk: 2 - Medium | Priority: 1
Tags: agent-eligible, backend, redis, security

Description:
As a Platform Security Engineer,
I want to enforce rate limiting on the /api/v1/auth/mfa/verify endpoint,
So that malicious actors cannot brute-force 6-digit TOTP tokens.

Technical Context:
- Target Endpoint: POST /api/v1/auth/mfa/verify
- Tech Stack: Node.js / Express, ioredis client.
- Rate Limit Rule: Max 5 failed attempts per user ID per 15-minute sliding window.

Acceptance Criteria (BDD Format):

Scenario 1: Successful verification under limit
Given an authenticated user submitting a valid 6-digit TOTP code
When the user has submitted fewer than 5 failed attempts in the last 15 minutes
Then return HTTP 200 OK with payload { "status": "verified" }
And reset the failed attempt counter in Redis for this user.

Scenario 2: Exceeding failed attempt threshold
Given a user who has accumulated 5 failed TOTP verification attempts within 15 minutes
When the user submits a 6th verification request (valid or invalid)
Then return HTTP 429 Too Many Requests
And return header Retry-After: <seconds_remaining>
And publish an audit event to events.auth.rate_limited.

Scenario 3: Rate limit expiry
Given a user who was rate limited at timestamp T
When 15 minutes have elapsed since the first failed attempt in the window (T + 900s)
Then allow subsequent verification attempts without returning 429.

Title: [TASK] [DB] Create Redis Key Schema and Helper Class for Sliding Window Counters
Parent Link: Issue 10820: Implement Redis Sliding-Window Rate Limiting on TOTP Endpoint
Area Path: Identity\Auth
Iteration Path: Sprint 42
Original Estimate: 3.0 Hours | Activity: Development
Tags: redis, backend

Description:
Write a modular helper class in src/services/rateLimiter.ts that interacts with Redis using atomic pipeline commands (MULTI/EXEC).

Implementation Steps:
1. Define key structure: rate_limit:mfa_verify:{userId} as a Redis Sorted Set (ZSET).
2. Implement isRateLimited(userId: string): Promise<RateLimitResult> method.
3. Use current UNIX timestamp in milliseconds as both the score and member value.
4. Execute atomic pipeline:
   - ZREMRANGEBYSCORE key 0 (now - 900000) (remove entries older than 15 mins)
   - ZCARD key (count remaining attempts)
   - EXPIRE key 900 (refresh key TTL)
5. Add unit tests in tests/services/rateLimiter.test.ts mocking Redis responses.

Title: [BUG] [API] TOTP Verification Throws HTTP 500 When User ID Contains Uppercase Characters
Area Path: Identity\Auth
Iteration Path: Sprint 42
Severity: 2 - High | Priority: 1 | Risk: 1 - High
Tags: bug, agent-eligible, production-issue

System Info:
- Environment: Staging & Production
- Service: auth-service:v2.14.1
- Database: PostgreSQL 15 / Redis 7.0

Steps to Reproduce:
1. Log in with an account whose user_id contains uppercase letters (e.g., User_992A).
2. Navigate to MFA prompt and enter valid TOTP token 123456.
3. Submit form to POST /api/v1/auth/mfa/verify.

Actual Behavior:
API responds with HTTP 500 Internal Server Error.
Stack trace log: Unhandled Exception: KeyNotFoundException in Redis lookup for rate_limit:mfa_verify:User_992A due to casing mismatch in DB query join.

Expected Behavior:
API should normalize user_id to lowercase before executing database queries and Redis lookups, returning HTTP 200 OK upon valid TOTP submission.

Acceptance Criteria:
- Write a failing integration test in tests/integration/mfa_casing.test.ts passing uppercase user IDs.
- Normalize user_id string inputs to lowercase at API route handling layer (src/routes/mfa.ts).
- Verify bug fix with zero regression on standard lowercase user IDs.
- All existing test suites pass successfully in CI/CD pipeline.