mirror of
https://github.com/nestriness/nestri.git
synced 2026-11-03 22:22:39 +02:00
Wanjohi
bd4029ba6e
bun run preview (in apps/auth) serves a gallery of all 18 states the sign-in flow can show, at desktop and phone sizes, each one also viewable full size. It needs no database or mail: each state is the real screen value, drawn by the real renderer with the real theme. bun --watch restarts the server on any change to the renderer, the stylesheet or the copy, and every page polls for the restart and reloads itself, so styling is edit, save, look.
63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# apps/auth
|
|
|
|
The authentication service for Nestri, built on
|
|
[`@nestri/auth`](../../packages/auth/README.md) (OpenAuth-style issuer). One
|
|
handler, run either as a Cloudflare Worker or as an ordinary HTTP server.
|
|
|
|
## What it does
|
|
|
|
Hosts the OAuth issuer and the sign-in UI:
|
|
|
|
- **Email code** — the only provider, on purpose. Verifying an email address is the one thing that
|
|
brings an account into existence, so an account is exactly as recoverable as its email. The
|
|
`success` callback finds or creates the `User` row, ensures a personal team exists, and issues a
|
|
JWT `user` subject containing `{ userID, linkedAccountID }`.
|
|
- **Device authorization grant** (RFC 8628) — for programs with no browser. A client starts a grant,
|
|
a person approves it in a browser, and the client collects tokens by polling. Connecting a Steam
|
|
account is not a sign-in and lives in `apps/api` instead, against a user who already exists.
|
|
|
|
## Key details
|
|
|
|
- **All issuer state is in Postgres.** There is no key-value binding. Signing keys, authorization
|
|
codes, refresh tokens and device grants each have a table, because each is either a record whose
|
|
loss ends every session (the keys) or one with a transition that must happen exactly once while
|
|
two callers are touching it — a code is redeemed once, a refresh token is spent once, a grant is
|
|
approved once. A store that reads and writes whole records cannot promise that. What is left in
|
|
the generic `auth_kv` table is the rate-limit counters, which are allowed to be approximate.
|
|
- Authorization codes, refresh tokens and device codes are stored as hashes. Each is a bearer
|
|
credential, so what is kept is enough to recognise one and not enough to present it.
|
|
- JWT subjects are defined in `@nestri/core/auth/subjects`.
|
|
- The API verifies tokens against this issuer through `AUTH_ISSUER_URL`, which must be this
|
|
service's **public** URL: a token carries the address it was minted through and the check is
|
|
literal.
|
|
|
|
## Structure
|
|
|
|
```text
|
|
src/index.ts # The handler: issuer config, stores, success callback
|
|
src/server.ts # The same handler behind a listening socket
|
|
src/email.ts # Verification code delivery
|
|
src/theme.ts # Title, favicon, brand colour and fonts
|
|
script/preview.ts # Every screen state, for styling without a database
|
|
wrangler.jsonc # Worker configuration, one environment per stage
|
|
Dockerfile # The container, built from the repository root
|
|
test/
|
|
```
|
|
|
|
## Running
|
|
|
|
```sh
|
|
bun run dev # under the Workers runtime, on :1337
|
|
bun run serve # as a plain process, on $PORT (default 1337)
|
|
bun run preview # every sign-in screen state on :1338, reloading on save
|
|
```
|
|
|
|
The preview needs no database or mail. It renders each screen the flow can show — every
|
|
alert, every device-grant outcome — with the real renderer and theme, so styling
|
|
`packages/auth/src/ui/` is edit, save, look. A screen added to the flow belongs in its `STATES`
|
|
list too, or nobody will see it before it ships.
|
|
|
|
Its only stateful dependency is Postgres — as a `HYPERDRIVE` binding on Workers, or as
|
|
`DATABASE_URL` anywhere else — alongside the mail settings. Full list and deployment steps:
|
|
[`docs/deploy.md`](../../docs/deploy.md).
|