@hgdc/auth 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,74 @@
 # @hgdc/auth
 
-Connexion HGDC : bouton « Se connecter avec HGDC », config better-auth et gardes Convex.
+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.
 
-Paquet réservé : son contenu arrive avec la vague 1 de la H family.
+| 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`                                                      |
+
+Pairs : better-auth 1.6, convex 1.46+, React 19 (chacun facultatif selon l'import).
+
+## Connecter un produit
+
+1. Demander à HGDC l'enregistrement du produit : il rend un `clientId` et un `clientSecret`. Adresse de retour : `https://<produit>/api/auth/oauth2/callback/hgdc`.
+2. Côté better-auth (serveur) :
+
+```ts
+import { hgdcProvider } from "@hgdc/auth/server"
+import { genericOAuth } from "better-auth/plugins"
+
+plugins: [
+  genericOAuth({
+    config: [hgdcProvider({ clientId: process.env.HGDC_CLIENT_ID!, clientSecret: process.env.HGDC_CLIENT_SECRET! })],
+  }),
+]
+```
+
+Le profil reçu est validé (`parseHgdcProfile`) avant de créer ou relier un compte ; l'émetteur est vérifié et PKCE est actif. Relier un compte existant par adresse e-mail reste un choix du produit (`account.accountLinking.trustedProviders: ["hgdc"]`).
+
+3. Côté client : plugin `genericOAuthClient()` dans `createAuthClient`, puis
+
+```tsx
+import { HgdcSignInButton } from "@hgdc/auth/react"
+
+<HgdcSignInButton authClient={authClient} callbackURL="/tableau-de-bord" className="…" onError={…} />
+```
+
+Le bouton n'a pas de style propre : le produit le met en forme. L'attente est exposée par `aria-busy` et `data-pending`.
+
+## Proxy `/api/auth` (TanStack Start + Convex)
+
+À utiliser à la place du `handler` de `@convex-dev/better-auth` 0.12, qui rend un 500 sur tout refus 401 et transforme les redirections OAuth en JSON :
+
+```ts
+// src/routes/api/auth/$.ts
+const proxy = createAuthProxy(process.env.VITE_CONVEX_SITE_URL!)
+// handlers: { GET: ({ request }) => proxy(request), POST: ({ request }) => proxy(request) }
+
+// convex/http.ts
+authComponent.registerRoutes(http, (ctx) => {
+  const auth = createAuth(ctx)
+  return { ...auth, handler: (request: Request) => auth.handler(restoreFetchMode(request)) }
+})
+```
+
+## Garder une fonction Convex
+
+```ts
+import { requireOrgMember } from "@hgdc/auth/convex"
+
+const { userId, role } = await requireOrgMember(ctx, organizationId, {
+  issuer: process.env.CONVEX_SITE_URL!, // émetteur des JWT du plugin convex
+  minRole: "admin",
+  load: async (ctx, { organizationId, userId }) => /* appartenance lue dans la base du produit */ null,
+})
+```
+
+À 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.
+
+Les organisations arrivent par la portée `organizations` : claim `organizations: [{ id, slug, name, role }]` de l'id_token et de userinfo.
 
 Tous droits réservés, Hugo Gebel Développement Conseil.

package/dist/convex.d.ts

