docs: the layered cross-site session design (hand-off, check, FedCM)

OP OpenVibers committed 18 Sept 2026 · 4694a0308c · 1 file, +1 −1

Changes

ddiff --git a/docs/platform-plan.md b/docs/platform-plan.md
iindex 809cb48f..1fb0e086 100644
---- a/docs/platform-plan.md
++++ b/docs/platform-plan.md
@@@ -38,7 +38,7 @@ into the Node services that need the server-side helpers.
  | System | Module | How a room uses it |
  |---|---|---|
  | **Identity / SSO** | OAuth2 in the Network (`/oauth/authorize`, `/oauth/token`, JWKS, `prompt=none`); `auth-client.js` + `middleware.js` server-side | Register a client, implement `/auth/login` (`?silent=1&next=`), `/auth/callback` (sets `ov_token` + `ov_sso_hint`), `/auth/logout?next=`, `/auth/me`. Live, Tools, Games and Community do this today. |
--| **Session pick-up (lazy SSO)** | `GET /sso/check` (`server/auth/sso-check.js`) + the `ov_sso` cookie + the navbar's `silentLogin` option | Nothing happens at sign-in. When a room is opened without a session it asks the network in a hidden iframe ("is this browser signed in?"); only a yes triggers one silent `prompt=none` sign-in that lands back on the same page. Browsers that partition third-party cookies answer no and the room falls back to its own `ov_sso_hint` from an earlier sign-in. `/sso/fanout` (the redirect chain) remains as the explicit "Sign in / out everywhere" buttons on `/my#linked`. |
++| **Session pick-up (lazy SSO)** | `sso-client.js` (link hand-off, FedCM RP), `GET /sso/check` + `ov_sso`, FedCM IdP (`server/auth/fedcm.js`), jwt-bearer grant | Nothing happens at sign-in. Layers, cheapest first: (1) **link hand-off** — while signed in, a click to another OpenVibe site goes through that site's silent sign-in and lands on the link (every browser, no third-party cookies; a site that already has a session answers in one redirect); (2) a site opened without a session: hint → hidden `/sso/check` → **FedCM** (browser-native, works with third-party cookies blocked; native chip once per site, silent re-auth after; a no-op for guests via the login-status API). `/sso/fanout` (the old chain) exists only behind the explicit "Sign in / out everywhere" buttons. |
  | **Navbar** | `navbar.js` — brand from the hostname (`Pastes · OpenVibe · Tools`), compact mode, `links`, `menu.before/after`, `addMenuItem`, account switcher, bell, "Recently used" | `OpenVibeNavbar.init({ service, links, menu, history, silentLogin })`. Nothing else. |
  | **Footer** | `footer.js` — network column, legal, socials, signed-in row, `full`/`compact` | `OpenVibeFooter.init({ service, variant, links })`. |
  | **Theme** | `theme-loader.js` + `builtin-themes.js` + `theme-sync.js` (generated loader map, derived tokens `--on-accent`, `--accent-rgb`, `--accent-glow`) | Load the loader first in `<head>`; style with the tokens. The user's theme follows them to every room. |

diff --git a/docs/platform-plan.md b/docs/platform-plan.md

index 809cb48f..1fb0e086 100644

--- a/docs/platform-plan.md

+++ b/docs/platform-plan.md

@@ -38,7 +38,7 @@ into the Node services that need the server-side helpers.

| System | Module | How a room uses it |

|---|---|---|

| **Identity / SSO** | OAuth2 in the Network (`/oauth/authorize`, `/oauth/token`, JWKS, `prompt=none`); `auth-client.js` + `middleware.js` server-side | Register a client, implement `/auth/login` (`?silent=1&next=`), `/auth/callback` (sets `ov_token` + `ov_sso_hint`), `/auth/logout?next=`, `/auth/me`. Live, Tools, Games and Community do this today. |

-| **Session pick-up (lazy SSO)** | `GET /sso/check` (`server/auth/sso-check.js`) + the `ov_sso` cookie + the navbar's `silentLogin` option | Nothing happens at sign-in. When a room is opened without a session it asks the network in a hidden iframe ("is this browser signed in?"); only a yes triggers one silent `prompt=none` sign-in that lands back on the same page. Browsers that partition third-party cookies answer no and the room falls back to its own `ov_sso_hint` from an earlier sign-in. `/sso/fanout` (the redirect chain) remains as the explicit "Sign in / out everywhere" buttons on `/my#linked`. |

+| **Session pick-up (lazy SSO)** | `sso-client.js` (link hand-off, FedCM RP), `GET /sso/check` + `ov_sso`, FedCM IdP (`server/auth/fedcm.js`), jwt-bearer grant | Nothing happens at sign-in. Layers, cheapest first: (1) **link hand-off** — while signed in, a click to another OpenVibe site goes through that site's silent sign-in and lands on the link (every browser, no third-party cookies; a site that already has a session answers in one redirect); (2) a site opened without a session: hint → hidden `/sso/check` → **FedCM** (browser-native, works with third-party cookies blocked; native chip once per site, silent re-auth after; a no-op for guests via the login-status API). `/sso/fanout` (the old chain) exists only behind the explicit "Sign in / out everywhere" buttons. |

| **Navbar** | `navbar.js` — brand from the hostname (`Pastes · OpenVibe · Tools`), compact mode, `links`, `menu.before/after`, `addMenuItem`, account switcher, bell, "Recently used" | `OpenVibeNavbar.init({ service, links, menu, history, silentLogin })`. Nothing else. |

| **Footer** | `footer.js` — network column, legal, socials, signed-in row, `full`/`compact` | `OpenVibeFooter.init({ service, variant, links })`. |

| **Theme** | `theme-loader.js` + `builtin-themes.js` + `theme-sync.js` (generated loader map, derived tokens `--on-accent`, `--accent-rgb`, `--accent-glow`) | Load the loader first in `<head>`; style with the tokens. The user's theme follows them to every room. |