github-mirrors/netris-nestri
1
0
Fork 0
mirror of https://github.com/nestriness/nestri.git synced 2026-09-19 17:25:19 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(deploy): drop the IaC layer, and make both apps runnable as containers (#325)

Browse Source 
Moving the issuer's state into Postgres (#324) removed the last thing
tying either app to one hosting provider. What was left was a deployment
tool describing resources that no longer existed — so this drops it in
favour of `wrangler`, which is what actually deploys a Worker, and adds
a second way to run each app that involves no provider at all.

## What changes

**Gone:** `alchemy.run.ts`, `docs/alchemy.md`, the `alchemy` and
`effect` root dependencies, and the two type imports that reached out of
`apps/api` into the infrastructure file.

**In its place**, per app:

| | |
|---|---|
| `wrangler.jsonc` | one environment per stage, custom-domain routes,
Hyperdrive, the `AUTH` service binding |
| `Dockerfile` + `server.ts` | the same handler behind a listening
socket |

The handler is the same one either way. What differs is only where its
settings come from, and two of them gained a second spelling so that
nothing has to branch on the runtime: Postgres arrives as a pooled
binding or as `DATABASE_URL`, and the route to the issuer is a service
binding or `AUTH_INTERNAL_URL`.

`docker-compose.yml` now brings up Postgres and both apps together,
which is both what a self-hoster runs and the shape this takes when it
stops being a set of Workers.

## `AUTH_INTERNAL_URL`, which is new

A service binding was quietly doing two jobs: routing to the issuer, and
letting the `iss` claim stay the issuer's public name. Nothing else can
do both with one setting — the public name is often not routable from
inside a deployment — so the name and the route are two settings now.
`AUTH_ISSUER_URL` is still compared literally against every token, and
is unchanged.

## DNS

Moves out of code and into [`docs/dns.md`](docs/dns.md): every hostname,
what it is for, and what answers it today. Six records that change
roughly never did not need a tool, and a table outlives whatever is
serving the names — which is the point, because some of them will stop
being Workers. `wrangler` keeps owning only the part that must stay in
step with a deploy, since a route and its hostname are one fact.

The one rule the table enforces is **one label deep on `nestri.io`**. A
certificate for `*.nestri.io` covers one level and not two, so the
sandbox names are hyphenated rather than nested —
`api-sandbox.nestri.io` can become an ordinary proxied origin later
without a certificate having to be ordered for it first. Production
hostnames are unchanged.

## Also

`EMAIL_DEV_LOG` moves from committed configuration into
`apps/auth/.dev.vars`, which `wrangler deploy` cannot upload. Printing a
live sign-in code to a log should not be one forgotten override away
from a stage somebody else can reach.

## Before this deploys

1. The Hyperdrive ids in both `wrangler.jsonc` files are placeholders.
`wrangler hyperdrive list` has the real ones. Local development works
without them.
2. The Worker names change, so the first deploy creates new Workers.
Confirm the custom domains answer, *then* remove the old Workers and
routes — that order, or the names resolve to nothing in between.
3. Set the secrets listed in [`docs/deploy.md`](docs/deploy.md). The
issuer refuses to sign anyone in without its three mail settings.

## Checks

- 316 tests pass, 0 fail, against a freshly migrated database.
- All four wrangler environments bundle with no warnings.
- Both images build, run, and report `healthy`; the API container
reaches the issuer container and rejects a bad token as 401 rather than
500.
- `AUTH_INTERNAL_URL` verified end to end: discovery and JWKS resolve
through the internal route while `iss` stays the public name.
- `oxlint` clean apart from one pre-existing unused import in
`packages/auth`.





<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR replaces the Alchemy deployment layer with direct Wrangler
configuration and container-based execution for both control-plane
applications.
- Adds Bun HTTP servers, production Dockerfiles, health checks, and a
Compose deployment for Postgres, auth, and API.
- Supports database and issuer routing through either Cloudflare
bindings or ordinary environment variables.
- Adds stage-specific Worker routes, service bindings, Hyperdrive
configuration, and deployment documentation.
- Moves DNS ownership and deployment guidance into dedicated
documentation.
- Removes unused Alchemy, Effect, and Steam API-key configuration.

<h3>Confidence Score: 5/5</h3>

The current changes appear safe to merge, with no established new
defects or outstanding previous findings.

The container and Worker configurations are internally consistent,
required privileged credentials no longer have Compose defaults, and
plaintext service ports are loopback-bound. The three previous threads
were manually resolved without explanation and therefore are not
outstanding.

<h3>Important Files Changed</h3>




| Filename | Overview |
|----------|----------|
| docker-compose.yml | Defines the self-hosted stack with required
credentials, loopback-bound ports, mail pass-through, health
dependencies, and internal issuer routing. |
| apps/api/app/middleware/auth.ts | Adds issuer access through either a
Worker service binding or AUTH_INTERNAL_URL while preserving the public
issuer used for token validation. |
| apps/api/app/server.ts | Exposes the existing API handler through
Bun’s HTTP server with a process-compatible execution context. |
| apps/auth/src/server.ts | Exposes the existing authentication handler
through Bun’s HTTP server. |
| apps/api/wrangler.jsonc | Configures API development, sandbox, and
production Workers with routes, Hyperdrive, issuer settings, and auth
service bindings. |
| apps/auth/wrangler.jsonc | Configures auth development, sandbox, and
production Workers with custom domains and Hyperdrive. |
| packages/core/src/env.ts | Supports database and issuer routing
through environment variables and removes an unused Steam API-key
setting. |


<h3>Flowchart</h3>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Client[Clients] --> Proxy[Custom domain or TLS proxy]
    Proxy --> API[API handler]
    Proxy --> Auth[Auth issuer handler]
    API -->|AUTH service binding| Auth
    API -->|AUTH_INTERNAL_URL in containers| Auth
    API --> DB[(Postgres)]
    Auth --> DB

    Wrangler[Cloudflare Wrangler runtime] --> API
    Wrangler --> Auth
    Compose[Docker Compose runtime] --> API
    Compose --> Auth
    Compose --> DB
```

<sub>Reviews (2): Last reviewed commit: ["fix(deploy): require every
credential,
a..."](f30a1432f8)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=60746897)</sub>

<!-- /greptile_comment -->
This commit is contained in:
Wanjohi
2026-09-05 13:19:44 +00:00
committed by GitHub
parent 3d0dcf3e46 f30a1432f8
commit 8c80c025be
29 changed files with 1076 additions and 1327 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.dockerignore
View File

@@ -1,18 +1,18 @@
# build/Dockerfile's context is the repo root (see build/Makefile), so this
# keeps the daemon-side context transfer to what it actually COPYs: the
# workspace manifests plus the five Rust members. Everything else here is
# TypeScript/tooling the guest rootfs build never touches.
# What no image in this repo ever wants: history, and build output produced
# outside the container.
#
# This file used to also exclude the TypeScript half, because the guest rootfs
# build was the only Dockerfile here. There are three now, and two of them are
# the TypeScript half — so what is specific to one build moved next to that
# build, as `<Dockerfile>.dockerignore`. Getting that wrong here is expensive
# in a way that is hard to see: an excluded path is not an error, it is a
# `COPY` that silently lands nothing.
.git
node_modules
target
build/output
docs
apps/api
apps/auth
packages
*.md
deno.lock
bun.lock
.env*
.zed
.github
.env
.env.*
.wrangler
dist
.output

34
.env.example
View File

@@ -1,9 +1,33 @@
STEAM_API_KEY=
DATABASE_PASSWORD=
DATABASE_HOST=
# Copy to `.env` before `docker compose up`. Compose reads every credential
# from here and has no defaults of its own — it refuses to start naming the
# variable it wanted rather than falling back to a value that would be public.
# The local database. Throwaway values are fine; these three are what compose
# creates the container with and what it builds DATABASE_URL from.
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=nestri
# For anything run outside a container — `bun dev`, `bun run db:migrate`.
DATABASE_URL=postgres://postgres:postgres@localhost:5432/nestri
# Isolated database for tests. Required by DB-backed tests; unset tests fail.
TEST_DATABASE_URL=
# Local development database (docker-compose)
DATABASE_URL=
# The issuer's public URL — the address a token's `iss` claim will carry.
AUTH_ISSUER_URL=http://localhost:1337
# Where to reach the issuer, if that is not where it lives. Unset unless the
# public name is unroutable from where the API runs; docker compose sets it.
AUTH_INTERNAL_URL=
# Turns any request carrying it into an operator, so generate one rather than
# typing something: `openssl rand -hex 32`.
ADMIN_SHARED_SECRET=
# Mail delivery. All three together, or none of them plus EMAIL_DEV_LOG=true,
# which prints sign-in codes to the log instead of sending them. Printing them
# is a local-development convenience and nothing else.
EMAIL_SEND_URL=
EMAIL_API_KEY=
EMAIL_FROM=
EMAIL_DEV_LOG=true

3
.gitignore vendored
View File

@@ -38,9 +38,6 @@ dist
.lunora-cache
lunora/_generated
# alchemy
.alchemy
#turbo
.turbo

11
CLAUDE.md
View File

@@ -13,7 +13,7 @@ apps/ what runs api, auth (TS) · nescope, neswire, nescapture, nes
nesdoctor (Rust, runs on the user's own machine)
crates/ shared Rust nesprotocol
packages/ shared TS core, auth
docs/ long-form alchemy.md
docs/ long-form deploy.md · dns.md
```
Both toolchains live at the root: `package.json` is the Bun workspace,
@@ -22,7 +22,7 @@ Both toolchains live at the root: `package.json` is the Bun workspace,
| | |
|---|---|
| `bun install` | dependencies |
| `bun dev` | local Cloudflare dev via Alchemy |
| `bun dev` | both control-plane apps locally, under the Workers runtime |
| `cargo build --workspace` · `cargo test --workspace` | the Rust half |
| `bun run deploy:sandbox` | deploy a stage |
@@ -96,8 +96,11 @@ them there rather than duplicating them here.
actor model, the error type, auth flow.
- [`apps/api/CLAUDE.md`](apps/api/CLAUDE.md) — route modules, registration,
`.meta()` vs `.openapi()`, error flow.
- [`docs/alchemy.md`](docs/alchemy.md) — infrastructure: stages, bindings,
secrets, service bindings, the CLI.
- [`docs/deploy.md`](docs/deploy.md) — the two ways each control-plane app
runs (Workers via `wrangler`, and a container), the settings each needs, and
what is shared between them.
- [`docs/dns.md`](docs/dns.md) — every hostname, what it is for, and the one
rule about their shape.
## Things worth knowing before you start