@@ -0,0 +1,60 @@
+import type { Auth, UserIdentity } from "convex/server";
+import { ConvexError } from "convex/values";
+import { type OrgRole } from "./index.ts";
+export type AuthErrorCode = "UNAUTHENTICATED" | "FORBIDDEN";
+/** Données d'une `ConvexError` levée par les gardes : `message` est affichable tel quel. */
+export type AuthErrorData = {
+    code: AuthErrorCode;
+    message: string;
+};
+/** Lien entre une personne et une organisation, tel que le produit le stocke. */
+export type Membership = {
+    organizationId: string;
+    userId: string;
+    /** Champ `role` de better-auth, éventuellement plusieurs rôles séparés par des virgules. */
+    role: string;
+};
+/**
+ * Lit l'appartenance de `userId` à `organizationId`, ou `null`. Account la lit dans les
+ * tables du plugin `organization` ; un produit, dans sa copie synchronisée depuis Account.
+ */
+export type MembershipLoader<Ctx> = (ctx: Ctx, args: {
+    organizationId: string;
+    userId: string;
+}) => Promise<Membership | null>;
+export type OrgAccess = {
+    identity: UserIdentity;
+    userId: string;
+    membership: Membership;
+    role: OrgRole;
+};
+/** Vrai si `error` vient d'une garde de ce module. */
+export declare function isAuthError(error: unknown): error is ConvexError<AuthErrorData>;
+/**
+ * Émetteur des jetons dont le `subject` désigne un utilisateur du produit. Avec le plugin
+ * `convex` de better-auth : `process.env.CONVEX_SITE_URL`. Un `subject` n'est unique que chez
+ * son émetteur : sans ce contrôle, un autre fournisseur accepté par Convex pourrait présenter
+ * le `subject` d'un membre et prendre ses droits. Un seul émetteur : l'appartenance est
+ * cherchée par `subject`, qui ne distingue pas deux fournisseurs.
+ */
+export type IssuerOption = {
+    issuer: string;
+};
+/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+export declare function requireIdentity(ctx: {
+    auth: Auth;
+}, options: IssuerOption): Promise<UserIdentity>;
+/**
+ * Garde d'une fonction Convex publique sur une ressource d'organisation : à appeler
+ * avant toute lecture ou écriture. Exige une session de l'émetteur attendu, l'appartenance à l'organisation
+ * 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.
+ */
+export declare function requireOrgMember<Ctx extends {
+    auth: Auth;
+}>(ctx: Ctx, organizationId: string, options: IssuerOption & {
+    load: MembershipLoader<Ctx>;
+    minRole?: OrgRole;
+}): Promise<OrgAccess>;

package/dist/convex.js

@@ -0,0 +1,52 @@
+import { ConvexError } from "convex/values";
+import { highestRole, ORG_ROLES } from "./index.js";
+function authError(code, message) {
+    return new ConvexError({ code, message });
+}
+/** Vrai si `error` vient d'une garde de ce module. */
+export function isAuthError(error) {
+    if (!(error instanceof ConvexError))
+        return false;
+    const data = error.data;
+    return (typeof data === "object" &&
+        data !== null &&
+        "code" in data &&
+        (data.code === "UNAUTHENTICATED" || data.code === "FORBIDDEN"));
+}
+function normalizeIssuer(value) {
+    return value.replace(/\/+$/, "");
+}
+/** Identité de la personne connectée, émise par `issuer`, ou erreur `UNAUTHENTICATED`. */
+export async function requireIdentity(ctx, options) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity)
+        throw authError("UNAUTHENTICATED", "Connectez-vous pour continuer.");
+    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.");
+    return identity;
+}
+/**
+ * Garde d'une fonction Convex publique sur une ressource d'organisation : à appeler
+ * avant toute lecture ou écriture. Exige une session de l'émetteur attendu, l'appartenance à l'organisation
+ * 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.
+ */
+export async function requireOrgMember(ctx, organizationId, options) {
+    const identity = await requireIdentity(ctx, options);
+    const userId = identity.subject;
+    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.");
+    }
+    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.");
+    }
+    return { identity, userId, membership, role };
+}

package/dist/index.d.ts

