feat: user service

gateway/README.md

@@ -23,6 +23,8 @@ Optional integrations:
 - `GATEWAY_ADMIN_HTTP_ADDR` enables the private `/metrics` listener;
 - `GATEWAY_AUTH_SERVICE_BASE_URL` enables real public auth handling through
   Auth / Session Service public HTTP;
+- `GATEWAY_USER_SERVICE_BASE_URL` enables direct authenticated self-service
+  routing to User Service internal HTTP;
 - injected downstream routes are required for successful `ExecuteCommand`.
 
 Operational caveats:
@@ -118,6 +120,10 @@ The public auth JSON contract uses a challenge-token flow:
 key for the device session being created.
 `time_zone` is the client-selected IANA time zone name forwarded unchanged to
 `Auth / Session Service`.
+The current create-path source of truth for `preferred_language` is still the
+temporary authsession-to-user rollout using `"en"`. Gateway-side language
+derivation is a later rollout. The public `confirm-email-code` DTO itself
+remains unchanged.
 
 These routes remain unauthenticated and delegate only through an injected
 `AuthServiceClient`.
@@ -322,10 +328,24 @@ The authenticated transport uses a split contract:
 - signatures are computed over canonical envelope fields and a hash of raw
   FlatBuffers bytes.
 
-The gateway treats authenticated request `payload_bytes` as opaque business
-data.
-It verifies integrity and forwards verified bytes downstream without rewriting
-them.
+The gateway verifies authenticated payload bytes before any downstream call.
+Most downstream routes may still treat those bytes as opaque, but the gateway
+is also allowed to transcode verified FlatBuffers payloads into trusted
+downstream REST/JSON calls when the concrete downstream contract requires it.
+
+The current direct `Gateway -> User` self-service boundary uses that pattern:
+
+- external message types:
+  - `user.account.get`
+  - `user.profile.update`
+  - `user.settings.update`
+- external payloads and responses:
+  - FlatBuffers
+- internal downstream transport:
+  - strict REST/JSON to User Service
+- business error projection:
+  - gateway `result_code`
+  - FlatBuffers error payload mirroring User Service `code` and `message`
 
 The request envelope version literal is `v1`.
 `payload_hash` is the raw 32-byte SHA-256 digest of `payload_bytes`.
@@ -965,6 +985,11 @@ failing process startup.
 Resolves the target downstream service or adapter by the full exact-match
 `message_type` literal.
 
+The default `cmd/gateway` wiring keeps the reserved `user.*` self-service
+message types mounted even when `GATEWAY_USER_SERVICE_BASE_URL` is unset. In
+that configuration they fail closed as dependency-unavailable instead of
+falling through to a generic route miss.
+
 ### DownstreamClient
 
 Executes a verified authenticated command against a downstream internal service
@@ -972,6 +997,11 @@ and returns response payload bytes plus a stable opaque result code.
 An empty or whitespace-only result code is treated as an internal downstream
 contract violation.
 
+Downstream clients may be pure pass-through adapters or gateway-owned
+transcoding adapters. The current User Service adapter decodes authenticated
+FlatBuffers payloads, calls the trusted internal REST API, and re-encodes the
+result into FlatBuffers before the signed gateway response is emitted.
+
 ### EventSubscriber
 
 Subscribes to internal pub/sub topics used for: