gateway readme and plan
This commit is contained in:
Ilia Denisov
+489
-5
@@ -1,9 +1,493 @@
|
||||
# Implementation plan for Edge Gateway service
|
||||
# Edge Gateway Implementation Plan
|
||||
|
||||
## [x] First step
|
||||
## Summary
|
||||
|
||||
Step description.
|
||||
This plan breaks implementation into small, reviewable phases.
|
||||
Each phase has a single primary goal, clear deliverables, explicit dependencies,
|
||||
acceptance criteria, and focused tests.
|
||||
|
||||
## [ ] Second step
|
||||
The intended v1 architecture is:
|
||||
|
||||
Step Description.
|
||||
- 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.
|
||||
- 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@@ -1 +1,414 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user