@@ -6,8 +6,8 @@ they do not create per-app auth or session tables. This service is **auth-only a
66dedicated 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.
1717Integrate this application with Syntax Auth by following the canonical instructions at
1818https://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
2424Forward the shared Better Auth cookie server-to-server to the central get-session endpoint with
2525caching disabled, expose only sanitized user/session fields in the per-request context, use the
2626validated central return flow for login, and preserve every Set-Cookie header during central logout
2727or 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+
2936Follow the guide's trust-boundary, authorization, and acceptance-test requirements. Inspect and
3037preserve this application's existing framework conventions while treating CONSUMING_AUTH.md as the
3138source of truth for authentication.
3239```
3340
34- ### OpenID Connect for localhost or external domains
41+ ### OpenID Connect for external domains
3542
3643``` text
3744Integrate this application with Syntax Auth by following the canonical instructions at
3845https://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
4148fallback with issuer https://auth.syntax.fm/api/auth. Use a maintained OIDC client and Authorization
4249Code with PKCE S256, state, and nonce. Discover endpoints from provider metadata and use the OIDC
4350sub 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
128138Useful 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
146156Production 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
150160Dynamic and unauthenticated client registration remain disabled. The registration command loads
151161the D1 binding through Wrangler's supported platform proxy and calls Better Auth's server-only
@@ -177,8 +187,8 @@ pnpm oauth:register \
177187```
178188
179189Remote 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
182192secret hashing and storage. The generated client secret is printed once, so store it immediately in
183193the 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
200210After deployment, verify health and discovery before updating any consumer to use the new issuer:
201211
0 commit comments