@hgdc/auth 0.3.0 → 0.5.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`, `organizationsFromIdToken`, `planOrganizationSync` |
-| `@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`, 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/react`  | `HgdcSignInButton`, `startHgdcSignIn`, `HgdcMark`                                                                                                                                                                                                                                                                                                                 |
 
 Pairs : better-auth 1.6, convex 1.46+, React 19 (chacun facultatif selon l'import).
 
@@ -55,6 +55,31 @@ authComponent.registerRoutes(http, (ctx) => {
 })
 ```
 
+## Entrée commune `/auth/hgdc`
+
+Le menu « Produits » (`@hgdc/ui/account-menu`) envoie vers `https://<mot>.hgdc.ch/auth/hgdc`, pas vers la page d'accueil publique. Chaque produit monte cette route serveur, au même chemin :
+
+```ts
+// src/routes/auth/hgdc.ts
+import { createHgdcEntry } from "@hgdc/auth/server"
+import { createFileRoute } from "@tanstack/react-router"
+
+import { proxyAuth } from "@/lib/auth-server" // le proxy /api/auth (createAuthProxy)
+
+const entry = createHgdcEntry({ proxy: proxyAuth, errorCallbackURL: "/sign-in?error=1" })
+
+export const Route = createFileRoute("/auth/hgdc")({
+  server: { handlers: { GET: ({ request }) => entry(request) } },
+})
+```
+
+- Session du produit ouverte : redirection vers `next`.
+- Sinon la connexion HGDC part aussitôt, côté serveur (même appel que le bouton), avec retour vers `next`. Session d'Account ouverte et produit autorisé : Account renvoie sans formulaire.
+- `next` (`?next=/o/acme`) n'accepte qu'un chemin du produit (`safeNextPath`) ; tout le reste devient `/`, que chaque produit redirige vers son app quand la session existe. `errorCallbackURL` : la page de connexion du produit avec son paramètre d'erreur.
+- Lien vers un produit depuis ailleurs : `hgdcEntryUrl("https://mail.hgdc.ch", "/o/acme")`.
+
+Décision : ADR 0010.
+
 ## Garder une fonction Convex
 
 ```ts
@@ -67,25 +92,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`. Elle se met à jour à chaque connexion :
+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 :
 
-```ts
-import { organizationsFromIdToken, planOrganizationSync } from "@hgdc/auth"
+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`).
 
-// better-auth : databaseHooks.session.create.after → mutation interne du produit
-const account = /* ligne `account` de la personne avec providerId "hgdc" */
-const claimed = organizationsFromIdToken(account.idToken) // jeton reçu du point de jeton, déjà validé
+```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)
-// plan.upsert : créer l'espace (index unique sur organizationId) et l'appartenance, ou mettre à jour rôle, nom, slug
-// plan.remove : retirer les appartenances des organisations quittées
+// 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
+}
 ```
 
-Un rôle changé dans Account n'arrive qu'à la connexion suivante : garder des sessions courtes (7 jours au plus).
+`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

@@ -6,6 +6,25 @@ export declare const HGDC_ISSUER = "https://account.hgdc.ch/api/auth";
 export declare const ORGANIZATIONS_SCOPE = "organizations";
 /** Portées demandées par défaut : identité, adresse vérifiée, renouvellement et organisations. */
 export declare const HGDC_SCOPES: readonly string[];
+/**
+ * Entrée commune des produits : `https://<mot>.hgdc.ch/auth/hgdc?next=<chemin>` ouvre le produit
+ * avec la session HGDC Account, sans page d'accueil ni bouton (`createHgdcEntry`, `@hgdc/auth/server`).
+ * Le menu « Produits » de `@hgdc/ui` y pointe : même chemin dans chaque produit.
+ */
+export declare const HGDC_ENTRY_PATH = "/auth/hgdc";
+/** Paramètre de l'entrée qui porte la page d'arrivée. */
+export declare const HGDC_ENTRY_NEXT_PARAM = "next";
+/**
+ * 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
+ * contrôle, et l'entrée ou `/api/auth` (boucle). Rend `fallback` dans tous ces cas.
+ */
+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.
+ */
+export declare function hgdcEntryUrl(productOrigin: string, next?: string): string;
 /** Rôles d'organisation, du plus faible au plus fort. */
 export declare const ORG_ROLES: readonly ["member", "admin", "owner"];
 export type OrgRole = (typeof ORG_ROLES)[number];
@@ -43,6 +62,8 @@ export declare function parseHgdcProfile(claims: unknown): HgdcProfile;
  * 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. */
