@hgdc/auth 0.11.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
 
@@ -157,10 +158,10 @@ Une absence de session n'est jamais gardée. Déconnexion : recharger la page, o
 ## Garder une fonction Convex
 
 ```ts
-import { requireOrgMember } from "@hgdc/auth/convex"
+import { convexIssuers, requireOrgMember } from "@hgdc/auth/convex"
 
 const { userId, role } = await requireOrgMember(ctx, organizationId, {
-  issuer: process.env.CONVEX_SITE_URL!, // émetteur des JWT du plugin convex
+  issuer: convexIssuers(process.env), // émetteurs des JWT du plugin convex
   minRole: "admin",
   load: async (ctx, { organizationId, userId }) => /* appartenance lue dans la base du produit */ null,
 })
@@ -187,6 +188,31 @@ if (authErrorReason(error) === "insufficient_role") showUpgradeHint()
 
 Les organisations arrivent par la portée `organizations` : claim `organizations: [{ id, slug, name, role }]` de l'id_token et de userinfo.
 
+### Changer le domaine du déploiement Convex
+
+Les jetons du plugin `convex` portent l'émetteur `CONVEX_SITE_URL`. Quand l'adresse du déploiement change (domaine personnalisé posé par `update_canonical_url`, migration vers un Convex auto-hébergé), les jetons déjà émis gardent l'ancienne pendant leur durée de vie (15 minutes) : Convex les refuse sur une connexion neuve (`NoAuthProvider`) et la garde répond `wrong_issuer` sur un WebSocket ouvert. La variable `CONVEX_PREVIOUS_SITE_URL` ouvre une fenêtre où les deux émetteurs sont acceptés :
+
+```ts
+// convex/auth.config.ts
+import { convexAuthProviders } from "@hgdc/auth/convex"
+
+export default {
+  providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+} satisfies AuthConfig
+
+// convex/auth.ts, dans les plugins : le plugin refuse deux fournisseurs « convex »
+convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+
+// gardes
+await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+```
+
+1. Poser `CONVEX_PREVIOUS_SITE_URL` à l'adresse actuelle (`npx convex env set`), puis `convex deploy`.
+2. Changer l'adresse. Les nouveaux jetons portent le nouvel émetteur, les anciens restent acceptés.
+3. Attendre 30 minutes (deux fois la durée d'un jeton), retirer la variable, redéployer.
+
+Hors bascule, la variable est absente et rien ne change : `convexAuthProviders` rend le seul fournisseur, `convexIssuers` la seule `CONVEX_SITE_URL`. La liste ne sert qu'à donner deux adresses au même émetteur (même clé, mêmes utilisateurs), jamais à accepter un autre fournisseur.
+
 ## Synchroniser les organisations
 
 Les organisations vivent dans Account ; le produit en garde une copie (espace par organisation, appartenances) que lit le chargeur de `requireOrgMember`. Le modèle recommandé, celui de Host :

package/dist/convex.d.ts

@@ -50,15 +50,69 @@ export declare function isAuthError(error: unknown): error is ConvexError<AuthEr
 export declare function authErrorReason(error: unknown): AuthErrorReason | null;
 /**
  * Émetteur des jetons dont le `subject` désigne un utilisateur du produit. Avec le plugin
- * `convex` de better-auth : `process.env.CONVEX_SITE_URL`. Un `subject` n'est unique que chez
- * son émetteur : sans ce contrôle, un autre fournisseur accepté par Convex pourrait présenter
- * le `subject` d'un membre et prendre ses droits. Un seul émetteur : l'appartenance est
- * cherchée par `subject`, qui ne distingue pas deux fournisseurs.
+ * `convex` de better-auth : `process.env.CONVEX_SITE_URL`, ou `convexIssuers(process.env)`.
+ * Un `subject` n'est unique que chez son émetteur : sans ce contrôle, un autre fournisseur
+ * accepté par Convex pourrait présenter le `subject` d'un membre et prendre ses droits.
+ *
+ * Une liste ne sert qu'à donner plusieurs adresses au même émetteur, le temps d'un changement
+ * de domaine du déploiement : l'appartenance est cherchée par `subject`, qui ne distingue pas
+ * deux fournisseurs. Jamais deux bases d'utilisateurs différentes.
  */
 export type IssuerOption = {
+    issuer: string | readonly string[];
+};
+/** Variables d'environnement lues par `convexIssuers` et `convexAuthProviders`. */
+export type ConvexIssuerEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * Émetteurs des jetons du plugin `convex` de better-auth sur ce déploiement, à passer tels quels
+ * à `requireIdentity` et `requireOrgMember` : `CONVEX_SITE_URL`, plus `CONVEX_PREVIOUS_SITE_URL`
+ * quand elle est posée.
+ *
+ * `CONVEX_PREVIOUS_SITE_URL` ne vit que pendant la bascule d'un domaine : l'ancienne adresse
+ * `actions` du déploiement, pour que les jetons émis avant la bascule restent valables jusqu'à
+ * leur expiration (15 minutes). Elle se retire ensuite.
+ *
+ * ```ts
+ * await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+ * ```
+ */
+export declare function convexIssuers(env: ConvexIssuerEnv): string[];
+/**
+ * Fournisseurs de `convex/auth.config.ts` : `provider` (celui de `getAuthConfigProvider`), plus
+ * sa copie pour `CONVEX_PREVIOUS_SITE_URL` quand elle est posée, avec la même clé. Sans elle,
+ * Convex refuse dès la bascule (`NoAuthProvider`) un jeton émis avant, sur une connexion neuve.
+ *
+ * La copie est gardée même si les deux adresses sont égales : elles le sont entre la pose de la
+ * variable et le changement de domaine, et seule `CONVEX_SITE_URL` suit alors le domaine.
+ * Le plugin `convex` de better-auth refuse deux fournisseurs `applicationID: "convex"` : il
+ * reçoit `currentAuthConfig(authConfig)`.
+ *
+ * ```ts
+ * export default {
+ *   providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+ * } satisfies AuthConfig
+ * ```
+ */
+export declare function convexAuthProviders<P extends {
     issuer: string;
+}>(provider: P, env: ConvexIssuerEnv): P[];
+/**
+ * Configuration à donner au plugin `convex` de better-auth : le seul fournisseur courant, le
+ * premier de `convexAuthProviders`.
+ *
+ * ```ts
+ * convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+ * ```
+ */
+export declare function currentAuthConfig<P>(config: {
+    providers: readonly P[];
+}): {
+    providers: P[];
 };
-/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+/**
+ * Identité de la personne connectée, émise par `issuer` (ou l'un d'eux), ou erreur
+ * `UNAUTHENTICATED`.
+ */
 export declare function requireIdentity(ctx: {
     auth: Auth;
 }, options: IssuerOption): Promise<UserIdentity>;

package/dist/convex.js

@@ -45,14 +45,84 @@ export function authErrorReason(error) {
 function normalizeIssuer(value) {
     return value.replace(/\/+$/, "");
 }
-/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+/**
+ * Émetteurs des jetons du plugin `convex` de better-auth sur ce déploiement, à passer tels quels
+ * à `requireIdentity` et `requireOrgMember` : `CONVEX_SITE_URL`, plus `CONVEX_PREVIOUS_SITE_URL`
+ * quand elle est posée.
+ *
+ * `CONVEX_PREVIOUS_SITE_URL` ne vit que pendant la bascule d'un domaine : l'ancienne adresse
+ * `actions` du déploiement, pour que les jetons émis avant la bascule restent valables jusqu'à
+ * leur expiration (15 minutes). Elle se retire ensuite.
+ *
+ * ```ts
+ * await requireIdentity(ctx, { issuer: convexIssuers(process.env) })
+ * ```
+ */
+export function convexIssuers(env) {
+    const issuers = [];
+    for (const value of [env.CONVEX_SITE_URL, env.CONVEX_PREVIOUS_SITE_URL]) {
+        const issuer = value ? normalizeIssuer(value.trim()) : "";
+        if (issuer && !issuers.includes(issuer))
+            issuers.push(issuer);
+    }
+    return issuers;
+}
+/** Lit une variable facultative dans `auth.config.ts`, où Convex lève sur une variable absente. */
+function optionalEnv(env, name) {
+    try {
+        return env[name]?.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fournisseurs de `convex/auth.config.ts` : `provider` (celui de `getAuthConfigProvider`), plus
+ * sa copie pour `CONVEX_PREVIOUS_SITE_URL` quand elle est posée, avec la même clé. Sans elle,
+ * Convex refuse dès la bascule (`NoAuthProvider`) un jeton émis avant, sur une connexion neuve.
+ *
+ * La copie est gardée même si les deux adresses sont égales : elles le sont entre la pose de la
+ * variable et le changement de domaine, et seule `CONVEX_SITE_URL` suit alors le domaine.
+ * Le plugin `convex` de better-auth refuse deux fournisseurs `applicationID: "convex"` : il
+ * reçoit `currentAuthConfig(authConfig)`.
+ *
+ * ```ts
+ * export default {
+ *   providers: convexAuthProviders(getAuthConfigProvider({ jwks: process.env.JWKS }), process.env),
+ * } satisfies AuthConfig
+ * ```
+ */
+export function convexAuthProviders(provider, env) {
+    // Convex refuse un push dont auth.config.ts lit une variable absente, et n'y énumère pas
+    // `process.env` (`in`, `Object.keys` ne voient rien) : seule une lecture directe, rattrapée, convient.
+    const previous = optionalEnv(env, "CONVEX_PREVIOUS_SITE_URL");
+    return previous ? [provider, { ...provider, issuer: normalizeIssuer(previous) }] : [provider];
+}
+/**
+ * Configuration à donner au plugin `convex` de better-auth : le seul fournisseur courant, le
+ * premier de `convexAuthProviders`.
+ *
+ * ```ts
+ * convex({ authConfig: currentAuthConfig(authConfig), jwks: process.env.JWKS })
+ * ```
+ */
+export function currentAuthConfig(config) {
+    return { providers: config.providers.slice(0, 1) };
+}
+/**
+ * Identité de la personne connectée, émise par `issuer` (ou l'un d'eux), ou erreur
+ * `UNAUTHENTICATED`.
+ */
 export async function requireIdentity(ctx, options) {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity)
         throw authError("no_session");
-    if (!options.issuer)
+    const expected = (typeof options.issuer === "string" ? [options.issuer] : options.issuer)
+        .map(normalizeIssuer)
+        .filter((issuer) => issuer !== "");
+    if (expected.length === 0)
         throw new Error("requireIdentity : émetteur attendu manquant (CONVEX_SITE_URL ?).");
-    if (normalizeIssuer(identity.issuer) !== normalizeIssuer(options.issuer))
+    if (!expected.includes(normalizeIssuer(identity.issuer)))
         throw authError("wrong_issuer");
     return identity;
 }

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.11.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",