docs: address CodeRabbit and Copilot review feedback

- Reflect current code: magic_account_session no longer exists (historical
  note only), /_magic/check-email replaced by /_internal/account-by-email,
  600s OTP TTL sourced to better-auth.ts not auth-flow.ts.
- AUTH_HOSTNAME subdomain is a recommended production relationship, not a
  hard runtime requirement (unrelated hostnames supported with null cookie
  domain).
- Scope the "in-process calls / fewer privileged endpoints" benefit to
  process-merge; origin-merge alone keeps the HTTP boundary.
- Add path-shadowing note (auth surface must move under /auth so it doesn't
  shadow pds-core's /oauth/* and /account*) and an explicit Set-Cookie
  contract (unique names, no Domain, __Host- vs /auth path-scope exclusivity).
- Require transition redirects to preserve full path + query string.
- Distinguish origin/base-URL/hostname config values (AUTH_PATH_PREFIX /
  AUTH_BASE_URL) instead of concatenating a path onto a hostname.
- Single-process merge: preserve one-time issuance gating in the direct path,
  and retain HMAC + signed callback route until legacy callers are drained
  (compatibility gate).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aspiers

docs/architecture.md

@@ -75,9 +75,16 @@ endpoint to issue an AT Protocol authorization code. For new users, a handle-pic
   `/oauth/epds-callback` is signed with `EPDS_CALLBACK_SECRET` so PDS Core can verify
   it was produced by a legitimate auth flow.
 
-- **Auth Service on a subdomain, not a single shared domain**: `AUTH_HOSTNAME`
-  must be a subdomain of `PDS_HOSTNAME` (e.g. `auth.pds.example` /
-  `pds.example`). A single-domain design — one origin, routing the auth paths
+- **Auth Service on a subdomain, not a single shared domain**: the
+  recommended production relationship is `AUTH_HOSTNAME` as a subdomain of
+  `PDS_HOSTNAME` (e.g. `auth.pds.example` / `pds.example`). This is not a hard
+  runtime requirement — the code also supports unrelated hostnames (e.g.
+  Railway preview envs where both services sit under `up.railway.app`), in
+  which case the shared cookie domain is `null` and device cookies stay
+  host-only (`deriveCookieDomain` in `pds-core/src/cookie-domain.ts`). The
+  cross-subdomain **device-session reuse** path only works when the subdomain
+  relationship holds, which is why it is the recommended arrangement. A
+  single-domain design — one origin, routing the auth paths
   by path prefix the way [pds-gatekeeper](https://tangled.org/baileytownsend.dev/pds-gatekeeper)
   does — was **considered and rejected**. The reasons:
   - **Mechanism (how the takeover happens)**: PDS Core overrides the
@@ -89,7 +96,8 @@ endpoint to issue an AT Protocol authorization code. For new users, a handle-pic
     motivation.
 
   - **Cookie isolation (the motivation)**: the Auth Service's session cookies
-    (Better Auth's `session`, historically `magic_account_session`) are a
+    (the Better Auth session cookie; historically `magic_account_session`,
+    no longer present in code) are a
     _separate authentication domain_ from AT Protocol access/refresh tokens.
     Giving the Auth Service its own origin keeps the two cookie namespaces from
     colliding by construction. (Note the tension: cross-subdomain cookie
@@ -117,12 +125,17 @@ endpoint to issue an AT Protocol authorization code. For new users, a handle-pic
   **On re-examination, none of the three benefits is a non-negotiable, and all
   the costs are artifacts of being cross-origin-but-same-site:**
   - _Cookie isolation_ is already done by explicit cookie **naming**
-    (`epds_csrf`, `magic_account_session`, the `DEVICE_COOKIE_NAMES` set), not
-    by origin — so it survives a collapse to one origin, optionally hardened
-    with a `__Host-`/path scope. The split does not just fail to be _required_
-    for isolation; it actively _creates_ a cookie problem — the
-    `Domain=<parent>` sharing in items 14–15 — that a single origin deletes
-    outright.
+    (`epds_csrf`, `epds_auth_flow`, the Better Auth session cookie, and the
+    `DEVICE_COOKIE_NAMES` device-session set), not by origin — so it survives a
+    collapse to one origin. Concretely, on a shared origin the contract is:
+    guaranteed-unique names, and **no parent `Domain` attribute** (cookies stay
+    host-only). This unique-name isolation is distinct from — and does not
+    require — `__Host-` prefixing; note `__Host-` mandates `Path=/` and so
+    cannot be combined with a `/auth` path scope, whereas plain path scoping
+    (`Path=/auth`) is an available but separate hardening option. The split
+    does not just fail to be _required_ for isolation; it actively _creates_ a
+    cookie problem — the `Domain=<parent>` sharing in items 14–15 — that a
+    single origin deletes outright.
   - _Security-header isolation_ is already per-route in both packages
     (`auth-service/src/lib/security-headers.ts` sets an auth-specific CSP per
     request; `pds-core` already rewrites the upstream CSP per response in
@@ -139,12 +152,14 @@ endpoint to issue an AT Protocol authorization code. For new users, a handle-pic
   benefits the split forecloses:
   - **Fewer privileged cross-service endpoints.** The split forces the two
     services to talk over authenticated HTTP: the HMAC-signed
-    `/oauth/epds-callback` and the `/_internal/*` / `/_magic/*` lookup
-    endpoints (e.g. `account-by-email`, `check-email`), each an attack surface
-    that has to be signed, gated, and kept in sync. Co-located on one origin,
-    much of this can become in-process calls with no wire boundary to secure.
-    (Whether to also merge the _processes_ — versus keep two behind path
-    routing — is a separate decision; see the migration doc.)
+    `/oauth/epds-callback` and the `/_internal/*` lookup endpoints (e.g.
+    `/_internal/account-by-email`, which replaced the old unauthenticated
+    `/_magic/check-email`), each an attack surface that has to be signed,
+    gated, and kept in sync. **Note this benefit requires merging the
+    _processes_, not just the origin**: a single origin with two processes
+    still has an HTTP boundary (merely same-origin now). Only a process merge
+    turns these into in-process calls with no wire boundary to secure — a
+    separate decision from origin-merging; see the migration doc.
 
   - **Operational simplicity.** One origin means one TLS cert, one DNS record,
     one CSP surface, and one set of cross-origin edge cases to reason about,

docs/design/single-domain-migration.md

@@ -13,20 +13,46 @@ that case is accepted and focuses on _how_.
 
 ## Summary of the change
 
-| Concern                                | Today (two origins)                                                 | After (one origin)                                                    |
-| -------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Auth UI location                       | `https://auth.pds.example/oauth/authorize`, `/auth/*`, `/account/*` | `https://pds.example/auth/*` (path-prefixed)                          |
-| `authorization_endpoint` (AS metadata) | `https://auth.<host>/oauth/authorize`                               | `https://<host>/auth/oauth/authorize`                                 |
-| `sec-fetch-site` on `/oauth/authorize` | `same-site`, rewritten to `same-origin` (item 5)                    | naturally `same-origin` — rewrite **deleted**                         |
-| Device-session cookies                 | `Domain=<parent>` so sibling subdomain can read them (items 14–15)  | host-only on the single origin — **plumbing deleted**                 |
-| Auth session cookie                    | `magic_account_session` / better-auth `session` on `auth.<host>`    | same names, path-scoped `/auth` on `<host>`                           |
-| CSP                                    | per-route in each service (unchanged approach)                      | per-route, unchanged                                                  |
-| Deploy units                           | two services                                                        | still two processes, one origin (Caddy path-routes) — or merged later |
+| Concern                                | Today (two origins)                                                                | After (one origin)                                                                                                     |
+| -------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Auth UI location                       | `https://auth.pds.example/oauth/authorize`, `/auth/*`, `/account/*`                | `https://pds.example/auth/*` — including `/auth/oauth/authorize` and `/auth/account/*` (see path-shadowing note below) |
+| `authorization_endpoint` (AS metadata) | `https://auth.<host>/oauth/authorize`                                              | `https://<host>/auth/oauth/authorize`                                                                                  |
+| `sec-fetch-site` on `/oauth/authorize` | `same-site`, rewritten to `same-origin` (item 5)                                   | naturally `same-origin` — rewrite **deleted**                                                                          |
+| Device-session cookies                 | `Domain=<parent>` so sibling subdomain can read them (items 14–15)                 | host-only on the single origin — **plumbing deleted** (see Set-Cookie contract below)                                  |
+| Auth session cookie                    | Better Auth session cookie (historically `magic_account_session`) on `auth.<host>` | same cookie, host-only on `<host>` (see Set-Cookie contract below)                                                     |
+| CSP                                    | per-route in each service (unchanged approach)                                     | per-route, unchanged                                                                                                   |
+| Deploy units                           | two services                                                                       | still two processes, one origin (Caddy path-routes) — or merged later                                                  |
 
 The routing model is exactly pds-gatekeeper's: **Caddy routes by path**, sending
-`/auth/*` (and the auth-owned `/oauth/authorize`, `/account/*`) to the
-auth-service process and everything else to the PDS. The auth-service stays a
-separate process; only its _origin_ changes.
+the auth surface to the auth-service process and everything else to the PDS. The
+auth-service stays a separate process; only its _origin_ changes.
+
+### Path shadowing — the auth surface must move under `/auth`
+
+On a single origin the auth service **cannot** keep serving `/oauth/authorize`
+and `/account/*` at the root: upstream `@atproto/oauth-provider` already renders
+`/oauth/*` and `/account*` on pds-core, so routing those roots to auth-service
+would shadow the PDS's own endpoints. The migration therefore exposes the entire
+auth surface under a non-conflicting prefix — `/auth/oauth/authorize`,
+`/auth/account/*`, `/auth/*` — optionally with a Caddy path-strip rewrite so the
+auth-service process can keep its current internal route paths unchanged.
+
+### Set-Cookie contract on the merged origin
+
+With one origin, the cookie isolation that the subdomain previously provided by
+separation must instead be provided by the cookie attributes:
+
+- **Auth session cookie** (Better Auth) and **CSRF / auth-flow cookies**
+  (`epds_csrf`, `epds_auth_flow`): guaranteed-**unique names**, **no `Domain`
+  attribute** (host-only), `Secure`, `HttpOnly` where applicable,
+  `SameSite=Lax`. Optionally scope non-`__Host-` cookies with `Path=/auth`.
+- **Device-session cookies** (`DEVICE_COOKIE_NAMES`): host-only — emit with **no
+  `Domain` attribute** at all, deleting the `Domain=<parent>` broadening (items
+  14–15).
+- `__Host-` prefixing is a possible hardening but is **mutually exclusive with a
+  `/auth` path scope**: `__Host-` requires `Path=/`. Pick unique-name +
+  host-only as the baseline; add either `__Host-` (at `Path=/`) or `Path=/auth`
+  scoping, not both.
 
 ## Two levels of "merge" — keep them distinct
 
@@ -46,7 +72,8 @@ This matters for both benefits and risks, so fix the terms up front:
 - **Fewer privileged cross-service endpoints.** The split _requires_ the two
   services to communicate over authenticated HTTP: the HMAC-signed
   `/oauth/epds-callback` plus the internal lookup endpoints (`/_internal/*`,
-  `/_magic/check-email`, `account-by-email`). Each is an attack surface that
+  e.g. `/_internal/account-by-email`, which replaced the old unauthenticated
+  `/_magic/check-email`). Each is an attack surface that
   must be signed, gated, and version-matched across the boundary. Merging the
   origin lets some of these relax; merging the processes lets most become
   in-process calls with no wire boundary at all.
@@ -87,7 +114,7 @@ The whole point. These exist solely because of cross-origin-same-site:
    `pds-core/src/index.ts:930`, and `authOrigin` derivation in
    `chooser-enrichment.ts`. The two hostnames become one.
 4. **(Process-merge only) some privileged cross-service endpoints** — the
-   `/_internal/*` / `/_magic/*` HTTP lookups become in-process calls. The
+   `/_internal/*` HTTP lookups become in-process calls. The
    HMAC-signed `/oauth/epds-callback` can also collapse to an in-process call
    if the processes merge. See "Two levels of merge" above.
 
@@ -116,28 +143,43 @@ would strand in-flight and cached clients.
 **Mitigation:** keep `auth.<host>` resolving during a transition window. Serve a
 301/302 (or continue proxying) from `auth.<host>/oauth/authorize` →
 `<host>/auth/oauth/authorize` until metadata TTLs expire and clients re-fetch.
-Only retire the subdomain DNS/cert after the window.
+The redirect/proxy **must preserve the complete request target** — full path and
+query string — because the authorization request carries `client_id`,
+`redirect_uri`, `code_challenge`, `state`, etc.; dropping the query breaks
+in-flight logins. Only retire the subdomain DNS/cert after the window.
 
 ### 2. `EPDS_LINK_BASE_URL` appears in live email links
 
 `auth-service/.env.example:94` — `EPDS_LINK_BASE_URL=https://auth.pds.example/auth/verify`.
 Verification/recovery links already delivered to inboxes point at the subdomain.
 
-**Mitigation:** same transition redirect covers these. Update the env var to the
-new path-based URL for _new_ emails; keep the subdomain redirecting for the
-lifetime of the longest-lived link (OTP/verification TTLs are short — 600s per
-`auth-flow.ts` — so this window is small).
+**Mitigation:** same transition redirect covers these — and, as above, it must
+**preserve the full path and query string** so the verification token in the
+link survives the hop. Update the env var to the new path-based URL for _new_
+emails; keep the subdomain redirecting for the lifetime of the longest-lived
+link (OTP/verification TTLs are short — `expiresIn: 600` in
+`auth-service/src/better-auth.ts` — so this window is small).
 
 ### 3. `AUTH_HOSTNAME` is load-bearing config
 
 Referenced in `pds-core/src/index.ts:138`, `auth-service/src/index.ts:138`,
 `session-reuse.ts`, `chooser-enrichment.ts` (`authOrigin`),
 `sec-fetch-site-rewrite.ts` allowlist, `demo/.env.example` (`AUTH_ENDPOINT`).
 
-**Approach:** introduce an `AUTH_PATH_PREFIX` (default `/auth`) and derive the
-auth origin as `PDS_HOSTNAME + AUTH_PATH_PREFIX`. Keep `AUTH_HOSTNAME` as an
-optional legacy override so existing subdomain deployments keep working during
-transition (config-gated, not a hard cutover).
+**Approach:** keep these as distinct values rather than conflating them —
+`PDS_HOSTNAME + AUTH_PATH_PREFIX` yields `pds.example/auth`, which is a **base
+URL/path, not an origin**, and today's `AuthServiceConfig.hostname` expects a
+bare hostname while public-URL config carries the scheme. So:
+
+- keep `AuthServiceConfig.hostname` a hostname;
+- introduce `AUTH_PATH_PREFIX` (default `/auth`) as the path the auth surface
+  mounts under;
+- derive the full mount point from an explicit **origin** (`https://<host>`)
+  joined with the prefix — or introduce an explicit `AUTH_BASE_URL` — and update
+  URL-joining so paths and origins are never concatenated as bare strings.
+
+Keep `AUTH_HOSTNAME` as an optional legacy override so existing subdomain
+deployments keep working during transition (config-gated, not a hard cutover).
 
 ### Non-blockers (confirmed)
 

docs/design/single-process-merge.md

@@ -22,9 +22,13 @@ adds a distinct set of wins that single-origin alone cannot deliver:
   auth-service can prove to pds-core that a redirect came from a legitimate auth
   flow, over the wire, signed with `EPDS_CALLBACK_SECRET`. In one process the
   auth flow can call the code-issuance path **directly** as a function — no
-  HMAC, no secret to rotate, no signature-verification code, no replay window.
-- **The internal HTTP lookups disappear.** `/_internal/account-by-email`,
-  `/_magic/check-email`, and the `/_internal/ping-request` keepalive become
+  HMAC, no secret to rotate, no signature-verification code. Note this removes
+  only the cross-service _authenticity_ check; the one-time, session-bound
+  issuance gating must be preserved in the direct path (see "Preserving
+  one-time issuance" below).
+- **The internal HTTP lookups disappear.** `/_internal/account-by-email` (which
+  replaced the old unauthenticated `/_magic/check-email`) and the
+  `/_internal/ping-request` keepalive become
   in-process function calls against the same objects (`pds.ctx.accountManager`,
   `provider.requestManager`) that pds-core already holds. No auth, no JSON
   round-trip, no drift between caller and callee.
@@ -132,9 +136,21 @@ Merged: the auth-complete handler calls the same `setAuthorized` path
   `requestManager.setAuthorized` / `createAccount`) into a plain function on a
   shared module, taking typed args instead of a signed request.
 - The auth `/auth/complete` handler calls that function directly.
-- `EPDS_CALLBACK_SECRET` and the signature-verification middleware are deleted.
-- **Keep the HTTP `/oauth/epds-callback` route only if** a transition period
-  needs old auth-service instances to still call it; otherwise remove it.
+- **Preserve the one-time issuance gating in the extracted function.** Dropping
+  HMAC removes only the cross-service _authenticity_ check — it does **not**
+  remove the need for one-time, session-bound, idempotent guards. The direct
+  path must still ensure a repeated or replayed `/auth/complete` cannot mint a
+  second authorization code (the auth-flow row is consumed exactly once, keyed
+  to the session). Carry these guards into the shared function; they are
+  independent of the HMAC and must not be deleted alongside it.
+- **Retain `EPDS_CALLBACK_SECRET`, the signature-verification middleware, and
+  the HTTP `/oauth/epds-callback` route while any legacy Auth instance can
+  still call it.** During a rolling deploy an old auth-service may still POST
+  the signed callback; deleting the verifier early would either break it or
+  (worse) expose an unauthenticated issuance route. Remove the secret, the
+  verifier, and the route **only** in a later compatibility gate, after all old
+  callers are drained and the direct-call path is fully deployed (see rollout
+  steps 4–5).
 
 This is the highest-value deletion in the whole merge and also the most
 security-sensitive change — the HMAC existed to stop an attacker forging a
@@ -172,10 +188,13 @@ come first. This process-merge adds:
    mounted at `/auth` on the PDS app; resolve hazards 1–6 above. Keep
    auth-service's standalone `listen()` behind a flag for rollback.
 4. **Switch `/auth/complete` to the in-process call.** Route code issuance
-   through the extracted function; stop signing/sending the HMAC callback.
-5. **Delete** `EPDS_CALLBACK_SECRET`, the callback signature middleware, the
-   `/_internal/*` + `/_magic/*` HTTP endpoints, and auth-service's standalone
-   server. Retire the second process.
+   through the extracted function; stop signing/sending the HMAC callback. The
+   signed HTTP route stays live and verified here — it is not yet removed.
+5. **Compatibility gate — delete only once legacy callers are drained.** After
+   confirming no old auth-service instance still POSTs the callback, delete
+   `EPDS_CALLBACK_SECRET`, the callback signature middleware, the HTTP
+   `/oauth/epds-callback` route, the `/_internal/*` HTTP endpoints, and
+   auth-service's standalone server. Retire the second process.
 
 Each step is independently shippable and reversible until step 5.