You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9468252
Browse filesBrowse the repository at this point in the historyBrowse files
Document shared development Auth and safe migration boundaries
Track cross-project work in Lab Dex task sjma39ae. Clarify validated direct server logout, host-only sessions, canonical origins, bounded consumer calls and cancellation responsibilities without personal setup instructions. Production behavior is unchanged.
The plugin adds each origin's name to Vite's `server.allowedHosts` (never `allowedHosts: true`),
176
242
and the proxy accepts that origin. An app may also pass `public_origins` to the plugin. Vite's
177
243
own `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` lets a name through Vite's host check too, but only
178
244
`SYNTAX_AUTH_PUBLIC_ORIGINS` tells the proxy a name is https.
179
-
-**HTTPS you run yourself** (Caddy, `tailscale serve`, or another TLS proxy): point it at the dev
180
-
server, keep the browser's `Host` header unchanged, and list the https origin in
181
-
`SYNTAX_AUTH_PUBLIC_ORIGINS`. The proxy reads the scheme from the connection itself (Vite's own
182
-
`server.https` counts) or from that list, never from `X-Forwarded-Proto` or any other header a
183
-
client could send. A sign-in from an https address the list doesn't name is refused with that
184
-
fix.
245
+
-**HTTPS you run yourself** (a local TLS proxy such as Caddy, or a managed HTTPS name that
246
+
forwards to this computer, like `https://app.example.com`): point it at the dev server, keep the
247
+
browser's `Host` header unchanged, and list the https origin in `SYNTAX_AUTH_PUBLIC_ORIGINS`. The
248
+
proxy reads the scheme from the connection itself (Vite's own `server.https` counts) or from
249
+
that list, never from `X-Forwarded-Proto` or any other header a client could send. A sign-in from
250
+
an https address the list doesn't name is refused with that fix. A public origin counts only for
251
+
its own host and port; one listed for another host, or for this host on another port, is never
252
+
accepted. An app server that checks origins itself ("Signing out from the app's own server")
253
+
reads the same list the same way.
254
+
255
+
### Cookies and sessions per address
185
256
186
257
Cookies are host-only: a sign-in on http sets `better-auth.session_token`, and one on https sets
187
258
`__Secure-better-auth.session_token` with `Secure`, each with `Path=/; HttpOnly; SameSite=Lax` and
188
-
no `Domain`. Each name keeps its own session, so signing in on one doesn't sign in on another. The
189
-
app server's calls to `http://localhost:37960` read, refresh, and delete either cookie under its
190
-
own name and attributes. A browser can hold both for one name, because cookies ignore ports and a
191
-
plain cookie from a name's http address also reaches its https address (and browsers send
192
-
`__Secure-` cookies to `http://localhost`). Then:
259
+
no `Domain`. So each host name keeps its own session: `localhost`, `127.0.0.1`, a LAN address, and
260
+
`dev.example.com` each sign in separately, even when they reach the same app. Cookies ignore ports,
261
+
so every app on one name shares that name's session: signing in to one app on `localhost` signs
262
+
you in to every app on `localhost`, whatever its port, and signing out of one signs out of all of
263
+
them. The app server's calls to `http://localhost:37960` read, refresh, and delete either cookie
264
+
under its own name and attributes. A browser can hold both for one name, because a plain cookie
265
+
from a name's http address also reaches its https address (and browsers send `__Secure-` cookies
266
+
to `http://localhost`). Then:
193
267
194
268
- get-session reads the `__Secure-` one, as before (and as Better Auth's `getSessionCookie` does);
195
269
- sign-out ends both sessions, whichever address it comes from, clearing each cookie in its own
@@ -223,7 +297,7 @@ The proxy answers only `/__syntax_auth/sign-in` (GET, HEAD, POST), `/__syntax_au
223
297
- A route's request goes only to `127.0.0.1:<its port>`, with its original path and `Host`. A path
224
298
with a `.` or `..` segment, an empty segment, a backslash, or an encoded dot, slash, or backslash,
225
299
and any request target that isn't a plain path (such as an absolute URL), is refused.
226
-
- Each wait has a limit: a form of at most 4 KB arriving within 10 seconds; local Syntax Auth
300
+
- Each of the proxy's own waits has a limit: a form of at most 4 KB arriving within 10 seconds; local Syntax Auth
227
301
accepting within 5 seconds and answering within 15, with at most 64 KB; a route accepting within
228
302
5 seconds, starting its answer within 30, with a request body of at most 1 MB and an exchange
229
303
idle for at most 2 minutes. A routed WebSocket upgrade must get a complete, valid `101` answer
@@ -234,14 +308,15 @@ The proxy answers only `/__syntax_auth/sign-in` (GET, HEAD, POST), `/__syntax_au
234
308
again** link (or, for a sign-out, a button) the person chooses; the dev server log gets the same
235
309
line, without cookies or tokens.
236
310
237
-
The proxy tells local Syntax Auth the browser origin it checked in a private
238
-
`x-syntax-auth-dev-origin` header on sign-in and sign-out, and drops any copy a client sent. Local
239
-
Syntax Auth reads it only in local mode, only on its loopback names, and only when it is a bare
240
-
http or https origin (no wildcard, path, or credentials) equal to the request's `Origin`; a
241
-
malformed one gets a 400 and a mismatched one a 403. It then trusts that one origin for that
242
-
request and picks the cookie for its scheme. Browsers can't send the header to
243
-
`localhost:37960` themselves: it needs a CORS preflight, which local Syntax Auth never grants.
244
-
Deployed Syntax Auth never reads it.
311
+
The proxy tells local Syntax Auth the browser origin it checked in the private
312
+
`x-syntax-auth-dev-origin` header on sign-in and sign-out, as an app's own sign-out does, and drops
313
+
any copy a client sent, including on routed requests. Local Syntax Auth reads it only in local
314
+
mode, only on its loopback names, and only when it is a bare http or https origin (no wildcard,
315
+
path, or credentials). A malformed one gets a 400; if `Origin` is present and differs, it gets a 403. A loopback caller may omit `Origin`, but the development proxy and consumer sign-out servers
316
+
send both checked headers. The service trusts that origin for the request and picks the cookie
317
+
for its scheme.
318
+
Browsers can't send the header to `localhost:37960` themselves: it needs a CORS preflight, which
319
+
local Syntax Auth never grants. Deployed Syntax Auth never reads it.
245
320
246
321
### Starting local Syntax Auth
247
322
@@ -279,11 +354,19 @@ Auth itself run `pnpm dev` or `pnpm preview` in this repository, which stops the
279
354
serves the same port; other apps then use that server. When it stops, it starts the container
280
355
again.
281
356
282
-
The Docker image is private to the Syntax team. For syntaxfm members, the plugin pulls it with
283
-
their GitHub CLI login in a throwaway Docker config, so the token is never stored and existing
284
-
Docker logins are untouched. Team members need Docker and a signed-in GitHub CLI
285
-
(`gh auth login`), plus once per machine `gh auth refresh -h github.com -s read:packages`. Anyone
286
-
without access still runs the app, signed out.
357
+
The Docker image, `ghcr.io/syntaxfm/auth-local`, is private to the Syntax team. The plugin first
358
+
tries a plain `docker pull`, so an existing GitHub Container Registry login that can read it
359
+
works. Otherwise, for syntaxfm members, it pulls with their GitHub CLI login in a throwaway Docker
360
+
config, so the token is never stored and existing Docker logins are untouched. Team members need:
361
+
362
+
- Docker: Docker Desktop or OrbStack on macOS, or Docker Engine on Linux, usable by their user;
363
+
- the GitHub CLI, signed in with `gh auth login` (its default scopes include `read:org`, which the
364
+
membership check needs);
365
+
- active membership of the `syntaxfm` GitHub organization (a pending invite must be accepted);
366
+
- once per machine, `gh auth refresh -h github.com -s read:packages`.
367
+
368
+
Each missing piece produces one warning naming it and its fix. Anyone without access still runs
369
+
the app, signed out.
287
370
288
371
### Local mode
289
372
@@ -300,9 +383,11 @@ The container publishes its port on `127.0.0.1` only.
300
383
301
384
Earlier versions set up `https://syntax.test`, `https://lab.syntax.test`, and
302
385
`https://auth.syntax.test` on macOS (a hosts-file block, Caddy routes, and trust in Caddy's root).
303
-
That setup, its `syntax-auth-local setup` command, and its localhost redirects are gone, and local
304
-
Syntax Auth no longer answers `auth.syntax.test`. Nothing removes what it added; Syntax Auth's
305
-
`README.md` shows how to undo each step by hand, if you want to.
386
+
The per-app development proxy above supersedes that architecture: its `syntax-auth-local setup`
387
+
command and its localhost redirects are gone, and local Syntax Auth no longer answers
388
+
`auth.syntax.test`. Nothing removes what it added, and leaving it in place doesn't affect the
389
+
current setup. Syntax Auth's `README.md` describes how to inspect it and remove only what it
390
+
added, if you want to.
306
391
307
392
## External domains
308
393
@@ -336,6 +421,8 @@ Before considering a first-party integration complete, verify:
336
421
7. On a machine where no other Syntax app is running, the app's dev command alone starts local
337
422
Syntax Auth, and **Continue as Local Developer** at the app's own `/__syntax_auth/sign-in`
338
423
returns to the app signed in with its development roles, on `localhost` and on any network or
339
-
HTTPS address the developer uses.
340
-
8. A production build uses `https://auth.syntax.fm` and rejects `http://localhost` return and
424
+
HTTPS address the developer uses, and the app's sign-out ends that session on each of them.
425
+
8. In development, a failed or signed-out non-`GET` request gets an error rather than a redirect,
426
+
and nothing is retried or replayed by itself.
427
+
9. A production build uses `https://auth.syntax.fm` and rejects `http://localhost` return and
0 commit comments