@hgdc/auth 0.2.0 → 0.4.0

package/README.md

@@ -2,12 +2,12 @@
 
 Connexion d'un produit HGDC à HGDC 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`, rôles (`highestRole`, `hasRole`), `parseHgdcProfile` |
-| `@hgdc/auth/server` | `hgdcProvider` (plugin `genericOAuth`), `createAuthProxy`, `restoreFetchMode`                          |
-| `@hgdc/auth/convex` | `requireIdentity`, `requireOrgMember`, `isAuthError`                                                   |
-| `@hgdc/auth/react`  | `HgdcSignInButton`, `startHgdcSignIn`, `HgdcMark`                                                      |
+| Import              | Contenu                                                                                                                                                                                                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@hgdc/auth`        | `HGDC_ISSUER`, `HGDC_PROVIDER_ID`, `HGDC_SCOPES`, 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`                                                                                                                                                                                                                 |
+| `@hgdc/auth/convex` | `requireIdentity`, `requireOrgMember`, `isAuthError`, `authErrorReason`, `AUTH_ERROR_MESSAGES`                                                                                                                                                                                                |
+| `@hgdc/auth/react`  | `HgdcSignInButton`, `startHgdcSignIn`, `HgdcMark`                                                                                                                                                                                                                                             |
 
 Pairs : better-auth 1.6, convex 1.46+, React 19 (chacun facultatif selon l'import).
 
@@ -67,8 +67,55 @@ const { userId, role } = await requireOrgMember(ctx, organizationId, {
 })
 ```
 
-À appeler avant toute lecture ou écriture. L'émetteur est obligatoire : un `subject` n'est unique que chez son émetteur, et sans ce contrôle un autre fournisseur accepté par Convex pourrait se faire passer pour un membre. Sans session ou d'un autre émetteur : `ConvexError({ code: "UNAUTHENTICATED" })`. Personne étrangère à l'organisation ou rôle insuffisant : `FORBIDDEN`. Une appartenance rendue pour une autre personne ou une autre organisation est refusée.
+À appeler avant toute lecture ou écriture. L'émetteur est obligatoire : un `subject` n'est unique que chez son émetteur, et sans ce contrôle un autre fournisseur accepté par Convex pourrait se faire passer pour un membre. Une appartenance rendue pour une autre personne ou une autre organisation est refusée.
+
+Un refus est une `ConvexError({ code, reason, message })`. `message` s'affiche tel quel (tutoiement) ; pour décider quoi montrer, lire `reason`, jamais le texte :
+
+| `reason`            | `code`            | Cas                                       |
+| ------------------- | ----------------- | ----------------------------------------- |
+| `no_session`        | `UNAUTHENTICATED` | Personne n'est connecté                   |
+| `wrong_issuer`      | `UNAUTHENTICATED` | Jeton d'un autre émetteur                 |
+| `not_member`        | `FORBIDDEN`       | La personne n'est pas dans l'organisation |
+| `insufficient_role` | `FORBIDDEN`       | Elle en est membre, rôle insuffisant      |
+
+```ts
+import { authErrorReason } from "@hgdc/auth/convex"
+
+if (authErrorReason(error) === "insufficient_role") showUpgradeHint()
+```
+
+`authErrorReason` marche des deux côtés (la `ConvexError` reconstruite par le client garde ses données) et déduit la raison d'une erreur d'avant 0.4 par son code.
 
 Les organisations arrivent par la portée `organizations` : claim `organizations: [{ id, slug, name, role }]` de l'id_token et de userinfo.
 
+## 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 :
+
+1. **Synchroniser dans `databaseHooks.session.create.before`**, avant que la session existe. Un id_token refusé fait échouer la connexion plutôt que d'ouvrir une session sur des droits périmés.
+2. **Sessions de 7 jours sans prolongation** : `session: { expiresIn: SESSION_TTL_SECONDS, disableSessionRefresh: true }`. Les organisations sont donc relues au moins une fois par semaine.
+3. **Appartenance périmée, pas d'accès** : chaque appartenance garde `syncedAt` (remis à jour à chaque connexion, même sans changement), et le chargeur rend `null` quand `membershipIsFresh` est faux. Une personne retirée dans Account perd l'accès au plus tard 8 jours après (`MEMBERSHIP_TTL_MS`).
+
+```ts
+import { HGDC_ISSUER, membershipIsFresh, planOrganizationSync, verifiedOrganizationsFromIdToken } from "@hgdc/auth"
+
+// better-auth : databaseHooks.session.create.before
+const hgdc = accounts.find((a) => a.providerId === "hgdc") // exactement un, sinon refuser
+const claimed = verifiedOrganizationsFromIdToken(hgdc.idToken ?? "", {
+  issuer: HGDC_ISSUER,
+  clientId: process.env.HGDC_CLIENT_ID!,
+  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
+
+// chargeur de requireOrgMember
+load: async (ctx, { organizationId, userId }) => {
+  const member = /* appartenance lue dans la base du produit */
+  return member && membershipIsFresh(member, Date.now()) ? member : null
+}
+```
+
+`verifyHgdcIdToken` rend aussi les claims du profil (nom, adresse, photo) pour les recopier. La signature n'est pas revérifiée : le jeton arrive du point de jeton d'Account, reçu en TLS par le serveur (OpenID Connect Core 3.1.3.7, point 6) ; le contrôle de fraîcheur empêche qu'un ancien jeton resté dans la table `account` rejoue des organisations. Une clé d'API vit hors session : `membershipIsFresh(member, now, KEY_MEMBERSHIP_TTL_MS)` lui laisse 30 jours. Les copies périmées se purgent par un cron.
+
 Tous droits réservés, Hugo Gebel Développement Conseil.

package/dist/convex.d.ts

@@ -2,9 +2,21 @@ import type { Auth, UserIdentity } from "convex/server";
 import { ConvexError } from "convex/values";
 import { type OrgRole } from "./index.ts";
 export type AuthErrorCode = "UNAUTHENTICATED" | "FORBIDDEN";
+/**
+ * Raison précise d'un refus, stable d'une version à l'autre : c'est elle qu'un produit lit pour
+ * choisir quoi afficher, jamais le texte de `message`.
+ * - `no_session` : personne n'est connecté (`UNAUTHENTICATED`) ;
+ * - `wrong_issuer` : jeton d'un autre émetteur que celui attendu (`UNAUTHENTICATED`) ;
+ * - `not_member` : la personne n'appartient pas à l'organisation (`FORBIDDEN`) ;
+ * - `insufficient_role` : elle en est membre, mais son rôle ne suffit pas (`FORBIDDEN`).
+ */
+export type AuthErrorReason = "no_session" | "wrong_issuer" | "not_member" | "insufficient_role";
+/** Messages des gardes, au tutoiement : ils s'affichent tels quels aux personnes. */
+export declare const AUTH_ERROR_MESSAGES: Readonly<Record<AuthErrorReason, string>>;
 /** Données d'une `ConvexError` levée par les gardes : `message` est affichable tel quel. */
 export type AuthErrorData = {
     code: AuthErrorCode;
+    reason: AuthErrorReason;
     message: string;
 };
 /** Lien entre une personne et une organisation, tel que le produit le stocke. */
@@ -30,6 +42,12 @@ export type OrgAccess = {
 };
 /** Vrai si `error` vient d'une garde de ce module. */
 export declare function isAuthError(error: unknown): error is ConvexError<AuthErrorData>;
+/**
+ * Raison d'un refus des gardes, ou `null` si `error` n'en vient pas. Côté client, l'erreur
+ * arrive sérialisée (`ConvexError` reconstruite par le client Convex) : la lecture vaut des deux
+ * côtés. Une erreur d'une version d'avant `reason` (0.3) est déduite de son code.
+ */
+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
@@ -50,7 +68,7 @@ export declare function requireIdentity(ctx: {
  * et au moins le rôle `minRole` (par défaut `member`).
  *
  * Une personne étrangère à l'organisation et un membre au rôle insuffisant reçoivent
- * tous deux `FORBIDDEN`, avec des messages distincts.
+ * tous deux `FORBIDDEN`, distingués par `reason` (`not_member`, `insufficient_role`).
  */
 export declare function requireOrgMember<Ctx extends {
     auth: Auth;

package/dist/convex.js

@@ -1,7 +1,20 @@
 import { ConvexError } from "convex/values";
 import { highestRole, ORG_ROLES } from "./index.js";
-function authError(code, message) {
-    return new ConvexError({ code, message });
+/** Messages des gardes, au tutoiement : ils s'affichent tels quels aux personnes. */
+export const AUTH_ERROR_MESSAGES = {
+    no_session: "Connecte-toi pour continuer.",
+    wrong_issuer: "Connecte-toi pour continuer.",
+    not_member: "Tu n'as pas accès à cette organisation.",
+    insufficient_role: "Ton rôle dans cette organisation ne permet pas cette action.",
+};
+const CODE_OF = {
+    no_session: "UNAUTHENTICATED",
+    wrong_issuer: "UNAUTHENTICATED",
+    not_member: "FORBIDDEN",
+    insufficient_role: "FORBIDDEN",
+};
+function authError(reason) {
+    return new ConvexError({ code: CODE_OF[reason], reason, message: AUTH_ERROR_MESSAGES[reason] });
 }
 /** Vrai si `error` vient d'une garde de ce module. */
 export function isAuthError(error) {
@@ -13,6 +26,22 @@ export function isAuthError(error) {
         "code" in data &&
         (data.code === "UNAUTHENTICATED" || data.code === "FORBIDDEN"));
 }
+function isReason(value) {
+    return typeof value === "string" && Object.hasOwn(CODE_OF, value);
+}
+/**
+ * Raison d'un refus des gardes, ou `null` si `error` n'en vient pas. Côté client, l'erreur
+ * arrive sérialisée (`ConvexError` reconstruite par le client Convex) : la lecture vaut des deux
+ * côtés. Une erreur d'une version d'avant `reason` (0.3) est déduite de son code.
+ */
+export function authErrorReason(error) {
+    if (!isAuthError(error))
+        return null;
+    const data = error.data;
+    if (typeof data === "object" && data !== null && "reason" in data && isReason(data.reason))
+        return data.reason;
+    return error.data.code === "UNAUTHENTICATED" ? "no_session" : "not_member";
+}
 function normalizeIssuer(value) {
     return value.replace(/\/+$/, "");
 }
@@ -20,11 +49,11 @@ function normalizeIssuer(value) {
 export async function requireIdentity(ctx, options) {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity)
-        throw authError("UNAUTHENTICATED", "Connectez-vous pour continuer.");
+        throw authError("no_session");
     if (!options.issuer)
         throw new Error("requireIdentity : émetteur attendu manquant (CONVEX_SITE_URL ?).");
     if (normalizeIssuer(identity.issuer) !== normalizeIssuer(options.issuer))
-        throw authError("UNAUTHENTICATED", "Connectez-vous pour continuer.");
+        throw authError("wrong_issuer");
     return identity;
 }
 /**
@@ -33,7 +62,7 @@ export async function requireIdentity(ctx, options) {
  * et au moins le rôle `minRole` (par défaut `member`).
  *
  * Une personne étrangère à l'organisation et un membre au rôle insuffisant reçoivent
- * tous deux `FORBIDDEN`, avec des messages distincts.
+ * tous deux `FORBIDDEN`, distingués par `reason` (`not_member`, `insufficient_role`).
  */
 export async function requireOrgMember(ctx, organizationId, options) {
     const identity = await requireIdentity(ctx, options);
@@ -41,12 +70,12 @@ export async function requireOrgMember(ctx, organizationId, options) {
     const membership = await options.load(ctx, { organizationId, userId });
     // Une copie mal synchronisée ne doit jamais ouvrir l'accès à la mauvaise personne.
     if (!membership || membership.userId !== userId || membership.organizationId !== organizationId) {
-        throw authError("FORBIDDEN", "Vous n'avez pas accès à cette organisation.");
+        throw authError("not_member");
     }
     const role = highestRole(membership.role);
     const minRole = options.minRole ?? "member";
     if (role === null || ORG_ROLES.indexOf(role) < ORG_ROLES.indexOf(minRole)) {
-        throw authError("FORBIDDEN", "Votre rôle dans cette organisation ne permet pas cette action.");
+        throw authError("insufficient_role");
     }
     return { identity, userId, membership, role };
 }

package/dist/index.d.ts

@@ -38,3 +38,103 @@ export type HgdcProfile = {
  * l'adresse n'est pas vérifiée : un tel profil ne doit jamais ouvrir de session.
  */
 export declare function parseHgdcProfile(claims: unknown): HgdcProfile;
+/**
+ * Organisations d'un id_token de HGDC Account. À n'appeler que sur un jeton reçu directement
+ * du point de jeton d'Account par le serveur (champ `idToken` de la table `account` de
+ * better-auth) : sa signature n'est pas revérifiée ici (OpenID Connect Core 3.1.3.7, point 6).
+ * Lève une erreur si le jeton est illisible ou si un claim est invalide ; `[]` sans la portée.
+ * À la connexion, préférer `verifiedOrganizationsFromIdToken`, qui contrôle aussi émetteur,
+ * audience et fraîcheur.
+ */
+export declare function organizationsFromIdToken(idToken: string): HgdcOrganization[];
+/** Appartenance d'une personne telle qu'un produit l'a copiée depuis Account. */
+export type SyncedMembership = {
+    organizationId: string;
+    slug: string;
+    name: string;
+    role: OrgRole;
+};
+export type OrganizationSyncPlan = {
+    /** Organisations à créer ou à mettre à jour chez le produit (espace et appartenance). */
+    upsert: HgdcOrganization[];
+    /** Organisations dont la personne ne fait plus partie : appartenance à retirer. */
+    remove: string[];
+};
+/**
+ * Écart entre les organisations reçues d'Account et la copie du produit, pour une personne.
+ * Ne renvoie que ce qui change : une connexion sans changement n'écrit rien.
+ */
+export declare function planOrganizationSync(claimed: readonly HgdcOrganization[], current: readonly SyncedMembership[]): OrganizationSyncPlan;
+/** Âge maximal d'un id_token lu à la connexion : il vient d'être reçu du point de jeton d'Account. */
+export declare const ID_TOKEN_MAX_AGE_SECONDS: number;
+/** Avance d'horloge tolérée entre Account et le produit, en secondes. */
+export declare const ID_TOKEN_CLOCK_SKEW_SECONDS: number;
+/** Pourquoi un id_token est refusé, pour les journaux : la personne ne voit que « Connexion HGDC requise ». */
+export type IdTokenRejection = "unreadable" | "wrong_issuer" | "wrong_audience" | "stale" | "invalid_claims";
+/** Erreur de `verifyHgdcIdToken` et `verifiedOrganizationsFromIdToken`. */
+export declare class HgdcIdTokenError extends Error {
+    readonly reason: IdTokenRejection;
+    constructor(reason: IdTokenRejection, message: string);
+}
+export type IdTokenExpectation = {
+    /** Émetteur attendu : `HGDC_ISSUER`, ou celui d'un Account de préproduction. */
+    issuer: string;
+    /** Identifiant du client du produit : l'audience du jeton. */
+    clientId: string;
+    /** Instant présent en millisecondes (`Date.now()`). */
+    now: number;
+};
+/**
+ * Contrôle de provenance et de fraîcheur d'un id_token lu dans la table `account` de better-auth,
+ * avant d'en recopier quoi que ce soit (OpenID Connect Core 3.1.3.7) :
+ * - `iss` égal à l'émetteur attendu ;
+ * - `aud` contient `clientId`, et `azp` vaut `clientId` quand il y a plusieurs audiences ;
+ * - `iat` de moins de `ID_TOKEN_MAX_AGE_SECONDS`, pas dans le futur, et `exp` non dépassé.
+ *
+ * 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.
+ */
+export declare function verifyHgdcIdToken(idToken: string, expected: IdTokenExpectation): {
+    claims: Record<string, unknown>;
+    organizations: HgdcOrganization[];
+};
+/**
+ * Organisations d'un id_token reçu à la connexion, après `verifyHgdcIdToken`. À appeler dans
+ * `databaseHooks.session.create.before` : un jeton refusé fait échouer la connexion plutôt que
+ * d'ouvrir une session sur des droits périmés.
+ *
+ * ```ts
+ * const organizations = verifiedOrganizationsFromIdToken(account.idToken, {
+ *   issuer: HGDC_ISSUER,
+ *   clientId: process.env.HGDC_CLIENT_ID!,
+ *   now: Date.now(),
+ * })
+ * ```
+ */
+export declare function verifiedOrganizationsFromIdToken(idToken: string, expected: IdTokenExpectation): HgdcOrganization[];
+/**
+ * Durée d'une session d'un produit, sans prolongation (`session: { expiresIn: SESSION_TTL_SECONDS,
+ * disableSessionRefresh: true }`) : les organisations sont relues à chaque connexion, donc au
+ * moins une fois tous les 7 jours.
+ */
+export declare const SESSION_TTL_SECONDS: number;
+/**
+ * Âge maximal d'une appartenance copiée depuis Account, en millisecondes : 8 jours, soit une
+ * session de 7 jours et un jour de marge. Une copie plus ancienne n'est plus portée par aucune
+ * session (personne retirée dans Account, session d'avant la synchronisation) : elle n'ouvre plus rien.
+ */
+export declare const MEMBERSHIP_TTL_MS: number;
+/**
+ * Âge maximal de l'appartenance de la créatrice d'une clé d'API, qui vit hors session (CLI,
+ * intégrations) : 30 jours. Passé ce délai sans reconnexion, la clé cesse d'agir.
+ */
+export declare const KEY_MEMBERSHIP_TTL_MS: number;
+/**
+ * Vrai si l'appartenance a été confirmée par Account il y a moins de `ttl` (par défaut
+ * `MEMBERSHIP_TTL_MS`). `syncedAt` : dernière synchronisation réussie, en millisecondes, mise
+ * à jour même quand rien n'a changé. Une copie sans date n'est jamais fraîche.
+ */
+export declare function membershipIsFresh(membership: {
+    syncedAt?: number | null | undefined;
+}, now: number, ttl?: number): boolean;

package/dist/index.js

@@ -56,3 +56,148 @@ export function parseHgdcProfile(claims) {
         throw new Error(`Profil HGDC invalide : ${z.prettifyError(result.error)}`);
     return result.data;
 }
+const organizationsClaim = z.object({ organizations: z.array(organizationClaim).optional() });
+function decodeBase64Url(segment) {
+    const base64 = segment
+        .replaceAll("-", "+")
+        .replaceAll("_", "/")
+        .padEnd(Math.ceil(segment.length / 4) * 4, "=");
+    const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Organisations d'un id_token de HGDC Account. À n'appeler que sur un jeton reçu directement
+ * du point de jeton d'Account par le serveur (champ `idToken` de la table `account` de
+ * better-auth) : sa signature n'est pas revérifiée ici (OpenID Connect Core 3.1.3.7, point 6).
+ * Lève une erreur si le jeton est illisible ou si un claim est invalide ; `[]` sans la portée.
+ * À la connexion, préférer `verifiedOrganizationsFromIdToken`, qui contrôle aussi émetteur,
+ * audience et fraîcheur.
+ */
+export function organizationsFromIdToken(idToken) {
+    const payload = idToken.split(".")[1];
+    if (!payload)
+        throw new Error("id_token HGDC illisible");
+    const result = organizationsClaim.safeParse(JSON.parse(decodeBase64Url(payload)));
+    if (!result.success)
+        throw new Error(`Organisations HGDC invalides : ${z.prettifyError(result.error)}`);
+    return result.data.organizations ?? [];
+}
+/**
+ * Écart entre les organisations reçues d'Account et la copie du produit, pour une personne.
+ * Ne renvoie que ce qui change : une connexion sans changement n'écrit rien.
+ */
+export function planOrganizationSync(claimed, current) {
+    const known = new Map(current.map((m) => [m.organizationId, m]));
+    const claimedIds = new Set(claimed.map((o) => o.id));
+    return {
+        upsert: claimed.filter((org) => {
+            const copy = known.get(org.id);
+            return !copy || copy.role !== org.role || copy.slug !== org.slug || copy.name !== org.name;
+        }),
+        remove: current.filter((m) => !claimedIds.has(m.organizationId)).map((m) => m.organizationId),
+    };
+}
+/** Âge maximal d'un id_token lu à la connexion : il vient d'être reçu du point de jeton d'Account. */
+export const ID_TOKEN_MAX_AGE_SECONDS = 10 * 60;
+/** Avance d'horloge tolérée entre Account et le produit, en secondes. */
+export const ID_TOKEN_CLOCK_SKEW_SECONDS = 60;
+/** Erreur de `verifyHgdcIdToken` et `verifiedOrganizationsFromIdToken`. */
+export class HgdcIdTokenError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "HgdcIdTokenError";
+        this.reason = reason;
+    }
+}
+function payloadOf(idToken) {
+    const segment = idToken.split(".")[1];
+    if (!segment)
+        throw new HgdcIdTokenError("unreadable", "id_token HGDC illisible");
+    let payload;
+    try {
+        payload = JSON.parse(decodeBase64Url(segment));
+    }
+    catch {
+        throw new HgdcIdTokenError("unreadable", "id_token HGDC illisible");
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+        throw new HgdcIdTokenError("unreadable", "id_token HGDC illisible");
+    return payload;
+}
+/**
+ * Contrôle de provenance et de fraîcheur d'un id_token lu dans la table `account` de better-auth,
+ * avant d'en recopier quoi que ce soit (OpenID Connect Core 3.1.3.7) :
+ * - `iss` égal à l'émetteur attendu ;
+ * - `aud` contient `clientId`, et `azp` vaut `clientId` quand il y a plusieurs audiences ;
+ * - `iat` de moins de `ID_TOKEN_MAX_AGE_SECONDS`, pas dans le futur, et `exp` non dépassé.
+ *
+ * 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.
+ */
+export function verifyHgdcIdToken(idToken, expected) {
+    if (!expected.issuer || !expected.clientId)
+        throw new Error("verifyHgdcIdToken : émetteur ou clientId attendu manquant (HGDC_CLIENT_ID ?).");
+    const claims = payloadOf(idToken);
+    const issuer = typeof claims.iss === "string" ? claims.iss.replace(/\/+$/, "") : null;
+    if (issuer !== expected.issuer.replace(/\/+$/, ""))
+        throw new HgdcIdTokenError("wrong_issuer", "id_token d'un autre émetteur");
+    const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (!audience.includes(expected.clientId))
+        throw new HgdcIdTokenError("wrong_audience", "id_token destiné à un autre client");
+    if (audience.length > 1 && claims.azp !== expected.clientId)
+        throw new HgdcIdTokenError("wrong_audience", "id_token destiné à un autre client");
+    const now = Math.floor(expected.now / 1000);
+    const iat = typeof claims.iat === "number" ? claims.iat : null;
+    if (iat === null || now - iat > ID_TOKEN_MAX_AGE_SECONDS || iat - now > ID_TOKEN_CLOCK_SKEW_SECONDS)
+        throw new HgdcIdTokenError("stale", "id_token périmé");
+    if (claims.exp !== undefined && (typeof claims.exp !== "number" || now - claims.exp > ID_TOKEN_CLOCK_SKEW_SECONDS))
+        throw new HgdcIdTokenError("stale", "id_token périmé");
+    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 ?? [] };
+}
+/**
+ * Organisations d'un id_token reçu à la connexion, après `verifyHgdcIdToken`. À appeler dans
+ * `databaseHooks.session.create.before` : un jeton refusé fait échouer la connexion plutôt que
+ * d'ouvrir une session sur des droits périmés.
+ *
+ * ```ts
+ * const organizations = verifiedOrganizationsFromIdToken(account.idToken, {
+ *   issuer: HGDC_ISSUER,
+ *   clientId: process.env.HGDC_CLIENT_ID!,
+ *   now: Date.now(),
+ * })
+ * ```
+ */
+export function verifiedOrganizationsFromIdToken(idToken, expected) {
+    return verifyHgdcIdToken(idToken, expected).organizations;
+}
+/**
+ * Durée d'une session d'un produit, sans prolongation (`session: { expiresIn: SESSION_TTL_SECONDS,
+ * disableSessionRefresh: true }`) : les organisations sont relues à chaque connexion, donc au
+ * moins une fois tous les 7 jours.
+ */
+export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Âge maximal d'une appartenance copiée depuis Account, en millisecondes : 8 jours, soit une
+ * session de 7 jours et un jour de marge. Une copie plus ancienne n'est plus portée par aucune
+ * session (personne retirée dans Account, session d'avant la synchronisation) : elle n'ouvre plus rien.
+ */
+export const MEMBERSHIP_TTL_MS = 8 * 24 * 60 * 60 * 1000;
+/**
+ * Âge maximal de l'appartenance de la créatrice d'une clé d'API, qui vit hors session (CLI,
+ * intégrations) : 30 jours. Passé ce délai sans reconnexion, la clé cesse d'agir.
+ */
+export const KEY_MEMBERSHIP_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Vrai si l'appartenance a été confirmée par Account il y a moins de `ttl` (par défaut
+ * `MEMBERSHIP_TTL_MS`). `syncedAt` : dernière synchronisation réussie, en millisecondes, mise
+ * à jour même quand rien n'a changé. Une copie sans date n'est jamais fraîche.
+ */
+export function membershipIsFresh(membership, now, ttl = MEMBERSHIP_TTL_MS) {
+    const { syncedAt } = membership;
+    return typeof syncedAt === "number" && now - syncedAt <= ttl;
+}

package/package.json

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