12
README.md
View File

@@ -66,7 +66,7 @@ Source and the full story: [`apps/nesdoctor`](apps/nesdoctor).
Two halves that meet over the network and share very little else, plus one
thing that runs on your own machine.
### The control plane — TypeScript, on Cloudflare Workers
### The control plane — TypeScript
| | |
|---|---|
@@ -75,8 +75,10 @@ thing that runs on your own machine.
| [`packages/core`](packages/core) | The domain: every table, every operation, no HTTP. |
| [`packages/auth`](packages/auth) | Shared auth types and subjects. |
Postgres for state, [Alchemy](https://alchemy.run) for infrastructure. See
[`docs/alchemy.md`](docs/alchemy.md).
Postgres for state. Both run on Cloudflare Workers today and as ordinary
containers wherever you like — one handler each, no infrastructure-as-code, and
a `Dockerfile` in each app. See [`docs/deploy.md`](docs/deploy.md) and
[`docs/dns.md`](docs/dns.md).
### The guest — Rust, inside the box
@@ -112,7 +114,11 @@ sandboxes, one GPU" possible instead of one tenant per card.
```sh
bun install
cp .env.example .env # compose reads every credential from here
docker compose up postgres # the database
bun run db:migrate # schema
bun dev # control plane, local Cloudflare runtime
docker compose up --build # or: the whole control plane as containers
cargo build --workspace # guest components
cargo test --workspace

178
alchemy.run.ts
View File

@@ -1,178 +0,0 @@
import * as Alchemy from 'alchemy';
import { adopt } from 'alchemy/AdoptPolicy';
import * as Cloudflare from 'alchemy/Cloudflare';
import { Redacted } from 'effect';
import * as Effect from 'effect/Effect';
const steamApiKey = Redacted.make(process.env.STEAM_API_KEY!);
const adminSharedSecret =
process.env.ADMIN_SHARED_SECRET || 'dev-admin-shared-secret-change-in-prod';
/**
* Stages where a missing setting is a deploy failure rather than a default.
*
* A stage somebody else can reach has to be configured; a throwaway one a
* developer made this morning does not. The list is the same one that decides
* observability and DNS below, named once so the two cannot drift apart.
*/
const PERMANENT_STAGES = ['production', 'sandbox', 'dev'];
/**
* Mail settings, refused rather than defaulted when a stage needs them.
*
* Verifying an address is the only way to sign in, so a worker that cannot
* send mail cannot sign anybody in — and the failure to catch is the one where
* that is discovered by a person staring at a screen that says "check your
* email". Checking here turns it into a deploy that stops with the name of the
* variable it wanted.
*/
function mailEnv(stage: string) {
const url = process.env.EMAIL_SEND_URL;
const key = process.env.EMAIL_API_KEY;
const from = process.env.EMAIL_FROM;
if (PERMANENT_STAGES.includes(stage)) {
const missing = [
['EMAIL_SEND_URL', url],
['EMAIL_API_KEY', key],
['EMAIL_FROM', from]
]
.filter(([, value]) => !value)
.map(([name]) => name);
if (missing.length > 0) {
throw new Error(
`Stage "${stage}" serves sign-in, so it needs mail delivery configured. ` +
`Missing: ${missing.join(', ')}.`
);
}
}
return {
...(url ? { EMAIL_SEND_URL: url } : {}),
...(key ? { EMAIL_API_KEY: Redacted.make(key) } : {}),
...(from ? { EMAIL_FROM: from } : {}),
// Printing a live sign-in code to the log is a thing you ask for by
// name. It is never set on a stage anyone else can reach, and the
// worker refuses to send without either this or real settings, so an
// unconfigured deploy fails loudly instead of quietly logging codes.
...(PERMANENT_STAGES.includes(stage) ? {} : { EMAIL_DEV_LOG: 'true' })
};
}
const Database = Effect.gen(function* () {
const { stage } = yield* Alchemy.Stack;
const database = stage === 'production' ? 'defaultdb' : 'sandbox';
return yield* Cloudflare.Hyperdrive.Connection('db', {
origin: {
scheme: 'postgres',
host: 'public-nestri-pg-1-atdogthbymao.db.upclouddatabases.com',
port: 11569,
database,
user: 'upadmin',
password: Redacted.make(process.env.DATABASE_PASSWORD!)
},
dev: {
scheme: 'postgres',
host: 'localhost',
port: 5432,
database: 'nestri',
user: 'postgres',
sslmode: 'disable',
password: Redacted.make('postgres')
}
});
});
export const Auth = Effect.gen(function* () {
const { stage } = yield* Alchemy.Stack;
const isPermanent = PERMANENT_STAGES.includes(stage);
return yield* Cloudflare.Worker('auth', {
main: 'apps/auth/src/index.ts',
compatibility: { flags: ['nodejs_compat'] },
// No Steam or SSH settings: the issuer serves one provider, and it is
// the email one. Linking a Steam account is `apps/api`'s job and its
// key is bound there.
env: {
HYPERDRIVE: Database,
...mailEnv(stage)
},
...(isPermanent ? { observability: { enabled: true } } : {})
});
});
export const Api = Effect.gen(function* () {
const { stage } = yield* Alchemy.Stack;
const isPermanent = PERMANENT_STAGES.includes(stage);
const prefix = stage === 'production' ? '' : `${stage}.`;
const authDomain = ['production', 'sandbox'].includes(stage)
? `${prefix}auth.nestri.io`
: undefined;
return yield* Cloudflare.Worker('api', {
main: 'apps/api/app/index.ts',
compatibility: { flags: ['nodejs_compat'] },
env: {
AUTH: Auth,
AUTH_ISSUER_URL: authDomain ? `https://${authDomain}` : 'http://localhost:1337',
HYPERDRIVE: Database,
STEAM_API_KEY: steamApiKey,
ADMIN_SHARED_SECRET: adminSharedSecret
},
...(isPermanent ? { observability: { enabled: true } } : {})
});
});
export default Alchemy.Stack(
'nestri',
{
providers: Cloudflare.providers(),
state: Alchemy.localState()
},
Effect.gen(function* () {
const { stage } = yield* Alchemy.Stack;
yield* Database;
const auth = yield* Auth;
const api = yield* Api;
if (stage === 'production' || stage === 'sandbox') {
const zone = yield* Cloudflare.Zone.Zone('zone', {
name: 'nestri.io'
}).pipe(adopt(true));
const prefix = stage === 'production' ? '' : `${stage}.`;
yield* Cloudflare.DNS.Record('auth-dns', {
zoneId: zone.zoneId,
name: `${prefix}auth.nestri.io`,
type: 'AAAA',
content: '100::',
proxied: true
});
yield* Cloudflare.DNS.Record('api-dns', {
zoneId: zone.zoneId,
name: `${prefix}api.nestri.io`,
type: 'AAAA',
content: '100::',
proxied: true
});
yield* Cloudflare.Workers.WorkerRoute('auth-route', {
zoneId: zone.zoneId,
pattern: `${prefix}auth.nestri.io/*`,
script: auth.workerName
});
yield* Cloudflare.Workers.WorkerRoute('api-route', {
zoneId: zone.zoneId,
pattern: `${prefix}api.nestri.io/*`,
script: api.workerName
});
}
return {
authUrl: auth.url.as<string>(),
apiUrl: api.url.as<string>()
};
})
);

