@hgdc/auth 0.4.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`, `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`                                                                                                                                                                                                                                             |
+| 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

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];

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) {

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.4.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",