@alxia/react-router 0.36.1 → 0.37.0

package/docs/guide/session.md

@@ -285,6 +285,11 @@ when the app is served over HTTPS, and `false` for plain HTTP in development.
 A wrong value in production would send the token over HTTP, so the package
 leaves that choice to you in plain sight.
 
+`sameSite` (`'lax'` by default, `'strict'` or `'none'`) sets the `SameSite`
+attribute of every cookie written, `destroy` and the challenge included. Use
+`'strict'` for an app that nobody reaches from a link on another site while
+signed in; `'none'` needs `secure: true` and throws a `TypeError` without it.
+
 | `secure` | session cookie | challenge cookie |
 | --- | --- | --- |
 | `true` | `__Host-my-app_session`, `Secure` | `__Secure-my-app_challenge`, `Secure` |
@@ -301,6 +306,8 @@ The bytes are, in this order:
 Name=value; Max-Age=n; Path=/; HttpOnly[; Secure]; SameSite=Lax
 ```
 
+(`SameSite=Strict` or `None` with the `sameSite` option.)
+
 The session cookie's value is `<expiry in ms>.<token>`, percent-encoded. A
 session set by an app that wrote its own cookies in this format is read as it
 is, so adopting the package does not sign anyone out.
@@ -357,7 +364,7 @@ sets. It clears the challenge blind: a client navigation fetches
 request never shows the challenge, yet a `Set-Cookie` with that path removes
 it. With `deadSession`, it also removes a session cookie the API refused.
 
-`serializeCookie(name, value, { maxAge, path?, secure })`,
+`serializeCookie(name, value, { maxAge, path?, secure, sameSite? })`,
 `readCookie(request, name)` and `secondsUntil(expiresAt, now?)` are exported
 for the cookies of your own (a language, a preference) that must be written in
 the same bytes. A name that is not an RFC 6265 token, or a path with a `;` or a
@@ -365,6 +372,48 @@ control character, throws a `TypeError`; a `maxAge` that is not finite is 0.
 `readCookie` returns the first non-empty cookie of that name, and `null` when
 its value is not valid percent-encoding.
 
+### A signed session without Janus
+
+An app with one local operator, whose password the server checks itself, has
+no API token to keep. `signedSession` writes a stateless cookie instead: the
+value is `<expiresAt ms>.<nonce>.<mac>`, the MAC an HMAC-SHA256 of
+`<expiresAt>.<nonce>`, so the expiry cannot be moved without the secret.
+
+```ts
+// app/operator.server.ts
+import { signedSession } from '@alxia/react-router/session';
+
+export const operator = signedSession({
+	secret: process.env.SESSION_SECRET ?? '',
+	name: 'my-app_operator',
+	maxAge: 8 * 60 * 60,
+	secure: !import.meta.env.DEV,
+	sameSite: 'strict',
+});
+```
+
+```ts
+// in the sign-in action, once the password was checked
+const headers = new Headers();
+headers.append('Set-Cookie', await operator.commit());
+
+// in a loader
+if (!(await operator.valid(request))) throw redirect('/sign-in');
+
+// sign-out
+headers.append('Set-Cookie', operator.destroy());
+```
+
+The cookie is `HttpOnly`, `Path=/`, has no `Domain`, is named `__Host-…` when
+`secure`, and its `Max-Age` is `maxAge`. `commit` and `valid` are async (Web Crypto, so the subpath keeps
+importing `react-router` alone). `valid` resolves to `false`, and never
+throws, for a missing cookie, a malformed value, an expiry that is not digits,
+a MAC of the wrong length or that does not match (compared in constant time)
+and an expiry in the past. `secret` is at least 32 characters, from the
+environment; changing it signs everyone out. The session is not revocable
+before its expiry: keep `maxAge` short, and check the password again for
+anything sensitive.
+
 ### Safari and `http://localhost`
 
 Safari (WebKit) drops a `Secure` cookie set over `http://localhost`, where

package/docs/troubleshooting.md