64
apps/api/Dockerfile Normal file
View File

@@ -0,0 +1,64 @@
# The API as a container.
#
# Build from the repository root — the workspace lockfile and two shared
# packages live there, so a context rooted at this directory could not resolve
# them:
#
# docker build -f apps/api/Dockerfile -t nestri-api .
#
# The repository-wide `.dockerignore` is what this build excludes. It used to
# exclude the whole TypeScript half, because the guest rootfs build was the
# only Dockerfile here — that part now lives in `build/Dockerfile.dockerignore`,
# beside the build it belongs to.
FROM oven/bun:1.3.11-alpine AS deps
WORKDIR /app
# Manifests first, source second. Dependencies change far less often than code
# does, so this layer survives most rebuilds. Every workspace member's manifest
# has to be here even if this image does not import it: the lockfile describes
# the whole workspace, and resolving it against a partial one is not frozen.
COPY package.json bun.lock ./
COPY apps/api/package.json apps/api/
COPY apps/auth/package.json apps/auth/
COPY packages/core/package.json packages/core/
COPY packages/auth/package.json packages/auth/
# No dev dependencies. Bun runs TypeScript without a build step, so nothing in
# them is reachable at runtime — they are the type definitions, the linter and
# the deployment CLI.
RUN bun install --frozen-lockfile --production
FROM oven/bun:1.3.11-alpine AS runtime
WORKDIR /app
COPY --from=deps /app/node_modules node_modules
COPY tsconfig.json ./
COPY package.json bun.lock ./
COPY apps/api apps/api
COPY packages/core packages/core
COPY packages/auth packages/auth
# The image ships no configuration. Every setting arrives from the environment,
# which is what makes one image good for a self-hoster and for us:
#
# DATABASE_URL postgres://… required
# AUTH_ISSUER_URL the issuer's public URL required
# STEAM_API_KEY for linking an account
# ADMIN_SHARED_SECRET operator access
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000
# `bun` is a non-root user the base image already provides.
USER bun
# `/` answers without touching the database, which is the right shape for a
# liveness probe: it says this process is serving, and leaves "can it reach
# Postgres" to a readiness check that is allowed to fail loudly.
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget -q -O /dev/null http://127.0.0.1:${PORT}/ || exit 1
CMD ["bun", "run", "apps/api/app/server.ts"]

31
apps/api/README.md
View File

@@ -1,6 +1,7 @@
# apps/api
The public HTTP API for Nestri — a [Hono](https://hono.dev) app deployed as a Cloudflare Worker.
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
@@ -26,19 +27,37 @@ Routes:
```text
app/
index.ts # Hono entrypoint: middleware, routes, error handler, /doc
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
test/ # Route tests (Vitest/Bun)
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 (see `ADMIN_SHARED_SECRET`).
- 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.
- The API worker receives its bindings (`AUTH`, `HYPERDRIVE`, `STEAM_API_KEY`, `ADMIN_SHARED_SECRET`) from Alchemy — see `alchemy.run.ts` at the repo root.
- 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
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.
```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).

29
apps/api/app/index.ts
View File

