Skip to content

Commit 795c115

Browse files
stolinskiclaude
andcommitted
Add zero-setup local Syntax Auth for consumer apps
- Local mode (loopback URL, no cookie domain): secret-free committed `local` Wrangler env, one-click local developer (id local-developer) instead of GitHub, localhost-only origins, refuses non-localhost hosts - Dockerfile + GitHub Action publishing ghcr.io/syntaxfm/auth-local - @syntaxfm/auth-local Vite plugin: every `pnpm dev` ensures the shared container on :37960, lock-serialized across apps, detached updates - Production serves only auth.syntax.fm (no workers.dev/preview URLs) - Consumer guide and one-prompt setup for local development Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 154ab4d commit 795c115

27 files changed

Lines changed: 657 additions & 107 deletions

‎.dev.vars.example‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎.dockerignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules
2+
.svelte-kit
3+
.wrangler
4+
.git
5+
.env
6+
.env.*
7+
.dev.vars
8+
.dev.vars.*

‎.github/workflows/local-image.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Publishes the local development image that consumer apps run (see CONSUMING_AUTH.md).
2+
name: Local development image
3+
4+
on:
5+
push:
6+
branches: [main]
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
packages: write
12+
13+
jobs:
14+
publish:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: docker/setup-qemu-action@v3
19+
- uses: docker/setup-buildx-action@v3
20+
- uses: docker/login-action@v3
21+
with:
22+
registry: ghcr.io
23+
username: ${{ github.actor }}
24+
password: ${{ secrets.GITHUB_TOKEN }}
25+
- uses: docker/build-push-action@v6
26+
with:
27+
context: .
28+
platforms: linux/amd64,linux/arm64
29+
push: true
30+
tags: ghcr.io/syntaxfm/auth-local:latest
31+
labels: org.opencontainers.image.source=https://github.com/syntaxfm/auth
32+
cache-from: type=gha
33+
cache-to: type=gha,mode=max

‎CONSUMING_AUTH.md‎

Lines changed: 58 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -86,25 +86,69 @@ unreviewed previews, or other untrusted services anywhere under `syntax.fm`.
8686
Compromise of one trusted subdomain can expose the cookie presented to that server. Keep each app
8787
patched, prevent request/header logging from recording cookies, and remove abandoned subdomains.
8888

89-
## Localhost and external domains
90-
91-
`localhost` cannot receive a `.syntax.fm` cookie. For behavior identical to production, use a
92-
controlled HTTPS development subdomain or tunnel under `syntax.fm`; because it receives the real
93-
bearer cookie, it must meet the same first-party trust requirements.
94-
95-
For plain localhost or an app outside `syntax.fm`, use this service's OIDC provider as the fallback:
89+
## Local development
90+
91+
`localhost` cannot receive the production `.syntax.fm` cookie, so every app runs one shared local
92+
Syntax Auth on `http://localhost:37960`. Cookies are shared across ports on the same host, so its
93+
host-only cookie reaches the app on any other `localhost` port, and the integration code is
94+
identical to production. It needs no secrets, 1Password, or GitHub OAuth App.
95+
96+
1. Add the `@syntaxfm/auth-local` dev dependency and its Vite plugin. Docker is the only
97+
prerequisite.
98+
99+
```sh
100+
pnpm add -D "github:syntaxfm/auth#path:/packages/auth-local"
101+
```
102+
103+
```ts
104+
import { syntax_auth } from '@syntaxfm/auth-local';
105+
106+
export default defineConfig({
107+
plugins: [syntax_auth(), sveltekit()]
108+
});
109+
```
110+
111+
Every `pnpm dev` then makes sure the one shared `syntax-auth` container is running, whether or
112+
not any other Syntax app is already running, without delaying the dev server. Any number of
113+
apps may start at once: container changes are serialized by a machine-wide lock that the OS
114+
releases even if a process crashes. It opens Docker Desktop on macOS when needed, pulls newer
115+
images and swaps them in from a detached process, keeps local users and sessions in a Docker
116+
volume, and skips Vitest. If Docker is missing or another program holds the port, it warns and
117+
the app runs signed out. Apps without Vite run the `syntax-auth-local` command before their dev
118+
server instead. Contributors working on Syntax Auth itself run `pnpm dev` in this repository,
119+
which stops the container and serves the same port; other apps then use that server.
120+
121+
2. Use `http://localhost:37960` as the Syntax Auth origin in development builds and keep
122+
`https://auth.syntax.fm` fixed in code for production builds, so no environment setting can
123+
point production elsewhere. Use the origin for `get-session`, `sign-in`, and `sign-out`. Accept
124+
`http://localhost` and `http://127.0.0.1` `return_to` and sign-out origins only in development
125+
builds.
126+
3. The app may run on any port. Local Syntax Auth accepts any `http://localhost` or
127+
`http://127.0.0.1` port for `return_to`, sign-in, and sign-out.
128+
4. Sign in with **Continue as Local Developer**. That account always has the central user ID
129+
`local-developer`. Make the app's existing local setup (seed, migration, or setup script) give
130+
this ID the roles needed for development, idempotently, so no manual step is required.
131+
Production never issues this ID.
132+
133+
Local mode turns on only when Syntax Auth runs on a loopback URL without a shared cookie domain. In
134+
that mode it serves only `localhost` requests, uses its own local D1 state and a development-only
135+
signing secret, and replaces GitHub with the local developer account. Its sessions are meaningless
136+
to production. The container publishes its port on `127.0.0.1` only.
137+
138+
## External domains
139+
140+
For an app outside `syntax.fm`, use this service's OIDC provider:
96141

