Skip to content

Commit 9468252

Browse files
committed
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.
1 parent 9c2cf3e commit 9468252

2 files changed

Lines changed: 170 additions & 71 deletions

File tree

‎CONSUMING_AUTH.md‎

Lines changed: 134 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ patched, prevent request/header logging from recording cookies, and remove aband
9191
`localhost` cannot receive the production `.syntax.fm` cookie, so every app runs one shared local
9292
Syntax Auth on `http://localhost:37960`, and each app's own dev server serves sign-in and sign-out
9393
at the app's own address. A browser never needs to reach `localhost:37960` itself, so an app works
94-
the same on `localhost`, on a LAN or Tailscale address, and on an HTTPS name you run yourself. None
95-
of it needs secrets, 1Password, a GitHub OAuth App, hosts-file entries, certificates, or an HTTPS
96-
proxy set up for you.
94+
the same on `localhost`, on a LAN or VPN address, and on an HTTPS name you run yourself. None of it
95+
needs secrets, a GitHub OAuth App, hosts-file entries, certificates, or an HTTPS proxy set up for
96+
you.
9797

9898
### Set up the app
9999

@@ -112,8 +112,9 @@ proxy set up for you.
112112
});
113113
```
114114

115-
An app that serves some paths from another local server (Lab's sync server) lists them, and the
116-
dev server proxies them, HTTP and WebSocket, from the app's own address:
115+
An app that serves some paths from another local server (a sync or WebSocket server, for
116+
example) lists them, and the dev server proxies them, HTTP and WebSocket, from the app's own
117+
address:
117118

118119
```ts
119120
syntax_auth({ routes: [{ path: '/parties/*', port: 1348 }] });
@@ -147,14 +148,12 @@ Production's contract above stays as it is. In development builds:
147148
without the app guessing either. The page signs in with one button and returns to `<path>`;
148149
anything but a path on the same app (an absolute or `//` URL, a backslash, a control character,
149150
or a `/__syntax_auth/` path) returns to `/`. A browser already signed in goes straight back.
150-
- **Sign out.** Render a form that posts to the app's own address, as below. It signs out
151-
centrally and returns to `return_to` (default `/`). There is no GET sign-out. An app server may
152-
still call `POST http://localhost:37960/api/auth/sign-out` itself with the browser's whole
153-
`Cookie` header and its own origin as `Origin`, but local Syntax Auth accepts that only from
154-
`http://localhost:<port>` and `http://127.0.0.1:<port>`; apps on any other address use the form.
155-
Either way, it ends the session of every local session cookie the `Cookie` header carries (see
156-
below) and answers with a `Set-Cookie` header clearing each, which the app forwards one by one,
157-
unchanged.
151+
- **Sign out.** Either render the form below, which posts to the development proxy at the app's
152+
own address and returns to `return_to` (default `/`), or keep the app's own `POST` sign-out
153+
endpoint and have its server call local Syntax Auth, as described next. Both work on every
154+
address and sign out centrally. There is no GET sign-out. Either way, local Syntax Auth ends the
155+
session of every local session cookie the `Cookie` header carries (see "Cookies and sessions
156+
per address") and answers with a `Set-Cookie` header clearing each.
158157

159158
```html
160159
<form method="post" action="/__syntax_auth/sign-out">
@@ -163,33 +162,108 @@ Production's contract above stays as it is. In development builds:
163162
</form>
164163
```
165164

165+
### Signing out from the app's own server
166+
167+
An app's own sign-out endpoint works for any browser origin the app itself has validated, on
168+
`localhost` or any other address, when its server does what the development proxy does:
169+
170+
1. Accept only `POST`. Read the browser's `Origin` and accept it only when it equals, exactly
171+
(scheme, host, and port), one of the origins the app can prove for this request: the request
172+
URL's own origin (the connection's scheme and the `Host` header) or a configured public origin
173+
(`SYNTAX_AUTH_PUBLIC_ORIGINS`, below) with that very host and port. Never derive an origin from
174+
`X-Forwarded-Host`, `X-Forwarded-Proto`, `Forwarded`, or any other header a client can send.
175+
Refuse a missing or `null` `Origin`, and a `Sec-Fetch-Site` other than `same-origin` when one
176+
is sent.
177+
2. Call `POST http://localhost:37960/api/auth/sign-out` with the browser's whole `Cookie` header
178+
unchanged, `Cache-Control: no-store`, `Origin: <the checked origin>`, and
179+
`x-syntax-auth-dev-origin: <the same origin>`. Build these headers on the server rather than
180+
copying the incoming request's headers through.
181+
3. Forward every returned `Set-Cookie` header to the browser as its own header, unchanged, on
182+
success and on failure, and return to the app with a relative `Location` (such as `/`).
183+
184+
`x-syntax-auth-dev-origin` belongs only on this server-to-loopback call. Local Syntax Auth reads
185+
it only in local mode, only on its loopback names, and only when it is a bare http or https origin.
186+
If `Origin` is present, it must match that value; a mismatch gets a 403 and a malformed private
187+
header gets a 400. The service also accepts a valid private header without `Origin` from a
188+
loopback caller. Consumer servers must still validate the browser origin and send both headers
189+
as described above. The service trusts that one origin for the request and clears cookies for
190+
its scheme. An app must
191+
ignore any copy a client sends to the app (never forward or trust it; the value it sends is the
192+
one it checked itself), and never send the header to production. Without the header, local Syntax
193+
Auth trusts only `http://localhost:<port>` and `http://127.0.0.1:<port>` origins.
194+
195+
### What the app server is responsible for
196+
197+
The development proxy's limits (below) cover only the proxy's own calls. An app server's direct
198+
calls to `http://localhost:37960` (get-session and sign-out) need their own:
199+
200+
- **One deadline per call, including any body read.** Session validation must bound both
201+
response headers and reading the whole body; Syntax's own apps use 5 seconds. A development
202+
build may also ask get-session without a cookie, so a stopped local Syntax Auth shows as an
203+
outage rather than a sign-in that can't work; that anonymous call gets the same deadline.
204+
A sign-out consumer that uses only the status and cookies may discard the body immediately
205+
instead of reading it. It must not wait indefinitely on an unused body or claim to validate it.
206+
- **The browser's request ends the call.** Where the runtime gives the incoming request an abort
207+
signal, pass it on: a request that already ended sends nothing, and one that ends partway
208+
cancels the call and its body.
209+
- **The exact `Cookie` header.** Use a fetch that sends it byte for byte. In SvelteKit that is the
210+
global `fetch`, not `event.fetch`, which rebuilds the `Cookie` header for requests to the page's
211+
own hostname, such as `localhost`.
212+
- **Separate `Set-Cookie` headers.** Keep them as soon as the response headers arrive, so a body
213+
that then fails or passes the deadline still forwards a refresh or a clear, each as its own
214+
header.
215+
- **No redirects followed, nothing repeated.** Don't follow a redirect from local Syntax Auth
216+
(`redirect: 'manual'`); treat a non-2xx answer or an unreadable session body as a failure. Never
217+
retry a call by itself.
218+
219+
How a signed-out or failed request is answered depends on its kind, and that is the app's job, in
220+
the form its framework expects:
221+
222+
- A document `GET` may redirect to sign-in, or show a page that names the problem and its fix with
223+
a **Try again** link the person chooses.
224+
- A client-side data request or remote read sent as `GET` gets the framework's own redirect or
225+
error answer for that kind of request (a plain `302` to a `fetch` is followed silently). Use what
226+
the framework itself sends; don't invent a format.
227+
- Anything other than `GET` (form actions, commands, mutations) gets an error, never a redirect,
228+
and is never replayed.
229+
230+
Nothing reloads or retries by itself, so an outage can't loop.
231+
166232
### Addresses
167233