@@ -1,6 +1,6 @@
import type { Hyperdrive } from '@cloudflare/workers-types';
import { Env } from '@nestri/core/env';
import { ErrorCodes, VisibleError } from '@nestri/core/error';
import type { InferEnv } from 'alchemy/Cloudflare';
import { Hono } from 'hono';
import { openAPISpecs } from 'hono-openapi';
import { cors } from 'hono/cors';
@@ -8,7 +8,6 @@ import { HTTPException } from 'hono/http-exception';
import { logger } from 'hono/logger';
import { type ContentfulStatusCode } from 'hono/utils/http-status';
import type { Api } from '../../../alchemy.run.ts';
import { auth } from './middleware/auth.js';
import { AccessTokenApi } from './routes/access-token.js';
import { GameApi } from './routes/game.js';
@@ -103,8 +102,32 @@ app.get(
})
);
/**
* Everything this app is handed, from a binding or from the environment.
*
* Two things here arrive one of two ways, and neither is a special case.
* `HYPERDRIVE` carries a connection string on a platform that pools
* connections for us, and `DATABASE_URL` says the same thing where nothing
* does. An `AUTH` binding is a route to the issuer that skips the internet,
* and `AUTH_INTERNAL_URL` is that route written out. Each pair is two
* spellings of one fact rather than two deployments, which is why nothing
* below branches on the runtime it is under.
*
* `AUTH_ISSUER_URL` is not part of either pair. It is the issuer's public
* *name*, it is required, and it is the same value however the issuer is
* reached — because it is what every token's `iss` claim is checked against.
*/
export type ApiEnv = {
AUTH?: { fetch: typeof fetch };
AUTH_ISSUER_URL?: string;
AUTH_INTERNAL_URL?: string;
HYPERDRIVE?: Hyperdrive;
DATABASE_URL?: string;
ADMIN_SHARED_SECRET?: string;
};
export default {
fetch(request: Request, env: InferEnv<typeof Api>, ctx: ExecutionContext) {
fetch(request: Request, env: ApiEnv, ctx?: ExecutionContext) {
Env.init(env as unknown as Record<string, unknown>);
return app.fetch(request, env, ctx);
}

57
apps/api/app/middleware/auth.ts
View File

@@ -9,30 +9,55 @@ import { Member } from '@nestri/core/team/member';
import type { MiddlewareHandler } from 'hono';
/**
* Reaches the auth worker over its service binding.
* Reaches the issuer, over a binding where the platform offers one.
*
* The origin has to survive. A binding routes by binding rather than by
* hostname, so the host is arbitrary — but `new Request` still demands an
* absolute URL, and stripping down to a bare path threw `Invalid URL` before
* the token was even looked at.
* A binding routes by binding rather than by hostname, which saves a trip out
* to the internet and back for a call this middleware makes on nearly every
* request. The host in the URL is then arbitrary — but `new Request` still
* demands an absolute URL, and stripping down to a bare path threw
* `Invalid URL` before the token was even looked at.
*
* Where there is no such binding the issuer is an ordinary HTTP origin at
* `AUTH_ISSUER_URL` and plain `fetch` is the whole of it. Nothing else here
* changes, because the URL being fetched is the same one either way.
*/
function bindingFetch(env: Record<string, unknown>) {
function issuerFetch(env: Record<string, unknown>, issuer: string) {
const binding = env?.AUTH as { fetch: typeof fetch } | undefined;
if (typeof binding?.fetch === 'function') {
return (input: RequestInfo | URL, init?: RequestInit) => {
const url = asUrl(input);
return binding.fetch(new Request(url, init));
};
}
// The same split the binding makes, spelled out: `AUTH_INTERNAL_URL` is
// the route and `issuer` stays the name. The client builds its URLs from
// the name, so the swap happens here, on the way out, and every claim
// checked afterwards is still checked against the name.
const internal = Env.get().AUTH_INTERNAL_URL?.replace(/\/+$/, '');
if (!internal || internal === issuer) {
return (input: RequestInfo | URL, init?: RequestInit) => fetch(asUrl(input), init);
}
return (input: RequestInfo | URL, init?: RequestInit) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
return (env.AUTH as { fetch: typeof fetch }).fetch(new Request(url, init));
const url = asUrl(input);
return fetch(url.startsWith(issuer) ? internal + url.slice(issuer.length) : url, init);
};
}
function asUrl(input: RequestInfo | URL): string {
return typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
}
/**
* The issuer must be the auth worker's **public** URL.
* The issuer must be its **public** URL.
*
* `verify` checks a token's `iss` claim against the issuer the client was
* built with, and the auth worker derives what it advertises from the URL it
* was reached on. Tokens are minted through the public URL, so they carry it.
* A placeholder like `https://auth.internal` addresses the binding perfectly
* well — the hostname is ignored there — and then disagrees with every real
* token. Discovery through the binding does not help: it answers with the
* placeholder too, because that is the host it was asked on.
* built with, and the issuer derives what it advertises from the URL it was
* reached on. Tokens are minted through the public URL, so they carry it. A
* placeholder like `https://auth.internal` addresses a binding perfectly well
* — the hostname is ignored there — and then disagrees with every real token.
* Discovery through the binding does not help: it answers with the placeholder
* too, because that is the host it was asked on.
*
* The failure is silent by nature. A rejected claim is reported as `err`,
* which is indistinguishable from an expired or forged token, so the whole
@@ -55,7 +80,7 @@ function getClient(env: Record<string, unknown>) {
return createClient({
issuer,
clientID: 'api',
fetch: bindingFetch(env)
fetch: issuerFetch(env, issuer)
});
}

40
apps/api/app/server.ts Normal file
View File

@@ -0,0 +1,40 @@
/**
* The API as an ordinary HTTP server.
*
* `index.ts` exports a handler taking `(request, env)` — the shape a Worker is
* invoked with, and also the shape of a plain function from a request to a
* response. So there is nothing here but the loop that calls it: the process
* environment stands in for the bindings, and a port stands in for the route.
*
* With no `AUTH` binding in that environment the middleware reaches the issuer
* over plain HTTP at `AUTH_ISSUER_URL`, which is a setting this deployment has
* either way. Nothing else differs.
*/
import handler, { type ApiEnv } from './index.js';
const port = Number(process.env.PORT ?? 3000);
Bun.serve({
port,
hostname: '0.0.0.0',
// A Worker runtime hands the handler a context whose `waitUntil` keeps the
// invocation alive past the response. A process does not need convincing to
// stay alive, so the equivalent is to let the promise run — with a catch,
// because an unobserved rejection here would take the server down rather
// than the request that caused it.
fetch: (request) =>
handler.fetch(
request,
process.env as unknown as ApiEnv,
{
waitUntil: (promise: Promise<unknown>) => {
void Promise.resolve(promise).catch((error: unknown) => {
console.error('[api] background task failed:', error);
});
},
passThroughOnException: () => {}
} as unknown as ExecutionContext
)
});
console.log(`[api] listening on http://0.0.0.0:${port}`);

5
apps/api/package.json
View File

@@ -1,6 +1,11 @@
{
"name": "api",
"type": "module",
"scripts": {
"dev": "wrangler dev",
"serve": "bun run app/server.ts",
"deploy": "wrangler deploy"
},
"dependencies": {
"@hono/zod-validator": "^0.9.0",
"@nestri/auth": "workspace:",

63
apps/api/wrangler.jsonc Normal file
View File

@@ -0,0 +1,63 @@
// The public API, deployed as a Cloudflare Worker.
//
// The same `app/index.ts` also runs as an ordinary HTTP server — see
// `app/server.ts` and the `Dockerfile` beside it.
//
// Hostnames and the reasoning behind their shape: `docs/dns.md`.
// Secrets, the Hyperdrive id, and how to deploy: `docs/deploy.md`.
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "nestri-api",
"main": "app/index.ts",
"compatibility_date": "2026-09-05",
"compatibility_flags": ["nodejs_compat"],
"workers_dev": false,
"dev": {
"port": 3000
},
// `AUTH` routes by binding rather than by hostname, so it is one hop
// shorter than a request over the internet and needs no public address.
// It is an optimisation and not a requirement: with no such binding the
// middleware reaches the issuer over plain HTTP at `AUTH_ISSUER_URL`,
// which is what the container path does.
//
// `wrangler dev` discovers a sibling session serving the same script name,
// so running both dev servers wires this up locally.
"services": [{ "binding": "AUTH", "service": "nestri-auth" }],
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "0000000000000000000000000000dev0",
"localConnectionString": "postgres://postgres:postgres@localhost:5432/nestri"
}
],
"vars": {
// The issuer's **public** URL, always. A token's `iss` claim carries
// the address it was minted through, and verification compares the two
// literally — so naming the binding here instead would reject every
// real token, and report it as an ordinary 401.
"AUTH_ISSUER_URL": "http://localhost:1337"
},
"env": {
"sandbox": {
"name": "nestri-api-sandbox",
"workers_dev": false,
"routes": [{ "pattern": "api.sandbox.nestri.io", "custom_domain": true }],
"observability": { "enabled": true },
"services": [{ "binding": "AUTH", "service": "nestri-auth-sandbox" }],
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<sandbox-hyperdrive-id>" }],
"vars": { "AUTH_ISSUER_URL": "https://auth.sandbox.nestri.io" }
},
"production": {
"name": "nestri-api",
"workers_dev": false,
"routes": [{ "pattern": "api.nestri.io", "custom_domain": true }],
"observability": { "enabled": true },
"services": [{ "binding": "AUTH", "service": "nestri-auth" }],
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<production-hyperdrive-id>" }],
"vars": { "AUTH_ISSUER_URL": "https://auth.nestri.io" }
}
}
}

9
apps/auth/.dev.vars Normal file
View File

@@ -0,0 +1,9 @@
# Local-only settings, read by `wrangler dev` and never uploaded by
# `wrangler deploy`. Committed because it holds no secret and because a
# checkout should be able to sign in without a mail provider.
#
# Printing a live sign-in code to the log is a thing you ask for by name. The
# issuer refuses to send with its mail settings absent rather than falling back
# to this, so a deployment that forgot them fails loudly instead of quietly
# logging usable codes.
EMAIL_DEV_LOG=true

68
apps/auth/Dockerfile Normal file
View File

@@ -0,0 +1,68 @@
# The issuer as a container.
#
# Build from the repository root — the workspace lockfile and two shared
# packages live there, so a context rooted at this directory could not resolve
# them:
#
# docker build -f apps/auth/Dockerfile -t nestri-auth .
#
# The repository-wide `.dockerignore` is what this build excludes. It used to
# exclude the whole TypeScript half, because the guest rootfs build was the
# only Dockerfile here — that part now lives in `build/Dockerfile.dockerignore`,
# beside the build it belongs to.
FROM oven/bun:1.3.11-alpine AS deps
WORKDIR /app
# Manifests first, source second. Dependencies change far less often than code
# does, so this layer survives most rebuilds. Every workspace member's manifest
# has to be here even if this image does not import it: the lockfile describes
# the whole workspace, and resolving it against a partial one is not frozen.
COPY package.json bun.lock ./
COPY apps/api/package.json apps/api/
COPY apps/auth/package.json apps/auth/
COPY packages/core/package.json packages/core/
COPY packages/auth/package.json packages/auth/
# No dev dependencies. Bun runs TypeScript without a build step, so nothing in
# them is reachable at runtime — they are the type definitions, the linter and
# the deployment CLI.
RUN bun install --frozen-lockfile --production
FROM oven/bun:1.3.11-alpine AS runtime
WORKDIR /app
COPY --from=deps /app/node_modules node_modules
COPY tsconfig.json ./
COPY package.json bun.lock ./
COPY apps/auth apps/auth
COPY packages/core packages/core
COPY packages/auth packages/auth
# The image ships no configuration. Every setting arrives from the environment,
# which is what makes one image good for a self-hoster and for us:
#
# DATABASE_URL postgres://… required
# EMAIL_SEND_URL where a code is posted \
# EMAIL_API_KEY credential for it > all three together, or none
# EMAIL_FROM the sender address /
# EMAIL_DEV_LOG `true` prints codes to the log instead of sending them
#
# With none of the three set and no `EMAIL_DEV_LOG`, the issuer refuses to send
# rather than falling back — a deployment that forgot its mail settings is
# exactly the one with nothing marking it as a real one.
ENV NODE_ENV=production
ENV PORT=1337
EXPOSE 1337
# `bun` is a non-root user the base image already provides.
USER bun
# The discovery document is served from memory and reaches no database, which
# is the right shape for a liveness probe.
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget -q -O /dev/null http://127.0.0.1:${PORT}/.well-known/oauth-authorization-server || exit 1
CMD ["bun", "run", "apps/auth/src/server.ts"]

26
apps/auth/README.md
View File

@@ -1,7 +1,8 @@
# apps/auth
The authentication worker for Nestri — a Cloudflare Worker built on
[`@nestri/auth`](../../packages/auth/README.md) (OpenAuth-style issuer).
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
@@ -26,17 +27,28 @@ Hosts the OAuth issuer and the sign-in UI:
- 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 worker verifies tokens against this issuer through `AUTH_ISSUER_URL`.
- 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 # Worker entrypoint: issuer config, stores, success callback
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
test/ # Worker tests
wrangler.jsonc # Worker configuration, one environment per stage
Dockerfile # The container, built from the repository root
test/
```
## Running
Deployed through Alchemy (`apps/auth` worker in `alchemy.run.ts` at the repo root). Its only
stateful binding is `HYPERDRIVE` (Postgres), alongside the mail settings.
```sh
bun run dev # under the Workers runtime, on :1337
bun run serve # as a plain process, on $PORT (default 1337)
```
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).

4
apps/auth/package.json
View File

@@ -2,7 +2,9 @@
"name": "auth",
"type": "module",
"scripts": {
"dev": "vite"
"dev": "wrangler dev",
"serve": "bun run src/server.ts",
"deploy": "wrangler deploy"
},
"dependencies": {
"@nestri/auth": "workspace:",

14
apps/auth/src/index.ts
View File

@@ -16,8 +16,18 @@ import { LinkedAccount } from '@nestri/core/user/linked-account';
import { sendVerificationCode } from './email.js';
/**
* Everything this issuer is handed, from a binding or from the environment.
*
* The database arrives one of two ways and neither is a special case:
* `HYPERDRIVE` carries a connection string on a platform that pools
* connections for us, `DATABASE_URL` says the same thing where nothing does.
* Both are optional here so that a deployment is free to supply either, and
* `@nestri/core`'s `Env` resolves the pair into one.
*/
type Env = {
HYPERDRIVE: Hyperdrive;
HYPERDRIVE?: Hyperdrive;
DATABASE_URL?: string;
EMAIL_SEND_URL?: string;
EMAIL_API_KEY?: string;
EMAIL_FROM?: string;
@@ -59,7 +69,7 @@ async function firstSteamLink(userID: string): Promise<string> {
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
async fetch(request: Request, env: Env, ctx?: ExecutionContext) {
Env.init(env as unknown as Record<string, unknown>);
const inner = issuer({
subjects,

42
apps/auth/src/server.ts Normal file
View File

@@ -0,0 +1,42 @@
/**
* The issuer as an ordinary HTTP server.
*
* `index.ts` exports a handler taking `(request, env)` — the shape a Worker is
* invoked with, and also the shape of a plain function from a request to a
* response. So there is nothing here but the loop that calls it: the process
* environment stands in for the bindings, and a port stands in for the route.
*
* This is the path a self-hoster takes, and the one this deployment takes when
* it stops being a Worker. Keeping it in the tree rather than writing it on
* that day is what stops the handler from quietly growing a dependency on a
* platform it will not always be on — the difference shows up as a type error
* here rather than as a discovery during a migration.
*/
import handler from './index.js';
const port = Number(process.env.PORT ?? 1337);
Bun.serve({
port,
hostname: '0.0.0.0',
// A Worker runtime hands the handler a context whose `waitUntil` keeps the
// invocation alive past the response. A process does not need convincing to
// stay alive, so the equivalent is to let the promise run — with a catch,
// because an unobserved rejection here would take the server down rather
// than the request that caused it.
fetch: (request) =>
handler.fetch(
request,
process.env as unknown as Parameters<typeof handler.fetch>[1],
{
waitUntil: (promise: Promise<unknown>) => {
void Promise.resolve(promise).catch((error: unknown) => {
console.error('[auth] background task failed:', error);
});
},
passThroughOnException: () => {}
} as unknown as ExecutionContext
)
});
console.log(`[auth] listening on http://0.0.0.0:${port}`);

59
apps/auth/wrangler.jsonc Normal file
View File

@@ -0,0 +1,59 @@
// The issuer, deployed as a Cloudflare Worker.
//
// The same `src/index.ts` also runs as an ordinary HTTP server — see
// `src/server.ts` and the `Dockerfile` beside it. Nothing in the handler is
// Workers-specific; what differs between the two is only where the settings
// below come from, so this file and the container's environment are two
// spellings of one list.
//
// Hostnames and the reasoning behind their shape: `docs/dns.md`.
// Secrets, the Hyperdrive id, and how to deploy: `docs/deploy.md`.
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "nestri-auth",
"main": "src/index.ts",
"compatibility_date": "2026-09-05",
"compatibility_flags": ["nodejs_compat"],
// No `*.workers.dev` hostname. A second address that mints tokens is a
// second issuer as far as a token's `iss` claim is concerned, and every
// token minted through it is rejected by the API.
"workers_dev": false,
"dev": {
"port": 1337
},
// Local-only settings live in `.dev.vars` beside this file rather than in
// `vars` here. `wrangler dev` reads that file and `wrangler deploy` cannot
// upload it — which is the guarantee wanted for the one setting in it:
// printing a live sign-in code to the log is a thing you ask for by name,
// and no stage anybody else can reach may have it. Written as a `vars`
// entry it would be one forgotten override away from being deployed.
// The default environment is the local one. `localConnectionString` is what
// `wrangler dev` uses, so a checkout with `docker compose up postgres`
// running needs nothing else; `id` is only read on deploy, and the two
// named environments below carry their own.
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "0000000000000000000000000000dev0",
"localConnectionString": "postgres://postgres:postgres@localhost:5432/nestri"
}
],
"env": {
"sandbox": {
"name": "nestri-auth-sandbox",
"workers_dev": false,
"routes": [{ "pattern": "auth.sandbox.nestri.io", "custom_domain": true }],
"observability": { "enabled": true },
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<sandbox-hyperdrive-id>" }]
},
"production": {
"name": "nestri-auth",
"workers_dev": false,
"routes": [{ "pattern": "auth.nestri.io", "custom_domain": true }],
"observability": { "enabled": true },
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<production-hyperdrive-id>" }]
}
}
}

