feat: edge gateway service

2026-04-02 19:18:42 +02:00
parent 8cde99936c
commit 436c97a38b
95 changed files with 20504 additions and 57 deletions
@@ -0,0 +1,86 @@
+# Request and Push Flows
+
+## Public Auth Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant Limiter as Public anti-abuse
+    participant Auth as AuthServiceClient
+
+    Client->>Gateway: POST /api/v1/public/auth/send-email-code
+    Gateway->>Limiter: classify + rate-limit + body checks
+    Limiter-->>Gateway: allowed
+    Gateway->>Auth: SendEmailCode(email)
+    Auth-->>Gateway: challenge_id
+    Gateway-->>Client: 200 {challenge_id}
+
+    Client->>Gateway: POST /api/v1/public/auth/confirm-email-code
+    Gateway->>Limiter: classify + rate-limit + body checks
+    Limiter-->>Gateway: allowed
+    Gateway->>Auth: ConfirmEmailCode(challenge_id, code, client_public_key)
+    Auth-->>Gateway: device_session_id
+    Gateway-->>Client: 200 {device_session_id}
+```
+
+## Authenticated ExecuteCommand Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant Cache as SessionCache
+    participant Replay as ReplayStore
+    participant Policy as Rate limit / policy
+    participant Downstream
+
+    Client->>Gateway: ExecuteCommand(envelope, payload_bytes, signature)
+    Gateway->>Gateway: validate envelope + protocol_version
+    Gateway->>Cache: lookup(device_session_id)
+    Cache-->>Gateway: session record
+    Gateway->>Gateway: verify payload_hash
+    Gateway->>Gateway: verify Ed25519 signature
+    Gateway->>Gateway: verify freshness window
+    Gateway->>Replay: reserve(device_session_id, request_id, ttl)
+    Replay-->>Gateway: accepted
+    Gateway->>Policy: apply IP/session/user/message_type budgets
+    Policy-->>Gateway: allowed
+    Gateway->>Downstream: verified authenticated command
+    Downstream-->>Gateway: result_code + payload_bytes
+    Gateway->>Gateway: hash payload + sign response
+    Gateway-->>Client: ExecuteCommandResponse + signature
+```
+
+## SubscribeEvents Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant Cache as SessionCache
+    participant Replay as ReplayStore
+    participant Hub as PushHub
+    participant Stream as Client event stream
+    participant Sess as Session event stream
+
+    Client->>Gateway: SubscribeEvents(envelope, signature)
+    Gateway->>Gateway: validate envelope + verify request
+    Gateway->>Cache: lookup(device_session_id)
+    Cache-->>Gateway: session record
+    Gateway->>Replay: reserve(device_session_id, request_id, ttl)
+    Replay-->>Gateway: accepted
+    Gateway->>Client: gateway.server_time event
+    Gateway->>Hub: register(user_id, device_session_id)
+
+    Stream-->>Gateway: client-facing event for user_id / device_session_id
+    Gateway->>Hub: publish signed event
+    Hub-->>Client: matching event delivery
+
+    Sess-->>Gateway: revoked session snapshot
+    Gateway->>Hub: revoke(device_session_id)
+    Hub-->>Client: stream closes with FAILED_PRECONDITION
+
+    Note over Gateway,Hub: During shutdown the gateway closes PushHub before gRPC graceful stop.
+    Hub-->>Client: stream closes with UNAVAILABLE
+```