sequenceDiagram participant U as 📱 User (eToro Plus) participant G as 🌐 API Gateway participant S as ⚙️ 2FA Service participant V as 🔐 Vault participant DB as 💾 PostgreSQL U->>G: POST /2fa/totp/setup (Bearer token) G->>G: Validate JWT + rate limit G->>S: Forward request S->>S: Generate TOTP secret (otplib) S->>V: Encrypt secret with AES-256-GCM V-->>S: Encrypted blob + IV S->>DB: Store encrypted secret (pending) S-->>U: { secret, qrUri: "otpauth://totp/eToro:user@email?secret=..." } Note over U: User scans QR / adds to authenticator U->>G: POST /2fa/totp/verify { code: "738204" } G->>S: Forward S->>V: Decrypt secret S->>S: Verify TOTP code (otplib.authenticator.check) S->>DB: Mark 2FA enabled, store recovery codes S-->>U: { enabled: true, backupCodes: [...] } S->>DB: INSERT audit_log (2fa_totp_enabled)

sequenceDiagram participant U as 📱 User participant G as 🌐 Gateway participant A as 🔑 Auth Service participant S as ⚙️ 2FA Service participant R as 📦 Redis U->>G: POST /auth/login { email, password } G->>A: Validate credentials A-->>G: { requires2FA: true, tempToken } G-->>U: 200 { requires2FA: true, tempToken } U->>G: POST /2fa/totp/validate { tempToken, code } G->>S: Validate TOTP S->>R: Check rate limit (userId) alt Rate limit exceeded S-->>U: 429 Too Many Requests (lockout 5min) else S->>S: Verify code (window ±1 step) S->>R: Check used codes (replay protection) alt Valid & not replayed S->>R: Store used code (TTL 90s) S-->>U: 200 { accessToken, refreshToken } else Invalid S->>R: Increment failure counter S-->>U: 401 Invalid code end end

sequenceDiagram participant U as 📱 User participant S as ⚙️ 2FA Service participant R as 📦 Redis participant DB as 💾 PostgreSQL U->>S: POST /2fa/webauthn/register/options S->>S: generateRegistrationOptions() S->>R: Store challenge (TTL 120s) S-->>U: { challenge, rp, user, pubKeyCredParams, ... } Note over U: Device biometric/PIN prompt U->>S: POST /2fa/webauthn/register/verify { attestation } S->>R: Retrieve & delete challenge S->>S: verifyRegistrationResponse() S->>DB: Store credential (credentialId, publicKey, counter) S-->>U: { registered: true, credentialId } S->>DB: INSERT audit_log (webauthn_registered)

sequenceDiagram participant U as 📱 User participant S as ⚙️ 2FA Service participant R as 📦 Redis participant DB as 💾 PostgreSQL U->>S: POST /2fa/webauthn/authenticate/options { tempToken } S->>DB: Fetch user's credentials S->>S: generateAuthenticationOptions() S->>R: Store challenge (TTL 120s) S-->>U: { challenge, allowCredentials, ... } Note over U: Biometric / PIN verification U->>S: POST /2fa/webauthn/authenticate/verify { assertion } S->>R: Retrieve & delete challenge S->>DB: Fetch credential publicKey S->>S: verifyAuthenticationResponse() S->>DB: Update credential counter (clone detection) S-->>U: { accessToken, refreshToken }

sequenceDiagram participant U as 📱 User participant S as ⚙️ 2FA Service participant DB as 💾 PostgreSQL Note over U,S: Generation (during 2FA setup) S->>S: Generate 10 codes (crypto.randomBytes) S->>S: Hash each code (bcrypt, cost 10) S->>DB: Store hashed codes S-->>U: { codes: ["XXXX-XXXX", ...] } (shown once) Note over U,S: Usage (during login) U->>S: POST /2fa/backup-codes/verify { code: "ABCD-1234" } S->>DB: Fetch unused hashed codes S->>S: bcrypt.compare against each alt Match found S->>DB: Mark code as used + timestamp S-->>U: 200 { accessToken } + warning: N codes remaining else No match S-->>U: 401 Invalid backup code end