29
build/Dockerfile.dockerignore Normal file
View File

@@ -0,0 +1,29 @@
# The guest rootfs build's context.
#
# A `<Dockerfile>.dockerignore` *replaces* the repository-wide `.dockerignore`
# rather than adding to it, so the first block below is that file repeated. The
# second is what only this build excludes.
#
# This build's context is the repository root (see `Makefile`), and it COPYs
# the workspace manifests plus the Rust members and nothing else. The
# TypeScript half is therefore dead weight in the context — a few megabytes
# sent to the daemon versus the whole tree.
.git
node_modules
target
build/output
.env
.env.*
.wrangler
dist
.output
docs
apps/api
apps/auth
packages
*.md
deno.lock
bun.lock
.zed
.github

864
bun.lock
View File

File diff suppressed because it is too large Load Diff

100
docker-compose.yml
View File

@@ -1,17 +1,105 @@
version: '3.8'
# The whole control plane on one machine.
#
# Two uses, deliberately the same file. It is what a self-hoster runs, and it
# is the shape this deployment takes when it stops being a set of Workers: two
# stateless processes and a database, with a reverse proxy in front of them
# terminating TLS. Nothing here knows about a hosting provider.
#
# cp .env.example .env # then fill it in
# docker compose up --build everything, built from source
# docker compose up postgres just the database, for `bun dev`
#
# **There are no credentials in this file, and none of them have defaults.**
# Every one is read from `.env`, and compose refuses to start naming the
# variable it wanted rather than falling back to something. A default is worth
# less than it looks: the deployment that never set the variable is exactly the
# one where the default is a publicly known value, and `ADMIN_SHARED_SECRET`
# below bypasses authentication entirely.
#
# Migrations are not run for you — `bun run db:migrate` against DATABASE_URL,
# because a container that migrates on boot races with the second copy of
# itself and there is eventually a second copy.
x-postgres-url: &postgres-url
DATABASE_URL: postgres://${POSTGRES_USER:?set POSTGRES_USER in .env}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:?set POSTGRES_DB in .env}
services:
postgres:
image: docker.io/postgres:18-alpine
container_name: nestri_postgres
environment:
POSTGRES_USER: postgres # Matches: user: 'postgres'
POSTGRES_PASSWORD: postgres # Matches: password: 'postgres'
POSTGRES_DB: nestri # Matches: database: 'nestri'
POSTGRES_USER: ${POSTGRES_USER:?set POSTGRES_USER in .env}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_DB: ${POSTGRES_DB:?set POSTGRES_DB in .env}
# Loopback, not every interface. `5432:5432` would publish the database to
# anything that can reach this host. The three services below talk to each
# other over the compose network and do not use this mapping at all; it is
# here only so `bun dev` and `bun run db:migrate` can reach the database
# from outside a container.
ports:
- '5432:5432' # Matches: port: 5432
- '127.0.0.1:5432:5432'
volumes:
- nestri_data:/var/lib/postgresql
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"']
interval: 5s
timeout: 5s
retries: 10
auth:
build:
# The repository root, because the lockfile and the shared packages are
# there. Same reason for the API below.
context: .
dockerfile: apps/auth/Dockerfile
container_name: nestri_auth
depends_on:
postgres:
condition: service_healthy
environment:
<<: *postgres-url
# Passed through rather than fixed here, so that setting them in `.env`
# is enough to make this deployment deliver mail. All three together or
# none of them: the issuer refuses to send when they are half configured.
EMAIL_SEND_URL: ${EMAIL_SEND_URL:-}
EMAIL_API_KEY: ${EMAIL_API_KEY:-}
EMAIL_FROM: ${EMAIL_FROM:-}
# Printing a live sign-in code to the log is a thing you ask for by name,
# and it is asked for in `.env` — not defaulted to here. With mail
# unconfigured and this unset, the issuer refuses to send rather than
# logging codes, which is the failure a self-hoster should get.
EMAIL_DEV_LOG: ${EMAIL_DEV_LOG:-}
# Loopback. This listener speaks plain HTTP and sets no `Secure` on the
# cookies it issues, because it expects to be behind something that
# terminates TLS. Published on every interface it would be a way to reach
# the issuer *around* that proxy, with codes and tokens in clear text.
ports:
- '127.0.0.1:1337:1337'
api:
build:
context: .
dockerfile: apps/api/Dockerfile
container_name: nestri_api
depends_on:
postgres:
condition: service_healthy
auth:
condition: service_started
environment:
<<: *postgres-url
# The issuer's public URL, and not `http://auth:1337`. A token carries
# the address it was minted through, and verification compares the two
# literally — so the name a browser used is the only one that can appear
# here. `AUTH_INTERNAL_URL` is how this container actually gets there.
AUTH_ISSUER_URL: ${AUTH_ISSUER_URL:?set AUTH_ISSUER_URL in .env}
AUTH_INTERNAL_URL: http://auth:1337
# A shared secret that turns any request carrying it into an operator.
# Required, with no default, for that reason.
ADMIN_SHARED_SECRET: ${ADMIN_SHARED_SECRET:?set ADMIN_SHARED_SECRET in .env to a value you generated}
# Loopback, for the same reason as the issuer above.
ports:
- '127.0.0.1:3000:3000'
volumes:
nestri_data: # Keeps your data safe when container restarts
nestri_data:

