Document what each browser actually does with cross-domain auth (#2222)

Measured on real domains over real certificates, Remark42 on one registrable
domain and the host page on another, with a control cookie behind every
blocked column so a run that blocks nothing cannot report a pass.

Three results the manual did not carry. Safari blocks third-party cookies out
of the box, so AUTH_SAME_SITE=none on its own has already stopped working
there, which makes the old recipe broken today and not deprecated later.
Firefox reaches a working session by a weaker route than Chrome and Safari do:
it accepts the server's attribute-less cookie, and because that cookie is
HttpOnly the browser then forbids the widget's script from replacing it, so the
session rides on an ordinary unpartitioned third-party cookie even with the
header flag on. And Firefox's block-all setting discards partitioned cookies
too, so no configuration survives it.

Two parameter descriptions were wrong in ways that matter here. AUTH_SAME_SITE
default emits no SameSite attribute rather than Lax, which is precisely what
lets the widget's own cookie land on Chrome and Safari. And AUTH_TTL_COOKIE
does not govern the cookie that carries the session under the header flag,
since the frontend hardcodes 200h to mirror the default.

backend/app/cmd/server.go

@@ -102,7 +102,7 @@ type ServerCommand struct {
 			Cookie time.Duration `long:"cookie" env:"COOKIE" default:"200h" description:"auth cookie TTL"`
 		} `group:"ttl" namespace:"ttl" env-namespace:"TTL"`
 
-		SendJWTHeader bool   `long:"send-jwt-header" env:"SEND_JWT_HEADER" description:"send JWT as a header instead of server-set cookie; with this enabled, frontend stores the JWT in a client-side cookie (note: increases vulnerability to XSS attacks)"`
+		SendJWTHeader bool   `long:"send-jwt-header" env:"SEND_JWT_HEADER" description:"also send JWT as a header, so the frontend can store it in a client-side cookie that survives third-party cookie blocking; server-set cookies are still sent (note: increases vulnerability to XSS attacks)"`
 		SameSite      string `long:"same-site" env:"SAME_SITE" description:"set same site policy for cookies" choice:"default" choice:"none" choice:"lax" choice:"strict" default:"default"` // nolint
 
 		Apple     AppleGroup         `group:"apple" namespace:"apple" env-namespace:"APPLE" description:"Apple OAuth"`

backend/app/rest/api/middleware_test.go

@@ -271,11 +271,14 @@ func TestRest_securityHeaders(t *testing.T) {
 	client := http.Client{}
 	resp, err := client.Get(ts.URL + "/web/index.html")
 	require.NoError(t, err)
-	defer resp.Body.Close()
 	assert.Equal(t, http.StatusOK, resp.StatusCode)
 	assert.Contains(t, resp.Header.Get("Content-Security-Policy"), "img-src *;")
 	assert.Equal(t, "nosniff", resp.Header.Get("X-Content-Type-Options"))
 	assert.Equal(t, "strict-origin-when-cross-origin", resp.Header.Get("Referrer-Policy"))
+	// httptest.Server.Close waits on connections still in use, and a deferred close does not run
+	// until the test ends, so the body has to be released before the server is torn down here
+	require.NoError(t, resp.Body.Close())
+	client.CloseIdleConnections()
 	teardown()
 
 	// check CSP with proxy enabled

backend/app/rest/api/rest_test.go

@@ -573,9 +573,12 @@ func TestRest_frameAncestors(t *testing.T) {
 	client := http.Client{}
 	resp, err := client.Get(ts.URL + "/web/index.html")
 	require.NoError(t, err)
-	defer resp.Body.Close()
 	assert.Equal(t, http.StatusOK, resp.StatusCode)
 	assert.Contains(t, resp.Header.Get("Content-Security-Policy"), "frame-ancestors 'self' https://example.com;")
+	// httptest.Server.Close waits on connections still in use, and a deferred close does not run
+	// until the test ends, so the body has to be released before the server is torn down here
+	require.NoError(t, resp.Body.Close())
+	client.CloseIdleConnections()
 	teardown()
 
 	// test case without frame-ancestors

site/content/docs/configuration/parameters/index.md

@@ -78,9 +78,9 @@ services:
 | image.resize-width             | IMAGE_RESIZE_WIDTH             | `2400`                  | width of a resized image                                 |
 | image.resize-height            | IMAGE_RESIZE_HEIGHT            | `900`                   | height of a resized image                                |
 | auth.ttl.jwt                   | AUTH_TTL_JWT                   | `5m`                    | JWT TTL                                                  |
-| auth.ttl.cookie                | AUTH_TTL_COOKIE                | `200h`                  | cookie TTL                                               |
+| auth.ttl.cookie                | AUTH_TTL_COOKIE                | `200h`                  | TTL of the server-set auth cookie. Note it does not govern the cookie the frontend writes under `auth.send-jwt-header`, which is fixed at 200h |
-| auth.send-jwt-header           | AUTH_SEND_JWT_HEADER           | `false`                 | send JWT as a header instead of a server-set cookie; with this enabled, frontend stores the JWT in a client-side cookie. [See security considerations](#security-considerations-for-authsend-jwt-header). |
+| auth.send-jwt-header           | AUTH_SEND_JWT_HEADER           | `false`                 | also send JWT as a header, so the frontend can store it in a client-side cookie that survives third-party cookie blocking; the server-set cookies are still sent. [See security considerations](#security-considerations-for-authsend-jwt-header). |
-| auth.same-site                 | AUTH_SAME_SITE                 | `default`               | set same site policy for cookies (`default`, `none`, `lax` or `strict`) |
+| auth.same-site                 | AUTH_SAME_SITE                 | `default`               | SameSite attribute for the server-set auth cookies (`default`, `none`, `lax` or `strict`). `default` emits no attribute at all and leaves the choice to the browser, which is not the same as `lax` |
 | auth.apple.cid                 | AUTH_APPLE_CID                 |                         | Apple client ID (App ID or Services ID)                  |
 | auth.apple.tid                 | AUTH_APPLE_TID                 |                         | Apple service ID                                         |
 | auth.apple.kid                 | AUTH_APPLE_KID                 |                         | Apple Private key ID                                     |
@@ -194,9 +194,14 @@ When `auth.send-jwt-header=true` is enabled:
 - **Security Impact**: JWT tokens are stored in client-accessible cookies that can be accessed by JavaScript
 - **Vulnerability**: This increases vulnerability to XSS attacks compared to server-set HttpOnly cookies
 - **Implementation Mitigations**:
-  - SameSite=Strict cookies to prevent CSRF attacks
+  - `SameSite=Strict` when the widget and the page share an origin, which is what prevents the
+    cookie being sent from another site
+  - `SameSite=None; Secure; Partitioned` when the widget is embedded on another domain, where
+    `Strict` would never be sent at all. `Partitioned` keys the cookie to the embedding top-level
+    site, so a different site gets a separate cookie and cannot reach this one. Pages and
+    subdomains under that same site do share it, since the partition key is the site rather than
+    the page
   - Secure flag automatically added on HTTPS connections
-  - __Host- prefix added on HTTPS to prevent subdomain attacks
   - Double Submit Cookie pattern with XSRF token matching the JWT ID
 
 This configuration should only be used when:

site/content/docs/manuals/separate-domain/index.md

@@ -6,23 +6,78 @@ title: Configure Instance on a different domain
 
 ### What doesn't work so far?
 
-Unless discussion [#1139](https://github.com/umputun/remark42/discussions/1139) has a marked answer, authorisation using oAuth like GitHub or Google is impossible on domains other than the original one. Telegram, Email and anonymous auth would work everywhere.
+Unless discussion [#1139](https://github.com/umputun/remark42/discussions/1139) has a marked answer, authorisation using oAuth like GitHub or Google is impossible on domains other than the original one. Telegram, Email and anonymous auth work on allowed HTTPS embedding domains when `AUTH_SEND_JWT_HEADER=true`.
 
 ### Setup
 
-Set `ALLOWED_HOSTS="'self',https://example1.org,https://example2.org"` with your domain names and `AUTH_SAME_SITE=none`.
+Set `ALLOWED_HOSTS="'self',https://example1.org,https://example2.org"` with your domain names, and `AUTH_SEND_JWT_HEADER=true`.
+
+`AUTH_SEND_JWT_HEADER` is what keeps a reader signed in across a page reload on Safari, in Chrome Incognito, and in any browser configured to block third-party cookies. Read [its security considerations](../../configuration/parameters/#security-considerations-for-authsend-jwt-header) before enabling it: it puts the token in a cookie JavaScript can read, which costs XSS exposure that a server-set `HttpOnly` cookie does not.
+
+**`AUTH_SAME_SITE=none` is not needed alongside it**, which reverses what this page recommended for years, so it is worth showing the measurement instead of asserting it. Signing in anonymously from an embedded widget over https and dumping the browser's cookie jar gives, with the setting:
+
+| name | httpOnly | partition key | written by |
+| --- | --- | --- | --- |
+| `JWT` | yes | none | the server |
+| `XSRF-TOKEN` | no | none | the server |
+| `JWT` | no | the embedding site | the widget |
+| `XSRF-TOKEN` | no | the embedding site | the widget |
+
+and without it, only the widget's own partitioned pair. Sign-in, posting and the reload all work either way, in a permissive browser and in one blocking third-party cookies. What the setting adds is the unpartitioned `HttpOnly` `JWT` in the first row, delivered as a third-party cookie to every listed domain wherever the browser still permits that. Nothing needs it, so leaving it at the default is the smaller exposure.
+
+Keep `AUTH_SAME_SITE=none` if you are *not* setting `AUTH_SEND_JWT_HEADER`. Then the server's cookies are the only ones there are, and this is what allows them to be set off-domain at all, for as long as the reader's browser still accepts unpartitioned third-party cookies.
 
 The `'self'` in `ALLOWED_HOSTS` value means "domain where Remark42 is installed on" and needed if you want `remark42.example.com/web/` to work in case you want to test something with it.
 
 ### Technical details
 
-`ALLOWED_HOSTS` sets CSP [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors), which, once enabled, limits the domains where Remark42 would work. The default value is `*` so that it would work on any domain`.
+`ALLOWED_HOSTS` sets CSP [frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors), which, once enabled, limits the domains where Remark42 would work. The default value is `*` so that it would work on any domain.
 
-`AUTH_SAME_SITE` sets the [SAME_SITE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attribute for authorisation cookies, allowing Remark42 either on the original domain and subdomains there (default value, which equals to `Lax`) or allows setting authorisation cookies on any domain where remark42 is shown (`None` setting).
+`AUTH_SAME_SITE` sets the [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attribute on the cookies the server sets. `none` lets those cookies be set on any domain where Remark42 is shown.
+
+The `default` setting does not mean `Lax`. It means Remark42 emits no `SameSite` attribute at all and leaves the choice to the browser, and browsers differ: Chromium treats a missing attribute as `Lax` and so refuses the cookie cross-site, while Firefox accepts it. That difference is not a detail, because it decides which of the two cookie pairs below a reader actually ends up with.
+
+`SameSite=None` is not sufficient on its own, and with `AUTH_SEND_JWT_HEADER` it is not necessary either. A browser that blocks third-party cookies drops a cookie set by Remark42 for a reader on another domain no matter what its `SameSite` value is, unless the cookie is explicitly marked [`Partitioned`](https://developer.mozilla.org/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies), and the server-set cookies are not. `AUTH_SEND_JWT_HEADER=true` is what closes that: the token comes back in an `X-JWT` response header and the widget stores it in its own cookie, written from inside the embedded frame and marked `SameSite=None; Secure; Partitioned`, so the browser keeps it for that embedding site and sends it back after a reload. That cookie is the widget's own doing and owes nothing to `AUTH_SAME_SITE`, which reaches only the pair the server sets.
+
+A browser that refuses a cross-site `Set-Cookie` lacking `SameSite=None` refuses it outright, so with the setting left at its default the server's pair is absent from the jar, not present with a stricter attribute.
+
+Note that this applies to Email, Telegram and anonymous authorisation, which the widget performs from inside the frame. It does not rescue oAuth, which completes in a popup that is a top-level page of its own, so the cookie set there belongs to the Remark42 domain and the embedded frame never sees it.
+
+### What each browser actually does
+
+Measured on real domains over real certificates, with Remark42 on one registrable domain and the
+host page on another, signing in and then reloading. Every "blocked" column below was verified with
+a control cookie: an ordinary third-party cookie written from inside the widget frame has to be
+dropped, or the run is not blocking anything and proves nothing.
+
+| configuration | Chrome, default | Chrome, third-party cookies blocked | Firefox, default | Firefox, "block all third-party" | Safari |
+| --- | --- | --- | --- | --- | --- |
+| `AUTH_SEND_JWT_HEADER` only | works | works | works | fails | works |
+| `AUTH_SAME_SITE=none` only | works | fails | works | fails | fails |
+| both | works | works | works | fails | works |
+
+Three things in that table are worth spelling out.
+
+**Safari needs no configuring to break the old recipe.** It blocks third-party cookies out of the
+box, so `AUTH_SAME_SITE=none` on its own has already stopped working there for every reader. This
+is not a future deprecation to plan for.
+
+**Firefox reaches "works" by a different route, and a weaker one.** Chrome and Safari refuse the
+server's cookie when it carries no `SameSite` attribute, which leaves the field clear for the
+widget to write its own partitioned pair. Firefox accepts that cookie, and because the server's
+`JWT` is `HttpOnly`, the browser then refuses to let the widget's script overwrite it: a cookie set
+by JavaScript may not replace an `HttpOnly` one of the same name. So on Firefox the session rides
+on an ordinary unpartitioned third-party cookie even with the header flag on, and it disappears the
+moment the reader blocks those.
+
+**No configuration survives Firefox's "block all third-party cookies" setting.** That mode discards
+partitioned cookies too, so the `Partitioned` escape hatch does not apply. A reader who has turned
+it on cannot stay signed in on an embedded widget, and nothing in Remark42 can change that.
 
 Here are all possible combinations of these two:
 
 - Default setup with unaltered variables: comments are shown on any domain, but the authorisation wouldn't work anywhere, except on the same domain Remark42 is installed on and subdomains of it.
-- `ALLOWED_HOSTS` set to a set of domains: comments are shown only on listed domains, and authorisation wouldn't work anywhere, expect on the same domain Remark42 is installed on and subdomains of it.
+- `ALLOWED_HOSTS` set to a set of domains: comments are shown only on listed domains, and authorisation wouldn't work anywhere, except on the same domain Remark42 is installed on and subdomains of it.
-- `AUTH_SAME_SITE` set to `None`: comments are shown on any domain. The authorisation would work anywhere.
+- `AUTH_SAME_SITE` set to `None`: comments are shown on any domain. Authorisation works on browsers that still permit third-party cookies, and stops working on the ones that block them.
-- `ALLOWED_HOSTS` set to a set of domains and `AUTH_SAME_SITE` set to `None`: comments are shown on listed domains. The authorisation would work on all of them.
+- `ALLOWED_HOSTS` set to a set of domains and `AUTH_SAME_SITE` set to `None`: comments are shown on listed domains, with the same authorisation caveat.
+- `ALLOWED_HOSTS` and `AUTH_SEND_JWT_HEADER=true`, with `AUTH_SAME_SITE` left alone: comments are shown on listed domains, and Email, Telegram and anonymous authorisation survives a reload whatever the browser's third-party cookie policy. This is the recommended arrangement. Adding `AUTH_SAME_SITE=none` on top changes nothing about whether a reader stays signed in; it only adds the server's unpartitioned cookies where the browser still takes them.