Re-evaluate auth-service subdomain split vs. single-domain architecture

[aspiers]

Question

Re-evaluate whether the auth-service-on-a-subdomain architecture still earns its keep, versus hosting the auth UI in-process on the PDS Core origin (single domain).

Background

The subdomain split (AUTH_HOSTNAME must be a subdomain of PDS_HOSTNAME) was inherited whole from the upstream magic-pds project at the initial commit (de3876e). The rationale was later written down in better-auth-migration-plan.md, section "Considered and rejected: single-domain architecture", and is now also summarised in docs/architecture.md (Key Design Decisions → "Auth Service on a subdomain").

Stated benefits of the split:

1. Cookie isolation — the auth-service session cookies (Better Auth session) are a separate authentication domain from AT Protocol access/refresh tokens; separate origins keep the namespaces from colliding by construction.
2. Security-header isolation — the auth-service is a full web app needing its own CSP/headers, independent of PDS Core's stricter policy.
3. Independent deployability — separate service/process, deployed and restarted on its own.

The OAuth authorization_endpoint metadata override is the mechanism that redirects clients to the auth service, but not a reason a separate origin is required: PDS Core already wraps upstream heavily (_router.stack surgery, metadata rewriting, middleware injection) and could shadow /oauth/authorize in-process.

Why revisit

The subdomain choice carries costs that have accumulated and were only partly documented at decision time — all in docs/design/pds-white-boxing.md:

• Item 5 — sec-fetch-site: same-site → same-origin rewrite, needed only because the redirect chain crosses origins within the same registrable domain.
• Items 14–15 — device-session cookie-domain plumbing (Domain=<parent>) so the sibling subdomain can read the upstream session; host-only cookies wouldn't cross.

These costs are a direct consequence of splitting across subdomains. The three benefits above have never been formally weighed against them, and benefit #3 (independent deployability) may be weak given both packages already share a repo, build, and (per the migration plan) a data volume.

Task

• Weigh the three isolation benefits against the accumulated same-site / cookie-domain costs.
• Assess feasibility of hosting the auth UI in-process on the PDS Core origin (given upstream is already wrapped), incl. whether cookie/CSP isolation can be achieved another way (cookie name prefixing, path-scoped cookies, per-route CSP).
• Decide: keep the subdomain split, or migrate to single-domain. Record the outcome as an ADR update in docs/architecture.md.

References

• docs/architecture.md — Key Design Decisions → "Auth Service on a subdomain, not a single shared domain"
• better-auth-migration-plan.md — "Considered and rejected: single-domain architecture"
• docs/design/pds-white-boxing.md — items 5, 14, 15 (the costs)

[aspiers]

Update: none of the three benefits is a non-negotiable

On re-examination against the code, all three stated benefits of the subdomain split are reproducible on a single origin, and every documented cost is an artifact of being cross-origin-but-same-site.

• Cookie isolation is already done by explicit cookie naming (epds_csrf, magic_account_session, DEVICE_COOKIE_NAMES), not by origin. Worse, the split creates a cookie problem — the Domain=<parent> sharing in white-boxing items 14–15 — that a single origin deletes.
• Security-header isolation is already per-route in both packages (auth-service/src/lib/security-headers.ts; pds-core rewrites upstream CSP per-response). No per-origin hosting needed.
• Independent deployability is soft — shared repo, build, and data volume already.
• The sec-fetch-site rewrite (item 5) exists only because the chain is same-site; one origin makes it same-origin, which upstream already allows. The one upstream validation that looks like a constraint actually favors single-origin.

Real blockers are external addressability, not the benefits: authorization_endpoint is cached by clients, EPDS_LINK_BASE_URL is in live email links, AUTH_HOSTNAME is load-bearing config. All handled by a transition-redirect window. No AT Protocol identity coupling (DIDs reference the PDS host; redirect_uri is always the client's).

Full migration design: docs/design/single-domain-migration.md.