345
docs/alchemy.md
View File

@@ -1,345 +0,0 @@
# Alchemy — infrastructure as code
This project uses [Alchemy](https://alchemy.run) (v0.93.12) for infrastructure-as-code — the equivalent of SST, but targeting Cloudflare Workers instead of AWS Lambda.
## Project structure
```
web/
alchemy.run.ts # Entry point — creates scope, imports infra
infra/
stage.ts # Stage detection (Scope.getCurrentScope().stage)
secret.ts # Encrypted secrets via alchemy.secret()
auth.ts # Auth Worker resource
api.ts # API Worker resource
```
## `alchemy.run.ts` — entry point
```ts
import alchemy from 'alchemy';
const app = await alchemy('nestri', {
password: process.env.ALCHEMY_PASSWORD // required for secrets
});
// Import infra modules in dependency order (SST-style)
await import('./infra/stage.ts');
await import('./infra/secret.ts');
await import('./infra/auth.ts');
await import('./infra/api.ts');
await app.finalize();
```
Key rules:
- `alchemy(appName, opts)` creates a **scope** — resources register into this scope automatically
- `app.finalize()` must be called at the end to persist state
- Import order matters — resources that depend on others must be imported after
- `--dev` flag runs locally via Miniflare; omit it to deploy to Cloudflare
## Infra resources
Each resource is imported from `alchemy/cloudflare` and called with an ID + props:
```ts
import { Worker, KVNamespace, D1Database } from 'alchemy/cloudflare';
export const kv = await KVNamespace('my-kv');
export const db = await D1Database('my-db');
export const worker = await Worker('my-worker', {
entrypoint: 'apps/some-app/src/index.ts',
compatibility: 'node', // enables nodejs_compat flag
url: true, // assign workers.dev URL
bindings: {
KV: kv, // resource binding → KVNamespace at runtime
DB: db, // → D1Database
PLAIN_VAR: 'hello' // → plain_text binding
}
});
```
### Supported resources (subset)
| Resource | Import | Purpose |
| ------------- | -------------------- | ----------------------------------------------- |
| `Worker` | `alchemy/cloudflare` | Cloudflare Worker (entrypoint or inline script) |
| `KVNamespace` | `alchemy/cloudflare` | KV storage |
| `D1Database` | `alchemy/cloudflare` | D1 SQL database |
| `R2Bucket` | `alchemy/cloudflare` | R2 object storage |
| `Queue` | `alchemy/cloudflare` | Queue/pub-sub |
### Compatibility flag
Always add `compatibility: 'node'` to Workers that use Node.js built-ins (`node:async_hooks`, `crypto`, `node:stream`, etc.):
```ts
Worker('api', {
entrypoint: 'apps/api/app/index.ts',
compatibility: 'node' // enables nodejs_compat
});
```
## Stage detection
```ts
// infra/stage.ts
import { Scope } from 'alchemy';
const scope = Scope.getCurrentScope();
export const stage = scope?.stage ?? 'dev';
export const isPermanent = ['production', 'dev'].includes(stage);
```
Use stage for conditional infrastructure:
```ts
const api = await Worker('api', {
...(isPermanent && {
observability: { enabled: true },
logpush: true
})
});
```
Pass `--stage` flag at runtime: `bun alchemy.run.ts --stage production`
## Secrets and environment variables
Three levels of env management, from most-secure to least:
### 1. `alchemy.secret.env.X` (preferred)
```ts
// infra/secret.ts
import alchemy from 'alchemy';
export const secret = {
steamApiKey: alchemy.secret.env.STEAM_API_KEY // reads process.env at deploy time
// Equivalent to:
// steamApiKey: alchemy.secret(process.env.STEAM_API_KEY),
};
```
- Reads from `process.env` at deploy time
- Throws a descriptive error if the env var is missing
- Encrypted in Alchemy state files (`.alchemy/`)
- Deployed as `secret_text` binding (hidden from Cloudflare API)
### 2. `alchemy.env()` (non-secret config)
```ts
export const frontendUrl = alchemy.env('FRONTEND_URL', 'http://localhost:5173');
```
- Optional default value
- Plain text — not encrypted
- Deployed as `plain_text` binding
### 3. Plain strings in `bindings` (inline)
```ts
bindings: {
MY_VAR: 'hello';
}
```
- Hard-coded, visible in state files
- Deployed as `plain_text` binding
### How bindings map to runtime types
| Alchemy binding type | Deployed as | Runtime type |
| -------------------- | -------------- | -------------------------- |
| `Worker` | `service` | `Service` (has `.fetch()`) |
| `KVNamespace` | `kv_namespace` | `KVNamespace` |
| `D1Database` | `d1` | `D1Database` |
| `alchemy.secret()` | `secret_text` | `string` |
| plain `string` | `plain_text` | `string` |
| `Json(...)` | `json` | `typeof json` |
## Service bindings (Worker → Worker)
Pass one Worker as a binding to another:
```ts
// infra/auth.ts
export const auth = await Worker('auth', {
entrypoint: 'apps/auth/src/index.ts',
compatibility: 'node',
bindings: { ... },
});
// infra/api.ts
import { auth } from './auth.ts';
export const api = await Worker('api', {
entrypoint: 'apps/api/app/index.ts',
bindings: { AUTH: auth },
});
```
At runtime, `env.AUTH` is a `Service` — call it directly:
```ts
const response = await env.AUTH.fetch(request);
```
### OpenAuth client + service binding
The `@openauthjs/openauth/client` only accepts a URL string for `issuer`, so use a custom `fetch` to route through the service binding:
```ts
function getClient(env: Record<string, unknown>) {
return createClient({
issuer: 'https://auth.internal', // dummy — used for path construction
clientID: 'api',
fetch: (input, init) => {
const url = new URL(typeof input === 'string' ? input : input.url);
const request = new Request(url.pathname + url.search, init);
return (env.AUTH as { fetch: typeof fetch }).fetch(request);
}
});
}
```
## Env propagation to Workers
CF Workers receive env vars as the second argument to the `fetch` handler (`env`), NOT via `process.env`. Bridge the gap with a lazy + overridable schema:
```ts
// packages/core/src/env.ts
import { memo } from '../utils/memo.ts';
let _overrides: Record<string, unknown> = {};
export namespace Env {
export const Info = z.object({
FRONTEND_URL: z.string().optional(),
STEAM_API_KEY: z.string().optional(),
AUTH_ISSUER_URL: z.string().optional()
});
export type Info = z.infer<typeof Info>;
const _get = memo(() => Info.parse({ ...process.env, ..._overrides }));
export function get(): Info {
return _get();
}
export function init(bindings: Record<string, unknown>) {
_overrides = bindings;
_get.reset();
}
}
```
Wire in the Hono entrypoint:
```ts
export default {
fetch(request, env, ctx) {
Env.init(env); // merge CF bindings into Env
return app.fetch(request, env, ctx);
}
};
```
Now any module that imports `Env.get()` gets the correct values — on Bun dev `process.env` provides them, on CF Workers the bindings override.
## CLI usage
```sh
# Local dev (Miniflare)
bun alchemy.run.ts --dev
# Deploy to Cloudflare
bun alchemy.run.ts --stage production
# Destroy all resources
bun alchemy.run.ts --destroy
# With custom stage
bun alchemy.run.ts --stage wanjohiryan
# Password (for encrypting secrets)
export ALCHEMY_PASSWORD="some-passphrase"
```
When deploying, set `CLOUDFLARE_API_TOKEN` or configure `alchemy login`.
## Common patterns
### Conditional infra per-stage
```ts
Worker('api', {
...(isPermanent && { logpush: true }),
...(stage === 'production' && { scaling: { min: 3, max: 10 } })
});
```
### Across-app resource references
Alchemy uses top-level await in infra files — resources resolve at import time within the active scope. The scope propagates via `AsyncLocalStorage`, so any `await import()` after `alchemy(appName)` picks it up.
### .alchemy/ directory
Created automatically — contains Miniflare state, build output, and encrypted state files. Add to `.gitignore`.
```gitignore
.alchemy/
```
---
### Index Rule: Null-Safe Exclusions (`IS DISTINCT FROM`)
When writing indices to track data drift, synchronization deltas, or pending background worker states where values might be nullable, **always build a partial index utilizing Postgres-native `IS DISTINCT FROM`**.
Standard inequality operators (`!=` or `<>`) evaluate to `NULL` if either column is `NULL`, causing them to bypass standard `WHERE` index filters. Using `is distinct from` allows Postgres to treat `NULL` as a real value for state comparison:
- Excludes perfectly synchronized records completely from the index footprint.
- Optimizes heavy background worker poll queries directly into small, lightning-fast index scans.
2. Add to the Pattern: index.ts (Domain Namespace) section
Replace the existing create block and add the upsert block inside SomeModule:
```ts
// ── create ───────────────────────────────────────────────────────────
// Use Info.pick({…}) for the schema — keeps fields in sync with Info.
// Always use .returning() to get the updated row context in one database trip.
export const create = fn(Info.pick({ id: true, name: true, email: true }), async (input) => {
return Database.use(async (tx) => {
const [row] = await tx
.insert(SomeTable)
.values({
id: input.id,
name: input.name,
email: input.email ?? null
})
.returning();
return row;
});
});
// ── upsert ───────────────────────────────────────────────────────────
// Simple copies use the input values directly. For coalesce-style set
// expressions, reference the excluded pseudo-table with unqualified
// identifiers: sql`excluded.${sql.identifier(SomeTable.name.name)}` —
// interpolating a column object (or its .name string) is invalid.
export const upsert = fn(Info.pick({ id: true, name: true }), async (input) => {
return Database.use(async (tx) => {
const [row] = await tx
.insert(SomeTable)
.values({ id: input.id, name: input.name })
.onConflictDoUpdate({
target: SomeTable.id,
set: { name: input.name }
})
.returning();
return row;
});
});
```

154
docs/deploy.md Normal file
View File

@@ -0,0 +1,154 @@
# Deploying the control plane
Two apps — [`apps/api`](../apps/api) and [`apps/auth`](../apps/auth) — and two
ways to run each of them. There is one handler per app and it is the same
handler both ways: a function from a request to a response, holding no opinion
about what is calling it.
| | |
| --- | --- |
| **Cloudflare Workers**, via `wrangler` | what production and sandbox are today |
| **A container**, via the `Dockerfile` in each app | what a self-hoster runs, and where this is going |
Settings arrive as bindings in the first case and as environment variables in
the second, and `@nestri/core`'s `Env` resolves the two into one shape — so
`HYPERDRIVE` and `DATABASE_URL` are two spellings of the database, and an
`AUTH` service binding and `AUTH_INTERNAL_URL` are two spellings of the route
to the issuer. Nothing in either app branches on which it got.
Hostnames, and why they are shaped the way they are: [`dns.md`](dns.md).
## Locally
Three ways, in increasing order of how much they resemble a deployment.
```sh
cp .env.example .env # once; compose has no credentials of its own
docker compose up postgres # the database, for either of the next two
bun dev # both apps under the Workers runtime
bun run dev:server # both apps as plain processes
docker compose up --build # both apps as containers, plus the database
```
`bun dev` runs two `wrangler dev` sessions, on ports 1337 and 3000. They find
each other through wrangler's local registry, so the API reaches the issuer
over the same service binding it uses in production rather than over the
network — which is the point of running it this way. Neither needs a
Cloudflare account: the Hyperdrive binding falls back to
`localConnectionString`, which is the compose database.
Settings that exist only locally live in `apps/auth/.dev.vars` rather than in
`vars`. `wrangler dev` reads that file and `wrangler deploy` cannot upload it,
which is the guarantee wanted for the one setting in it — the one that prints
sign-in codes to the log.
`docker compose` here is Docker's plugin or `podman-compose`; both read the
file unchanged.
Migrations are never run for you, in any of the three:
```sh
bun run db:migrate # against DATABASE_URL
```
## Cloudflare Workers
Configuration is [`apps/auth/wrangler.jsonc`](../apps/auth/wrangler.jsonc) and
[`apps/api/wrangler.jsonc`](../apps/api/wrangler.jsonc). Each has two named
environments, `sandbox` and `production`, plus an unnamed default that is the
local one.
Wrangler's named environments do **not** inherit bindings from the top level —
`vars`, `services` and `hyperdrive` are repeated in each on purpose, and a
setting added to one environment and not the other is a silent hole rather than
an error.
### One-time setup
```sh
bunx wrangler login
# Once per database. Prints an id; paste it into both wrangler.jsonc files,
# replacing the placeholder for that environment.
bunx wrangler hyperdrive create nestri-production --connection-string "postgres://…"
bunx wrangler hyperdrive create nestri-sandbox --connection-string "postgres://…"
```
Hyperdrive is a connection pool in front of Postgres, and it is there because
each Worker isolate would otherwise open a connection of its own — which
Postgres answers, at some point in a busy hour, with *"sorry, too many clients
already"*. A container has one pool per process and needs none of this.
### Secrets
Set per app and per environment, and held by Cloudflare rather than by this
repository:
```sh
cd apps/auth
bunx wrangler secret put EMAIL_SEND_URL --env production
bunx wrangler secret put EMAIL_API_KEY --env production
bunx wrangler secret put EMAIL_FROM --env production
cd ../api
bunx wrangler secret put ADMIN_SHARED_SECRET --env production
```
`ADMIN_SHARED_SECRET` turns any request carrying it into an operator, so
generate it rather than choosing it — `openssl rand -hex 32` — and never give
it a default anywhere. What it is for is listed in
[`apps/api/README.md`](../apps/api/README.md).
The issuer refuses to send a sign-in code with its mail settings half
configured or absent, rather than falling back to printing codes to the log —
so a deployment that forgets these fails at the first sign-in attempt with a
message naming what is missing, instead of quietly logging usable codes.
### Deploying
```sh
bun run deploy:sandbox
bun run deploy:production
```
Both deploy the issuer first and the API second, because the API's `AUTH`
binding names a script that has to exist. The custom domains in the config are
what create the DNS records — there is no separate step, and no separate tool
holding the other half of that fact.
## Containers
```sh
docker build -f apps/api/Dockerfile -t nestri-api .
docker build -f apps/auth/Dockerfile -t nestri-auth .
```
The context is the repository root in both cases: the lockfile and the two
shared packages are there, and a context rooted at the app directory could not
reach them. Both use the repository-wide `.dockerignore`; only the guest rootfs
build has one of its own, as `build/Dockerfile.dockerignore` — a
`<Dockerfile>.dockerignore` **replaces** the repository-wide file rather than
adding to it, which is worth knowing before writing a third.
Both images are stateless and hold no configuration. What they need:
| | `auth` | `api` |
| --- | --- | --- |
| `DATABASE_URL` | required | required |
| `AUTH_ISSUER_URL` | — | required, the issuer's **public** URL |
| `AUTH_INTERNAL_URL` | — | only if that URL is unroutable from here |
| `EMAIL_SEND_URL` `EMAIL_API_KEY` `EMAIL_FROM` | all three, or none | — |
| `EMAIL_DEV_LOG` | `true` prints codes instead of sending | — |
| `ADMIN_SHARED_SECRET` | — | required; operator access |
| `PORT` | default `1337` | default `3000` |
[`docker-compose.yml`](../docker-compose.yml) at the root wires all of it
together with a Postgres, and is the smallest complete answer to *"how do I run
this myself"*.
Neither image terminates TLS or serves a certificate, and neither marks the
cookies it sets `Secure`, because both expect to sit behind something that does
terminate TLS. So put a reverse proxy in front of them and keep the origin
unreachable except through it — `docker-compose.yml` publishes their ports on
loopback only for exactly this reason, and changing that to `0.0.0.0` is a way
to reach the issuer *around* the proxy with codes and tokens in clear text.

92
docs/dns.md Normal file
View File

@@ -0,0 +1,92 @@
# DNS
Cloudflare holds the zones. Once the control plane moves off Workers that is
the only thing it holds, so this file is deliberately written to survive the
move: it says what each name **is for**, and treats what currently answers it
as a detail that changes.
There is no infrastructure-as-code here, on purpose. There are six records.
They change roughly never, they outlive several generations of whatever serves
them, and the failure mode of getting one wrong is that sign-in stops working
for everybody — which is a thing to do slowly, by hand, having read this table,
rather than as a side effect of a deploy. What *is* automated is only the part
that must stay in step with a deploy: while the control plane is a set of
Workers, `wrangler` creates and owns the four control-plane records itself,
because a route and its hostname are one fact and splitting them across two
tools is how they drift.
## The rule
**A domain gets one certificate, obtained once, and it covers that domain and
nothing else.** Names are then grouped so that the grouping is the same shape
as the certificate: production sits directly under `nestri.io`, and everything
that is not production sits under `sandbox.nestri.io`.
That is why the sandbox names are nested rather than hyphenated. `sandbox` is a
domain, not a prefix — it holds whatever is not production, which today is the
API and the issuer and later is more. Once the shape is a domain, a single
certificate for `*.sandbox.nestri.io` covers all of it, including per-pull-
request deployments at `pr-<id>.sandbox.nestri.io` if those ever arrive; those
would be unbounded and unpredictable names, which is precisely the case that a
name-by-name certificate cannot serve and a domain-wide one can.
It also means a certificate that can be presented for a sandbox name cannot be
presented for `api.nestri.io`. Leaning on the zone-wide `*.nestri.io` instead
would have given every scratch deployment a certificate for production's own
domain, which is the opposite of what a sandbox is for.
Nothing extra is needed while these are Workers — a custom domain is issued its
own certificate for the exact hostname, at any depth. The rule binds on the day
they become origins, and it is written down now because that is the day it is
expensive to have got wrong.
## `nestri.io`
| Name | What it is | Answered today by |
| ------------------------ | -------------------------------- | -------------------- |
| `nestri.io` | The website, and `ssh nestri.io` | Website |
| `api.nestri.io` | The API, production | Worker custom domain |
| `auth.nestri.io` | The issuer, production | Worker custom domain |
| `doctor.nestri.io` | Where `nesdoctor` is downloaded | Static site |
## `sandbox.nestri.io`
Everything that is not production, under one domain and one certificate.
| Name | What it is | Answered today by |
| ------------------------- | ------------------ | -------------------- |
| `api.sandbox.nestri.io` | The API, sandbox | Worker custom domain |
| `auth.sandbox.nestri.io` | The issuer, sandbox| Worker custom domain |
`auth.nestri.io` is the one name in either table that cannot be changed
casually. A token carries the address it was minted through in its `iss` claim,
and every API request verifies that claim literally — so renaming the issuer
invalidates every token in circulation at once, including the refresh tokens
that would otherwise have recovered from it. The sandbox issuer has the same
property and none of the consequences, which is the point of having one.
## After the move off Workers
Each of the four control-plane names becomes a proxied `A` record pointing at
the host running the containers, and nothing else about them changes: same
names, same `iss` claim. Cloudflare keeps terminating public TLS, so there is
no certificate on our own host to renew, and the origin is not addressable
except through the proxy.
The order that matters, on the day: create the `A` records with the proxy on,
confirm the containers answer through them, *then* remove the Worker routes.
Doing it the other way leaves a window where the name resolves to nothing.
## `nestri.link`
A second zone, reserved and not yet serving anything. It exists so that a
per-box hostname — one name, one box, the address a person opens to set their
box up — never has to live under `nestri.io` beside the control plane. Two
reasons, both of which get worse to fix later than to decide now: a box serves
content we do not write, and cookie scope is a property of the registrable
domain, so a name under `nestri.io` would put that content inside the same
cookie boundary as sign-in.
`*.nestri.link` will be proxied for the same reason the control plane is: the
public certificate stays Cloudflare's, and the only key on our own host is an
origin certificate that is useless anywhere else.

20
package.json
View File

@@ -19,25 +19,21 @@
},
"type": "module",
"scripts": {
"dev": "alchemy dev",
"dev": "wrangler dev -c apps/auth/wrangler.jsonc -c apps/api/wrangler.jsonc",
"dev:server": "bun run --cwd apps/auth serve & bun run --cwd apps/api serve",
"dev:docker": "docker compose up --build",
"db:migrate": "bun run --cwd packages/core db:migrate",
"db:push": "bun run --cwd packages/core db:push",
"test": "test",
"deploy:sandbox": "alchemy deploy --stage sandbox --yes",
"deploy:production": "alchemy deploy --stage production --yes"
},
"dependencies": {
"@effect/platform-bun": "4.0.0-beta.102",
"@effect/platform-node": "4.0.0-beta.102",
"@effect/sql-pg": "4.0.0-beta.102",
"alchemy": "^2.0.0-beta.67",
"effect": "^4.0.0-beta.102"
"deploy:sandbox": "wrangler deploy -c apps/auth/wrangler.jsonc -e sandbox && wrangler deploy -c apps/api/wrangler.jsonc -e sandbox",
"deploy:production": "wrangler deploy -c apps/auth/wrangler.jsonc -e production && wrangler deploy -c apps/api/wrangler.jsonc -e production"
},
"devDependencies": {
"oxfmt": "^0.61.0",
"oxlint": "^1.76.0"
"oxlint": "^1.76.0",
"wrangler": "^4.45.0"
},
"peerDependencies": {
"typescript": "^7.0.1-rc"
"typescript": "catalog:"
}
}

