@hgdc/auth 0.8.0 → 0.10.0

package/README.md

@@ -2,13 +2,13 @@
 
 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.
 
-| 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
@@ -183,7 +206,7 @@ const claimed = verifiedOrganizationsFromIdToken(hgdc.idToken ?? "", {
   now: Date.now(),
 }) // lève HgdcIdTokenError : émetteur, audience (clientId), iat de plus de 10 minutes
 const plan = planOrganizationSync(claimed, membershipsOfThisUser)
-// mutation interne : plan.upsert (espace + appartenance), plan.remove, et syncedAt = Date.now() partout
+// mutation interne : plan.upsert (espace + appartenance), plan.remove, et syncedAt = issuedAt partout (iat du jeton, verifyHgdcIdToken), jamais Date.now()
 
 // chargeur de requireOrgMember
 load: async (ctx, { organizationId, userId }) => {
@@ -207,6 +230,7 @@ http.route({
   method: "POST",
   handler: httpAction(async (ctx, request) =>
     handleAccountEventRequest(request, {
+      audience: "host", // le produit : signé par Account, vérifié ici
       secret: process.env.ACCOUNT_EVENTS_SECRET,
       apply: (event) => ctx.runMutation(internal.organizations.applyAccountEvent, { event }),
     }),
@@ -218,6 +242,7 @@ http.route({
 // convex/organizations.ts
 export const applyAccountEvent = internalMutation({
   args: { event: vAccountEvent },
+  returns: vAccountEventOutcome, // "applied" | "duplicate" | "ignored:<raison>"
   handler: async (ctx, { event }) => {
     const seen = await ctx.db
       .query("accountEvents")
@@ -229,12 +254,15 @@ export const applyAccountEvent = internalMutation({
     // member.removed : retirer l'appartenance, sauf si accountEventIsStale(event, membre.syncedAt)
     // member.role_changed : rôle et syncedAt = max(syncedAt, event.occurredAt) ; ne crée jamais d'appartenance
     // organization.deleted : retirer toutes les appartenances, garder les données de l'espace
+    // rien à appliquer : "ignored:unknown_organization" | "ignored:unknown_user" | "ignored:not_member" | "ignored:stale"
     return "applied"
   },
 })
 ```
 
-Le secret (32 caractères au moins) est propre au produit : `ACCOUNT_EVENTS_SECRET` chez lui, `ACCOUNT_EVENTS_SECRET_<PRODUIT>` chez Account avec l'adresse de l'endpoint. Sans secret, l'endpoint répond 503 et Account réessaie (1, 5, 15, 60 minutes). Une signature invalide, un horodatage à plus de 5 minutes ou un corps altéré rendent 401 ; un identifiant déjà traité, `duplicate`. Les identifiants se purgent après `ACCOUNT_EVENT_RETENTION_MS` (cron, index `by_received`).
+Le secret (32 caractères au moins) est propre au produit : `ACCOUNT_EVENTS_SECRET` chez lui, `ACCOUNT_EVENTS_SECRET_<PRODUIT>` chez Account avec l'adresse de l'endpoint. La signature `v2=` couvre l'audience (`x-hgdc-audience`, le produit destinataire) : un événement signé pour un autre produit rend 401. Le corps est lu en flux et plafonné à 8 Ko (`readBodyText`, réutilisable). Sans secret, l'endpoint répond 503 et Account réessaie (1, 5, 15, 60 minutes). Une signature invalide ou d'une autre audience, ou un horodatage à plus de 5 minutes rendent 401 ; un corps invalide ou un `occurredAt` à plus de 5 minutes dans le futur, 400. La réponse 200 porte l'issue : `{"status":"applied"}`, `{"status":"duplicate"}` ou `{"status":"ignored","reason":…}` (`unknown_organization`, `unknown_user`, `not_member`, `stale`), journalisée en avertissement chez le produit ; Account remonte à GlitchTip un retrait ignoré pour une autre raison que `unknown_organization`. Les identifiants se purgent après `ACCOUNT_EVENT_RETENTION_MS` (cron, index `by_received`).
+
+Ordre : `accountEventIsStale(event, syncedAt)` compare l'événement à `syncedAt`, qui doit être l'`iat` du jeton lu à la connexion (`verifyHgdcIdToken(...).issuedAt`) et non l'heure de la copie : un jeton émis avant un retrait mais lu après ne doit pas le masquer.
 
 Les gardes doivent lire l'appartenance à chaque requête (chargeur de `requireOrgMember`) : c'est ce qui rend le retrait immédiat.
 

package/dist/events.d.ts

@@ -4,14 +4,21 @@ import { z } from "zod";
 import { type OrgRole } from "./index.ts";
 /** Chemin de l'endpoint de chaque produit, sur son déploiement Convex (`https://<…>.convex.site`). */
 export declare const ACCOUNT_EVENTS_PATH = "/hgdc/v1/account-events";
+/** Produits destinataires : l'audience signée de chaque événement. */
+export declare const ACCOUNT_EVENT_AUDIENCES: readonly ["host", "mail", "status", "portal", "analytics", "docs"];
+export type AccountEventAudience = (typeof ACCOUNT_EVENT_AUDIENCES)[number];
 /** En-têtes de la requête signée. */
 export declare const ACCOUNT_EVENT_HEADERS: {
     readonly id: "x-hgdc-event-id";
     readonly timestamp: "x-hgdc-timestamp";
+    readonly audience: "x-hgdc-audience";
     readonly signature: "x-hgdc-signature";
+    readonly signatureV2: "x-hgdc-signature-v2";
 };
 /** Écart toléré entre l'horodatage signé et l'horloge du produit, en secondes. */
 export declare const ACCOUNT_EVENT_TOLERANCE_SECONDS = 300;
+/** Avance tolérée de `occurredAt` sur l'horloge du produit, en millisecondes : au-delà, refusé. */
+export declare const ACCOUNT_EVENT_FUTURE_TOLERANCE_MS: number;
 /** Taille maximale du corps, en octets. Un événement en pèse moins de 400. */
 export declare const ACCOUNT_EVENT_MAX_BYTES: number;
 /** Longueur minimale du secret partagé (32 octets aléatoires en base64url : 43 caractères). */
@@ -46,21 +53,56 @@ export type AccountEvent = (EventBase & {
 });
 export declare const accountEventSchema: z.ZodType<AccountEvent>;
 export type AccountEventType = AccountEvent["type"];
-/** Ce que le produit a fait de l'événement : rendu dans la réponse, pour les journaux d'Account. */
-export type AccountEventOutcome = "applied" | "ignored" | "duplicate";
+/**
+ * Pourquoi un produit n'a rien appliqué :
+ * - `unknown_organization` : aucun espace pour cette organisation (le seul cas normal) ;
+ * - `unknown_user` : personne sans compte `hgdc` chez le produit ;
+ * - `not_member` : personne connue, sans appartenance à cet espace ;
+ * - `stale` : appartenance confirmée par Account après l'événement (`accountEventIsStale`).
+ */
+export declare const ACCOUNT_EVENT_IGNORED_REASONS: readonly ["unknown_organization", "unknown_user", "not_member", "stale"];
+export type AccountEventIgnoredReason = (typeof ACCOUNT_EVENT_IGNORED_REASONS)[number];
+/** Ce que le produit a fait de l'événement : `applied`, `duplicate` ou `ignored:<raison>`. */
+export type AccountEventOutcome = "applied" | "duplicate" | `ignored:${AccountEventIgnoredReason}`;
+/** Réponse 200 du produit. */
+export type AccountEventResponse = {
+    status: "applied" | "duplicate";
+} | {
+    status: "ignored";
+    reason: AccountEventIgnoredReason;
+};
+/** Côté Account : l'issue lue dans la réponse 200 d'un produit, ou `null` si illisible. */
+export declare function accountEventOutcomeOf(body: unknown): AccountEventOutcome | null;
 /** Identifiant d'événement neuf (UUID sans tirets), à garder pour tous les essais. */
 export declare function newAccountEventId(): string;
 /**
- * Côté Account : corps et en-têtes d'un envoi. À rappeler à chaque essai (horodatage neuf),
- * avec le même événement (même `id`).
+ * Côté Account : corps et en-têtes d'un envoi à `audience`. À rappeler à chaque essai (horodatage
+ * neuf), avec le même événement (même `id`). `legacy` ajoute l'ancienne signature `v1=` (sans
+ * audience) pour un produit pas encore monté : `v1=` dans `x-hgdc-signature`, `v2=` dans
+ * `x-hgdc-signature-v2`. Sans `legacy`, `x-hgdc-signature` porte `v2=`.
  */
 export declare function signAccountEvent(event: AccountEvent, options: {
     secret: string;
     now: number;
+    audience: AccountEventAudience;
+    legacy?: boolean;
 }): Promise<{
     body: string;
     headers: Record<string, string>;
 }>;
+export type BodyText = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: "too_large";
+};
+/**
+ * Lecture bornée du corps d'une requête : par morceaux, abandonnée dès qu'elle dépasse `maxBytes`
+ * (en octets, « é » en compte deux). `request.text()` lit tout avant qu'on puisse compter, y
+ * compris un envoi sans `content-length` (chunked).
+ */
+export declare function readBodyText(request: Request, maxBytes: number): Promise<BodyText>;
 /** Pourquoi une requête est refusée. La réponse ne porte que le code, jamais le détail. */
 export type AccountEventRejection = "too_large" | "unauthorized" | "invalid_body";
 export type AccountEventVerification = {
@@ -72,13 +114,16 @@ export type AccountEventVerification = {
     error: AccountEventRejection;
 };
 /**
- * Côté produit : vérifie taille, horodatage (±5 minutes), signature en temps constant, puis le
- * corps (`accountEventSchema`) et l'accord entre l'identifiant signé et celui du corps. Ne lit le
- * corps qu'une fois. Ne dit rien du rejeu : à écarter par la table des événements traités.
+ * Côté produit : lit le corps en flux (plafond `ACCOUNT_EVENT_MAX_BYTES`), vérifie horodatage
+ * (±5 minutes), audience (celle du produit), signature `v2=` en temps constant, puis le corps
+ * (`accountEventSchema`), l'accord entre l'identifiant signé et celui du corps, et un
+ * `occurredAt` sans plus de 5 minutes d'avance. Ne dit rien du rejeu : à écarter par la table
+ * des événements traités.
  */
 export declare function verifyAccountEvent(request: Request, options: {
     secret: string;
     now: number;
+    audience: AccountEventAudience;
 }): Promise<AccountEventVerification>;
 /**
  * Endpoint complet d'un produit, à envelopper dans une `httpAction` Convex :
@@ -86,6 +131,7 @@ export declare function verifyAccountEvent(request: Request, options: {
  * ```ts
  * export const accountEvents = httpAction(async (ctx, request) =>
  *   handleAccountEventRequest(request, {
+ *     audience: "host",
  *     secret: process.env.ACCOUNT_EVENTS_SECRET,
  *     apply: (event) => ctx.runMutation(internal.organizations.applyAccountEvent, { event }),
  *   }),
@@ -94,22 +140,29 @@ export declare function verifyAccountEvent(request: Request, options: {
  * ```
  *
  * `apply` est une mutation interne qui, dans la même transaction, écarte un `id` déjà traité,
- * l'enregistre et applique l'événement. Sans secret posé : 503, Account réessaie plus tard.
- * Une erreur de `apply` remonte (500) : Account réessaie aussi.
+ * l'enregistre et applique l'événement ; elle rend son issue détaillée (`AccountEventOutcome`),
+ * renvoyée à Account et journalisée en avertissement quand rien n'est appliqué. Sans secret
+ * posé : 503, Account réessaie plus tard. Une erreur de `apply` remonte (500) : Account réessaie.
  */
 export declare function handleAccountEventRequest(request: Request, options: {
+    audience: AccountEventAudience;
     secret: string | undefined;
     apply: (event: AccountEvent) => Promise<AccountEventOutcome>;
     now?: number;
 }): Promise<Response>;
 /**
- * Vrai si l'appartenance a été confirmée par Account après l'événement (`syncedAt` plus récent) :
- * un essai en retard ne doit pas défaire une connexion plus récente (personne retirée puis
- * réinvitée, rôle changé deux fois). Une copie sans `syncedAt` n'est jamais plus récente.
+ * Vrai si l'appartenance a été confirmée par Account après l'événement : un essai en retard ne
+ * doit pas défaire une connexion plus récente (personne retirée puis réinvitée, rôle changé deux
+ * fois). `syncedAt` doit être l'instant où Account a émis les droits recopiés, soit l'`iat` de
+ * l'id_token (`verifyHgdcIdToken(...).issuedAt`), jamais l'heure de la copie : un jeton émis avant
+ * un retrait puis lu après ne doit pas masquer ce retrait. Une copie sans `syncedAt` n'est jamais
+ * plus récente.
  */
 export declare function accountEventIsStale(event: Pick<AccountEvent, "occurredAt">, syncedAt: number | null | undefined): boolean;
 /** Validateur Convex d'un `AccountEvent` : argument de la mutation interne qui l'applique. */
 export declare const vAccountEvent: Validator<AccountEvent, "required", string>;
+/** Validateur Convex de l'issue rendue par la mutation qui applique un événement. */
+export declare const vAccountEventOutcome: Validator<AccountEventOutcome, "required", string>;
 type AccountEventRow = {
     eventId: string;
     type: string;

package/dist/events.js

@@ -8,20 +8,36 @@ import { ORG_ROLES } from "./index.js";
  * relecture des organisations à la connexion suivante.
  *
  * Signature HMAC-SHA256 par produit, Web Crypto seulement (Convex, Node, Bun, navigateurs) :
- * `v1=` hex de HMAC(secret, "<id>.<horodatage>.<corps brut>"). L'identifiant de l'événement est
- * dans le MAC : rejouer une requête captée dans la fenêtre de 5 minutes ne passe pas la table des
- * événements déjà traités du produit.
+ * `v2=` hex de HMAC(secret, "v2.<audience>.<id>.<horodatage>.<corps brut>"). L'audience (le
+ * produit destinataire) et l'identifiant de l'événement sont dans le MAC : un événement destiné à
+ * un autre produit est refusé même si deux secrets venaient à se confondre, et rejouer une requête
+ * captée dans la fenêtre de 5 minutes ne passe pas la table des événements déjà traités.
+ * L'ancien format `v1=` (sans audience) n'est plus accepté à la réception ; Account peut encore
+ * l'ajouter (`legacy`) le temps que tous les produits soient montés.
  */
 /** Chemin de l'endpoint de chaque produit, sur son déploiement Convex (`https://<…>.convex.site`). */
 export const ACCOUNT_EVENTS_PATH = "/hgdc/v1/account-events";
+/** Produits destinataires : l'audience signée de chaque événement. */
+export const ACCOUNT_EVENT_AUDIENCES = [
+    "host",
+    "mail",
+    "status",
+    "portal",
+    "analytics",
+    "docs",
+];
 /** En-têtes de la requête signée. */
 export const ACCOUNT_EVENT_HEADERS = {
     id: "x-hgdc-event-id",
     timestamp: "x-hgdc-timestamp",
+    audience: "x-hgdc-audience",
     signature: "x-hgdc-signature",
+    signatureV2: "x-hgdc-signature-v2",
 };
 /** Écart toléré entre l'horodatage signé et l'horloge du produit, en secondes. */
 export const ACCOUNT_EVENT_TOLERANCE_SECONDS = 300;
+/** Avance tolérée de `occurredAt` sur l'horloge du produit, en millisecondes : au-delà, refusé. */
+export const ACCOUNT_EVENT_FUTURE_TOLERANCE_MS = ACCOUNT_EVENT_TOLERANCE_SECONDS * 1000;
 /** Taille maximale du corps, en octets. Un événement en pèse moins de 400. */
 export const ACCOUNT_EVENT_MAX_BYTES = 8 * 1024;
 /** Longueur minimale du secret partagé (32 octets aléatoires en base64url : 43 caractères). */
@@ -55,6 +71,39 @@ export const accountEventSchema = z.discriminatedUnion("type", [
         type: z.literal("organization.deleted"),
     }),
 ]);
+/**
+ * Pourquoi un produit n'a rien appliqué :
+ * - `unknown_organization` : aucun espace pour cette organisation (le seul cas normal) ;
+ * - `unknown_user` : personne sans compte `hgdc` chez le produit ;
+ * - `not_member` : personne connue, sans appartenance à cet espace ;
+ * - `stale` : appartenance confirmée par Account après l'événement (`accountEventIsStale`).
+ */
+export const ACCOUNT_EVENT_IGNORED_REASONS = [
+    "unknown_organization",
+    "unknown_user",
+    "not_member",
+    "stale",
+];
+function isIgnoredReason(value) {
+    return ACCOUNT_EVENT_IGNORED_REASONS.includes(value);
+}
+function responseOf(outcome) {
+    if (outcome === "applied" || outcome === "duplicate")
+        return { status: outcome };
+    const reason = outcome.slice("ignored:".length);
+    return { status: "ignored", reason: isIgnoredReason(reason) ? reason : "not_member" };
+}
+/** Côté Account : l'issue lue dans la réponse 200 d'un produit, ou `null` si illisible. */
+export function accountEventOutcomeOf(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const { status, reason } = body;
+    if (status === "applied" || status === "duplicate")
+        return status;
+    if (status === "ignored" && isIgnoredReason(reason))
+        return `ignored:${reason}`;
+    return null;
+}
 const encoder = new TextEncoder();
 async function hmacHex(secret, payload) {
     const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
@@ -75,29 +124,77 @@ function assertSecret(secret) {
     if (typeof secret !== "string" || secret.length < ACCOUNT_EVENT_SECRET_MIN_LENGTH)
         throw new Error(`Secret des événements Account absent ou trop court (${ACCOUNT_EVENT_SECRET_MIN_LENGTH} caractères au moins).`);
 }
+function assertAudience(audience) {
+    if (!ACCOUNT_EVENT_AUDIENCES.includes(audience))
+        throw new Error("Audience d'événement Account inconnue.");
+}
+function signedPayloadV2(audience, eventId, timestamp, body) {
+    return `v2.${audience}.${eventId}.${timestamp}.${body}`;
+}
 /** Identifiant d'événement neuf (UUID sans tirets), à garder pour tous les essais. */
 export function newAccountEventId() {
     return crypto.randomUUID().replaceAll("-", "");
 }
 /**
- * Côté Account : corps et en-têtes d'un envoi. À rappeler à chaque essai (horodatage neuf),
- * avec le même événement (même `id`).
+ * Côté Account : corps et en-têtes d'un envoi à `audience`. À rappeler à chaque essai (horodatage
+ * neuf), avec le même événement (même `id`). `legacy` ajoute l'ancienne signature `v1=` (sans
+ * audience) pour un produit pas encore monté : `v1=` dans `x-hgdc-signature`, `v2=` dans
+ * `x-hgdc-signature-v2`. Sans `legacy`, `x-hgdc-signature` porte `v2=`.
  */
 export async function signAccountEvent(event, options) {
     assertSecret(options.secret);
+    assertAudience(options.audience);
     const parsed = accountEventSchema.parse(event);
     const body = JSON.stringify(parsed);
     const timestamp = String(Math.floor(options.now / 1000));
-    const signature = `v1=${await hmacHex(options.secret, `${parsed.id}.${timestamp}.${body}`)}`;
-    return {
-        body,
-        headers: {
-            "content-type": "application/json",
-            [ACCOUNT_EVENT_HEADERS.id]: parsed.id,
-            [ACCOUNT_EVENT_HEADERS.timestamp]: timestamp,
-            [ACCOUNT_EVENT_HEADERS.signature]: signature,
-        },
+    const v2 = `v2=${await hmacHex(options.secret, signedPayloadV2(options.audience, parsed.id, timestamp, body))}`;
+    const headers = {
+        "content-type": "application/json",
+        [ACCOUNT_EVENT_HEADERS.id]: parsed.id,
+        [ACCOUNT_EVENT_HEADERS.timestamp]: timestamp,
+        [ACCOUNT_EVENT_HEADERS.audience]: options.audience,
     };
+    if (options.legacy) {
+        headers[ACCOUNT_EVENT_HEADERS.signature] =
+            `v1=${await hmacHex(options.secret, `${parsed.id}.${timestamp}.${body}`)}`;
+        headers[ACCOUNT_EVENT_HEADERS.signatureV2] = v2;
+    }
+    else
+        headers[ACCOUNT_EVENT_HEADERS.signature] = v2;
+    return { body, headers };
+}
+/**
+ * Lecture bornée du corps d'une requête : par morceaux, abandonnée dès qu'elle dépasse `maxBytes`
+ * (en octets, « é » en compte deux). `request.text()` lit tout avant qu'on puisse compter, y
+ * compris un envoi sans `content-length` (chunked).
+ */
+export async function readBodyText(request, maxBytes) {
+    const declared = Number(request.headers.get("content-length") ?? 0);
+    if (declared > maxBytes)
+        return { ok: false, reason: "too_large" };
+    if (!request.body)
+        return { ok: true, text: "" };
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            return { ok: false, reason: "too_large" };
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { ok: true, text: new TextDecoder().decode(bytes) };
 }
 const reject = (status, error) => ({
     ok: false,
@@ -105,26 +202,33 @@ const reject = (status, error) => ({
     error,
 });
 /**
- * Côté produit : vérifie taille, horodatage (±5 minutes), signature en temps constant, puis le
- * corps (`accountEventSchema`) et l'accord entre l'identifiant signé et celui du corps. Ne lit le
- * corps qu'une fois. Ne dit rien du rejeu : à écarter par la table des événements traités.
+ * Côté produit : lit le corps en flux (plafond `ACCOUNT_EVENT_MAX_BYTES`), vérifie horodatage
+ * (±5 minutes), audience (celle du produit), signature `v2=` en temps constant, puis le corps
+ * (`accountEventSchema`), l'accord entre l'identifiant signé et celui du corps, et un
+ * `occurredAt` sans plus de 5 minutes d'avance. Ne dit rien du rejeu : à écarter par la table
+ * des événements traités.
  */
 export async function verifyAccountEvent(request, options) {
     assertSecret(options.secret);
-    const declared = Number(request.headers.get("content-length") ?? "0");
-    if (declared > ACCOUNT_EVENT_MAX_BYTES)
-        return reject(413, "too_large");
-    const raw = await request.text();
-    if (encoder.encode(raw).byteLength > ACCOUNT_EVENT_MAX_BYTES)
+    assertAudience(options.audience);
+    const read = await readBodyText(request, ACCOUNT_EVENT_MAX_BYTES);
+    if (!read.ok)
         return reject(413, "too_large");
+    const raw = read.text;
     const eventId = request.headers.get(ACCOUNT_EVENT_HEADERS.id) ?? "";
     const timestamp = request.headers.get(ACCOUNT_EVENT_HEADERS.timestamp) ?? "";
-    const signature = request.headers.get(ACCOUNT_EVENT_HEADERS.signature) ?? "";
+    const audience = request.headers.get(ACCOUNT_EVENT_HEADERS.audience) ?? "";
+    const signature = [
+        request.headers.get(ACCOUNT_EVENT_HEADERS.signatureV2),
+        request.headers.get(ACCOUNT_EVENT_HEADERS.signature),
+    ].find((value) => value?.startsWith("v2="));
+    if (!signature || audience !== options.audience)
+        return reject(401, "unauthorized");
     if (!/^[A-Za-z0-9_-]{16,64}$/.test(eventId) || !/^\d{1,12}$/.test(timestamp))
         return reject(401, "unauthorized");
     if (Math.abs(options.now / 1000 - Number(timestamp)) > ACCOUNT_EVENT_TOLERANCE_SECONDS)
         return reject(401, "unauthorized");
-    const expected = `v1=${await hmacHex(options.secret, `${eventId}.${timestamp}.${raw}`)}`;
+    const expected = `v2=${await hmacHex(options.secret, signedPayloadV2(options.audience, eventId, timestamp, raw))}`;
     if (!constantTimeEqual(signature, expected))
         return reject(401, "unauthorized");
     let json;
@@ -137,6 +241,8 @@ export async function verifyAccountEvent(request, options) {
     const parsed = accountEventSchema.safeParse(json);
     if (!parsed.success || parsed.data.id !== eventId)
         return reject(400, "invalid_body");
+    if (parsed.data.occurredAt > options.now + ACCOUNT_EVENT_FUTURE_TOLERANCE_MS)
+        return reject(400, "invalid_body");
     return { ok: true, event: parsed.data };
 }
 const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
@@ -146,6 +252,7 @@ const json = (status, body) => new Response(JSON.stringify(body), { status, head
  * ```ts
  * export const accountEvents = httpAction(async (ctx, request) =>
  *   handleAccountEventRequest(request, {
+ *     audience: "host",
  *     secret: process.env.ACCOUNT_EVENTS_SECRET,
  *     apply: (event) => ctx.runMutation(internal.organizations.applyAccountEvent, { event }),
  *   }),
@@ -154,23 +261,35 @@ const json = (status, body) => new Response(JSON.stringify(body), { status, head
  * ```
  *
  * `apply` est une mutation interne qui, dans la même transaction, écarte un `id` déjà traité,
- * l'enregistre et applique l'événement. Sans secret posé : 503, Account réessaie plus tard.
- * Une erreur de `apply` remonte (500) : Account réessaie aussi.
+ * l'enregistre et applique l'événement ; elle rend son issue détaillée (`AccountEventOutcome`),
+ * renvoyée à Account et journalisée en avertissement quand rien n'est appliqué. Sans secret
+ * posé : 503, Account réessaie plus tard. Une erreur de `apply` remonte (500) : Account réessaie.
  */
 export async function handleAccountEventRequest(request, options) {
     const { secret } = options;
     if (typeof secret !== "string" || secret.length < ACCOUNT_EVENT_SECRET_MIN_LENGTH)
         return json(503, { error: "not_configured" });
-    const verified = await verifyAccountEvent(request, { secret, now: options.now ?? Date.now() });
+    const verified = await verifyAccountEvent(request, {
+        secret,
+        now: options.now ?? Date.now(),
+        audience: options.audience,
+    });
     if (!verified.ok)
         return json(verified.status, { error: verified.error });
-    const outcome = await options.apply(verified.event);
-    return json(200, { status: outcome });
+    const { event } = verified;
+    const outcome = await options.apply(event);
+    // Des identifiants seulement, jamais d'adresse : de quoi retrouver l'événement chez Account.
+    if (outcome !== "applied")
+        console.warn("Événement Account non appliqué", JSON.stringify({ id: event.id, type: event.type, organizationId: event.organizationId, outcome }));
+    return json(200, responseOf(outcome));
 }
 /**
- * Vrai si l'appartenance a été confirmée par Account après l'événement (`syncedAt` plus récent) :
- * un essai en retard ne doit pas défaire une connexion plus récente (personne retirée puis
- * réinvitée, rôle changé deux fois). Une copie sans `syncedAt` n'est jamais plus récente.
+ * Vrai si l'appartenance a été confirmée par Account après l'événement : un essai en retard ne
+ * doit pas défaire une connexion plus récente (personne retirée puis réinvitée, rôle changé deux
+ * fois). `syncedAt` doit être l'instant où Account a émis les droits recopiés, soit l'`iat` de
+ * l'id_token (`verifyHgdcIdToken(...).issuedAt`), jamais l'heure de la copie : un jeton émis avant
+ * un retrait puis lu après ne doit pas masquer ce retrait. Une copie sans `syncedAt` n'est jamais
+ * plus récente.
  */
 export function accountEventIsStale(event, syncedAt) {
     return typeof syncedAt === "number" && syncedAt > event.occurredAt;
@@ -197,6 +316,8 @@ export const vAccountEvent = v.union(v.object({
     occurredAt: v.number(),
     organizationId: v.string(),
 }));
+/** Validateur Convex de l'issue rendue par la mutation qui applique un événement. */
+export const vAccountEventOutcome = v.union(v.literal("applied"), v.literal("duplicate"), v.literal("ignored:unknown_organization"), v.literal("ignored:unknown_user"), v.literal("ignored:not_member"), v.literal("ignored:stale"));
 /**
  * Table des événements déjà traités, pour l'idempotence (`accountEvents: accountEventsTable` dans
  * le schéma du produit). Purge après `ACCOUNT_EVENT_RETENTION_MS` par l'index `by_received`.

package/dist/index.d.ts

@@ -141,10 +141,15 @@ export type IdTokenExpectation = {
  * La signature n'est pas revérifiée : le jeton vient du point de jeton d'Account, reçu par le
  * serveur en TLS (point 6). Le contrôle de fraîcheur empêche qu'un jeton ancien, que
  * better-auth n'aurait pas réécrit, rejoue des organisations périmées.
+ *
+ * `issuedAt` (`iat` en millisecondes) est l'instant où Account a lu les organisations : c'est lui,
+ * pas l'heure de la copie, qui doit devenir le `syncedAt` des appartenances recopiées
+ * (`accountEventIsStale` le compare aux événements poussés par Account).
  */
 export declare function verifyHgdcIdToken(idToken: string, expected: IdTokenExpectation): {
     claims: Record<string, unknown>;
     organizations: HgdcOrganization[];
+    issuedAt: number;
 };
 /**
  * Organisations d'un id_token reçu à la connexion, après `verifyHgdcIdToken`. À appeler dans
@@ -185,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

@@ -243,6 +243,10 @@ function payloadOf(idToken) {
  * La signature n'est pas revérifiée : le jeton vient du point de jeton d'Account, reçu par le
  * serveur en TLS (point 6). Le contrôle de fraîcheur empêche qu'un jeton ancien, que
  * better-auth n'aurait pas réécrit, rejoue des organisations périmées.
+ *
+ * `issuedAt` (`iat` en millisecondes) est l'instant où Account a lu les organisations : c'est lui,
+ * pas l'heure de la copie, qui doit devenir le `syncedAt` des appartenances recopiées
+ * (`accountEventIsStale` le compare aux événements poussés par Account).
  */
 export function verifyHgdcIdToken(idToken, expected) {
     if (!expected.issuer || !expected.clientId)
@@ -265,7 +269,7 @@ export function verifyHgdcIdToken(idToken, expected) {
     const result = organizationsClaim.safeParse(claims);
     if (!result.success)
         throw new HgdcIdTokenError("invalid_claims", `Organisations HGDC invalides : ${z.prettifyError(result.error)}`);
-    return { claims, organizations: result.data.organizations ?? [] };
+    return { claims, organizations: result.data.organizations ?? [], issuedAt: iat * 1000 };
 }
 /**
  * Organisations d'un id_token reçu à la connexion, après `verifyHgdcIdToken`. À appeler dans
@@ -309,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/package.json

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