97142
- Issuer: `https://auth.syntax.fm/api/auth`
98143
- Discovery: `https://auth.syntax.fm/api/auth/.well-known/openid-configuration`
99144
- Flow: Authorization Code with PKCE (`S256`), state, and nonce
100145
- Identity scopes: `openid profile email`
101146

102-
Use a maintained OIDC client and discover endpoints from metadata. This fallback does not require
147+
Use a maintained OIDC client and discover endpoints from metadata. This flow does not require
103148
a local user/session table. A server-rendered client can keep the centrally issued short-lived
104149
token in a host-only HttpOnly cookie and validate or introspect it centrally on requests. Keep the
105150
token out of browser JavaScript, validate issuer/audience/expiration, and use the OIDC `sub` as the
106-
same central user ID. Register only the exact callback needed for this localhost or external-domain
107-
fallback.
151+
same central user ID. Register only the exact callback needed for the external domain.
108152

109153
## Acceptance checks
110154

@@ -119,3 +163,7 @@ Before considering a first-party integration complete, verify:
119163
5. App authorization still blocks authenticated users without the required app role.
120164
6. Central POST sign-out clears the cookie across Syntax apps, with every `Set-Cookie` header
121165
preserved.
166+
7. On a machine where no other Syntax app is running, `pnpm dev` alone starts local Syntax Auth,
167+
and **Continue as Local Developer** returns to the app signed in with its development roles.
168+
8. A production build uses `https://auth.syntax.fm` and rejects `http://localhost` return and
169+
sign-out origins.

‎Dockerfile‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Local development image: runs Syntax Auth in its secret-free `local` mode on port 37960.
2+
# Never deploy this image; production runs on Cloudflare Workers.
3+
FROM node:22-slim
4+
WORKDIR /app
5+
RUN corepack enable
6+
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
7+
RUN pnpm install --frozen-lockfile
8+
COPY . .
9+
EXPOSE 37960
10+
VOLUME /app/.wrangler
11+
CMD ["sh", "-c", "pnpm d1:migrate:local && exec node_modules/.bin/vite dev --host 0.0.0.0"]

‎README.md‎

Lines changed: 34 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ they do not create per-app auth or session tables. This service is **auth-only a
66
dedicated D1 database is named `syntax-auth`.
77

88
**Integrating an app? Read [`CONSUMING_AUTH.md`](./CONSUMING_AUTH.md).** It defines the central
9-
first-party session contract, trust boundary, safe login return flow, central logout, and the OIDC
10-
fallback for localhost or external domains.
9+
first-party session contract, trust boundary, safe login return flow, central logout, local
10+
development against a local Syntax Auth, and the OIDC flow for external domains.
1111

