feat: edge gateway service

gateway/PLAN.md

@@ -21,11 +21,19 @@ The intended v1 architecture is:
 - `protocol_version` covers transport and envelope compatibility, not business
   payload schema compatibility.
 - FlatBuffers are used for business payload bytes only.
+- Phase 3 public auth uses a challenge-token REST flow:
+  `send-email-code(email) -> challenge_id` and
+  `confirm-email-code(challenge_id, code, client_public_key) -> device_session_id`.
+- Phase 3 uses a consumer-side `AuthServiceClient` inside `gateway`; the
+  default process wiring keeps public auth routes mounted and returns
+  `503 service_unavailable` until a concrete upstream adapter is added.
 - Browser bootstrap and asset traffic are within gateway scope, even when backed
   by a pluggable proxy or handler.
 - Long-polling is out of scope for v1.
 
-## Phase 1. Module Skeleton
+## ~~Phase 1.~~ Module Skeleton
+
+Status: implemented.
 
 Goal: create the runnable gateway process skeleton.
 
@@ -49,7 +57,9 @@ Targeted tests:
 - startup with valid config;
 - shutdown without leaked goroutines.
 
-## Phase 2. Public REST Server
+## ~~Phase 2.~~ Public REST Server
+
+Status: implemented.
 
 Goal: add the unauthenticated HTTP server shell.
 
@@ -73,7 +83,9 @@ Targeted tests:
 - health endpoint responses;
 - request classification smoke tests.
 
-## Phase 3. Public Auth REST Handlers
+## ~~Phase 3.~~ Public Auth REST Handlers
+
+Status: implemented.
 
 Goal: expose unauthenticated auth commands through REST/JSON.
 
@@ -96,7 +108,9 @@ Targeted tests:
 - success and validation errors for both routes;
 - no session lookup on public auth paths.
 
-## Phase 4. Public Traffic Classification
+## ~~Phase 4.~~ Public Traffic Classification
+
+Status: implemented.
 
 Goal: isolate public traffic into stable anti-abuse classes.
 
@@ -118,7 +132,9 @@ Targeted tests:
 - per-class routing tests;
 - bucket isolation tests.
 
-## Phase 5. Public REST Anti-Abuse
+## ~~Phase 5.~~ Public REST Anti-Abuse
+
+Status: implemented.
 
 Goal: add coarse protection to unauthenticated REST traffic.
 
@@ -142,7 +158,9 @@ Targeted tests:
 - bootstrap burst stays outside auth abuse counters;
 - invalid methods and oversized bodies are rejected.
 
-## Phase 6. gRPC Server and Public Contracts
+## ~~Phase 6.~~ gRPC Server and Public Contracts
+
+Status: implemented.
 
 Goal: bring up authenticated transport over gRPC and HTTP/2.
 
@@ -165,7 +183,9 @@ Targeted tests:
 - unary transport smoke test;
 - stream transport smoke test.
 
-## Phase 7. Envelope Parsing and Protocol Gate
+## ~~Phase 7.~~ Envelope Parsing and Protocol Gate
+
+Status: implemented.
 
 Goal: validate the gRPC control envelope before security checks continue.
 
@@ -186,7 +206,9 @@ Targeted tests:
 - missing field rejection;
 - unsupported `protocol_version` rejection.
 
-## Phase 8. Session Cache Lookup
+## ~~Phase 8.~~ Session Cache Lookup
+
+Status: implemented.
 
 Goal: resolve authenticated identity from cache.
 
@@ -208,7 +230,9 @@ Targeted tests:
 - cache miss reject;
 - revoked session reject.
 
-## Phase 9. Payload Hash and Signing Input
+## ~~Phase 9.~~ Payload Hash and Signing Input
+
+Status: implemented.
 
 Goal: verify payload integrity before signature verification.
 
@@ -228,7 +252,9 @@ Targeted tests:
 - payload hash mismatch reject;
 - canonical bytes differ when signed fields change.
 
