chore: Update Readme

2026-09-23 11:08:18 +03:00 · 2026-08-06 22:32:33 +03:00
parent 293c099835
commit a8b9a11de0
8 changed files with 244 additions and 3 deletions
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -0,0 +1,44 @@
+# apps/api
+
+The public HTTP API for Nestri — a [Hono](https://hono.dev) app deployed as a Cloudflare Worker.
+
+## What it does
+
+Exposes the JSON API consumed by frontends and other clients. Every route is a thin wrapper that
+validates input, delegates to a domain function in [`@nestri/core`](../../packages/core/README.md),
+and returns `{ data: ... }`. All business logic lives in the core package.
+
+Routes:
+
+| Prefix            | Purpose                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `/`               | Health check                                                  |
+| `/user`           | Current user profile, fingerprints, linked accounts           |
+| `/steam`          | Link / sync / unlink a Steam account                          |
+| `/library`        | Owned games with playtime                                     |
+| `/games`          | Game catalog                                                 |
+| `/pairing-code`   | Device pairing codes                                          |
+| `/machine`        | Host machines                                                 |
+| `/access-token`   | Short-lived access tokens                                     |
+| `/doc`            | Generated OpenAPI spec                                        |
+
+## Structure
+
+```text
+app/
+  index.ts           # Hono entrypoint: middleware, routes, error handler, /doc
+  middleware/auth.ts # Bearer JWT + admin shared-secret auth → Actor
+  routes/*.ts        # Thin route namespaces (UserApi, SteamApi, ...)
+  utils/             # ErrorResponses, Result(), validator wrapping
+test/                # Route tests (Vitest/Bun)
+```
+
+## Key details
+
+- Auth: `Authorization: Bearer <JWT>` verified against `@nestri/auth`; or the `x-nestri-admin-token` header (see `ADMIN_SHARED_SECRET`).
+- Errors: centralized `VisibleError` → typed JSON responses.
+- The API worker receives its bindings (`AUTH`, `HYPERDRIVE`, `STEAM_API_KEY`, `ADMIN_SHARED_SECRET`) from Alchemy — see `alchemy.run.ts` at the repo root.
+
+## Running
+
+Run via the root Alchemy setup (`bun alchemy.run.ts --dev`). Needs a Postgres database and an auth worker; see the root README for full dev setup.
--- a/apps/auth/README.md
+++ b/apps/auth/README.md
@@ -0,0 +1,32 @@
+# apps/auth
+
+The authentication worker for Nestri — a Cloudflare Worker built on
+[`@nestri/auth`](../../packages/auth/README.md) (OpenAuth-style issuer).
+
+## What it does
+
+Hosts the OpenID Connect / OAuth issuer and the login UI:
+
+- **Steam OAuth** — the primary login flow. After Steam redirects back, the worker fetches the
+  player's profile, creates (or finds) the `User` + `LinkedAccount` rows in Postgres, auto-creates a
+  personal team on first login, and issues a JWT `user` subject containing `{ userID, linkedAccountID }`.
+- **SSH login** — authenticates a device via its SSH fingerprint (keyed by `SSH_AUTH_KEY`),
+  resolving the identity through `Steam.resolveSshIdentity` in `@nestri/core`.
+
+## Key details
+
+- Signing keys are generated at runtime and persisted in the `AuthStorage` KV namespace.
+- JWT subjects are defined in `@nestri/core/auth/subjects`.
+- The API worker calls this worker via a service binding (`AUTH`), verified through `AUTH_ISSUER_URL`.
+
+## Structure
+
+```text
+src/index.ts      # Worker entrypoint: issuer config + success callbacks (steam, ssh)
+test/             # Worker tests
+```
+
+## Running
+
+Deployed through Alchemy (`apps/auth` worker in `alchemy.run.ts` at the repo root) with bindings
+`AuthStorage` (KV), `HYPERDRIVE` (Postgres), `STEAM_API_KEY`, `SSH_AUTH_KEY`.