galaxy-game/authsession/docs/examples.md

# Configuration And Contract Examples

The examples below are illustrative. Values such as keys, codes, and IDs are
placeholders unless explicitly stated otherwise.

## Example Environment

Minimal local-development shape:

```dotenv
AUTHSESSION_REDIS_ADDR=127.0.0.1:6379
AUTHSESSION_PUBLIC_HTTP_ADDR=:8080
AUTHSESSION_INTERNAL_HTTP_ADDR=:8081

AUTHSESSION_USER_SERVICE_MODE=stub
AUTHSESSION_MAIL_SERVICE_MODE=stub

OTEL_SERVICE_NAME=galaxy-authsession
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=none
```

Example REST-backed integration shape:

```dotenv
AUTHSESSION_REDIS_ADDR=127.0.0.1:6379

AUTHSESSION_USER_SERVICE_MODE=rest
AUTHSESSION_USER_SERVICE_BASE_URL=http://127.0.0.1:8091
AUTHSESSION_USER_SERVICE_REQUEST_TIMEOUT=1s

AUTHSESSION_MAIL_SERVICE_MODE=rest
AUTHSESSION_MAIL_SERVICE_BASE_URL=http://127.0.0.1:8092
AUTHSESSION_MAIL_SERVICE_REQUEST_TIMEOUT=1s
```

## Public Auth HTTP Examples

Start an e-mail challenge:

```bash
curl -X POST http://127.0.0.1:8080/api/v1/public/auth/send-email-code \
  -H 'Content-Type: application/json' \
  -d '{"email":"pilot@example.com"}'
```

Example response:

```json
{
  "challenge_id": "challenge-123"
}
```

Confirm the challenge and register the device public key:

```bash
curl -X POST http://127.0.0.1:8080/api/v1/public/auth/confirm-email-code \
  -H 'Content-Type: application/json' \
  -d '{
    "challenge_id": "challenge-123",
    "code": "123456",
    "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no="
  }'
```

Example response:

```json
{
  "device_session_id": "device-session-123"
}
```

Stable public error example:

```json
{
  "error": {
    "code": "challenge_expired",
    "message": "challenge expired"
  }
}
```

## Trusted Internal HTTP Examples

Read one session:

```bash
curl http://127.0.0.1:8081/api/v1/internal/sessions/device-session-123
```

Example response:

```json
{
  "session": {
    "device_session_id": "device-session-123",
    "user_id": "user-123",
    "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no=",
    "status": "active",
    "created_at": "2026-04-05T12:00:00Z"
  }
}
```

Revoke one session:

```bash
curl -X POST http://127.0.0.1:8081/api/v1/internal/sessions/device-session-123/revoke \
  -H 'Content-Type: application/json' \
  -d '{"reason_code":"admin_revoke","actor":{"type":"system"}}'
```

Example response:

```json
{
  "outcome": "revoked",
  "device_session_id": "device-session-123",
  "affected_session_count": 1
}
```

Block by e-mail:

```bash
curl -X POST http://127.0.0.1:8081/api/v1/internal/user-blocks \
  -H 'Content-Type: application/json' \
  -d '{"email":"pilot@example.com","reason_code":"policy_blocked","actor":{"type":"admin","id":"admin-1"}}'
```

Example response:

```json
{
  "outcome": "blocked",
  "subject_kind": "email",
  "subject_value": "pilot@example.com",
  "affected_session_count": 0,
  "affected_device_session_ids": []
}
```

## Redis Projection Examples

### Gateway Session Cache Record

Example Redis key and JSON value written by authsession for gateway:

```text
gateway:session:device-session-123
```

```json
{
  "device_session_id": "device-session-123",
  "user_id": "user-123",
  "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no=",
  "status": "active"
}
```

### Gateway Session-Event Stream Entry

Active snapshot:

```bash
redis-cli XADD gateway:session_events '*' \
  device_session_id device-session-123 \
  user_id user-123 \
  client_public_key 11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no= \
  status active
```

Revoked snapshot:

```bash
redis-cli XADD gateway:session_events '*' \
  device_session_id device-session-123 \
  user_id user-123 \
  client_public_key 11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no= \
  status revoked \
  revoked_at_ms 1775121700000
```

Notes:

- projected field values are strings in the Redis Stream payload
- `revoked_at_ms` is written only for revoked snapshots
- duplicate full-snapshot stream events are acceptable
- the cache snapshot and stream event intentionally omit revoke reason and
  actor metadata because gateway does not consume them