@@ -1 +1,40 @@
-export {};
+/** Identifiant du fournisseur dans `genericOAuth` et dans la table `account` des produits. */
+export declare const HGDC_PROVIDER_ID = "hgdc";
+/** Émetteur OIDC de HGDC Account (`iss` des jetons, base de la découverte). */
+export declare const HGDC_ISSUER = "https://account.hgdc.ch/api/auth";
+/** Portée qui ajoute les organisations de la personne et son rôle dans chacune. */
+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[];
+/** 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];
+/**
+ * Rôle le plus fort d'un champ `role` de better-auth. Le plugin `organization` accepte
+ * plusieurs rôles séparés par des virgules (« admin,member ») ; un rôle inconnu ne
+ * donne aucun droit. `null` quand aucun rôle connu.
+ */
+export declare function highestRole(role: string): OrgRole | null;
+/** Vrai si `role` atteint au moins `minimum`. */
+export declare function hasRole(role: string, minimum: OrgRole): boolean;
+export type HgdcOrganization = {
+    id: string;
+    slug: string;
+    name: string;
+    role: OrgRole;
+};
+/** Profil d'une personne tel que HGDC Account le donne (id_token ou userinfo). */
+export type HgdcProfile = {
+    sub: string;
+    email: string;
+    email_verified: true;
+    name: string;
+    picture?: string | null | undefined;
+    /** Présent seulement si la portée `organizations` a été accordée. */
+    organizations?: HgdcOrganization[] | undefined;
+};
+/**
+ * Valide les claims reçus de HGDC Account. Lève une erreur si un champ attendu manque ou si
+ * l'adresse n'est pas vérifiée : un tel profil ne doit jamais ouvrir de session.
+ */
+export declare function parseHgdcProfile(claims: unknown): HgdcProfile;

package/dist/index.js

@@ -1,2 +1,58 @@
-export {};
-// Paquet réservé : contenu livré par le chantier B de la vague 1 (HANDOFF.md).
+import { z } from "zod";
+/** Identifiant du fournisseur dans `genericOAuth` et dans la table `account` des produits. */
+export const HGDC_PROVIDER_ID = "hgdc";
+/** Émetteur OIDC de HGDC Account (`iss` des jetons, base de la découverte). */
+export const HGDC_ISSUER = "https://account.hgdc.ch/api/auth";
+/** Portée qui ajoute les organisations de la personne et son rôle dans chacune. */
+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];
+/** Rôles d'organisation, du plus faible au plus fort. */
+export const ORG_ROLES = ["member", "admin", "owner"];
+function isOrgRole(value) {
+    return ORG_ROLES.includes(value);
+}
+/**
+ * Rôle le plus fort d'un champ `role` de better-auth. Le plugin `organization` accepte
+ * plusieurs rôles séparés par des virgules (« admin,member ») ; un rôle inconnu ne
+ * donne aucun droit. `null` quand aucun rôle connu.
+ */
+export function highestRole(role) {
+    let best = null;
+    for (const part of role.split(",")) {
+        const name = part.trim();
+        if (isOrgRole(name) && (best === null || ORG_ROLES.indexOf(name) > ORG_ROLES.indexOf(best)))
+            best = name;
+    }
+    return best;
+}
+/** Vrai si `role` atteint au moins `minimum`. */
+export function hasRole(role, minimum) {
+    const best = highestRole(role);
+    return best !== null && ORG_ROLES.indexOf(best) >= ORG_ROLES.indexOf(minimum);
+}
+const organizationClaim = z.object({
+    id: z.string().min(1),
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    role: z.enum(ORG_ROLES),
+});
+const profileClaims = z.object({
+    sub: z.string().min(1),
+    email: z.email(),
+    // Une adresse non vérifiée ne doit jamais créer ni relier un compte (liaison par e-mail).
+    email_verified: z.literal(true),
+    name: z.string().min(1),
+    picture: z.url().nullish(),
+    organizations: z.array(organizationClaim).optional(),
+});
+/**
+ * Valide les claims reçus de HGDC Account. Lève une erreur si un champ attendu manque ou si
+ * l'adresse n'est pas vérifiée : un tel profil ne doit jamais ouvrir de session.
+ */
+export function parseHgdcProfile(claims) {
+    const result = profileClaims.safeParse(claims);
+    if (!result.success)
+        throw new Error(`Profil HGDC invalide : ${z.prettifyError(result.error)}`);
+    return result.data;
+}