3
packages/core/CLAUDE.md
View File

@@ -401,7 +401,6 @@ export namespace Env {
export const Info = z.object({
NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
FRONTEND_URL: z.string().optional(),
STEAM_API_KEY: z.string().optional(),
AUTH_ISSUER_URL: z.string().optional() // used by API auth middleware to verify tokens
});
export type Info = z.infer<typeof Info>;
@@ -577,7 +576,7 @@ A Cloudflare Worker using `@nestri/auth` (OpenAuth). Entry point is the `success
Server-to-server calls can authenticate as an `admin` actor by setting the `x-nestri-admin-token` header to the value of `ADMIN_SHARED_SECRET`. This bypasses JWT auth entirely and grants a system-level actor with no user scope — useful for operations like adding games to the DB, syncing data, or other admin tasks.
Configure `ADMIN_SHARED_SECRET` in `.env`; defaults to the same value as `SSH_AUTH_KEY` in dev (`dev-ssh-auth-key-change-in-prod`).
Configure `ADMIN_SHARED_SECRET` in `.env`. It has no default anywhere — a known value here is an authentication bypass, so nothing falls back to one.
### Auth Middleware (`apps/api/app/middleware/auth.ts`)

19
packages/core/src/env.ts
View File

@@ -8,10 +8,25 @@ export namespace Env {
export const Info = z.object({
NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
STEAM_API_KEY: z.string().optional(),
AUTH_ISSUER_URL: z.string().optional(),
/**
* Where to *reach* the issuer, when that is not where it *lives*.
*
* `AUTH_ISSUER_URL` is an identity: a token carries the address it was
* minted through and verification compares the two literally, so it is
* the public name and can be nothing else. But the public name is
* often not routable from inside a deployment — a container on a
* private network, a host behind its own proxy — and one setting
* cannot be both.
*
* So this one is the route and the other is the name, which is the
* same split a service binding makes on its own: the binding is the
* route, and the `iss` claim is still the name. Unset means they are
* the same address, which is the ordinary case.
*/
AUTH_INTERNAL_URL: z.string().optional(),
SSH_AUTH_KEY: z.string().optional(),
ADMIN_SHARED_SECRET: z.string().optional(),