@sanghosdk/oauth 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sangho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @sanghosdk/oauth
+
+« Se connecter avec Sangho » — client OAuth2 Authorization Code + PKCE (RFC 7636).
+
+**Librairie distincte du SDK de paiement (`@sanghosdk/js`)** : l'authentification d'une personne
+et l'encaissement d'un paiement sont deux usages différents, avec des cycles de vie et des
+audiences différents (c'est aussi le choix de la plupart des plateformes — l'OAuth Stripe Connect
+ne vit pas dans le SDK `stripe`). N'importez cette librairie que si vous ajoutez un bouton
+« Se connecter avec Sangho », pas pour accepter des paiements.
+
+## Installation
+
+```bash
+pnpm add @sanghosdk/oauth
+# ou : npm install @sanghosdk/oauth  /  yarn add @sanghosdk/oauth
+```
+
+## Prérequis côté dashboard Sangho
+
+Créez un client OAuth (`dash.sangho.ga` → Clés API → Clients OAuth) et enregistrez l'URI de redirection EXACTE que
+vous utiliserez. Vous obtenez un `client_id` et un `client_secret` (affiché une seule fois). Ces clients sont
+*confidentiels* : le secret est **obligatoire** pour échanger le code, rafraîchir et révoquer un jeton, en plus de PKCE.
+
+> ⚠️ `clientSecret` ne doit être utilisé que **côté serveur** (Node, SSR, BFF). Jamais dans un navigateur, une
+> application mobile ou un bundle public : pour une SPA, faites passer l'échange du code par votre serveur.
+
+## Options
+
+| Option         | Défaut                   | Rôle |
+| -------------- | ------------------------ | ---- |
+| `clientId`     | —                        | Identifiant du client (obligatoire). |
+| `clientSecret` | —                        | Secret du client, côté serveur uniquement. |
+| `redirectUri`  | —                        | URI de retour, identique à celle enregistrée (obligatoire). |
+| `scopes`       | `["profile", "email"]`   | Portées demandées. |
+| `baseUrl`      | `https://accounts.sangho.ga` | Hôte OAuth de Sangho (une base terminée par `/o` est acceptée). |
+| `timeoutMs`    | `10000`                  | Délai maximal d'un appel réseau. |
+| `fetch`        | `globalThis.fetch`       | `fetch` à utiliser (proxy, tests, runtime sans `fetch` global). |
+
+## Flow complet (SSR — Node/Express)
+
+```typescript
+import { SanghoOAuthClient } from "@sanghosdk/oauth"
+
+const sangho = new SanghoOAuthClient({
+  clientId: process.env.SANGHO_OAUTH_CLIENT_ID!,
+  clientSecret: process.env.SANGHO_OAUTH_CLIENT_SECRET!,
+  redirectUri: "https://monapp.com/auth/sangho/callback",
+})
+
+// 1. Redirection — GET /auth/sangho/login
+app.get("/auth/sangho/login", async (req, res) => {
+  const { url, codeVerifier, state } = await sangho.createAuthorizationRequest()
+  // codeVerifier et state doivent survivre à l'aller-retour : session serveur ou cookie httpOnly signé.
+  req.session.oauthCodeVerifier = codeVerifier
+  req.session.oauthState = state
+  res.redirect(url)
+})
+
+// 2. Callback — GET /auth/sangho/callback?code=...&state=...
+app.get("/auth/sangho/callback", async (req, res) => {
+  try {
+    const tokens = await sangho.exchangeCode({
+      code: req.query.code as string,
+      codeVerifier: req.session.oauthCodeVerifier,
+      receivedState: req.query.state as string,
+      expectedState: req.session.oauthState,
+    })
+    const profile = await sangho.getUserInfo(tokens.access_token)
+    // profile.sub est l'identifiant STABLE à stocker (jamais profile.email, modifiable).
+    req.session.user = { sub: profile.sub, email: profile.email }
+    res.redirect("/dashboard")
+  } catch (err) {
+    res.redirect("/auth/sangho/login?error=1")
+  }
+})
+```
+
+## Rafraîchir un jeton expiré
+
+```typescript
+const tokens = await sangho.refreshToken(storedRefreshToken)
+```
+
+## Scopes
+
+| Scope     | Revendications ajoutées à `getUserInfo()`        |
+| --------- | ------------------------------------------------- |
+| `profile` | `name`, `given_name`, `family_name`, `picture`     |
+| `email`   | `email`, `email_verified`                          |
+
+`sub` (identifiant stable, UUID opaque) est toujours renvoyé, quel que soit le scope.
+
+## Gestion des erreurs
+
+```typescript
+import { SanghoOAuthError, SanghoOAuthStateMismatchError } from "@sanghosdk/oauth"
+
+try {
+  await sangho.exchangeCode({ ... })
+} catch (err) {
+  if (err instanceof SanghoOAuthStateMismatchError) {
+    // `state` invalide — tentative de CSRF ou session expirée, ne PAS poursuivre le flow.
+  } else if (err instanceof SanghoOAuthError) {
+    // code : "invalid_client" (secret refusé), "invalid_grant" (code expiré ou déjà utilisé),
+    //        "network_error", "timeout", "invalid_response"…
+    console.error(err.code, err.description)
+  }
+}
+```
+
+## Développement et publication
+
+Le projet utilise **pnpm** (version épinglée dans `packageManager` ; `corepack enable` active la bonne). Un
+`Makefile` regroupe les commandes (`make help`) ; la logique qui dépasse un simple `pnpm …` est dans `scripts/dev.mjs` (Node
+pur, sans shell POSIX : ça fonctionne sous Windows/PowerShell comme sous Linux et macOS) ; la version de Node recommandée est dans `.nvmrc` (Node ≥ 20 requis :
+`globalThis.crypto` n'existe pas par défaut sous Node 18).
+
+```bash
+corepack enable   # une fois, pour obtenir pnpm
+make install      # pnpm install --frozen-lockfile
+make test         # vitest
+make typecheck    # tsc
+make build        # dist/ (ESM + CJS + types)
+make smoke        # installe l'archive dans un dossier vide et l'importe en ESM et en CommonJS
+make matrix       # tests sur Node 20, 22 et 24 (via pnpm dlx node@X, sans nvm)
+make check        # tout ce que la CI vérifie
+make release      # tag vX.Y.Z → .github/workflows/release.yml publie sur npm (secret NPM_TOKEN)
+```
+
+Sans `make` : `pnpm install`, `pnpm test`, `pnpm run build`… (voir `scripts` dans `package.json`).

package/dist/index.cjs

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SanghoOAuthClient: () => SanghoOAuthClient,
+  SanghoOAuthError: () => SanghoOAuthError,
+  SanghoOAuthStateMismatchError: () => SanghoOAuthStateMismatchError,
+  generateCodeChallenge: () => generateCodeChallenge,
+  generateCodeVerifier: () => generateCodeVerifier,
+  generateState: () => generateState,
+  normalizeBaseUrl: () => normalizeBaseUrl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/pkce.ts
+function getCrypto() {
+  const c = globalThis.crypto;
+  if (!c || !c.subtle) {
+    throw new Error(
+      "Web Crypto API indisponible (globalThis.crypto.subtle). Node >= 20 ou un navigateur moderne sont requis."
+    );
+  }
+  return c;
+}
+function base64UrlEncode(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const b of arr) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(32);
+  getCrypto().getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function generateCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await getCrypto().subtle.digest("SHA-256", data);
+  return base64UrlEncode(digest);
+}
+function generateState() {
+  return generateCodeVerifier();
+}
+
+// src/errors.ts
+var SanghoOAuthError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "SanghoOAuthError";
+    this.code = options?.code;
+    this.description = options?.description;
+    this.statusCode = options?.statusCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var SanghoOAuthStateMismatchError = class extends SanghoOAuthError {
+  constructor() {
+    super("The `state` parameter does not match the one issued for this authorization request.", {
+      code: "state_mismatch"
+    });
+    this.name = "SanghoOAuthStateMismatchError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://accounts.sangho.ga";
+var DEFAULT_SCOPES = ["profile", "email"];
+var DEFAULT_TIMEOUT_MS = 1e4;
+function normalizeBaseUrl(url) {
+  return url.trim().replace(/\/+$/, "").replace(/\/o$/, "").replace(/\/+$/, "");
+}
+function sameSecret(a, b) {
+  if (!a || !b || a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var SanghoOAuthClient = class {
+  constructor(config) {
+    if (!config.clientId) throw new SanghoOAuthError("`clientId` is required.");
+    if (!config.redirectUri) throw new SanghoOAuthError("`redirectUri` is required.");
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (!fetchImpl) throw new SanghoOAuthError("No `fetch` implementation available (Node >= 20 or pass `fetch`).");
+    this.config = {
+      clientId: config.clientId,
+      clientSecret: config.clientSecret || void 0,
+      redirectUri: config.redirectUri,
+      baseUrl: normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL),
+      scopes: config.scopes ? [...config.scopes] : [...DEFAULT_SCOPES],
+      timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetch: fetchImpl.bind(globalThis)
+    };
+  }
+  /**
+   * Construit l'URL d'autorisation (`/o/authorize/`) et génère le couple PKCE + `state`.
+   * L'appelant DOIT persister `codeVerifier` et `state` (session serveur, ou cookie httpOnly signé) le temps de
+   * l'aller-retour, puis les repasser à `exchangeCode`.
+   */
+  async createAuthorizationRequest() {
+    const codeVerifier = generateCodeVerifier();
+    const state = generateState();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scopes.join(" "),
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
+    });
+    return { url: `${this.config.baseUrl}/o/authorize/?${params.toString()}`, codeVerifier, state };
+  }
+  /**
+   * Vérifie le `state` renvoyé par le callback puis échange le `code` contre des jetons (`/o/token/`).
+   * Lève `SanghoOAuthStateMismatchError` avant tout appel réseau si les `state` ne correspondent pas (protection CSRF).
+   */
+  async exchangeCode(params) {
+    if (!sameSecret(params.receivedState, params.expectedState)) {
+      throw new SanghoOAuthStateMismatchError();
+    }
+    return this.postToken({
+      grant_type: "authorization_code",
+      code: params.code,
+      redirect_uri: this.config.redirectUri,
+      code_verifier: params.codeVerifier
+    });
+  }
+  /** Rafraîchit un jeton expiré (un `refresh_token` n'est renvoyé que si le serveur en émet pour ce client). */
+  async refreshToken(refreshToken) {
+    return this.postToken({ grant_type: "refresh_token", refresh_token: refreshToken });
+  }
+  /** Révoque un jeton (déconnexion explicite). */
+  async revokeToken(token) {
+    const { response, data } = await this.send("/o/revoke_token/", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: this.clientAuth({ token })
+    });
+    if (!response.ok) throw this.toError(response, data, "Failed to revoke token.");
+  }
+  /** Profil du porteur du jeton (`/o/userinfo/`) — les champs renvoyés dépendent des scopes accordés. */
+  async getUserInfo(accessToken) {
+    const { response, data } = await this.send("/o/userinfo/", {
+      method: "GET",
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    if (!response.ok) throw this.toError(response, data, "Failed to fetch user info.");
+    if (typeof data.sub !== "string" || !data.sub) {
+      throw new SanghoOAuthError("User info response has no `sub` claim.", { code: "invalid_response" });
+    }
+    return data;
+  }
+  // ── interne ────────────────────────────────────────────────────────────────
+  clientAuth(fields) {
+    const body = new URLSearchParams({ ...fields, client_id: this.config.clientId });
+    if (this.config.clientSecret) body.set("client_secret", this.config.clientSecret);
+    return body.toString();
+  }
+  async postToken(fields) {
+    const { response, data } = await this.send("/o/token/", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: this.clientAuth(fields)
+    });
+    if (!response.ok) throw this.toError(response, data, "Token request failed.");
+    if (typeof data.access_token !== "string" || !data.access_token) {
+      throw new SanghoOAuthError("Token response has no `access_token`.", {
+        code: "invalid_response",
+        statusCode: response.status
+      });
+    }
+    return data;
+  }
+  toError(response, data, fallback) {
+    const description = typeof data.error_description === "string" ? data.error_description : void 0;
+    return new SanghoOAuthError(description ?? fallback, {
+      code: typeof data.error === "string" ? data.error : void 0,
+      description,
+      statusCode: response.status
+    });
+  }
+  async send(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const response = await this.config.fetch(`${this.config.baseUrl}${path}`, {
+        ...init,
+        headers: { Accept: "application/json", ...init.headers },
+        redirect: "error",
+        // un endpoint OAuth ne redirige jamais : ne pas suivre (et ne pas renvoyer un secret ailleurs)
+        signal: controller.signal
+      });
+      const parsed = await response.json().catch(() => ({}));
+      const data = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+      return { response, data };
+    } catch (err) {
+      if (err instanceof SanghoOAuthError) throw err;
+      const aborted = err instanceof Error && err.name === "AbortError";
+      throw new SanghoOAuthError(aborted ? "Sangho request timed out." : `Could not reach Sangho: ${err.message}`, {
+        code: aborted ? "timeout" : "network_error"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SanghoOAuthClient,
+  SanghoOAuthError,
+  SanghoOAuthStateMismatchError,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  normalizeBaseUrl
+});

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+/** Portées reconnues par /o/userinfo/ (cf. backend/dash/oauth/claims.py côté Sangho). */
+type SanghoOAuthScope = "profile" | "email";
+interface SanghoOAuthConfig {
+    /** Identifiant du client OAuth (créé dans le tableau de bord Sangho). */
+    clientId: string;
+    /**
+     * Secret du client. Les clients créés dans le tableau de bord Sangho sont CONFIDENTIELS : le secret est obligatoire
+     * pour échanger le code, rafraîchir et révoquer un jeton. À utiliser UNIQUEMENT côté serveur — jamais dans un
+     * navigateur, une application mobile ou un bundle public.
+     */
+    clientSecret?: string;
+    /** URI de redirection, doit correspondre EXACTEMENT à celle enregistrée pour ce client. */
+    redirectUri: string;
+    /** Portées demandées. Par défaut `["profile", "email"]`. */
+    scopes?: SanghoOAuthScope[];
+    /** Hôte du fournisseur OAuth2 Sangho (une base terminée par `/o` est acceptée). Par défaut `https://accounts.sangho.ga`. */
+    baseUrl?: string;
+    /** Délai maximal d'un appel réseau, en millisecondes. Par défaut 10 000. */
+    timeoutMs?: number;
+    /** Implémentation de `fetch` à utiliser (proxy, tests, runtime sans `fetch` global). Par défaut `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+interface AuthorizationRequest {
+    /** URL complète à laquelle rediriger l'utilisateur (`/o/authorize/?...`). */
+    url: string;
+    /** À conserver côté serveur (session, cookie httpOnly signé) le temps de l'aller-retour — jamais dans l'URL de retour. */
+    codeVerifier: string;
+    /** À conserver de la même façon et à comparer avec le `state` du callback (protection CSRF). */
+    state: string;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope: string;
+}
+/** Revendications OIDC-lite de /o/userinfo/ — un champ est absent si le jeton n'a pas la portée correspondante. */
+interface SanghoUserInfo {
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string | null;
+    email?: string;
+    email_verified?: boolean;
+}
+
+/** `https://h/`, `https://h/o` et `https://h/o/` désignent le même hôte : évite les `/o/o/token/`. */
+declare function normalizeBaseUrl(url: string): string;
+declare class SanghoOAuthClient {
+    private readonly config;
+    constructor(config: SanghoOAuthConfig);
+    /**
+     * Construit l'URL d'autorisation (`/o/authorize/`) et génère le couple PKCE + `state`.
+     * L'appelant DOIT persister `codeVerifier` et `state` (session serveur, ou cookie httpOnly signé) le temps de
+     * l'aller-retour, puis les repasser à `exchangeCode`.
+     */
+    createAuthorizationRequest(): Promise<AuthorizationRequest>;
+    /**
+     * Vérifie le `state` renvoyé par le callback puis échange le `code` contre des jetons (`/o/token/`).
+     * Lève `SanghoOAuthStateMismatchError` avant tout appel réseau si les `state` ne correspondent pas (protection CSRF).
+     */
+    exchangeCode(params: {
+        code: string;
+        codeVerifier: string;
+        receivedState: string;
+        expectedState: string;
+    }): Promise<TokenResponse>;
+    /** Rafraîchit un jeton expiré (un `refresh_token` n'est renvoyé que si le serveur en émet pour ce client). */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /** Révoque un jeton (déconnexion explicite). */
+    revokeToken(token: string): Promise<void>;
+    /** Profil du porteur du jeton (`/o/userinfo/`) — les champs renvoyés dépendent des scopes accordés. */
+    getUserInfo(accessToken: string): Promise<SanghoUserInfo>;
+    private clientAuth;
+    private postToken;
+    private toError;
+    private send;
+}
+
+/** Génère un `code_verifier` aléatoire (43-128 caractères, alphabet non-réservé RFC 7636 §4.1). */
+declare function generateCodeVerifier(): string;
+/** Dérive le `code_challenge` (méthode S256, seule acceptée par le serveur OAuth2 de Sangho). */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/** État anti-CSRF (OAuth2 `state`) — même génération que le code_verifier, usage différent. */
+declare function generateState(): string;
+
+declare class SanghoOAuthError extends Error {
+    /** Code renvoyé par le endpoint token/userinfo (`error`), ex: "invalid_grant", "invalid_client". */
+    readonly code?: string;
+    readonly description?: string;
+    readonly statusCode?: number;
+    constructor(message: string, options?: {
+        code?: string;
+        description?: string;
+        statusCode?: number;
+    });
+}
+/** `state` renvoyé par le callback ne correspond pas à celui émis à l'aller — signe possible de CSRF. */
+declare class SanghoOAuthStateMismatchError extends SanghoOAuthError {
+    constructor();
+}
+
+export { type AuthorizationRequest, SanghoOAuthClient, type SanghoOAuthConfig, SanghoOAuthError, type SanghoOAuthScope, SanghoOAuthStateMismatchError, type SanghoUserInfo, type TokenResponse, generateCodeChallenge, generateCodeVerifier, generateState, normalizeBaseUrl };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/** Portées reconnues par /o/userinfo/ (cf. backend/dash/oauth/claims.py côté Sangho). */
+type SanghoOAuthScope = "profile" | "email";
+interface SanghoOAuthConfig {
+    /** Identifiant du client OAuth (créé dans le tableau de bord Sangho). */
+    clientId: string;
+    /**
+     * Secret du client. Les clients créés dans le tableau de bord Sangho sont CONFIDENTIELS : le secret est obligatoire
+     * pour échanger le code, rafraîchir et révoquer un jeton. À utiliser UNIQUEMENT côté serveur — jamais dans un
+     * navigateur, une application mobile ou un bundle public.
+     */
+    clientSecret?: string;
+    /** URI de redirection, doit correspondre EXACTEMENT à celle enregistrée pour ce client. */
+    redirectUri: string;
+    /** Portées demandées. Par défaut `["profile", "email"]`. */
+    scopes?: SanghoOAuthScope[];
+    /** Hôte du fournisseur OAuth2 Sangho (une base terminée par `/o` est acceptée). Par défaut `https://accounts.sangho.ga`. */
+    baseUrl?: string;
+    /** Délai maximal d'un appel réseau, en millisecondes. Par défaut 10 000. */
+    timeoutMs?: number;
+    /** Implémentation de `fetch` à utiliser (proxy, tests, runtime sans `fetch` global). Par défaut `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+interface AuthorizationRequest {
+    /** URL complète à laquelle rediriger l'utilisateur (`/o/authorize/?...`). */
+    url: string;
+    /** À conserver côté serveur (session, cookie httpOnly signé) le temps de l'aller-retour — jamais dans l'URL de retour. */
+    codeVerifier: string;
+    /** À conserver de la même façon et à comparer avec le `state` du callback (protection CSRF). */
+    state: string;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope: string;
+}
+/** Revendications OIDC-lite de /o/userinfo/ — un champ est absent si le jeton n'a pas la portée correspondante. */
+interface SanghoUserInfo {
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string | null;
+    email?: string;
+    email_verified?: boolean;
+}
+
+/** `https://h/`, `https://h/o` et `https://h/o/` désignent le même hôte : évite les `/o/o/token/`. */
+declare function normalizeBaseUrl(url: string): string;
+declare class SanghoOAuthClient {
+    private readonly config;
+    constructor(config: SanghoOAuthConfig);
+    /**
+     * Construit l'URL d'autorisation (`/o/authorize/`) et génère le couple PKCE + `state`.
+     * L'appelant DOIT persister `codeVerifier` et `state` (session serveur, ou cookie httpOnly signé) le temps de
+     * l'aller-retour, puis les repasser à `exchangeCode`.
+     */
+    createAuthorizationRequest(): Promise<AuthorizationRequest>;
+    /**
+     * Vérifie le `state` renvoyé par le callback puis échange le `code` contre des jetons (`/o/token/`).
+     * Lève `SanghoOAuthStateMismatchError` avant tout appel réseau si les `state` ne correspondent pas (protection CSRF).
+     */
+    exchangeCode(params: {
+        code: string;
+        codeVerifier: string;
+        receivedState: string;
+        expectedState: string;
+    }): Promise<TokenResponse>;
+    /** Rafraîchit un jeton expiré (un `refresh_token` n'est renvoyé que si le serveur en émet pour ce client). */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /** Révoque un jeton (déconnexion explicite). */
+    revokeToken(token: string): Promise<void>;
+    /** Profil du porteur du jeton (`/o/userinfo/`) — les champs renvoyés dépendent des scopes accordés. */
+    getUserInfo(accessToken: string): Promise<SanghoUserInfo>;
+    private clientAuth;
+    private postToken;
+    private toError;
+    private send;
+}
+
+/** Génère un `code_verifier` aléatoire (43-128 caractères, alphabet non-réservé RFC 7636 §4.1). */
+declare function generateCodeVerifier(): string;
+/** Dérive le `code_challenge` (méthode S256, seule acceptée par le serveur OAuth2 de Sangho). */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/** État anti-CSRF (OAuth2 `state`) — même génération que le code_verifier, usage différent. */
+declare function generateState(): string;
+
+declare class SanghoOAuthError extends Error {
+    /** Code renvoyé par le endpoint token/userinfo (`error`), ex: "invalid_grant", "invalid_client". */
+    readonly code?: string;
+    readonly description?: string;
+    readonly statusCode?: number;
+    constructor(message: string, options?: {
+        code?: string;
+        description?: string;
+        statusCode?: number;
+    });
+}
+/** `state` renvoyé par le callback ne correspond pas à celui émis à l'aller — signe possible de CSRF. */
+declare class SanghoOAuthStateMismatchError extends SanghoOAuthError {
+    constructor();
+}
+
+export { type AuthorizationRequest, SanghoOAuthClient, type SanghoOAuthConfig, SanghoOAuthError, type SanghoOAuthScope, SanghoOAuthStateMismatchError, type SanghoUserInfo, type TokenResponse, generateCodeChallenge, generateCodeVerifier, generateState, normalizeBaseUrl };

package/dist/index.js

@@ -0,0 +1,202 @@
+// src/pkce.ts
+function getCrypto() {
+  const c = globalThis.crypto;
+  if (!c || !c.subtle) {
+    throw new Error(
+      "Web Crypto API indisponible (globalThis.crypto.subtle). Node >= 20 ou un navigateur moderne sont requis."
+    );
+  }
+  return c;
+}
+function base64UrlEncode(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const b of arr) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(32);
+  getCrypto().getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function generateCodeChallenge(verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await getCrypto().subtle.digest("SHA-256", data);
+  return base64UrlEncode(digest);
+}
+function generateState() {
+  return generateCodeVerifier();
+}
+
+// src/errors.ts
+var SanghoOAuthError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "SanghoOAuthError";
+    this.code = options?.code;
+    this.description = options?.description;
+    this.statusCode = options?.statusCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var SanghoOAuthStateMismatchError = class extends SanghoOAuthError {
+  constructor() {
+    super("The `state` parameter does not match the one issued for this authorization request.", {
+      code: "state_mismatch"
+    });
+    this.name = "SanghoOAuthStateMismatchError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://accounts.sangho.ga";
+var DEFAULT_SCOPES = ["profile", "email"];
+var DEFAULT_TIMEOUT_MS = 1e4;
+function normalizeBaseUrl(url) {
+  return url.trim().replace(/\/+$/, "").replace(/\/o$/, "").replace(/\/+$/, "");
+}
+function sameSecret(a, b) {
+  if (!a || !b || a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var SanghoOAuthClient = class {
+  constructor(config) {
+    if (!config.clientId) throw new SanghoOAuthError("`clientId` is required.");
+    if (!config.redirectUri) throw new SanghoOAuthError("`redirectUri` is required.");
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (!fetchImpl) throw new SanghoOAuthError("No `fetch` implementation available (Node >= 20 or pass `fetch`).");
+    this.config = {
+      clientId: config.clientId,
+      clientSecret: config.clientSecret || void 0,
+      redirectUri: config.redirectUri,
+      baseUrl: normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL),
+      scopes: config.scopes ? [...config.scopes] : [...DEFAULT_SCOPES],
+      timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetch: fetchImpl.bind(globalThis)
+    };
+  }
+  /**
+   * Construit l'URL d'autorisation (`/o/authorize/`) et génère le couple PKCE + `state`.
+   * L'appelant DOIT persister `codeVerifier` et `state` (session serveur, ou cookie httpOnly signé) le temps de
+   * l'aller-retour, puis les repasser à `exchangeCode`.
+   */
+  async createAuthorizationRequest() {
+    const codeVerifier = generateCodeVerifier();
+    const state = generateState();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scopes.join(" "),
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
+    });
+    return { url: `${this.config.baseUrl}/o/authorize/?${params.toString()}`, codeVerifier, state };
+  }
+  /**
+   * Vérifie le `state` renvoyé par le callback puis échange le `code` contre des jetons (`/o/token/`).
+   * Lève `SanghoOAuthStateMismatchError` avant tout appel réseau si les `state` ne correspondent pas (protection CSRF).
+   */
+  async exchangeCode(params) {
+    if (!sameSecret(params.receivedState, params.expectedState)) {
+      throw new SanghoOAuthStateMismatchError();
+    }
+    return this.postToken({
+      grant_type: "authorization_code",
+      code: params.code,
+      redirect_uri: this.config.redirectUri,
+      code_verifier: params.codeVerifier
+    });
+  }
+  /** Rafraîchit un jeton expiré (un `refresh_token` n'est renvoyé que si le serveur en émet pour ce client). */
+  async refreshToken(refreshToken) {
+    return this.postToken({ grant_type: "refresh_token", refresh_token: refreshToken });
+  }
+  /** Révoque un jeton (déconnexion explicite). */
+  async revokeToken(token) {
+    const { response, data } = await this.send("/o/revoke_token/", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: this.clientAuth({ token })
+    });
+    if (!response.ok) throw this.toError(response, data, "Failed to revoke token.");
+  }
+  /** Profil du porteur du jeton (`/o/userinfo/`) — les champs renvoyés dépendent des scopes accordés. */
+  async getUserInfo(accessToken) {
+    const { response, data } = await this.send("/o/userinfo/", {
+      method: "GET",
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    if (!response.ok) throw this.toError(response, data, "Failed to fetch user info.");
+    if (typeof data.sub !== "string" || !data.sub) {
+      throw new SanghoOAuthError("User info response has no `sub` claim.", { code: "invalid_response" });
+    }
+    return data;
+  }
+  // ── interne ────────────────────────────────────────────────────────────────
+  clientAuth(fields) {
+    const body = new URLSearchParams({ ...fields, client_id: this.config.clientId });
+    if (this.config.clientSecret) body.set("client_secret", this.config.clientSecret);
+    return body.toString();
+  }
+  async postToken(fields) {
+    const { response, data } = await this.send("/o/token/", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: this.clientAuth(fields)
+    });
+    if (!response.ok) throw this.toError(response, data, "Token request failed.");
+    if (typeof data.access_token !== "string" || !data.access_token) {
+      throw new SanghoOAuthError("Token response has no `access_token`.", {
+        code: "invalid_response",
+        statusCode: response.status
+      });
+    }
+    return data;
+  }
+  toError(response, data, fallback) {
+    const description = typeof data.error_description === "string" ? data.error_description : void 0;
+    return new SanghoOAuthError(description ?? fallback, {
+      code: typeof data.error === "string" ? data.error : void 0,
+      description,
+      statusCode: response.status
+    });
+  }
+  async send(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const response = await this.config.fetch(`${this.config.baseUrl}${path}`, {
+        ...init,
+        headers: { Accept: "application/json", ...init.headers },
+        redirect: "error",
+        // un endpoint OAuth ne redirige jamais : ne pas suivre (et ne pas renvoyer un secret ailleurs)
+        signal: controller.signal
+      });
+      const parsed = await response.json().catch(() => ({}));
+      const data = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+      return { response, data };
+    } catch (err) {
+      if (err instanceof SanghoOAuthError) throw err;
+      const aborted = err instanceof Error && err.name === "AbortError";
+      throw new SanghoOAuthError(aborted ? "Sangho request timed out." : `Could not reach Sangho: ${err.message}`, {
+        code: aborted ? "timeout" : "network_error"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+export {
+  SanghoOAuthClient,
+  SanghoOAuthError,
+  SanghoOAuthStateMismatchError,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  normalizeBaseUrl
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sanghosdk/oauth",
+  "version": "0.2.0",
+  "description": "Se connecter avec Sangho — client OAuth2/PKCE (Authorization Code + PKCE), séparé du SDK de paiement.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axon-libs/sangho-oauth-js.git"
+  },
+  "keywords": [
+    "sangho",
+    "oauth2",
+    "pkce",
+    "login"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}