-## Phase 10. Client Signature Verification
+## ~~Phase 10.~~ Client Signature Verification
+
+Status: implemented.
 
 Goal: authenticate the request origin using the session public key.
 
@@ -249,7 +275,9 @@ Targeted tests:
 - bad signature reject;
 - wrong-key reject.
 
-## Phase 11. Freshness and Anti-Replay
+## ~~Phase 11.~~ Freshness and Anti-Replay
+
+Status: implemented.
 
 Goal: enforce transport freshness and replay protection.
 
@@ -271,7 +299,9 @@ Targeted tests:
 - replay reject for same session and request ID;
 - distinct sessions do not collide.
 
-## Phase 12. Authenticated Rate Limits and Policy
+## ~~Phase 12.~~ Authenticated Rate Limits and Policy
+
+Status: implemented.
 
 Goal: apply edge policy after transport authenticity is established.
 
@@ -291,7 +321,10 @@ Targeted tests:
 - per-dimension throttling;
 - bucket isolation from public traffic.
 
-## Phase 13. Internal Authenticated Command and Routing
+## ~~Phase 13.~~ Internal Authenticated Command and Routing
+
+Status: implemented.
+Note: delivered together with Phase 14 signed unary responses.
 
 Goal: forward only verified context to downstream services.
 
@@ -313,7 +346,9 @@ Targeted tests:
 - route selection by `message_type`;
 - downstream receives the expected authenticated context.
 
-## Phase 14. Signed Unary Responses
+## ~~Phase 14.~~ Signed Unary Responses
+
+Status: implemented as part of Phase 13 delivery.
 
 Goal: return verifiable server responses to authenticated clients.
 
@@ -335,7 +370,9 @@ Targeted tests:
 - response correlation test;
 - server signature generation test.
 
-## Phase 15. Session Update and Revocation Events
+## ~~Phase 15.~~ Session Update and Revocation Events
+
+Status: implemented.
 
 Goal: keep gateway session state current without synchronous hot-path lookups.
 
@@ -357,7 +394,9 @@ Targeted tests:
 - cache update from event;
 - revocation event invalidates cached session.
 
-## Phase 16. Authenticated Push Stream
+## ~~Phase 16.~~ Authenticated Push Stream
+
+Status: implemented.
 
 Goal: open a verified server-streaming channel for client-facing delivery.
 
@@ -379,7 +418,9 @@ Targeted tests:
 - rejected stream open for invalid session;
 - first event contains server time.
 
-## Phase 17. Event Fan-Out
+## ~~Phase 17.~~ Event Fan-Out
+
+Status: implemented.
 
 Goal: deliver client-facing events from internal pub/sub to active streams.
 
@@ -401,7 +442,9 @@ Targeted tests:
 - multi-device delivery for one user;
 - unrelated sessions do not receive the event.
 
-## Phase 18. Revocation-Driven Stream Teardown
+## ~~Phase 18.~~ Revocation-Driven Stream Teardown
+
+Status: implemented.
 
 Goal: terminate active delivery channels when a session is revoked.
 
@@ -422,7 +465,12 @@ Targeted tests:
 - revoke closes active stream;
 - revoked session cannot reopen the stream.
 
-## Phase 19. Observability and Shutdown Hardening
+## ~~Phase 19.~~ Observability and Shutdown Hardening
+
+Status: implemented.
+Note: delivered with `zap` structured logging, OpenTelemetry tracing and
+metrics, the optional private admin `/metrics` listener, timeout budgets, and
+shutdown-driven push-stream teardown.
 
 Goal: make the service operable in production.
 
@@ -446,7 +494,12 @@ Targeted tests:
 - shutdown closes listeners and active streams;
 - secret and signature values are not logged.
 
-## Phase 20. Acceptance Pass
+## ~~Phase 20.~~ Acceptance Pass
+
+Status: implemented.
+Note: acceptance pass reconciled README/OpenAPI/root architecture
+documentation, fixed the documented public-auth projected-error contract, and
+added focused regression coverage including OpenAPI validation.
 
 Goal: reconcile implementation, documentation, and regression coverage.