🔐 Structured Prompt — Session Management + 2FA Implementation (Binding)

Objective: Implement backend-authoritative licensed session management with takeover flow and Two-Factor Authentication (2FA) in the Next.js frontend, fully mirroring the existing Blazor behavior.

Constraints:

• Backend C# projects are frozen except for:

  • Session enforcement logic
  • 2FA verification endpoints (if already present or minimal additions)

• Do not refactor existing business logic

• Do not redesign authentication models

• Reuse existing backend mechanisms wherever possible

PART 1 — LICENSED SESSION MANAGEMENT (MANDATORY)

1.1 Data Model (Backend)

Study the users table in the systemdb. You can write the migration script for extending this table.

1.2 Session Validity Rule

A session is ACTIVE if:

IsRevoked = 0
AND LastSeenAt >= NOW - IdleTimeout

IdleTimeout = 10 minutes

1.3 Session Start Flow

Endpoint:

POST /api/auth/session/start
Authorization: Bearer <Firebase JWT>

Backend logic:

1. Resolve UserId + Tenant

2. Fetch active sessions for user

3. If active sessions < MaxConcurrentSessions:

   • Create new session
   • Return SessionToken

4. Else:

   • Return 409 CONFLICT with payload:

{
  "reason": "ACTIVE_SESSION_EXISTS",
  "sessions": [
    {
      "deviceId": "...",
      "lastSeenAt": "..."
    }
  ]
}

1.4 Takeover Flow (“Already signed in”)

Frontend UX:

Show modal:

You are already signed in on another device. Do you want to continue and release that session?

Buttons:

• Continue & Sign Out Other Device • Cancel

Endpoint:

POST /api/auth/session/takeover
Authorization: Bearer <Firebase JWT>

Backend logic:

• Revoke all active sessions
• Create new session
• Return new SessionToken

1.5 Heartbeat

Every authenticated API call must:

UPDATE Users SET LastSeenAt = NOW WHERE SessionId = @SessionId

(Optional ping endpoint allowed)

1.6 Enforcement

For every API request:

• Validate SessionToken
• Ensure active lease
• If invalid → 401

PART 2 — TWO-FACTOR AUTHENTICATION (2FA) PARITY

2.1 Supported Methods (Must Match Blazor)

Implement in Next.js frontend:

✅ Email OTP ✅ Google Authenticator (TOTP)

Reuse existing backend 2FA endpoints and logic.

2.2 2FA Flow

After Firebase login and before session start:

1. Backend checks if user requires 2FA
2. If yes → return:

{
  "requires2FA": true,
  "methods": ["EMAIL", "TOTP"]
}

3. Frontend displays 2FA selection UI
4. User completes verification
5. Backend confirms 2FA
6. Proceed to session start

2.3 Verification Endpoints

Use existing backend endpoints if present:

• Send OTP
• Verify OTP
• Verify TOTP

If minimal endpoints are missing, add without refactoring.

PART 3 — 6-HOUR TRUSTED SESSION WINDOW (CRITICAL)

3.1 Behavior (Must Match Blazor)

If user has completed 2FA successfully:

👉 Do NOT ask for 2FA again for 6 hours

Even if user logs out and logs in again.

3.2 Backend Storage

Add (or reuse) field:

Last2FAVerifiedAt

Associated with:

• User or Session (prefer User-level)

3.3 Logic

On login:

if NOW - Last2FAVerifiedAt < 6 hours:
    skip 2FA
else:
    require 2FA

On successful 2FA:

update Last2FAVerifiedAt = NOW

PART 4 — FRONTEND UX REQUIREMENTS

4.1 Session Conflict UI

• Modal, not alert
• Clear explanation
• No crash
• Cancel option returns to login

4.2 2FA UI

• Method selection screen
• OTP input screen
• TOTP input screen
• Error handling
• Resend OTP option

4.3 Edge Handling

• Session expired → redirect to login
• 2FA failed → retry allowed
• Multiple wrong OTP attempts → follow backend behavior

PART 5 — SECURITY & COMPLIANCE RULES

✅ Backend authoritative for:

• Sessions
• 2FA enforcement

❌ Frontend must not:

• Decide session validity
• Skip 2FA without backend approval

❌ No localStorage for:

• Session authority
• 2FA state

PART 6 — COMPLETION CONFIRMATION (REQUIRED)

After implementation, explicitly confirm:

✔ Licensed sessions enforce concurrency ✔ Takeover flow works ✔ Idle sessions auto-expire ✔ 2FA methods work ✔ 6-hour trusted window respected ✔ Backend authority preserved

📌 FINAL NOTE (NON-NEGOTIABLE)

Do not redesign:

• Authentication stack
• RBAC
• Tenant resolution

Implement exactly as specified.

✅ What this will deliver

When Antigravity completes this:

✔ No credential sharing abuse ✔ No capacity surprise ✔ Full security parity with Blazor ✔ Modern mobile UX ✔ No lockouts ✔ No repeated 2FA annoyance