galaxy-game/README_security.md

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

## 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
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`
- 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`

### Request Signing Input

The client signs canonical bytes built from:

- request domain marker, for example `myapp-request-v1`
- `protocol_version`
- `device_session_id`
- `message_type`
- `timestamp_ms`
- `request_id`
- `payload_hash`

`payload_hash` should be computed from raw `payload_bytes`.

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, for example `myapp-response-v1`
- `protocol_version`
- `request_id`
- `timestamp_ms`
- `result_code`
- `payload_hash`

The client verifies the signature using a trusted server public key.

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

## Anti-Replay Model

Transport anti-replay uses:

- `timestamp_ms`
- `request_id`

The server accepts requests only inside an allowed time window.
Recently seen `request_id` values must be tracked for the corresponding session and rejected on reuse.

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 authenticated long-polling / push connection
- server provides current server time
- client computes local offset
- subsequent signed requests use adjusted time

No extra sync request is required if push / long-polling already exists.

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