168234
- **`localhost`** works out of the box, on any port.
169-
- **A LAN or Tailscale IP address** (`http://192.168.1.20:5173`, `http://100.101.102.103:5173`, or
170-
an IPv6 address) works once the dev server listens on the network, which stays opt-in: for
171-
example `pnpm dev --host`, or the app's own way of setting Vite's `server.host`.
235+
- **A LAN or VPN IP address** (`http://192.0.2.10:5173`, or an IPv6 address such as
236+
`http://[2001:db8::10]:5173`) works once the dev server listens on the network, which stays
237+
opt-in: for example `pnpm dev --host`, or the app's own way of setting Vite's `server.host`.
172238
- **Any other name**, over http or https, is set per developer, without editing the app, in
173239
`SYNTAX_AUTH_PUBLIC_ORIGINS` (origins separated by commas or spaces), for example
174-
`SYNTAX_AUTH_PUBLIC_ORIGINS=http://box.tail1234.ts.net:5173,https://lab.example.dev pnpm dev`.
240+
`SYNTAX_AUTH_PUBLIC_ORIGINS=http://dev.example.com:5173,https://app.example.com pnpm dev`.
175241
The plugin adds each origin's name to Vite's `server.allowedHosts` (never `allowedHosts: true`),
176242
and the proxy accepts that origin. An app may also pass `public_origins` to the plugin. Vite's
177243
own `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` lets a name through Vite's host check too, but only
178244
`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
185256

186257
Cookies are host-only: a sign-in on http sets `better-auth.session_token`, and one on https sets
187258
`__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:
193267

194268
- get-session reads the `__Secure-` one, as before (and as Better Auth's `getSessionCookie` does);
195269
- 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
223297
- A route's request goes only to `127.0.0.1:<its port>`, with its original path and `Host`. A path
224298
with a `.` or `..` segment, an empty segment, a backslash, or an encoded dot, slash, or backslash,
225299
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
227301
accepting within 5 seconds and answering within 15, with at most 64 KB; a route accepting within
228302
5 seconds, starting its answer within 30, with a request body of at most 1 MB and an exchange
229303
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
234308
again** link (or, for a sign-out, a button) the person chooses; the dev server log gets the same
235309
line, without cookies or tokens.
236310

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.
245320

246321
### Starting local Syntax Auth
247322

@@ -279,11 +354,19 @@ Auth itself run `pnpm dev` or `pnpm preview` in this repository, which stops the
279354
serves the same port; other apps then use that server. When it stops, it starts the container
280355
again.
281356

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.
287370

288371
### Local mode
289372

@@ -300,9 +383,11 @@ The container publishes its port on `127.0.0.1` only.
300383

301384
Earlier versions set up `https://syntax.test`, `https://lab.syntax.test`, and
302385
`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.
306391

307392
## External domains
308393

@@ -336,6 +421,8 @@ Before considering a first-party integration complete, verify:
336421
7. On a machine where no other Syntax app is running, the app's dev command alone starts local
337422
Syntax Auth, and **Continue as Local Developer** at the app's own `/__syntax_auth/sign-in`
338423
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
341428
sign-out origins.

0 commit comments

Comments
 (0)