Files
pages/docs/design/browser-request-security.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

92 lines
5.2 KiB
Markdown

# Browser request and session boundaries
Implemented 2026-09-14. All requests pass the browser mutation guard before
authorization's legacy-mode or handler-owned route branches. Same-origin forms
and fetch calls continue working without page-specific hidden-token injection.
## CSRF
The guard uses Go's `http.CrossOriginProtection` (available since Go 1.25) and
has no trusted cross-origin list or route-prefix exceptions. Fetch Metadata and
Origin distinguish same-origin requests from unrelated or sibling origins;
`Origin: null` is rejected. Host resolution never trusts `X-Forwarded-Host`.
For legacy clients without same-origin Fetch Metadata, Origin must also use the
request's scheme; an HTTP origin cannot target an HTTPS browser session merely
because the host matches. TLS-terminating proxies must preserve forwarded scheme.
See the [Go 1.25 HTTP release notes](https://go.dev/doc/go1.25#net/http).
Unsafe requests carrying an ambient session/MFA cookie must additionally have
validated origin metadata or a matching HTTP(S) Referer. Missing browser-origin
evidence fails closed. Headerless server-to-server clients remain supported;
API clients should use explicit Bearer authentication. Cross-origin login,
profile/group/configuration/upload and API mutations are covered, not just
document save routes. API denials return JSON with status 403.
Logout is POST-only for revocation; GET/HEAD render confirmation without
changing session state. Profile menus submit a native same-origin POST form.
Bearer logout revokes exactly the supplied token, not an unrelated cookie.
Legacy semantic editor GET entry can still allocate an empty Page. Its entry
routes are therefore checked as mutations too; direct address-bar/bookmark
navigation with browser `Sec-Fetch-Site: none` remains allowed. Moving creation
fully into the save transaction remains a separate editor API correction.
OIDC/magic-link callbacks are one-use, purpose-bound login flows, not generic
state-changing GET endpoints. OIDC additionally has browser-bound state.
## Credential purpose
New API tokens begin with `pw_api_`; new cookie sessions begin with
`pw_browser_`. The complete prefix plus random secret is SHA-256 hashed in the
session store. Changing/removing a prefix cannot convert its purpose.
Browser tokens are rejected in Authorization; API tokens are rejected in the
session cookie. Adapter/federation/challenge tokens use independent validation
and tables and are not accepted as login sessions.
Unprefixed pre-upgrade sessions retain compatibility until their recorded
expiry (normally 24 hours). No live session is forcibly migrated or broadened.
Once the old rows expire, new sessions enforce transport separation throughout.
Store helpers without HTTP context remain trusted internal APIs.
Session insertion itself requires an active/readonly Principal and active Domain
membership in the same SQL statement. Each session lookup rechecks membership;
disabling/removing it invalidates the next request even if a session row remains.
Dynamic responses default to `private, no-store` with credential variation;
individual immutable projections can opt into a specific private cache policy.
An explicitly supplied invalid/unknown/ambiguous Authorization header never
falls back to a cookie. Duplicate session cookies are rejected. Login body
size and local return URLs are validated; slash/backslash/control-character
redirect variants cannot redirect to another authority.
## Request-scoped read authorization
Domain lookup is cached only in one request. A bounded single-query snapshot
loads at most 4096 direct-role/group Path read grants, honoring principal and
membership states, exact direct grants and literal group subtree boundaries.
It is immutable, contains no list of all document Paths and is discarded at
request end. Errors/oversized policies fail closed. Tree/children/search/City
read filtering reuses this snapshot; mutation authorization does not.
The next request rechecks sessions, membership and grants. There is no TTL
allow-cache that outlives revocation. A change during an already-rendering
request takes effect on the next request; transactional mutation authorization
and streaming revocation have separate contracts.
## City projection
Map/detail/Spot Page APIs, City macros and Viewer locality badges filter by
readable locality boundaries and Page Paths. Counts and portal choices are
recomputed from visible Pages; nearby relations require both visible ends.
No Domain-only topology ETag is reused across callers (`private, no-store`).
Parents without readable boundaries are not exposed just because a descendant
or MagicPage happens to be readable. Unbound/hidden aliases are not substituted
with UUID links to bypass Path visibility. The complete topology is still loaded
before projection; lazy server-side City pagination remains outstanding.
Regression tests cover cross-origin/missing-metadata denials, login/logout,
purpose confusion, exact/wildcard grant semantics, principal states, next-request
revocation, hidden City metadata/counts/portals/relations and macro projection.
An opt-in Chromium regression additionally submits the real login and logout
forms using HttpOnly cookies and actual Fetch Metadata, with no injected Bearer
credential, and verifies logout leaves a separate API session intact.