1212
## Consumer agent prompts
1313

@@ -17,27 +17,34 @@ fallback for localhost or external domains.
1717
Integrate this application with Syntax Auth by following the canonical instructions at
1818
https://github.com/syntaxfm/auth/blob/main/CONSUMING_AUTH.md.
1919
20-
This is a trusted production application on syntax.fm or *.syntax.fm. Use the shared central Better
21-
Auth session. Do not create app-local auth, user, account, or session tables; do not add an OAuth
22-
client, callback handler, or app-specific auth cookie.
20+
This is a trusted application on syntax.fm or *.syntax.fm. Use the shared central Better Auth
21+
session. Do not create app-local auth, user, account, or session tables; do not add an OAuth client,
22+
callback handler, or app-specific auth cookie.
2323
2424
Forward the shared Better Auth cookie server-to-server to the central get-session endpoint with
2525
caching disabled, expose only sanitized user/session fields in the per-request context, use the
2626
validated central return flow for login, and preserve every Set-Cookie header during central logout
2727
or session refresh.
2828
29+
Local development must work with nothing but `pnpm dev`. Follow the guide's Local development
30+
section exactly: add the @syntaxfm/auth-local dev dependency and its Vite plugin (or its
31+
syntax-auth-local command before a non-Vite dev server), use http://localhost:37960 as the Syntax
32+
Auth origin and accept http://localhost return and sign-out origins in development builds only, keep
33+
https://auth.syntax.fm fixed for production builds, and make the app's local setup give the central
34+
user ID local-developer the roles needed to develop.
35+
2936
Follow the guide's trust-boundary, authorization, and acceptance-test requirements. Inspect and
3037
preserve this application's existing framework conventions while treating CONSUMING_AUTH.md as the
3138
source of truth for authentication.
3239
```
3340

34-
### OpenID Connect for localhost or external domains
41+
### OpenID Connect for external domains
3542

3643
```text
3744
Integrate this application with Syntax Auth by following the canonical instructions at
3845
https://github.com/syntaxfm/auth/blob/main/CONSUMING_AUTH.md.
3946
40-
This application runs on plain localhost or outside syntax.fm, so use the documented OpenID Connect
47+
This application runs outside syntax.fm, so use the documented OpenID Connect
4148
fallback with issuer https://auth.syntax.fm/api/auth. Use a maintained OIDC client and Authorization
4249
Code with PKCE S256, state, and nonce. Discover endpoints from provider metadata and use the OIDC
4350
sub claim as the canonical Syntax user ID.
@@ -110,20 +117,23 @@ PostgreSQL database.
110117

111118
## Local development
112119

113-
1. Copy `.dev.vars.example` to `.dev.vars` and replace every example value with local,
114-
non-production values. `.dev.vars` is ignored; never commit it.
115-
2. Apply the migration to Wrangler's local D1 state and start SvelteKit:
120+
```sh
121+
pnpm install
122+
pnpm dev
123+
```
116124

117-
```sh
118-
pnpm d1:migrate:local
119-
pnpm dev
120-
```
125+
`pnpm dev` stops the shared `syntax-auth` container if one is running, applies migrations to local
126+
D1, and serves `http://localhost:37960`. It needs no secrets:
127+
the Cloudflare adapter reads the committed `local` Wrangler environment, which has a loopback URL,
128+
no shared cookie domain, and a local-only D1 database under the ignored `.wrangler/` directory. In
129+
that mode Syntax Auth replaces GitHub with a one-click local developer account (user ID
130+
`local-developer`), trusts only `localhost` origins, and refuses requests for any other host.
131+
Deploys use the top-level configuration and never enable local mode.
121132

