galaxy-game/gateway/README.md

# Edge Gateway

## Purpose

`Edge Gateway` is the only public ingress for Galaxy Plus clients.
It terminates the external transport and security boundary, enforces edge
policies, and routes verified requests to internal services.

The gateway does not implement domain-specific business logic.
Business validation, authorization, ownership checks, and state transitions
remain inside downstream services.

## Trust Boundary

The gateway sits between untrusted external clients and trusted internal
services.

The gateway is responsible for:

- parsing external transport requests;
- classifying public REST traffic;
- authenticating protected gRPC traffic;
- loading session state from cache;
- verifying request freshness and anti-replay constraints;
- applying edge rate limits and anti-abuse policy;
- building an authenticated internal command context;
- routing verified commands to internal services;
- maintaining authenticated push delivery connections.

The gateway is not responsible for:

- deciding whether a user is allowed to execute a business action;
- validating domain invariants;
- storing the source-of-truth session record;
- implementing business idempotency.

## Transport Matrix

The gateway exposes two external transport classes.

| Transport | Audience | Authentication | Payload format | Primary use |
| --- | --- | --- | --- | --- |
| REST/JSON | Public, unauthenticated traffic | No device session auth | JSON | Public auth commands, health checks, browser/bootstrap traffic |
| gRPC over HTTP/2 | Authenticated clients only | Required | FlatBuffers payload inside protobuf control envelope | Verified commands and push delivery |

### Public REST Surface

The public REST surface is used for commands that must work before a device
session exists and for browser-originated traffic that may share the same edge.

Stable public endpoints:

- `POST /api/v1/public/auth/send-email-code`
- `POST /api/v1/public/auth/confirm-email-code`
- `GET /healthz`
- `GET /readyz`

In addition to the fixed endpoints above, the gateway may front browser
bootstrap or asset traffic through a pluggable public handler or proxy.
That traffic belongs to dedicated public route classes and must not share rate
limit buckets or abuse counters with the public auth API.

### Authenticated gRPC Surface

All authenticated client requests use HTTP/2 and gRPC.

The public gRPC service exposes two methods:

- `ExecuteCommand(ExecuteCommandRequest) returns (ExecuteCommandResponse)`
- `SubscribeEvents(SubscribeEventsRequest) returns (stream GatewayEvent)`

`ExecuteCommand` is a generic unary RPC.
The gateway routes the request downstream by `message_type` after transport
verification succeeds.

`SubscribeEvents` is an authenticated server-streaming RPC.
It binds the stream to `user_id` and `device_session_id` and starts by sending
a service event that includes the current server time in milliseconds.

## Envelope and Payload Model

The authenticated transport uses a split contract:

- gRPC control messages are protobuf-based;
- business payload bytes are FlatBuffers;
- signatures are computed over canonical envelope fields and a hash of raw
  FlatBuffers bytes.

The gateway treats `payload_bytes` as opaque business data.
It verifies integrity and forwards verified bytes downstream without rewriting
them.

### ExecuteCommandRequest

Required fields:

- `protocol_version`
- `device_session_id`
- `message_type`
- `timestamp_ms`
- `request_id`
- `payload_bytes`
- `payload_hash`
- `signature`

Optional fields:

- `trace_id`

### ExecuteCommandResponse

Required fields:

- `protocol_version`
- `request_id`
- `timestamp_ms`
- `result_code`
- `payload_bytes`
- `payload_hash`
- `signature`

### SubscribeEventsRequest

The stream open request reuses the authenticated request model.
It contains the same authentication fields as the unary request and either an
empty payload or a minimal connect payload.

Required fields:

- `protocol_version`
- `device_session_id`
- `message_type`
- `timestamp_ms`
- `request_id`
- `payload_hash`
- `signature`

Optional fields:

- `payload_bytes`
- `trace_id`

### GatewayEvent

Every stream event is a client-facing signed server message.

Required fields:

- `event_type`
- `event_id`
- `timestamp_ms`
- `payload_bytes`
- `payload_hash`
- `signature`

Optional fields:

- `request_id`
- `trace_id`

## Verification and Routing Pipeline

The gateway applies the same strict verification order for authenticated gRPC
ingress.

1. Parse the control envelope and validate required fields.
2. Check whether `protocol_version` is supported.
3. Resolve `device_session_id` through `SessionCache`.
4. Reject unknown or revoked sessions.
5. Verify that `payload_hash` matches raw `payload_bytes`.
6. Verify the client signature using the public key from session cache.
7. Verify that `timestamp_ms` is inside the accepted freshness window.
8. Verify anti-replay by checking `device_session_id + request_id`.
9. Apply authenticated rate limit and edge policy checks.
10. Build the authenticated internal command context.
11. Route the command downstream by `message_type`.

No downstream business service should receive a request that has not passed
this full verification pipeline.

## Internal Authenticated Contract

Downstream services should receive an internal authenticated command rather than
raw external gRPC transport data.

The minimum authenticated context is:

- `user_id`
- `device_session_id`
- `message_type`
- verified `payload_bytes`
- `request_id`
- optional `trace_id`
- optional client metadata needed for logs and tracing