@@ -63,3 +84,76 @@ export type OrganizationSyncPlan = {
  * 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

@@ -7,6 +7,55 @@ export const HGDC_ISSUER = "https://account.hgdc.ch/api/auth";
 export const ORGANIZATIONS_SCOPE = "organizations";
 /** Portées demandées par défaut : identité, adresse vérifiée, renouvellement et organisations. */
 export const HGDC_SCOPES = ["openid", "profile", "email", "offline_access", ORGANIZATIONS_SCOPE];
+/**
+ * Entrée commune des produits : `https://<mot>.hgdc.ch/auth/hgdc?next=<chemin>` ouvre le produit
+ * avec la session HGDC Account, sans page d'accueil ni bouton (`createHgdcEntry`, `@hgdc/auth/server`).
+ * Le menu « Produits » de `@hgdc/ui` y pointe : même chemin dans chaque produit.
+ */
+export const HGDC_ENTRY_PATH = "/auth/hgdc";
+/** Paramètre de l'entrée qui porte la page d'arrivée. */
+export const HGDC_ENTRY_NEXT_PARAM = "next";
+const NEXT_MAX_LENGTH = 2048;
+const NEXT_BASE = "https://next.invalid";
+/**
+ * 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
+ * contrôle, et l'entrée ou `/api/auth` (boucle). Rend `fallback` dans tous ces cas.
+ */
+export function safeNextPath(value, fallback = "/") {
+    if (typeof value !== "string" || value.length === 0 || value.length > NEXT_MAX_LENGTH)
+        return fallback;
+    if (!value.startsWith("/") || value.startsWith("//"))
+        return fallback;
+    // Les navigateurs lisent `\` comme `/` : `/\evil.ch` serait une adresse externe.
+    // oxlint-disable-next-line no-control-regex -- refuser les caractères de contrôle est le but
+    if (/[\\\u0000-\u001f\u007f]/.test(value))
+        return fallback;
+    let url;
+    try {
+        url = new URL(value, NEXT_BASE);
+    }
+    catch {
+        return fallback;
+    }
+    if (url.origin !== NEXT_BASE)
+        return fallback;
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    if (path === HGDC_ENTRY_PATH || path === "/api/auth" || path.startsWith("/api/auth/"))
+        return fallback;
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+/**
+ * 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.
+ */
+export function hgdcEntryUrl(productOrigin, next) {
+    const url = new URL(HGDC_ENTRY_PATH, new URL(productOrigin).origin);
+    const path = next === undefined ? "/" : safeNextPath(next);
+    if (path !== "/")
+        url.searchParams.set(HGDC_ENTRY_NEXT_PARAM, path);
+    return url.toString();
+}
 /** Rôles d'organisation, du plus faible au plus fort. */
 export const ORG_ROLES = ["member", "admin", "owner"];
 function isOrgRole(value) {
@@ -70,6 +119,8 @@ function decodeBase64Url(segment) {
  * 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];
@@ -95,3 +146,107 @@ export function planOrganizationSync(claimed, current) {
         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/dist/server.d.ts

@@ -19,6 +19,39 @@ export declare function restoreFetchMode(request: Request): Request;
  *   `x-hgdc-fetch-mode`.
  */
 export declare function createAuthProxy(convexSiteUrl: string, fetchImpl?: typeof fetch): (request: Request) => Promise<Response>;
+export type HgdcEntryOptions = {
+    /** Le proxy `/api/auth` du produit (`createAuthProxy`). */
+    proxy: (request: Request) => Promise<Response>;
+    /**
+     * Page du produit si la connexion échoue (Account refuse, réseau) : sa page de connexion avec
+     * son paramètre d'erreur, par exemple `/sign-in?error=1`. Chemin relatif du produit.
+     */
+    errorCallbackURL: string;
+    /** Chemin de better-auth, `/api/auth` par défaut. */
+    basePath?: string;
+};
+/**
+ * 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 HGDC ».
+ *
+ * - Session du produit ouverte : redirection vers `next`.
+ * - Sinon : la connexion HGDC part aussitôt (même appel que `HgdcSignInButton`, fait par le
+ *   serveur), retour vers `next`. Si la session d'Account est ouverte et le produit déjà
+ *   autorisé, Account renvoie sans formulaire : trois redirections, aucun clic.
+ *
+ * `next` est filtré par `safeNextPath` (chemin du produit seulement, pas de redirection ouverte),
+ * puis better-auth le revérifie contre ses `trustedOrigins`.
+ *
+ * ```ts
+ * // src/routes/auth/hgdc.ts
+ * const entry = createHgdcEntry({ proxy: proxyAuth, errorCallbackURL: "/sign-in?error=1" })
+ * export const Route = createFileRoute("/auth/hgdc")({
+ *   server: { handlers: { GET: ({ request }) => entry(request) } },
+ * })
+ * ```
+ */
+export declare function createHgdcEntry(options: HgdcEntryOptions): (request: Request) => Promise<Response>;
 export type HgdcProviderOptions = {
     /** Identifiant du client, remis par HGDC à l'enregistrement du produit. */
     clientId: string;

package/dist/server.js

@@ -1,4 +1,4 @@
-import { HGDC_ISSUER, HGDC_PROVIDER_ID, HGDC_SCOPES, parseHgdcProfile } from "./index.js";
+import { HGDC_ENTRY_NEXT_PARAM, HGDC_ISSUER, HGDC_PROVIDER_ID, HGDC_SCOPES, parseHgdcProfile, safeNextPath, } 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"]);
@@ -55,6 +55,111 @@ export function createAuthProxy(convexSiteUrl, fetchImpl = fetch) {
         });
     };
 }
+const STRIPPED_ON_INTERNAL_CALL = [
+    "content-length",
+    "content-type",
+    "accept",
+    "sec-fetch-mode",
+    "sec-fetch-dest",
+    "sec-fetch-site",
+    "sec-fetch-user",
+    FETCH_MODE_HEADER,
+];
+function internalHeaders(request, origin) {
+    // Garde cookies, adresse IP et user-agent (limites de débit, sessions) ; retire le mode de
+    // navigation, sinon better-auth rendrait une redirection au lieu du JSON attendu.
+    const headers = new Headers(request.headers);
+    for (const name of STRIPPED_ON_INTERNAL_CALL)
+        headers.delete(name);
+    headers.set("accept", "application/json");
+    headers.set("origin", origin);
+    return headers;
+}
+function setCookies(response) {
+    return typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [];
+}
+function redirectTo(location, cookies = []) {
+    const headers = new Headers({ location, "cache-control": "no-store", "referrer-policy": "no-referrer" });
+    for (const cookie of cookies)
+        headers.append("set-cookie", cookie);
+    return new Response(null, { status: 302, headers });
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+function hasSessionBody(body) {
+    return typeof body === "object" && body !== null && "session" in body && Boolean(body.session);
+}
+function authorizationUrl(body) {
+    if (typeof body !== "object" || body === null || !("url" in body) || typeof body.url !== "string")
+        return null;
+    try {
+        const url = new URL(body.url);
+        return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 HGDC ».
+ *
+ * - Session du produit ouverte : redirection vers `next`.
+ * - Sinon : la connexion HGDC part aussitôt (même appel que `HgdcSignInButton`, fait par le
+ *   serveur), retour vers `next`. Si la session d'Account est ouverte et le produit déjà
+ *   autorisé, Account renvoie sans formulaire : trois redirections, aucun clic.
+ *
+ * `next` est filtré par `safeNextPath` (chemin du produit seulement, pas de redirection ouverte),
+ * puis better-auth le revérifie contre ses `trustedOrigins`.
+ *
+ * ```ts
+ * // src/routes/auth/hgdc.ts
+ * const entry = createHgdcEntry({ proxy: proxyAuth, errorCallbackURL: "/sign-in?error=1" })
+ * export const Route = createFileRoute("/auth/hgdc")({
+ *   server: { handlers: { GET: ({ request }) => entry(request) } },
+ * })
+ * ```
+ */
+export function createHgdcEntry(options) {
+    const errorCallbackURL = safeNextPath(options.errorCallbackURL, "");
+    if (!errorCallbackURL)
+        throw new Error("createHgdcEntry : errorCallbackURL doit être un chemin du produit.");
+    const basePath = (options.basePath ?? "/api/auth").replace(/\/+$/, "");
+    return async (request) => {
+        const url = new URL(request.url);
+        const next = safeNextPath(url.searchParams.get(HGDC_ENTRY_NEXT_PARAM));
+        const cookies = [];
+        try {
+            if (request.headers.has("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);
+            }
+            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: next, errorCallbackURL }),
+            }));
+            const target = signIn.ok ? authorizationUrl(await readJson(signIn)) : null;
+            if (!target)
+                return redirectTo(errorCallbackURL, cookies);
+            return redirectTo(target, [...cookies, ...setCookies(signIn)]);
+        }
+        catch {
+            return redirectTo(errorCallbackURL, cookies);
+        }
+    };
+}
 /**
  * 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.3.0",
+  "version": "0.5.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",