package/dist/react.d.ts

@@ -0,0 +1,46 @@
+import { type ButtonHTMLAttributes, type ReactElement } from "react";
+/** Ce que le bouton utilise du client better-auth (plugin `genericOAuthClient`). */
+export type HgdcAuthClient = {
+    signIn: {
+        oauth2: (args: {
+            providerId: string;
+            callbackURL?: string;
+            errorCallbackURL?: string;
+        }) => Promise<{
+            error?: unknown;
+        } | null | undefined>;
+    };
+};
+export type HgdcSignInButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "type" | "children"> & {
+    authClient: HgdcAuthClient;
+    /** Page d'arrivée après la connexion, `/` par défaut. */
+    callbackURL?: string;
+    /** Page d'arrivée si HGDC Account refuse ou si la personne annule. */
+    errorCallbackURL?: string;
+    /** Appelé quand la redirection n'a pas pu partir (réseau, configuration). */
+    onError?: (error: unknown) => void;
+    label?: string;
+};
+export type HgdcSignInOptions = {
+    callbackURL?: string;
+    errorCallbackURL?: string;
+};
+/**
+ * Part vers HGDC Account. Renvoie `{ ok: true }` quand la redirection est lancée,
+ * sinon l'erreur du client ou du réseau, sans lever.
+ */
+export declare function startHgdcSignIn(authClient: HgdcAuthClient, { callbackURL, errorCallbackURL }?: HgdcSignInOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+}>;
+/** Monogramme HGDC, en `currentColor`. */
+export declare function HgdcMark(props: {
+    className?: string;
+}): ReactElement;
+/**
+ * Bouton « Se connecter avec HGDC ». Sans style propre : le produit le met en forme par
+ * `className`, l'état d'attente est exposé par `aria-busy` et `data-pending`.
+ */
+export declare function HgdcSignInButton({ authClient, callbackURL, errorCallbackURL, onError, label, disabled, ...rest }: HgdcSignInButtonProps): ReactElement;