@@ -82,6 +82,10 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: sessionCookies(): the … name "…" already carries a prefix. Pass the base name: the package adds __Host- (session) or __Secure- (challenge) when secure is true.`](#typeerror-sessioncookies-the--name--already-carries-a-prefix-pass-the-base-name-the-package-adds-__host--session-or-__secure--challenge-when-secure-is-true)
 - [`TypeError: sessionCookies(): challengeSeconds must be a positive integer; got ….`](#typeerror-sessioncookies-challengeseconds-must-be-a-positive-integer-got-)
 - [`TypeError: sessionCookies(): challengePath must start with "/" and hold no ";" or control character; got ….`](#typeerror-sessioncookies-challengepath-must-start-with--and-hold-no--or-control-character-got-)
+- [`TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got ….`](#typeerror-sessioncookies-samesite-must-be-lax-strict-or-none-got-)
+- [`TypeError: sessionCookies(): sameSite "none" needs secure: true, since a browser drops a SameSite=None cookie without Secure.`](#typeerror-sessioncookies-samesite-none-needs-secure-true-since-a-browser-drops-a-samesitenone-cookie-without-secure)
+- [`TypeError: signedSession(): secret must be a string of at least 32 characters.`](#typeerror-signedsession-secret-must-be-a-string-of-at-least-32-characters)
+- [`TypeError: signedSession(): the name "…" must be an RFC 6265 token without a __Host- or __Secure- prefix; …` or `maxAge must be a positive integer of seconds; got ….`](#typeerror-signedsession-the-name--must-be-an-rfc-6265-token-without-a-__host--or-__secure--prefix--or-maxage-must-be-a-positive-integer-of-seconds-got-)
 - [`TypeError: signInFlow(): paths.… must be a path of this site with no query or fragment, starting with a single "/"; got ….`](#typeerror-signinflow-paths-must-be-a-path-of-this-site-with-no-query-or-fragment-starting-with-a-single--got-)
 - [`TypeError: signInPath(): options.path must be a path of this site with no query or fragment, starting with a single "/"; got ….`](#typeerror-signinpath-optionspath-must-be-a-path-of-this-site-with-no-query-or-fragment-starting-with-a-single--got-)
 - [`TypeError: signInFlow(): json must come from jsonActions(), which carries the site check every step runs; this object has none (a hand-made double?). Pass the app's jsonActions({ origin }) instance, or a spread copy of it.`](#typeerror-signinflow-json-must-come-from-jsonactions-which-carries-the-site-check-every-step-runs-this-object-has-none-a-hand-made-double-pass-the-apps-jsonactions-origin--instance-or-a-spread-copy-of-it)
@@ -1822,6 +1826,42 @@ TypeError: sessionCookies(): challengePath must start with "/" and hold no ";" o
 
 **Fix:** pass the path of the sign-in pages with its leading slash. The default is `'/sign-in'`, which covers `/sign-in` and the pages under it; not `/sign-in/code` alone, since a client navigation fetches `/sign-in/code.data`, which that path would not match.
 
+### `TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got ….`
+
+```
+TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got "sometimes".
+```
+
+**When:** the module that calls `sessionCookies`, `signedSession` or `serializeCookie` is imported (the message starts with that function's name).
+
+**Why:** `sameSite` is one of the three values, in lower case.
+
+**Fix:** pass `'lax'` (the default), `'strict'` or `'none'`.
+
+### `TypeError: sessionCookies(): sameSite "none" needs secure: true, since a browser drops a SameSite=None cookie without Secure.`
+
+**When:** `sameSite: 'none'` with `secure: false` (development over plain HTTP).
+
+**Why:** a browser drops a `SameSite=None` cookie that is not `Secure`.
+
+**Fix:** use `'lax'` or `'strict'` in development, for example `sameSite: import.meta.env.DEV ? 'lax' : 'none'`.
+
+### `TypeError: signedSession(): secret must be a string of at least 32 characters.`
+
+**When:** the module that calls `signedSession` is imported, often because the secret's environment variable is unset and `?? ''` gave an empty string.
+
+**Why:** an HMAC key shorter than 32 characters is guessable.
+
+**Fix:** set the variable to a random value of 32 characters or more (`openssl rand -base64 32`). Changing it later signs every operator out.
+
+### `TypeError: signedSession(): the name "…" must be an RFC 6265 token without a __Host- or __Secure- prefix; …` or `maxAge must be a positive integer of seconds; got ….`
+
+**When:** the module that calls `signedSession` is imported.
+
+**Why:** the name is not a cookie name or already carries a prefix (the package adds `__Host-` when `secure`), or `maxAge` is not a positive whole number of seconds.
+
+**Fix:** pass a base name such as `'my-app_operator'` and `maxAge: 8 * 60 * 60`.
+
 ### `TypeError: signInFlow(): paths.… must be a path of this site with no query or fragment, starting with a single "/"; got ….`
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.36.1",
+	"version": "0.37.0",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), a GraphQL subscription relayed to the browser over SSE (`/subscription`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",