galaxy-game/gateway/PLAN.md

# Edge Gateway Implementation Plan

## Summary

This plan breaks implementation into small, reviewable phases.
Each phase has a single primary goal, clear deliverables, explicit dependencies,
acceptance criteria, and focused tests.

The intended v1 architecture is:

- unauthenticated public ingress over REST/JSON;
- authenticated ingress over gRPC on HTTP/2;
- FlatBuffers payloads for authenticated business commands;
- protobuf-based gRPC control envelopes;
- authenticated server-streaming push through gRPC;
- separate public traffic classes and isolated anti-abuse counters.

## Assumptions and Defaults

- `message_type` is the stable downstream routing key.
- `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

Status: implemented.

Goal: create the runnable gateway process skeleton.

Artifacts:

- `cmd/gateway`
- `internal/app`
- base configuration types
- startup and shutdown wiring

Dependencies: none.

Acceptance criteria:

- the process starts with config;
- the process shuts down cleanly on signal;
- lifecycle wiring is testable.

Targeted tests:

- startup with valid config;
- shutdown without leaked goroutines.

## ~~Phase 2.~~ Public REST Server

Status: implemented.

Goal: add the unauthenticated HTTP server shell.

Artifacts:

- public REST listener
- `GET /healthz`
- `GET /readyz`
- base error serialization
- request classification hook

Dependencies: Phase 1.

Acceptance criteria:

- health endpoints respond deterministically;
- public requests are classified at least into `public_auth` and `browser_*`.

Targeted tests:

- health endpoint responses;
- request classification smoke tests.

## ~~Phase 3.~~ Public Auth REST Handlers

Status: implemented.

Goal: expose unauthenticated auth commands through REST/JSON.

Artifacts:

- `POST /api/v1/public/auth/send-email-code`
- `POST /api/v1/public/auth/confirm-email-code`
- request and response DTOs
- adapter calls into `AuthServiceClient`

Dependencies: Phase 2.

Acceptance criteria:

- no session authentication is required for these routes;
- handlers delegate only through the auth service adapter.

Targeted tests:

- success and validation errors for both routes;
- no session lookup on public auth paths.

## ~~Phase 4.~~ Public Traffic Classification

Status: implemented.

Goal: isolate public traffic into stable anti-abuse classes.

Artifacts:

- `PublicTrafficClassifier`
- classes `public_auth`, `browser_bootstrap`, `browser_asset`, `public_misc`
- isolated rate-limit bucket keys

Dependencies: Phase 2.

Acceptance criteria:

- browser traffic does not share buckets with public auth;
- auth counters remain unaffected by asset bursts.

Targeted tests:

- per-class routing tests;
- bucket isolation tests.

## ~~Phase 5.~~ Public REST Anti-Abuse

Status: implemented.

Goal: add coarse protection to unauthenticated REST traffic.

Artifacts:

- body size limits
- method allow-lists
- malformed request counters
- per-class rate-limit thresholds

Dependencies: Phase 4.

Acceptance criteria:

- first-load browser bursts are not marked hostile because of burst pattern
  alone;
- malformed or oversized requests are rejected predictably.

Targeted tests:

- bootstrap burst stays outside auth abuse counters;
- invalid methods and oversized bodies are rejected.

## ~~Phase 6.~~ gRPC Server and Public Contracts

Status: implemented.

Goal: bring up authenticated transport over gRPC and HTTP/2.

Artifacts:

- gRPC listener
- protobuf service definitions
- `ExecuteCommand`
- `SubscribeEvents`

Dependencies: Phase 1.

Acceptance criteria:

- unary and server-streaming RPCs are reachable;
- the server runs only over HTTP/2.

Targeted tests:

- unary transport smoke test;
- stream transport smoke test.

## ~~Phase 7.~~ Envelope Parsing and Protocol Gate

Status: implemented.

Goal: validate the gRPC control envelope before security checks continue.

Artifacts:

- envelope parser
- required-field validation
- protocol version gate

Dependencies: Phase 6.

Acceptance criteria:

- unsupported or malformed envelopes are rejected before routing.

Targeted tests:

- missing field rejection;
- unsupported `protocol_version` rejection.

## ~~Phase 8.~~ Session Cache Lookup

Status: implemented.

Goal: resolve authenticated identity from cache.

Artifacts:

- `SessionCache`
- session lookup pipeline
- revoked versus active session handling

Dependencies: Phase 7.

Acceptance criteria:

- unknown and revoked sessions are blocked before signature verification.

Targeted tests:

- cache hit with active session;
- cache miss reject;
- revoked session reject.

## ~~Phase 9.~~ Payload Hash and Signing Input

Status: implemented.

Goal: verify payload integrity before signature verification.

Artifacts:

- `payload_hash` verification
- canonical signing input builder

Dependencies: Phase 8.

Acceptance criteria:

- changing payload bytes or envelope fields breaks the signing input.

Targeted tests:

- payload hash mismatch reject;
- canonical bytes differ when signed fields change.

## ~~Phase 10.~~ Client Signature Verification

Status: implemented.

Goal: authenticate the request origin using the session public key.

Artifacts:

- signature verifier
- deterministic auth reject mapping

Dependencies: Phase 9.

Acceptance criteria:

- wrong key and invalid signature produce stable rejects.

Targeted tests:

- success case with valid signature;
- bad signature reject;
- wrong-key reject.

## ~~Phase 11.~~ Freshness and Anti-Replay

Status: implemented.

Goal: enforce transport freshness and replay protection.

Artifacts:

- timestamp freshness window
- `ReplayStore`
- replay reservation and rejection logic

Dependencies: Phase 10.

Acceptance criteria:

- stale requests and duplicate `request_id` values are rejected.

Targeted tests:

- stale timestamp reject;
- replay reject for same session and request ID;
- distinct sessions do not collide.

## ~~Phase 12.~~ Authenticated Rate Limits and Policy

Status: implemented.

Goal: apply edge policy after transport authenticity is established.

Artifacts:

- rate-limit keys for IP, session, user, and message class
- authenticated policy evaluation hook

Dependencies: Phase 11.

Acceptance criteria:

- authenticated buckets are independent from public REST buckets.

Targeted tests:

- per-dimension throttling;
- bucket isolation from public traffic.

## ~~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.

Artifacts:

- `AuthenticatedCommand`
- `DownstreamRouter`
- `DownstreamClient`

Dependencies: Phase 12.

Acceptance criteria:

- downstream services receive verified context only;
- raw transport details do not leak as authoritative input.

Targeted tests:

- route selection by `message_type`;
- downstream receives the expected authenticated context.

## ~~Phase 14.~~ Signed Unary Responses

Status: implemented as part of Phase 13 delivery.

Goal: return verifiable server responses to authenticated clients.

Artifacts:

- response envelope builder
- payload hash generation
- `ResponseSigner`

Dependencies: Phase 13.

Acceptance criteria:

- unary responses always carry the original `request_id`, `payload_hash`, and
  server signature.

Targeted tests:

- response correlation test;
- server signature generation test.

## ~~Phase 15.~~ Session Update and Revocation Events

Status: implemented.

Goal: keep gateway session state current without synchronous hot-path lookups.

Artifacts:

- `EventSubscriber`
- session update handlers
- session revoke handlers

Dependencies: Phase 8.

Acceptance criteria:

- session updates change gateway behavior without per-request sync calls to the
  auth service.

Targeted tests:

- cache update from event;
- revocation event invalidates cached session.

## ~~Phase 16.~~ Authenticated Push Stream

Status: implemented.

Goal: open a verified server-streaming channel for client-facing delivery.

Artifacts:

- `SubscribeEvents` handler
- stream binding to `user_id` and `device_session_id`
- initial server time event

Dependencies: Phase 15.

Acceptance criteria:

- the stream opens only after the full auth pipeline succeeds.

Targeted tests:

- authorized stream open;
- rejected stream open for invalid session;
- first event contains server time.

## ~~Phase 17.~~ Event Fan-Out

Status: implemented.

Goal: deliver client-facing events from internal pub/sub to active streams.

Artifacts:

- `PushHub`
- event fan-out logic
- user and session targeting rules

Dependencies: Phase 16.

Acceptance criteria:

- events are delivered to the correct active streams only.

Targeted tests:

- single-session delivery;
- multi-device delivery for one user;
- unrelated sessions do not receive the event.

## ~~Phase 18.~~ Revocation-Driven Stream Teardown

Status: implemented.

Goal: terminate active delivery channels when a session is revoked.

Artifacts:

- stream teardown on revoke
- connection cleanup logic

Dependencies: Phase 17.

Acceptance criteria:

- revocation blocks new unary requests and closes active streams for the same
  session.

Targeted tests:

- revoke closes active stream;
- revoked session cannot reopen the stream.

## ~~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.

Artifacts:

- structured logs
- metrics
- trace propagation
- timeout budgets
- graceful shutdown for unary and streaming traffic

Dependencies: Phase 18.

Acceptance criteria:

- shutdown is deterministic;
- logs and metrics expose stable edge outcomes without leaking secrets.

Targeted tests:

- shutdown closes listeners and active streams;
- secret and signature values are not logged.

## ~~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.

Artifacts:

- updated README and PLAN
- final protocol and interface review
- focused regression test run

Dependencies: Phases 1 through 19.

Acceptance criteria:

- implementation matches documented contracts and ordering guarantees;
- docs describe the actual gateway behavior.

Targeted tests:

- run focused package tests for gateway packages;
- rerun cross-cutting regression scenarios.

## Cross-Cutting Regression Scenarios

- `send_email_code` and `confirm_email_code` are available without session auth
  and are still limited by public auth policy.
- Public browser bootstrap and asset bursts do not increase auth abuse counters
  and are not rejected as hostile because of intensity alone.
- Any gRPC command without a valid session is rejected before routing.
- Unknown and revoked sessions are handled predictably and consistently where
  policy requires identical behavior.
- Signature verification fails when `payload_bytes`, `payload_hash`,
  `message_type`, `request_id`, or the signing key changes.
- `payload_hash` is verified before downstream execution.
- Requests outside the freshness window are rejected.
- Reused `request_id` values are rejected within the session replay window.
- Public REST and authenticated gRPC traffic use independent buckets and
  independent abuse telemetry.
- Downstream services receive `AuthenticatedCommand`, not raw REST or gRPC
  transport requests.
- Unary responses preserve `request_id` correlation and are server-signed.
- Streaming connections open only after the auth pipeline and close on revoke.
- Session cache updates from events change gateway behavior without synchronous
  auth-service lookups per request.
- Graceful shutdown terminates unary and streaming traffic cleanly.