package/dist/react.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { HGDC_PROVIDER_ID } from "./index.js";
+/**
+ * Part vers HGDC Account. Renvoie `{ ok: true }` quand la redirection est lancée,
+ * sinon l'erreur du client ou du réseau, sans lever.
+ */
+export async function startHgdcSignIn(authClient, { callbackURL = "/", errorCallbackURL } = {}) {
+    try {
+        const result = await authClient.signIn.oauth2({
+            providerId: HGDC_PROVIDER_ID,
+            callbackURL,
+            ...(errorCallbackURL ? { errorCallbackURL } : {}),
+        });
+        return result?.error ? { ok: false, error: result.error } : { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+/** Monogramme HGDC, en `currentColor`. */
+export function HgdcMark(props) {
+    return (_jsxs("svg", { viewBox: "0 0 24 24", width: "16", height: "16", fill: "currentColor", "aria-hidden": "true", ...props, children: [_jsx("rect", { x: "2.5", y: "8.5", width: "13", height: "7", rx: "2", transform: "rotate(45 9 12)" }), _jsx("rect", { x: "8.5", y: "8.5", width: "13", height: "7", rx: "2", transform: "rotate(45 15 12)", opacity: "0.6" })] }));
+}
+/**
+ * Bouton « Se connecter avec HGDC ». Sans style propre : le produit le met en forme par
+ * `className`, l'état d'attente est exposé par `aria-busy` et `data-pending`.
+ */
+export function HgdcSignInButton({ authClient, callbackURL = "/", errorCallbackURL, onError, label = "Se connecter avec HGDC", disabled, ...rest }) {
+    const [pending, setPending] = useState(false);
+    async function signIn() {
+        setPending(true);
+        const result = await startHgdcSignIn(authClient, {
+            callbackURL,
+            ...(errorCallbackURL ? { errorCallbackURL } : {}),
+        });
+        // Succès : le navigateur part vers HGDC Account, le bouton reste en attente.
+        if (!result.ok) {
+            setPending(false);
+            onError?.(result.error);
+        }
+    }
+    return (_jsxs("button", { ...rest, type: "button", disabled: disabled === true || pending, "aria-busy": pending, "data-pending": pending ? "" : undefined, onClick: () => void signIn(), children: [_jsx(HgdcMark, {}), _jsx("span", { children: pending ? "Redirection vers HGDC…" : label })] }));
+}

package/dist/server.d.ts

@@ -0,0 +1,41 @@
+import type { GenericOAuthConfig } from "better-auth/plugins/generic-oauth";
+/** En-tête qui porte le `sec-fetch-mode` du navigateur à travers le proxy. */
+export declare const FETCH_MODE_HEADER = "x-hgdc-fetch-mode";
+/**
+ * Côté Convex, avant better-auth : remet le `sec-fetch-mode` d'origine. better-auth y lit si
+ * une réponse doit rediriger (navigation) ou rendre du JSON (`fetch`). Sans cela, toute
+ * navigation vers `/oauth2/authorize` passée par le proxy reçoit du JSON au lieu d'un 302.
+ * Sans risque : qui appelle Convex directement choisit déjà cet en-tête.
+ */
+export declare function restoreFetchMode(request: Request): Request;
+/**
+ * Proxy de `/api/auth/*` vers better-auth sur Convex (`https://<deploiement>.convex.site`),
+ * à monter dans la route serveur d'un produit TanStack Start, avec `restoreFetchMode` côté Convex.
+ *
+ * Remplace le `handler` de @convex-dev/better-auth 0.12, qui a deux défauts :
+ * - le corps part en flux : sur une réponse 401, undici échoue (« expected non-null body
+ *   source ») et le client reçoit un 500 au lieu du refus. Ici il part en mémoire ;
+ * - undici impose `sec-fetch-mode: cors` : le mode du navigateur voyage donc dans
+ *   `x-hgdc-fetch-mode`.
+ */
+export declare function createAuthProxy(convexSiteUrl: string, fetchImpl?: typeof fetch): (request: Request) => Promise<Response>;
+export type HgdcProviderOptions = {
+    /** Identifiant du client, remis par HGDC à l'enregistrement du produit. */
+    clientId: string;
+    /** Secret du client : variable d'environnement côté serveur, jamais dans le navigateur. */
+    clientSecret: string;
+    /** Émetteur, à changer seulement pour un Account de préproduction. */
+    issuer?: string;
+    /** Portées demandées, `HGDC_SCOPES` par défaut. */
+    scopes?: readonly string[];
+};
+/**
+ * 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
+ * entre fournisseurs. Le profil reçu est validé avant de créer ou relier un compte.
+ *
+ * ```ts
+ * genericOAuth({ config: [hgdcProvider({ clientId, clientSecret })] })
+ * ```
+ */
+export declare function hgdcProvider(options: HgdcProviderOptions): GenericOAuthConfig;

package/dist/server.js

@@ -0,0 +1,92 @@
+import { HGDC_ISSUER, HGDC_PROVIDER_ID, HGDC_SCOPES, parseHgdcProfile } 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"]);
+/**
+ * Côté Convex, avant better-auth : remet le `sec-fetch-mode` d'origine. better-auth y lit si
+ * une réponse doit rediriger (navigation) ou rendre du JSON (`fetch`). Sans cela, toute
+ * navigation vers `/oauth2/authorize` passée par le proxy reçoit du JSON au lieu d'un 302.
+ * Sans risque : qui appelle Convex directement choisit déjà cet en-tête.
+ */
+export function restoreFetchMode(request) {
+    const mode = request.headers.get(FETCH_MODE_HEADER);
+    if (!mode || !FETCH_MODES.has(mode))
+        return request;
+    const headers = new Headers(request.headers);
+    headers.set("sec-fetch-mode", mode);
+    headers.delete(FETCH_MODE_HEADER);
+    return new Request(request, { headers });
+}
+/**
+ * Proxy de `/api/auth/*` vers better-auth sur Convex (`https://<deploiement>.convex.site`),
+ * à monter dans la route serveur d'un produit TanStack Start, avec `restoreFetchMode` côté Convex.
+ *
+ * Remplace le `handler` de @convex-dev/better-auth 0.12, qui a deux défauts :
+ * - le corps part en flux : sur une réponse 401, undici échoue (« expected non-null body
+ *   source ») et le client reçoit un 500 au lieu du refus. Ici il part en mémoire ;
+ * - undici impose `sec-fetch-mode: cors` : le mode du navigateur voyage donc dans
+ *   `x-hgdc-fetch-mode`.
+ */
+export function createAuthProxy(convexSiteUrl, fetchImpl = fetch) {
+    const target = new URL(convexSiteUrl);
+    return async (request) => {
+        const url = new URL(request.url);
+        const headers = new Headers(request.headers);
+        for (const name of ["transfer-encoding", "content-length", "connection"])
+            headers.delete(name);
+        headers.set("accept-encoding", "application/json");
+        headers.set("host", target.host);
+        const proto = url.protocol.replace(/:$/, "");
+        headers.set("x-forwarded-host", url.host);
+        headers.set("x-forwarded-proto", proto);
+        headers.set("x-better-auth-forwarded-host", url.host);
+        headers.set("x-better-auth-forwarded-proto", proto);
+        const mode = request.headers.get("sec-fetch-mode");
+        if (mode)
+            headers.set(FETCH_MODE_HEADER, mode);
+        else
+            headers.delete(FETCH_MODE_HEADER);
+        const hasBody = request.method !== "GET" && request.method !== "HEAD";
+        return await fetchImpl(`${target.origin}${url.pathname}${url.search}`, {
+            method: request.method,
+            headers,
+            redirect: "manual",
+            ...(hasBody ? { body: await request.arrayBuffer() } : {}),
+        });
+    };
+}
+/**
+ * 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
+ * entre fournisseurs. Le profil reçu est validé avant de créer ou relier un compte.
+ *
+ * ```ts
+ * genericOAuth({ config: [hgdcProvider({ clientId, clientSecret })] })
+ * ```
+ */
+export function hgdcProvider(options) {
+    if (!options.clientId || !options.clientSecret) {
+        throw new Error("HGDC Account : clientId et clientSecret sont requis (voir le runbook d'Account).");
+    }
+    const issuer = (options.issuer ?? HGDC_ISSUER).replace(/\/+$/, "");
+    return {
+        providerId: HGDC_PROVIDER_ID,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        issuer,
+        discoveryUrl: `${issuer}/.well-known/openid-configuration`,
+        requireIssuerValidation: true,
+        scopes: [...(options.scopes ?? HGDC_SCOPES)],
+        pkce: true,
+        // L'identifiant du compte reste `sub` (lu par better-auth) ; ici seulement l'utilisateur.
+        mapProfileToUser: (claims) => {
+            const profile = parseHgdcProfile(claims);
+            return {
+                email: profile.email,
+                emailVerified: profile.email_verified,
+                name: profile.name,
+                image: profile.picture ?? null,
+            };
+        },
+    };
+}

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@hgdc/auth",
-  "version": "0.1.0",
+  "version": "0.2.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",
+  "bugs": "https://github.com/hugogebel-boop/hgdc-kit/security/advisories/new",
   "type": "module",
   "repository": {
     "type": "git",
@@ -21,13 +23,48 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./convex": {
+      "types": "./dist/convex.d.ts",
+      "default": "./dist/convex.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json"
   },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
   "peerDependencies": {
-    "better-auth": "^1.6.16",
-    "convex": "^1.46.0"
+    "better-auth": ">=1.6.16 <1.7.0",
+    "convex": "^1.46.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    },
+    "convex": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "better-auth": "1.6.16",
+    "convex": "1.46.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
   }
 }