sequenceDiagram participant U as 📱 User participant S as ⚙️ 2FA Service participant SMS as 📨 SMS Provider Note over U,SMS: User currently has SMS-based 2FA U->>S: POST /2fa/totp/setup S-->>U: { secret, qrUri } + prompt to upgrade U->>U: Scan QR, enter code U->>S: POST /2fa/totp/verify { code } S->>S: Verify TOTP works S->>S: Disable SMS fallback S->>SMS: Remove phone from SMS 2FA pool S-->>U: { method: "totp", smsMigrated: true } S->>S: Log audit: sms_to_totp_migration

sequenceDiagram participant U as 👤 User participant B as 🌐 Browser (Conditional UI) participant S as ⚙️ eToro Server U->>B: Navigate to etoro.com/login B->>S: POST /passkey/authenticate/options
{mediation: "conditional"} S-->>B: {challenge} (no allowCredentials — discoverable) B->>B: Autofill UI shows available passkeys
"Sign in as yoni@etoro.com 🔑" U->>B: Taps passkey suggestion B->>B: Biometric verification (Face ID) B->>S: POST /passkey/authenticate/verify
{assertion with userHandle} S->>S: Look up user by userHandle S->>S: Verify assertion signature S-->>B: {accessToken} — Logged in! ✅ Note over U,S: No username. No password. No OTP. Just biometrics.

sequenceDiagram participant U as 📱 User participant A as 📲 eToro App participant S as ⚙️ 2FA Service participant R as 📦 Redis participant DB as 💾 PostgreSQL U->>A: Tap "Add Passkey" in Security settings A->>S: POST /passkey/register/options S->>S: generateRegistrationOptions({
rpName: "eToro", rpID: "etoro.com",
userName: user.email,
attestationType: "none",
residentKey: "required",
userVerification: "preferred"
}) S->>R: Store challenge (key=userId, TTL=120s) S-->>A: {challenge, rp, user, pubKeyCredParams, excludeCredentials} A->>A: startRegistration(options) Note over U,A: OS biometric prompt:
"Create a passkey for etoro.com?"
Face ID / Touch ID / PIN U->>A: Authenticates with biometric A->>S: POST /passkey/register/verify {attestationResponse} S->>R: Retrieve + delete challenge S->>S: verifyRegistrationResponse({
expectedChallenge, expectedOrigin,
expectedRPID: "etoro.com"
}) S->>DB: INSERT webauthn_credentials {
credential_id, public_key, counter: 0,
transports, device_type, backed_up,
aaguid, device_name
} S->>DB: UPDATE user_2fa_settings SET webauthn_enabled=true S-->>A: {registered: true, credentialId, deviceName} A->>U: ✅ "Passkey created for iPhone 15 Pro"

sequenceDiagram participant U as 👤 User participant A as 📲 eToro App participant S as ⚙️ 2FA Service participant R as 📦 Redis participant DB as 💾 PostgreSQL U->>A: Enter email + password A->>S: POST /auth/login S-->>A: {requires2FA: true, tempToken, methods: ["passkey","totp"]} A->>A: Show "Use Passkey" button (preferred) U->>A: Tap "Sign in with Passkey" A->>S: POST /passkey/authenticate/options {tempToken} S->>DB: Fetch user's credentials S->>S: generateAuthenticationOptions({
allowCredentials: user.credentials,
userVerification: "preferred"
}) S->>R: Store challenge (TTL=120s) S-->>A: {challenge, allowCredentials, timeout} A->>A: startAuthentication(options) Note over U,A: Biometric prompt:
"Sign in to etoro.com"
Face ID → ✅ U->>A: Biometric verified A->>S: POST /passkey/authenticate/verify {assertion} S->>R: Retrieve + delete challenge S->>DB: Fetch credential public key S->>S: verifyAuthenticationResponse() S->>DB: UPDATE counter, last_used_at S-->>A: {accessToken, refreshToken} ✅ A->>U: Welcome back! 🎉