mirror of
https://github.com/nestriness/nestri.git
synced 2026-09-19 17:25:19 +03:00
f30a1432f8
Three things review caught, and one shape correction. **No credential has a default any more.** The compose file shipped `ADMIN_SHARED_SECRET` falling back to a value written in this repository — and that header bypasses token verification entirely, so anyone reading the file could act as an operator against any deployment that had not overridden it. A default is worth less than it looks here: the deployment that never set the variable is exactly the one where the default is public. Every credential now comes from `.env`, and compose refuses to start naming the variable it wanted. That also takes the last literal password out of a tracked file. **The origin ports are on loopback.** Both services speak plain HTTP and mark no cookie `Secure`, because both expect to sit behind something that terminates TLS. Published on every interface they were a way to reach the issuer around that proxy, with sign-in codes and tokens in clear text. **Mail settings are passed through rather than fixed.** The issuer was pinned to printing sign-in codes to its log, and the three delivery settings never reached it — so the documented way to configure mail could not work, and every code and recipient went to the container log instead. Printing codes is now asked for in `.env` like everything else, and with nothing configured the issuer refuses to send rather than logging. **Sandbox becomes a domain rather than a prefix.** `api.sandbox.nestri.io` and `auth.sandbox.nestri.io`, because sandbox holds whatever is not production and that set grows. One certificate for `*.sandbox.nestri.io` then covers all of it, including unpredictable per-pull-request names, and cannot be presented for production's own domain — which the zone-wide wildcard the previous shape leaned on could. Also drops `STEAM_API_KEY`. It was declared in two type definitions and read by nothing: linking an account makes no outbound call that needs it.
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# apps/api
|
|
|
|
The public HTTP API for Nestri — a [Hono](https://hono.dev) app. One handler, run either as a
|
|
Cloudflare Worker or as an ordinary HTTP server.
|
|
|
|
## 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 # The handler: middleware, routes, error handler, /doc
|
|
server.ts # The same handler behind a listening socket
|
|
middleware/auth.ts # Bearer JWT + admin shared-secret auth → Actor
|
|
routes/*.ts # Thin route namespaces (UserApi, SteamApi, ...)
|
|
utils/ # ErrorResponses, Result(), validator wrapping
|
|
wrangler.jsonc # Worker configuration, one environment per stage
|
|
Dockerfile # The container, built from the repository root
|
|
test/ # Route tests
|
|
```
|
|
|
|
## Key details
|
|
|
|
- Auth: `Authorization: Bearer <JWT>` verified against `@nestri/auth`; or the `x-nestri-admin-token` header
|
|
carrying `ADMIN_SHARED_SECRET`, which bypasses JWT verification entirely and is required — it has no
|
|
default anywhere. It is what authenticates the callers that have no user identity to present:
|
|
`POST /pairing-code/claim` (a device being paired has no identity yet, which is the whole point),
|
|
`POST /games`, `POST /games/sync`, `POST /library/sync`, `GET /waitlist`, `POST /steam/link` on behalf
|
|
of another user, and `POST /games/download-state` when an operator is repairing state a box reported.
|
|
- Errors: centralized `VisibleError` → typed JSON responses.
|
|
- Settings arrive as bindings or as environment variables, and two of them have one spelling of
|
|
each: Postgres is `HYPERDRIVE` or `DATABASE_URL`, and the route to the issuer is an `AUTH`
|
|
service binding or `AUTH_INTERNAL_URL`. Nothing here branches on which it got.
|
|
- `AUTH_ISSUER_URL` is the issuer's **public** URL and never the internal one, because it is
|
|
compared literally against the `iss` claim on every token.
|
|
|
|
## Running
|
|
|
|
```sh
|
|
bun run dev # under the Workers runtime, on :3000
|
|
bun run serve # as a plain process, on $PORT (default 3000)
|
|
```
|
|
|
|
Needs a Postgres database and a reachable issuer. Full list and deployment steps:
|
|
[`docs/deploy.md`](../../docs/deploy.md). |