@hgdc/auth 0.9.0 → 0.11.0

package/README.md

@@ -1,14 +1,14 @@
 # @hgdc/auth
 
-Connexion d'un produit de la famille à Account (OIDC) : bouton « Se connecter avec H family », configuration du client better-auth, proxy `/api/auth` pour TanStack Start et gardes Convex.
+Connexion d'un produit de la famille à Account (OIDC) : bouton « Se connecter avec HGDC », configuration du client better-auth, proxy `/api/auth` pour TanStack Start et gardes Convex.
 
-| Import              | Contenu                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@hgdc/auth`        | `HGDC_ISSUER`, `HGDC_PROVIDER_ID`, `HGDC_SCOPES`, entrée commune (`HGDC_ENTRY_PATH`, `safeNextPath`, `hgdcEntryUrl`), rôles (`highestRole`, `hasRole`), `parseHgdcProfile`, `verifiedOrganizationsFromIdToken`, `verifyHgdcIdToken`, `planOrganizationSync`, fraîcheur (`membershipIsFresh`, `SESSION_TTL_SECONDS`, `MEMBERSHIP_TTL_MS`, `KEY_MEMBERSHIP_TTL_MS`) |
-| `@hgdc/auth/server` | `hgdcProvider` (plugin `genericOAuth`), `createAuthProxy`, `restoreFetchMode`, `createHgdcEntry`                                                                                                                                                                                                                                                                  |
-| `@hgdc/auth/convex` | `requireIdentity`, `requireOrgMember`, `isAuthError`, `authErrorReason`, `AUTH_ERROR_MESSAGES`                                                                                                                                                                                                                                                                    |
-| `@hgdc/auth/events` | Événements poussés par Account : `ACCOUNT_EVENTS_PATH`, `signAccountEvent`, `verifyAccountEvent`, `handleAccountEventRequest`, `accountEventSchema`, `accountEventIsStale`, `ACCOUNT_EVENT_RETENTION_MS`, et pour Convex `vAccountEvent`, `accountEventsTable`                                                                                                    |
-| `@hgdc/auth/react`  | `HgdcSignInButton`, `startHgdcSignIn`, `HgdcMark` (le H tricolore de la famille, `HGDC_MARK_SVG`)                                                                                                                                                                                                                                                                 |
+| Import              | Contenu                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@hgdc/auth`        | `HGDC_ISSUER`, `HGDC_PROVIDER_ID`, `HGDC_SCOPES`, entrée commune (`HGDC_ENTRY_PATH`, `safeNextPath`, `hgdcEntryUrl`), rôles (`highestRole`, `hasRole`), `parseHgdcProfile`, `verifiedOrganizationsFromIdToken`, `verifyHgdcIdToken`, `planOrganizationSync`, fraîcheur (`membershipIsFresh`, `SESSION_TTL_SECONDS`, `MEMBERSHIP_TTL_MS`, `KEY_MEMBERSHIP_TTL_MS`), `createSessionTokenCache` |
+| `@hgdc/auth/server` | `hgdcProvider` (plugin `genericOAuth`), `createAuthProxy`, `restoreFetchMode`, `createHgdcEntry`                                                                                                                                                                                                                                                                                             |
+| `@hgdc/auth/convex` | `requireIdentity`, `requireOrgMember`, `isAuthError`, `authErrorReason`, `AUTH_ERROR_MESSAGES`                                                                                                                                                                                                                                                                                               |
+| `@hgdc/auth/events` | Événements poussés par Account : `ACCOUNT_EVENTS_PATH`, `signAccountEvent`, `verifyAccountEvent`, `handleAccountEventRequest`, `accountEventSchema`, `accountEventIsStale`, `ACCOUNT_EVENT_RETENTION_MS`, et pour Convex `vAccountEvent`, `accountEventsTable`                                                                                                                               |
+| `@hgdc/auth/react`  | `HgdcSignInButton`, `startHgdcSignIn`, `HgdcMark` (le H tricolore de la famille, `HGDC_MARK_SVG`)                                                                                                                                                                                                                                                                                            |
 
 Pairs : better-auth 1.6, convex 1.46+, React 19 (chacun facultatif selon l'import).
 
@@ -131,6 +131,29 @@ if (!organization && !hasSyncedMarker(location.searchStr))
 
 Décisions : ADR 0010, ADR 0013.
 
+## Session dans le `beforeLoad` de la racine
+
+Sans cache, chaque navigation côté navigateur rappelait le serveur (`getAuth`) avant tout rendu : l'ancienne page restait figée, et TanStack Router n'affiche aucun chargement pendant un `beforeLoad`. `createSessionTokenCache` reprend au navigateur une session ouverte pendant 5 minutes (le client Convex renouvelle lui-même son jeton), relit toujours au serveur, et s'amorce avec le jeton du rendu serveur :
+
+```ts
+const session = createSessionTokenCache(() => getAuth())
+
+export const Route = createRootRouteWithContext<…>()({
+  beforeLoad: async ({ context }) => {
+    const token = await session.read()
+    if (token) context.convexQueryClient.serverHttpClient?.setAuth(token)
+    return { isAuthenticated: Boolean(token), token }
+  },
+  component: () => {
+    const context = Route.useRouteContext()
+    useEffect(() => session.seed(context.token), [context.token])
+    …
+  },
+})
+```
+
+Une absence de session n'est jamais gardée. Déconnexion : recharger la page, ou `session.clear()`.
+
 ## Garder une fonction Convex
 
 ```ts

package/dist/index.d.ts

@@ -190,3 +190,37 @@ export declare const KEY_MEMBERSHIP_TTL_MS: number;
 export declare function membershipIsFresh(membership: {
     syncedAt?: number | null | undefined;
 }, now: number, ttl?: number): boolean;
+/**
+ * Durée pendant laquelle le navigateur reprend le jeton de session déjà lu plutôt que de le
+ * redemander au serveur : 5 minutes. Le client Convex renouvelle lui-même son jeton ; celui-ci ne
+ * sert qu'aux gardes de route et à amorcer le client.
+ */
+export declare const CLIENT_SESSION_TOKEN_TTL_MS: number;
+export type SessionTokenCache = {
+    /** Jeton courant : au serveur, toujours relu ; au navigateur, repris s'il a moins de 5 minutes. */
+    read: () => Promise<string | null>;
+    /** Amorce le cache avec le jeton du rendu serveur, à l'hydratation (la racine ne repasse pas par `read`). */
+    seed: (token: string | null | undefined) => void;
+    /** Oublie le jeton (déconnexion sans rechargement). */
+    clear: () => void;
+};
+/**
+ * Jeton de session pour le `beforeLoad` de la racine d'un produit TanStack Start. Sans cache, chaque
+ * navigation côté navigateur rappelait le serveur (`getAuth`) avant tout rendu : l'ancienne page
+ * restait figée le temps de l'aller-retour. Seule une session ouverte est gardée, jamais une absence
+ * de session ; les appels simultanés partagent la même requête.
+ *
+ * ```ts
+ * const session = createSessionTokenCache(() => getAuth())
+ * beforeLoad: async ({ context }) => {
+ *   const token = await session.read()
+ *   …
+ * }
+ * // composant racine : useEffect(() => session.seed(context.token), [context.token])
+ * ```
+ */
+export declare function createSessionTokenCache(fetchToken: () => Promise<string | null>, options?: {
+    ttlMs?: number;
+    now?: () => number;
+    isBrowser?: () => boolean;
+}): SessionTokenCache;

package/dist/index.js

@@ -313,3 +313,55 @@ export function membershipIsFresh(membership, now, ttl = MEMBERSHIP_TTL_MS) {
     const { syncedAt } = membership;
     return typeof syncedAt === "number" && now - syncedAt <= ttl;
 }
+/**
+ * Durée pendant laquelle le navigateur reprend le jeton de session déjà lu plutôt que de le
+ * redemander au serveur : 5 minutes. Le client Convex renouvelle lui-même son jeton ; celui-ci ne
+ * sert qu'aux gardes de route et à amorcer le client.
+ */
+export const CLIENT_SESSION_TOKEN_TTL_MS = 5 * 60 * 1000;
+/**
+ * Jeton de session pour le `beforeLoad` de la racine d'un produit TanStack Start. Sans cache, chaque
+ * navigation côté navigateur rappelait le serveur (`getAuth`) avant tout rendu : l'ancienne page
+ * restait figée le temps de l'aller-retour. Seule une session ouverte est gardée, jamais une absence
+ * de session ; les appels simultanés partagent la même requête.
+ *
+ * ```ts
+ * const session = createSessionTokenCache(() => getAuth())
+ * beforeLoad: async ({ context }) => {
+ *   const token = await session.read()
+ *   …
+ * }
+ * // composant racine : useEffect(() => session.seed(context.token), [context.token])
+ * ```
+ */
+export function createSessionTokenCache(fetchToken, options = {}) {
+    const ttl = options.ttlMs ?? CLIENT_SESSION_TOKEN_TTL_MS;
+    const now = options.now ?? Date.now;
+    const isBrowser = options.isBrowser ?? (() => typeof document !== "undefined");
+    let cached = null;
+    let inflight = null;
+    return {
+        read: async () => {
+            if (!isBrowser())
+                return await fetchToken();
+            if (cached && now() - cached.at < ttl)
+                return cached.token;
+            inflight ??= fetchToken()
+                .then((token) => {
+                cached = token ? { token, at: now() } : null;
+                return token;
+            })
+                .finally(() => {
+                inflight = null;
+            });
+            return await inflight;
+        },
+        seed: (token) => {
+            if (isBrowser() && token && !cached)
+                cached = { token, at: now() };
+        },
+        clear: () => {
+            cached = null;
+        },
+    };
+}

package/dist/react.d.ts

@@ -48,7 +48,7 @@ export declare function HgdcMark({ className }: {
     className?: string;
 }): ReactElement;
 /**
- * Bouton « Se connecter avec H family ». Sans style propre : le produit le met en forme par
+ * Bouton « Se connecter avec HGDC ». Sans style propre : le produit le met en forme par
  * `className`, l'état d'attente est exposé par `aria-busy` et `data-pending`.
  */
 export declare function HgdcSignInButton({ authClient, callbackURL, errorCallbackURL, onError, label, disabled, ...rest }: HgdcSignInButtonProps): ReactElement;

package/dist/react.js

@@ -31,10 +31,10 @@ export function HgdcMark({ className }) {
     return (_jsx("img", { src: `data:image/svg+xml,${encodeURIComponent(HGDC_MARK_SVG)}`, alt: "", "aria-hidden": "true", width: 16, height: 16, draggable: false, className: className }));
 }
 /**
- * Bouton « Se connecter avec H family ». Sans style propre : le produit le met en forme par
+ * Bouton « Se connecter avec HGDC ». Sans style propre : le produit le met en forme par
  * `className`, l'état d'attente est exposé par `aria-busy` et `data-pending`.
  */
-export function HgdcSignInButton({ authClient, callbackURL = "/", errorCallbackURL, onError, label = "Se connecter avec H family", disabled, ...rest }) {
+export function HgdcSignInButton({ authClient, callbackURL = "/", errorCallbackURL, onError, label = "Se connecter avec HGDC", disabled, ...rest }) {
     const [pending, setPending] = useState(false);
     async function signIn() {
         setPending(true);

package/dist/server.d.ts

@@ -33,7 +33,7 @@ export type HgdcEntryOptions = {
 /**
  * Entrée commune `GET /auth/hgdc?next=<chemin>` (`HGDC_ENTRY_PATH`), à monter comme route
  * serveur du produit. Le menu « Produits » de `@hgdc/ui` y envoie : on entre dans le produit
- * sans passer par sa page d'accueil ni recliquer « Se connecter avec H family ».
+ * sans passer par sa page d'accueil ni recliquer « Se connecter avec HGDC ».
  *
  * - Session du produit ouverte : redirection vers `next`.
  * - Sinon : la connexion HGDC part aussitôt (même appel que `HgdcSignInButton`, fait par le

package/dist/server.js

@@ -109,7 +109,7 @@ function authorizationUrl(body) {
 /**
  * Entrée commune `GET /auth/hgdc?next=<chemin>` (`HGDC_ENTRY_PATH`), à monter comme route
  * serveur du produit. Le menu « Produits » de `@hgdc/ui` y envoie : on entre dans le produit
- * sans passer par sa page d'accueil ni recliquer « Se connecter avec H family ».
+ * sans passer par sa page d'accueil ni recliquer « Se connecter avec HGDC ».
  *
  * - Session du produit ouverte : redirection vers `next`.
  * - Sinon : la connexion HGDC part aussitôt (même appel que `HgdcSignInButton`, fait par le

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/auth",
-  "version": "0.9.0",
+  "version": "0.11.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",