Add Fraudulent Login Evaluation Enhancement Proposal

Taskfile.yaml

@@ -0,0 +1,13 @@
+version: '3'
+
+includes:
+  # Documentation tasks
+  docs:
+    taskfile: ./docs/Taskfile.yaml
+    dir: ./docs
+
+tasks:
+  generate:
+    desc: Run code generation (deepcopy, defaults)
+    deps:
+      - task: docs:generate

docs/Taskfile.yaml

@@ -0,0 +1,69 @@
+version: '3'
+
+vars:
+  DIAGRAMS_DIR: "{{.ROOT_DIR}}/docs/diagrams"
+  OUTPUT_FORMAT: "png"
+  PLANTUML_IMAGE: plantuml/plantuml:1.2026.4
+
+tasks:
+  generate:
+    desc: Generate all documentation artifacts (diagrams, etc.)
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:
+    desc: Generate all architecture diagrams from PlantUML
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:render:
+    desc: Render PlantUML diagrams to PNG format using Docker
+    cmds:
+      - |
+        set -e
+        echo "Rendering PlantUML diagrams..."
+        echo ""
+
+        # Check if PlantUML files exist
+        if ! ls {{.DIAGRAMS_DIR}}/*.puml >/dev/null 2>&1; then
+          echo "❌ Error: PlantUML source files (*.puml) not found in {{.DIAGRAMS_DIR}}"
+          exit 1
+        fi
+
+        # Render using Docker (no local installation required)
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -t{{.OUTPUT_FORMAT}} \
+          /data/*.puml
+
+        echo ""
+        echo "✅ Diagrams rendered in {{.DIAGRAMS_DIR}}"
+        echo ""
+        echo "Generated files:"
+        ls -1 {{.DIAGRAMS_DIR}}/*.{{.OUTPUT_FORMAT}} 2>/dev/null | xargs -n1 basename || echo "No output files found"
+    silent: true
+
+  diagrams:clean:
+    desc: Remove generated diagram files
+    cmds:
+      - |
+        rm -f {{.DIAGRAMS_DIR}}/*.png {{.DIAGRAMS_DIR}}/*.svg
+        echo "✅ Generated diagram files removed"
+    silent: true
+
+  diagrams:validate:
+    desc: Validate PlantUML syntax using Docker
+    cmds:
+      - |
+        set -e
+        echo "Validating PlantUML diagrams..."
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -syntax \
+          /data/*.puml
+        echo "✅ All diagrams are valid"
+    silent: true

docs/diagrams/fraudulent-login-sequence.puml

@@ -0,0 +1,51 @@
+@startuml
+skinparam handwritten false
+skinparam participantPadding 10
+skinparam boxPadding 10
+
+box "Authentication System" #LightBlue
+participant "Zitadel Event Handler" as Zitadel
+end box
+
+box "Kubernetes Control Plane" #LightYellow
+database "K8s API Server" as K8s
+end box
+
+box "Fraud System" #LightPink
+participant "Fraud Controller" as FraudCtrl
+end box
+
+box "Notification System" #LightGreen
+participant "Notification Operator" as Notif
+end box
+
+== 1. Session Created Event ==
+Zitadel -> Zitadel: Webhook received:\noidc_session.added
+Zitadel -> K8s: Create LoginEvaluation resource\n(Spec: UserRef, loginEmail, LoginContext)
+
+== 2. Reconcile & Fraud Evaluation ==
+K8s -> FraudCtrl: Watch event: LoginEvaluation Created
+activate FraudCtrl
+
+FraudCtrl -> K8s: List Sessions (for UserRef)
+K8s --> FraudCtrl: Return historical Session resources
+
+FraudCtrl -> FraudCtrl: Compare current LoginContext\nagainst historical sessions\n(Compare IP, UserAgent, Fingerprint)
+
+alt Login is Fraudulent (Suspicious)
+    FraudCtrl -> K8s: Resolve Location (via GraphQL Gateway LookupIP)
+    K8s --> FraudCtrl: Return resolved Location details
+    FraudCtrl -> K8s: Parse User-Agent (via GraphQL Gateway ParseUserAgent)
+    K8s --> FraudCtrl: Return parsed Device & Browser
+
+    FraudCtrl -> K8s: Create Email resource\n(Spec: Recipient, Template, Variables)
+    activate Notif
+    Notif -> K8s: Update Email status to Sent
+    deactivate Notif
+
+    FraudCtrl -> K8s: Update LoginEvaluation Status\n(isFraudulent=true, phase=Completed)
+else Login is Normal
+    FraudCtrl -> K8s: Update LoginEvaluation Status\n(isFraudulent=false, phase=Completed)
+end
+deactivate FraudCtrl
+@enduml