@hgdc/auth 0.12.0 → 0.13.0

package/README.md

@@ -109,7 +109,8 @@ export const Route = createFileRoute("/auth/hgdc")({
 
 Le claim `organizations` n'est lu qu'à la création d'une session (étape 1 ci-dessous). Une organisation rejointe dans Account reste donc invisible dans un produit dont la session est ouverte, jusqu'à 7 jours. `refresh=1` repasse par Account même avec une session ouverte : la nouvelle session relit le claim, sans formulaire quand la session d'Account existe.
 
-- Barre et menu des produits (`@hgdc/ui/products`) : `https://<mot>.hgdc.ch/auth/hgdc?refresh=1&next=/`. Chaque passage d'un produit à l'autre resynchronise.
+- Barre et menu des produits (`@hgdc/ui/products`) : `https://<mot>.hgdc.ch/auth/hgdc?refresh=background&next=/` (ADR 0016). Session du produit ouverte : redirection immédiate vers `next` et cookie `HGDC_ORG_SYNC_COOKIE` ; la coque (`AppShell`) le consomme et relit les organisations dans un cadre caché sans script (`HGDC_BACKGROUND_REFRESH_PATH`, `frame=1`), qui revient sur une réponse vide (`HGDC_FRAME_DONE_PATH`). La nouvelle session recopie les organisations, les requêtes abonnées se mettent à jour. Sans session : connexion habituelle.
+- Préchargement au survol (Speculation Rules, `prefetch` seulement) : l'entrée ne rend que la redirection d'une session ouverte ; tout ce qui démarrerait une connexion (`refresh=1`, `frame=1`, pas de session) répond 503 à une requête `Sec-Purpose: prefetch`.
 - Page d'une organisation inconnue du produit (ou dont la personne n'est pas membre localement) : une seule redirection vers `hgdcRefreshPath("/o/acme")` avant d'afficher « introuvable ». Au retour, `next` porte `?synced=1` : `hasSyncedMarker(location.search)` vrai, la page affiche « introuvable » au lieu de relancer. L'entrée elle-même ne relance jamais un `next` déjà marqué : pas de boucle.
 
 ```tsx
@@ -129,7 +130,7 @@ if (!organization && !hasSyncedMarker(location.searchStr))
 - L'ancienne session n'est pas révoquée : si Account ne répond pas, la personne garde son accès, et la session expire seule (`SESSION_TTL_SECONDS`).
 - Lien vers un produit avec relecture : `hgdcEntryUrl(origin, "/o/acme", { refresh: true })`.
 
-Décisions : ADR 0010, ADR 0013.
+Décisions : ADR 0010, ADR 0013, ADR 0016.
 
 ## Session dans le `beforeLoad` de la racine
 

package/dist/index.d.ts

@@ -25,6 +25,31 @@ export declare const HGDC_ENTRY_REFRESH_PARAM = "refresh";
  * viennent d'être relues et ne relance pas l'entrée (une seule resynchronisation par navigation).
  */
 export declare const HGDC_SYNCED_PARAM = "synced";
+/**
+ * `refresh=background` sur l'entrée (barre des produits, ADR 0016) : avec une session du produit
+ * ouverte, l'entrée va droit à `next` et pose `HGDC_ORG_SYNC_COOKIE` ; la page d'arrivée relit les
+ * organisations en arrière-plan (`HGDC_BACKGROUND_REFRESH_PATH`). Sans session : connexion HGDC
+ * habituelle, qui lit déjà les organisations. Un produit plus ancien l'ignore (pas de relecture).
+ */
+export declare const HGDC_ENTRY_REFRESH_BACKGROUND = "background";
+/**
+ * Cookie du produit posé par l'entrée `refresh=background` : « relire les organisations ». Lu et
+ * effacé par la page d'arrivée (`@hgdc/ui/app-shell`). Lisible en JavaScript, il ne porte rien
+ * d'autre que `1` : le forger ne fait que lancer une relecture par Account.
+ */
+export declare const HGDC_ORG_SYNC_COOKIE = "hgdc-org-sync";
+/** Durée de vie du cookie `HGDC_ORG_SYNC_COOKIE`, en secondes. */
+export declare const HGDC_ORG_SYNC_COOKIE_MAX_AGE = 60;
+/**
+ * `frame=1` : relecture des organisations dans un cadre caché de la page (même origine). L'entrée
+ * repasse par Account comme `refresh=1`, et le retour se fait sur `HGDC_FRAME_DONE_PATH`, une
+ * réponse vide : jamais sur une page du produit, jamais sur un `next` reçu.
+ */
+export declare const HGDC_ENTRY_FRAME_PARAM = "frame";
+/** Fin de la relecture en arrière-plan : réponse vide de l'entrée, sans appel à better-auth. */
+export declare const HGDC_FRAME_DONE_PATH: string;
+/** Adresse du cadre caché qui relit les organisations (`frame=1`). */
+export declare const HGDC_BACKGROUND_REFRESH_PATH: string;
 /**
  * Page d'arrivée sûre : un chemin du produit lui-même, jamais une autre origine. Refuse ce qu'un
  * navigateur lirait comme une adresse externe (`//hôte`, `/\hôte`, schéma), les caractères de
@@ -33,10 +58,12 @@ export declare const HGDC_SYNCED_PARAM = "synced";
 export declare function safeNextPath(value: string | null | undefined, fallback?: string): string;
 /**
  * Adresse de l'entrée commune d'un produit : `hgdcEntryUrl("https://mail.hgdc.ch", "/o/acme")`.
- * Sans `next` (ou `next` refusé), le produit ouvre sa page d'accueil connectée.
+ * Sans `next` (ou `next` refusé), le produit ouvre sa page d'accueil connectée. `refresh: true`
+ * relit les organisations avant d'arriver (`refresh=1`) ; `refresh: "background"` arrive tout de
+ * suite si la session du produit est ouverte et relit en arrière-plan (ADR 0016).
  */
 export declare function hgdcEntryUrl(productOrigin: string, next?: string, options?: {
-    refresh?: boolean;
+    refresh?: boolean | typeof HGDC_ENTRY_REFRESH_BACKGROUND;
 }): string;
 /**
  * Chemin relatif qui relit les organisations puis revient sur `next` :

package/dist/index.js

@@ -26,6 +26,31 @@ export const HGDC_ENTRY_REFRESH_PARAM = "refresh";
  * viennent d'être relues et ne relance pas l'entrée (une seule resynchronisation par navigation).
  */
 export const HGDC_SYNCED_PARAM = "synced";
+/**
+ * `refresh=background` sur l'entrée (barre des produits, ADR 0016) : avec une session du produit
+ * ouverte, l'entrée va droit à `next` et pose `HGDC_ORG_SYNC_COOKIE` ; la page d'arrivée relit les
+ * organisations en arrière-plan (`HGDC_BACKGROUND_REFRESH_PATH`). Sans session : connexion HGDC
+ * habituelle, qui lit déjà les organisations. Un produit plus ancien l'ignore (pas de relecture).
+ */
+export const HGDC_ENTRY_REFRESH_BACKGROUND = "background";
+/**
+ * Cookie du produit posé par l'entrée `refresh=background` : « relire les organisations ». Lu et
+ * effacé par la page d'arrivée (`@hgdc/ui/app-shell`). Lisible en JavaScript, il ne porte rien
+ * d'autre que `1` : le forger ne fait que lancer une relecture par Account.
+ */
+export const HGDC_ORG_SYNC_COOKIE = "hgdc-org-sync";
+/** Durée de vie du cookie `HGDC_ORG_SYNC_COOKIE`, en secondes. */
+export const HGDC_ORG_SYNC_COOKIE_MAX_AGE = 60;
+/**
+ * `frame=1` : relecture des organisations dans un cadre caché de la page (même origine). L'entrée
+ * repasse par Account comme `refresh=1`, et le retour se fait sur `HGDC_FRAME_DONE_PATH`, une
+ * réponse vide : jamais sur une page du produit, jamais sur un `next` reçu.
+ */
+export const HGDC_ENTRY_FRAME_PARAM = "frame";
+/** Fin de la relecture en arrière-plan : réponse vide de l'entrée, sans appel à better-auth. */
+export const HGDC_FRAME_DONE_PATH = `${HGDC_ENTRY_PATH}?${HGDC_ENTRY_FRAME_PARAM}=done`;
+/** Adresse du cadre caché qui relit les organisations (`frame=1`). */
+export const HGDC_BACKGROUND_REFRESH_PATH = `${HGDC_ENTRY_PATH}?${HGDC_ENTRY_REFRESH_PARAM}=1&${HGDC_ENTRY_FRAME_PARAM}=1`;
 const NEXT_MAX_LENGTH = 2048;
 const NEXT_BASE = "https://next.invalid";
 /**
@@ -58,13 +83,15 @@ export function safeNextPath(value, fallback = "/") {
 }
 /**
  * Adresse de l'entrée commune d'un produit : `hgdcEntryUrl("https://mail.hgdc.ch", "/o/acme")`.
- * Sans `next` (ou `next` refusé), le produit ouvre sa page d'accueil connectée.
+ * Sans `next` (ou `next` refusé), le produit ouvre sa page d'accueil connectée. `refresh: true`
+ * relit les organisations avant d'arriver (`refresh=1`) ; `refresh: "background"` arrive tout de
+ * suite si la session du produit est ouverte et relit en arrière-plan (ADR 0016).
  */
 export function hgdcEntryUrl(productOrigin, next, options = {}) {
     const url = new URL(HGDC_ENTRY_PATH, new URL(productOrigin).origin);
     const path = next === undefined ? "/" : safeNextPath(next);
     if (options.refresh)
-        url.searchParams.set(HGDC_ENTRY_REFRESH_PARAM, "1");
+        url.searchParams.set(HGDC_ENTRY_REFRESH_PARAM, options.refresh === HGDC_ENTRY_REFRESH_BACKGROUND ? HGDC_ENTRY_REFRESH_BACKGROUND : "1");
     if (path !== "/" || options.refresh)
         url.searchParams.set(HGDC_ENTRY_NEXT_PARAM, path);
     return url.toString();

package/dist/server.d.ts

@@ -45,6 +45,12 @@ export type HgdcEntryOptions = {
  *   page ne relance pas l'entrée. Un `next` qui porte déjà `synced=1` ne relance rien : pas de
  *   boucle. L'ancienne session n'est pas révoquée : si Account ne répond pas, la personne garde
  *   son accès, et la session expire seule (`SESSION_TTL_SECONDS`).
+ * - `refresh=background` (barre des produits, ADR 0016) : session du produit ouverte, droit à
+ *   `next` avec le cookie `HGDC_ORG_SYNC_COOKIE` ; la page d'arrivée relit les organisations dans
+ *   un cadre caché (`frame=1`, retour sur `HGDC_FRAME_DONE_PATH`). Sans session, comme sans
+ *   paramètre.
+ * - Préchargement (`Sec-Purpose: prefetch`) : seule la redirection d'une session ouverte est
+ *   rendue ; tout ce qui démarrerait une connexion répond 503, que le navigateur jette.
  *
  * `next` est filtré par `safeNextPath` (chemin du produit seulement, pas de redirection ouverte),
  * puis better-auth le revérifie contre ses `trustedOrigins`.

package/dist/server.js

@@ -1,4 +1,4 @@
-import { HGDC_ENTRY_NEXT_PARAM, HGDC_ENTRY_REFRESH_PARAM, HGDC_ISSUER, HGDC_PROVIDER_ID, HGDC_SCOPES, hasSyncedMarker, parseHgdcProfile, safeNextPath, withSyncedMarker, } from "./index.js";
+import { HGDC_ENTRY_FRAME_PARAM, HGDC_ENTRY_NEXT_PARAM, HGDC_ENTRY_REFRESH_BACKGROUND, HGDC_ENTRY_REFRESH_PARAM, HGDC_FRAME_DONE_PATH, HGDC_ISSUER, HGDC_PROVIDER_ID, HGDC_ORG_SYNC_COOKIE, HGDC_ORG_SYNC_COOKIE_MAX_AGE, HGDC_SCOPES, hasSyncedMarker, parseHgdcProfile, safeNextPath, withSyncedMarker, } from "./index.js";
 /** En-tête qui porte le `sec-fetch-mode` du navigateur à travers le proxy. */
 export const FETCH_MODE_HEADER = "x-hgdc-fetch-mode";
 const FETCH_MODES = new Set(["navigate", "cors", "no-cors", "same-origin", "websocket"]);
@@ -121,6 +121,12 @@ function authorizationUrl(body) {
  *   page ne relance pas l'entrée. Un `next` qui porte déjà `synced=1` ne relance rien : pas de
  *   boucle. L'ancienne session n'est pas révoquée : si Account ne répond pas, la personne garde
  *   son accès, et la session expire seule (`SESSION_TTL_SECONDS`).
+ * - `refresh=background` (barre des produits, ADR 0016) : session du produit ouverte, droit à
+ *   `next` avec le cookie `HGDC_ORG_SYNC_COOKIE` ; la page d'arrivée relit les organisations dans
+ *   un cadre caché (`frame=1`, retour sur `HGDC_FRAME_DONE_PATH`). Sans session, comme sans
+ *   paramètre.
+ * - Préchargement (`Sec-Purpose: prefetch`) : seule la redirection d'une session ouverte est
+ *   rendue ; tout ce qui démarrerait une connexion répond 503, que le navigateur jette.
  *
  * `next` est filtré par `safeNextPath` (chemin du produit seulement, pas de redirection ouverte),
  * puis better-auth le revérifie contre ses `trustedOrigins`.
@@ -140,35 +146,75 @@ export function createHgdcEntry(options) {
     const basePath = (options.basePath ?? "/api/auth").replace(/\/+$/, "");
     return async (request) => {
         const url = new URL(request.url);
+        const frame = url.searchParams.get(HGDC_ENTRY_FRAME_PARAM);
+        // Fin d'une relecture dans le cadre caché : rien à lire, rien à appeler.
+        if (frame === "done")
+            return frameDone();
+        const inFrame = frame === "1";
+        const speculative = isSpeculative(request);
         const next = safeNextPath(url.searchParams.get(HGDC_ENTRY_NEXT_PARAM));
+        const refreshParam = url.searchParams.get(HGDC_ENTRY_REFRESH_PARAM);
         // Un `next` déjà marqué revient d'une resynchronisation : on n'en relance pas une autre.
-        const refresh = url.searchParams.get(HGDC_ENTRY_REFRESH_PARAM) === "1" && !hasSyncedMarker(next);
-        const callbackURL = refresh ? withSyncedMarker(next) : next;
+        const refresh = inFrame || (refreshParam === "1" && !hasSyncedMarker(next));
+        const background = !refresh && refreshParam === HGDC_ENTRY_REFRESH_BACKGROUND;
+        // Le cadre revient toujours sur la réponse vide, jamais sur une page reçue en paramètre.
+        const callbackURL = inFrame ? HGDC_FRAME_DONE_PATH : refresh ? withSyncedMarker(next) : next;
+        const errorURL = inFrame ? HGDC_FRAME_DONE_PATH : errorCallbackURL;
+        // Un préchargement ne démarre jamais de connexion : état OAuth, code d'Account et session
+        // créés pour un survol sans clic. Il ne sert que si la session du produit est déjà ouverte.
+        if (refresh && speculative)
+            return notForSpeculation();
         const cookies = [];
         try {
             if (!refresh && request.headers.has("cookie")) {
+                // Session vérifiée par better-auth (base du produit), pas seulement la présence du cookie.
                 const session = await options.proxy(new Request(`${url.origin}${basePath}/get-session`, { headers: internalHeaders(request, url.origin) }));
                 cookies.push(...setCookies(session));
                 if (session.ok && hasSessionBody(await readJson(session)))
-                    return redirectTo(next, cookies);
+                    return redirectTo(next, background ? [...cookies, orgSyncCookie(url)] : cookies);
             }
+            if (speculative)
+                return notForSpeculation();
             const headers = internalHeaders(request, url.origin);
             headers.set("content-type", "application/json");
             const signIn = await options.proxy(new Request(`${url.origin}${basePath}/sign-in/oauth2`, {
                 method: "POST",
                 headers,
-                body: JSON.stringify({ providerId: HGDC_PROVIDER_ID, callbackURL, errorCallbackURL }),
+                body: JSON.stringify({ providerId: HGDC_PROVIDER_ID, callbackURL, errorCallbackURL: errorURL }),
             }));
             const target = signIn.ok ? authorizationUrl(await readJson(signIn)) : null;
             if (!target)
-                return redirectTo(errorCallbackURL, cookies);
+                return redirectTo(errorURL, cookies);
             return redirectTo(target, [...cookies, ...setCookies(signIn)]);
         }
         catch {
-            return redirectTo(errorCallbackURL, cookies);
+            return speculative ? notForSpeculation() : redirectTo(errorURL, cookies);
         }
     };
 }
+/** Préchargement ou prérendu (Speculation Rules) : `Sec-Purpose: prefetch`, `prefetch;prerender`. */
+function isSpeculative(request) {
+    const purpose = request.headers.get("sec-purpose") ?? request.headers.get("purpose") ?? "";
+    return /\b(prefetch|prerender)\b/i.test(purpose);
+}
+/** Refus d'un préchargement : le navigateur jette une réponse qui n'est pas 2xx, le clic repart. */
+function notForSpeculation() {
+    return new Response(null, { status: 503, headers: { "cache-control": "no-store", "retry-after": "0" } });
+}
+function frameDone() {
+    return new Response(null, {
+        status: 200,
+        headers: {
+            "content-type": "text/plain; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+        },
+    });
+}
+function orgSyncCookie(url) {
+    const secure = url.protocol === "https:" ? "; Secure" : "";
+    return `${HGDC_ORG_SYNC_COOKIE}=1; Path=/; Max-Age=${HGDC_ORG_SYNC_COOKIE_MAX_AGE}; SameSite=Lax${secure}`;
+}
 /**
  * Configuration du fournisseur « HGDC » pour le plugin `genericOAuth` de better-auth :
  * découverte OIDC, code d'autorisation avec PKCE, émetteur vérifié contre la confusion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/auth",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Connexion HGDC : bouton « Se connecter avec HGDC », config better-auth et gardes Convex.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/hugogebel-boop/hgdc-kit/tree/main/packages/auth#readme",