feat: authsession service

authsession/docs/examples.md

@@ -0,0 +1,194 @@
+# 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