Downstream services may trust that the gateway has already performed transport
authentication, freshness verification, and anti-replay checks.
They must still perform business authorization and domain validation.

## Session Model

The Auth / Session Service is the source of truth for device session state.
The gateway is designed to authenticate the hot path from cache.

Expected session fields available to the gateway:

- `device_session_id`
- `user_id`
- client public key
- session status
- revoke metadata
- optional client metadata

### Session Cache

`SessionCache` provides the fast path for:

- session existence checks;
- `device_session_id -> user_id`;
- access to the client public key used for signature verification;
- revoked versus active status checks.

Cache updates are event-driven.
TTL is allowed only as a safety net and must not replace invalidation events.

### Revocation Behavior

When a device session is revoked:

1. the Auth / Session Service updates the source of truth;
2. it publishes a session update or revoke event;
3. the gateway invalidates or updates `SessionCache`;
4. new unary gRPC requests for that session are rejected;
5. active `SubscribeEvents` streams for that session are closed.

## Public Anti-Abuse Model

The public REST layer must distinguish between public auth operations and
browser-originated traffic that may burst during a normal first page load.

The gateway uses these public route classes:

- `public_auth`
- `browser_bootstrap`
- `browser_asset`
- `public_misc`

### Public Auth

`public_auth` includes `send-email-code` and `confirm-email-code`.
This class uses stricter limits and abuse scoring because it directly touches
account and session creation flows.

Controls include:

- per-IP and per-identity rate limits;
- request body size limits;
- method allow-lists;
- malformed request counters;
- elevated logging and security telemetry for repeated failures.

### Browser Bootstrap and Asset Traffic

`browser_bootstrap` and `browser_asset` use separate coarse-grained budgets.
They may exhibit bursty behavior during the first load and therefore must not
be treated as hostile based on burst pattern alone.

This traffic is still constrained by:

- dedicated rate limits;
- method allow-lists;
- body size limits where request bodies are expected;
- protocol and path validation;
- independent abuse telemetry.

The gateway must not merge these buckets or counters with `public_auth`.

## Push Delivery Model

The v1 push channel is a gRPC server stream.
Long-polling is intentionally out of scope for the first version.

Expected stream behavior:

1. the client opens `SubscribeEvents`;
2. the gateway applies the full authenticated ingress verification pipeline;
3. the stream is bound to `user_id` and `device_session_id`;
4. the first service event includes `server_time_ms`;
5. client-facing events from internal pub/sub are fanned out to matching active
   streams;
6. revoke events close affected streams.

## Recommended Package Layout

The initial package layout should keep transport, policy, and downstream
adapters separate:

- `cmd/gateway`
- `internal/app`
- `internal/config`
- `internal/restapi`
- `internal/grpcapi`
- `internal/authn`
- `internal/session`
- `internal/replay`
- `internal/ratelimit`
- `internal/downstream`
- `internal/push`
- `internal/events`
- `internal/clock`

## Key Interfaces

The gateway should be built around explicit consumer-side interfaces.

### SessionCache

Provides cached session lookup by `device_session_id`.
Returns enough data to verify signatures and identify the authenticated user.

### ReplayStore

Tracks recently seen `request_id` values per device session and rejects replayed
requests inside the accepted freshness window.

### RateLimiter

Applies independent policies for:

- public REST route classes;
- authenticated gRPC requests by IP;
- authenticated gRPC requests by session;
- authenticated gRPC requests by user;
- authenticated gRPC requests by message class.

### PublicTrafficClassifier

Maps incoming public REST requests to one of the public route classes so that
limits and anti-abuse counters remain isolated.

### AuthServiceClient

Handles public auth commands and session-related updates exchanged with the
Auth / Session Service.

### DownstreamRouter

Resolves the target downstream service or adapter by `message_type`.

### DownstreamClient

Executes a verified authenticated command against a downstream internal service
and returns response payload bytes plus a stable result code.

### EventSubscriber

Subscribes to internal pub/sub topics used for:

- session cache updates;
- revocations;
- client-facing event delivery.

### PushHub

Tracks active `SubscribeEvents` streams, binds them to authenticated identities,
and delivers events to the correct connections.

### ResponseSigner

Signs unary responses and stream events so clients can verify server-originated
messages.

### Clock

Provides current server time and supports consistent freshness-window checks.

## Error Model and Observability

The gateway should expose stable edge-level error classes instead of leaking
internal implementation details.

Minimum error categories:

- malformed request;
- unsupported protocol;
- unknown session;
- revoked session;
- invalid signature;
- stale request;
- replay detected;
- rate limited;
- downstream unavailable;
- internal error.

Observability requirements:

- stable correlation identifiers, including `request_id` and optional `trace_id`;
- structured logs;
- security audit events for rejects and abuse signals;
- metrics keyed by route class, message type, result code, and reject reason;
- no logging of secrets, raw private material, or raw signatures.

## Non-Goals

The gateway is not a business authorization layer and must not grow into a
domain coordinator.

The gateway must not:

- implement business ownership checks;
- validate domain state transitions;
- replace the Auth / Session Service as the session source of truth;
- degrade into a synchronous pass-through that reloads session state for every
  authenticated request.