# Secure Exchange Architecture

## Purpose

This document fixes the transport-level secure exchange model between client and server.
It is the starting point for implementing authenticated device sessions, signed requests/responses, and anti-replay protection.

## Main Principles

- No browser cookies are used.
- Authentication is device-session based.
- Each device/session is unique and independently revocable.
- There are no short-lived access tokens or refresh-token flows in the main design.
- Requests are authenticated by client-side signatures.
- Responses are authenticated by server-side signatures.
- Transport integrity and freshness are verified before payload is processed.

```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant SessionCache
    participant ReplayStore
    participant Business

    Client->>Gateway: ExecuteCommand / SubscribeEvents\n(protocol_version, device_session_id,\nmessage_type, timestamp_ms, request_id,\npayload_hash, signature)
    Gateway->>SessionCache: lookup(device_session_id)
    SessionCache-->>Gateway: user_id, client_public_key, status
    Gateway->>Gateway: verify payload_hash, signature,\nfreshness window
    Gateway->>ReplayStore: reserve(device_session_id, request_id, ttl)
    ReplayStore-->>Gateway: accepted / duplicate
    Gateway->>Business: verified command context
    Business-->>Gateway: response payload
    Gateway-->>Client: signed response
    Gateway-->>Client: signed push events on SubscribeEvents
```

## Device Session Model

After successful login through e-mail code:

1. client generates an asymmetric key pair
2. private key remains on the client device
3. public key is registered on the server as the standard base64-encoded raw
   32-byte Ed25519 public key
4. server creates a persistent `device_session`
5. client stores:
   - `device_session_id`
   - private key

The server stores at least:

- `device_session_id`
- `user_id`
- base64-encoded raw 32-byte Ed25519 client public key
- session status
- revoke metadata

## Key Storage

### Native Clients

Private key should be stored in platform secure storage.

### Browser / WASM Clients

Private key should be created and used through WebCrypto.
Non-exportable key storage is preferred.
Loss of browser storage is acceptable and means re-login is required.

## Request Structure

Each authenticated request logically contains:

- `payload_bytes`
- `request_envelope`
- `signature`

### Request Envelope

Minimal required fields:

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

The supported request `protocol_version` literal for the v1 gateway transport
is `v1`.
The v1 authenticated request signature scheme is Ed25519.
The stored client public key is the standard base64-encoded raw 32-byte
Ed25519 public key, and the request `signature` field carries the raw
64-byte Ed25519 signature bytes.

### Request Signing Input

The client signs canonical bytes built from:

- request domain marker `galaxy-request-v1`
- `protocol_version`
- `device_session_id`
- `message_type`
- `timestamp_ms`
- `request_id`
- `payload_hash`

The canonical v1 request signing input uses this binary encoding:

- each `string` and `bytes` field is encoded as `uvarint(len(field_bytes))`
  followed by raw bytes
- `timestamp_ms` is encoded as an 8-byte big-endian unsigned integer
- fields are appended in the exact order listed above

`payload_hash` is the raw 32-byte SHA-256 digest computed from raw
`payload_bytes`.
Empty payloads still use the SHA-256 digest of the empty byte slice.

The goal is to bind the signature to:

- the concrete device session
- the concrete message type
- the concrete payload
- a fresh request instance

## Response Structure

Each server response logically contains:

- `payload_bytes`
- `response_envelope`
- `signature`

### Response Envelope

Minimal required fields:

- `protocol_version`
- `request_id`
- `timestamp_ms`
- `result_code`
- `payload_hash`

### Response Signing Input

The server signs canonical bytes built from:

- response domain marker `galaxy-response-v1`
- `protocol_version`
- `request_id`
- `timestamp_ms`
- `result_code`
- `payload_hash`

The current gateway v1 response signature scheme is Ed25519.
The canonical v1 response signing input uses this binary encoding:

- each `string` and `bytes` field is encoded as `uvarint(len(field_bytes))`
  followed by raw bytes
- `timestamp_ms` is encoded as an 8-byte big-endian unsigned integer
- fields are appended in the exact order listed above

The gateway server loads the response signing key from a PKCS#8 PEM-encoded
Ed25519 private key.
The client verifies the signature using a trusted server public key.

## Event Structure

Each server push event logically contains:

- `payload_bytes`
- `event_envelope`
- `signature`

### Event Envelope

Minimal required fields:

- `event_type`
- `event_id`
- `timestamp_ms`
- `payload_hash`

Optional fields:

- `request_id`
- `trace_id`

The current gateway v1 stream-event signature scheme is Ed25519.
The gateway currently signs unary responses and stream events with the same
PKCS#8 PEM-encoded Ed25519 private key.
The bootstrap event implemented for `SubscribeEvents` uses
`event_type = gateway.server_time`, reuses the opening subscribe `request_id`
as `event_id`, and encodes `server_time_ms` in a FlatBuffers
`gateway.ServerTimeEvent` payload.
Later client-facing push events are sourced from internal pub/sub with target
metadata `user_id` and optional `device_session_id`, plus `event_type`,
`event_id`, `payload_bytes`, and optional `request_id` / `trace_id`.
The gateway derives `timestamp_ms`, recomputes `payload_hash`, signs the
event at delivery time, and only then forwards it to the matching active
streams.

### Event Signing Input

The server signs canonical bytes built from:

- event domain marker `galaxy-event-v1`
- `event_type`
- `event_id`
- `timestamp_ms`
- `request_id`
- `trace_id`
- `payload_hash`

The canonical v1 event signing input uses this binary encoding:

- each `string` and `bytes` field is encoded as `uvarint(len(field_bytes))`
  followed by raw bytes
- `timestamp_ms` is encoded as an 8-byte big-endian unsigned integer
- fields are appended in the exact order listed above

## Verification Order on Server

Before processing payload, the server/gateway must:

1. verify that the transport envelope is present and supported
2. resolve `device_session_id`
3. reject unknown or revoked sessions
4. verify client signature using stored public key
5. verify timestamp freshness window
6. verify anti-replay constraints using `request_id`
7. only then pass payload to business processing

## Verification Order on Client

Before accepting response payload, the client must:

1. verify server signature
2. verify `request_id` matches the corresponding request
3. verify `payload_hash`
4. verify timestamp freshness if applicable
5. only then accept the response payload

Before accepting push-event payload, the client must:

1. verify server event signature
2. verify `payload_hash`
3. verify `request_id` when the event is correlated to the opening request
4. verify timestamp freshness if applicable
5. only then accept the event payload

## Anti-Replay Model

Transport anti-replay uses:

- `timestamp_ms`
- `request_id`

The server accepts requests only inside an allowed time window.
The current gateway v1 freshness window is symmetric `±5 minutes` around
server time.
Recently seen `request_id` values must be tracked for the corresponding session and rejected on reuse.
Replay reservations should remain active until `timestamp_ms + freshness_window`
so future-skewed but still valid requests stay protected after acceptance.

This protects transport freshness.
It does not replace business idempotency.

## Server Time Offset

Clients use server time offset instead of trusting local clock directly.

Expected approach:

- client establishes an authenticated `SubscribeEvents` gRPC stream
- server provides current server time
- client computes local offset
- subsequent signed requests use adjusted time

No extra sync request is required when the authenticated push stream is already
open.

## TLS and MITM Considerations

### Native Clients notes

Native clients should use TLS pinning in addition to signed request/response exchange.
Pinning should be based on public key / SPKI rather than leaf certificate whenever possible.

### Browser / WASM Clients notes

Real TLS pinning is not available in the browser in the same way as in native clients.
Browser clients still use the signed request/response model, but browser-managed TLS remains the platform limitation.

## Threat Model Boundaries

This design protects against:

- request/response tampering in transit
- replay of previously seen transport messages inside the protected window
- use of unknown or revoked device sessions
- forged server responses without server signing key
- forged client requests without client signing key

This design does not guarantee that a legitimate user cannot generate their own valid requests from their own client environment.
That is handled by server-side business validation and authorization.

## Architectural Notes

- Transport authentication and business authorization are separate concerns.
- Signed transport proves message origin and integrity.
- Business services must still validate command correctness, ownership, permissions, and state transitions.
- Transport `request_id` is not the same as business idempotency key.

## Recommended Outcome

The system should treat the secure exchange layer as the mandatory outer contract for all authenticated traffic.
Only after successful transport validation may payload be routed to business logic.