122-
The Cloudflare adapter supplies `event.platform.env`, including the local `DB` binding and the
123-
variables from `.dev.vars`. Local D1 data is stored under the ignored `.wrangler/` directory.
124-
Leave `AUTH_COOKIE_DOMAIN` unset locally: localhost uses a host-only cookie and cannot reproduce
125-
cross-subdomain sharing. Use a controlled HTTPS Syntax development subdomain/tunnel for identical
126-
behavior, or use the OIDC fallback documented in `CONSUMING_AUTH.md`.
133+
Consumer apps run the same thing as the `ghcr.io/syntaxfm/auth-local` Docker image, published from
134+
`main` by `.github/workflows/local-image.yml` and started by the `packages/auth-local` Vite plugin;
135+
see `CONSUMING_AUTH.md`. The port lives in `packages/auth-local/index.js`, `vite.config.ts`, and the
136+
`local` and `oauth-registration` envs in `wrangler.jsonc`.
127137

128138
Useful commands:
129139

@@ -144,8 +154,8 @@ with Wrangler's `d1:migrate:local` and `d1:migrate:remote` commands.
144154
## Register an OAuth client for fallback consumers
145155

146156
Production first-party `*.syntax.fm` applications use the shared central session and do not need an
147-
OAuth client. Registration is only for plain localhost or consumers outside `syntax.fm` that use
148-
the OIDC fallback.
157+
OAuth client, including during local development. Registration is only for consumers outside
158+
`syntax.fm` that use the OIDC flow.
149159

150160
Dynamic and unauthenticated client registration remain disabled. The registration command loads
151161
the D1 binding through Wrangler's supported platform proxy and calls Better Auth's server-only
@@ -177,8 +187,8 @@ pnpm oauth:register \
177187
```
178188

179189
Remote registration requires Wrangler authentication. The dedicated `oauth-registration` Wrangler
180-
environment marks only the D1 binding as remote; local values from `.dev.vars` initialize Better
181-
Auth without exposing production Worker secrets to the Node script. Better Auth performs the client
190+
environment marks only the D1 binding as remote and initializes Better Auth in local mode, without
191+
exposing production Worker secrets to the Node script. Better Auth performs the client
182192
secret hashing and storage. The generated client secret is printed once, so store it immediately in
183193
the client application's secret manager. Omit `--skip-consent` unless the client is trusted. Add
184194
`--public` for a client that cannot hold a secret; PKCE is required for every registered client.
@@ -195,7 +205,7 @@ Discovery metadata is available at:
195205
- `/api/auth/.well-known/oauth-authorization-server`
196206
- `/.well-known/oauth-authorization-server/api/auth`
197207

198-
`GET /api/health` returns `{ "status": "ok" }` without opening D1 or requiring auth secrets.
208+
`GET /api/health` returns `{ "status": "ok", "service": "syntax-auth" }` without opening D1 or requiring auth secrets.
199209

200210
After deployment, verify health and discovery before updating any consumer to use the new issuer:
201211

‎package.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,16 @@
44
"private": true,
55
"type": "module",
66
"scripts": {
7-
"dev": "vite dev",
7+
"dev": "docker stop syntax-auth >/dev/null 2>&1; pnpm d1:migrate:local && vite dev",
88
"build": "vite build",
9-
"preview": "pnpm build && wrangler dev",
9+
"preview": "pnpm build && wrangler dev --env local",
1010
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
1111
"lint": "prettier --check . && eslint .",
1212
"format": "prettier --write .",
1313
"cf-typegen": "wrangler types",
1414
"db:generate": "drizzle-kit generate",
1515
"d1:migration:create": "wrangler d1 migrations create syntax-auth",
16-
"d1:migrate:local": "wrangler d1 migrations apply syntax-auth --local",
16+
"d1:migrate:local": "wrangler d1 migrations apply syntax-auth --local --env local",
1717
"d1:migrate:remote": "wrangler d1 migrations apply syntax-auth --remote",
1818
"deploy": "pnpm build && wrangler deploy --env=\"\"",
1919
"oauth:register": "tsx scripts/register_oauth_client.ts"

‎packages/auth-local/bin.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env node
2+
// For non-Vite dev scripts: `syntax-auth-local && next dev`.
3+
import { ensure_syntax_auth } from './index.js';
4+
5+
await ensure_syntax_auth();

0 commit comments

Comments
 (0)