@mostajs/auth 2.5.2 → 3.1.0

package/dist/lib/mfa-totp.d.ts

@@ -0,0 +1,154 @@
+export type MfaFactorKind = 'totp';
+export interface MfaFactorRecord {
+    /** PK opaque. */
+    id: string;
+    /** User propriétaire — clé d'isolation. */
+    userId: string;
+    kind: MfaFactorKind;
+    /** Label utilisateur (ex: "iPhone 15", "Authy 2026"). */
+    label: string;
+    /**
+     * Secret TOTP en base32 — utilisé pour générer les codes côté authentificator.
+     *
+     * v2.9.0 : stocké en clair (`secretEncrypted: false` ou champ absent).
+     * v2.9.1 : peut être chiffré at-rest si `SecretEncrypter` fourni au boot
+     * (`secretEncrypted: true`). Le module appelle transparentement encrypt/decrypt.
+     * Cohabitation : un record v2.9.0 sans flag est lu en clair, un record v2.9.1
+     * est déchiffré au verify.
+     */
+    secret: string;
+    /** v2.9.1+ : true si `secret` est chiffré via SecretEncrypter. Default: false (legacy). */
+    secretEncrypted?: boolean;
+    /**
+     * 10 backup codes hashés argon2id. Chaque entrée :
+     *   `null`  = code consommé (one-shot)
+     *   string  = hash argon2 du code en clair
+     * On garde la longueur 10 stable pour l'audit ("3 backup codes restants").
+     */
+    backupCodesHashed: (string | null)[];
+    /** `false` jusqu'à ce que l'user confirme un premier code → flip à `true`. */
+    enabled: boolean;
+    createdAt: Date | string;
+    /** Timestamp dernière vérification réussie (TOTP ou backup code). */
+    lastUsedAt?: Date | string | null;
+}
+/**
+ * v2.9.1+ — DI optionnelle pour chiffrer le secret TOTP at-rest.
+ *
+ * Le module ne ship PAS d'implémentation : c'est au host de fournir une stratégie
+ * (AWS KMS / GCP KMS / clé locale issue de @mostajs/config / HashiCorp Vault).
+ * Si non fourni, secrets stockés en clair (comportement v2.9.0 préservé).
+ *
+ * Contrat : encrypt → decrypt(encrypt(s)) === s. Idempotent. Constant-time recommandé.
+ */
+export interface SecretEncrypter {
+    /** Chiffre une valeur clair en string base64/hex (forme stockable en `string` DB). */
+    encrypt(plaintext: string): Promise<string>;
+    /** Déchiffre — throw si tampering / mauvaise clé. */
+    decrypt(ciphertext: string): Promise<string>;
+}
+export interface MfaFactorRepo {
+    insert(record: Omit<MfaFactorRecord, 'id'>): Promise<MfaFactorRecord>;
+    findById(id: string): Promise<MfaFactorRecord | null>;
+    /** Liste tous les factors d'un user (TOTP + futurs WebAuthn). */
+    findAllByUser(userId: string): Promise<MfaFactorRecord[]>;
+    /** Le premier factor TOTP enabled d'un user, ou null. */
+    findActiveTotp(userId: string): Promise<MfaFactorRecord | null>;
+    /** Marque le factor enabled (post-confirmation). */
+    setEnabled(id: string, enabled: boolean): Promise<void>;
+    /** Met à jour les backup codes (after consume) + lastUsedAt. */
+    updateAfterUse(id: string, args: {
+        backupCodesHashed: (string | null)[];
+        lastUsedAt: Date;
+    }): Promise<void>;
+    /** Supprime un factor (disable totp / passkey deletion). */
+    delete(id: string): Promise<void>;
+}
+/** Génère 10 backup codes alphanum en clair — à montrer UNE FOIS à l'user. */
+export declare function generateBackupCodes(): string[];
+/** Hash argon2 chacun des codes — pour persistance one-shot. */
+export declare function hashBackupCodes(codes: string[]): Promise<string[]>;
+/** Normalise (uppercase, trim, retire espaces et dashes) avant hash/verify. */
+declare function normalizeBackupCode(input: string): string;
+export interface EnrollOptions {
+    userId: string;
+    /** Email/login de l'user — affiché dans l'authenticator app. */
+    accountName: string;
+    /** Nom du service — affiché dans l'authenticator app (ex: "Octonet"). */
+    issuer: string;
+    /** Label libre du factor (par défaut : `${issuer} — ${accountName}`). */
+    label?: string;
+    /** v2.9.1+ — si fourni, le secret est chiffré at-rest avant persistance. */
+    encrypter?: SecretEncrypter;
+}
+export interface EnrollResult {
+    /** Record persisté avec `enabled: false` — sera flip après verifyEnrollmentCode. */
+    factor: MfaFactorRecord;
+    /** Secret base32 (à montrer en fallback si QR non scannable). */
+    secret: string;
+    /** URL otpauth:// pour le QR code (RFC otpauth). */
+    otpAuthUrl: string;
+    /** Data-URL PNG du QR code (à afficher directement <img src=...>). */
+    qrCodeDataUrl: string;
+    /** Backup codes en clair — à montrer UNE FOIS à l'user, jamais ré-affichés. */
+    backupCodes: string[];
+}
+/**
+ * Démarre l'enrollment :
+ *   1. génère secret + backup codes
+ *   2. produit le QR code
+ *   3. persiste un MfaFactorRecord avec `enabled: false`
+ * L'user doit ensuite scanner le QR + valider un code via `verifyEnrollmentCode`
+ * pour que le factor soit `enabled = true`.
+ */
+export declare function enrollTotp(repo: MfaFactorRepo, opts: EnrollOptions): Promise<EnrollResult>;
+/**
+ * Confirme l'enrollment : l'user a scanné le QR + saisi un code TOTP courant.
+ * Si OK, le factor passe `enabled = true`.
+ */
+export declare function verifyEnrollmentCode(repo: MfaFactorRepo, args: {
+    factorId: string;
+    code: string;
+    encrypter?: SecretEncrypter;
+}): Promise<{
+    ok: boolean;
+    reason?: 'not_found' | 'already_enabled' | 'wrong_code';
+}>;
+export type VerifyResult = {
+    ok: true;
+    method: 'totp' | 'backup_code';
+    remainingBackupCodes: number;
+} | {
+    ok: false;
+    reason: 'no_factor' | 'wrong_code' | 'no_backup_codes_left';
+};
+/**
+ * Vérifie un code TOTP OU un backup code.
+ * Le caller est responsable du rate-limit en amont (cf. lib/auth-rate-limit.ts).
+ */
+export declare function verifyMfaCode(repo: MfaFactorRepo, args: {
+    userId: string;
+    code: string;
+    encrypter?: SecretEncrypter;
+}): Promise<VerifyResult>;
+/**
+ * Désactive le TOTP d'un user. Le caller DOIT exiger une preuve fraîche d'identité
+ * (password ré-entré + code TOTP courant OU backup code) AVANT d'appeler cette
+ * fonction — ce module ne re-vérifie pas, il fait juste la suppression.
+ */
+export declare function disableTotp(repo: MfaFactorRepo, args: {
+    userId: string;
+}): Promise<{
+    deletedFactorIds: string[];
+}>;
+export interface MfaStatus {
+    totpEnrolled: boolean;
+    totpEnabled: boolean;
+    remainingBackupCodes: number;
+}
+/** Pour l'UI compte / settings. */
+export declare function getMfaStatus(repo: MfaFactorRepo, userId: string): Promise<MfaStatus>;
+export declare const __testing: {
+    normalizeBackupCode: typeof normalizeBackupCode;
+};
+export {};

package/dist/lib/mfa-totp.js

@@ -0,0 +1,193 @@
+// @mostajs/auth — MFA TOTP (RFC 6238) — Lot 4 / v2.9.0+
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// TOTP (Time-based One-Time Password, RFC 6238) — second factor compatible
+// Google Authenticator / 1Password / Authy / Bitwarden / Microsoft Authenticator.
+//
+// Design clé :
+//   - Le secret TOTP (base32) est généré côté serveur, jamais transmis en clair
+//     deux fois — le QR code data-URL est émis UNE FOIS à l'enroll, puis perdu.
+//   - L'app cliente scanne le QR + entre un premier code TOTP pour confirmer
+//     que la lecture s'est bien faite (`verifyEnrollmentCode`) avant que le
+//     factor soit marqué `enabled` côté serveur.
+//   - Backup codes : 10 codes one-shot de 8 chars, hashés (argon2 — réutilise
+//     `lib/password.ts`), persistés dans le record. Marqués `consumed` à l'usage.
+//   - Storage agnostique : le consumer fournit `MfaFactorRepo` (DI).
+//
+// Stockage :
+//   - secret en clair dans `MfaFactorRecord.secret` — c'est un compromis
+//     standard (Supabase, Auth0 font pareil) ; chiffrement at-rest = job du DBA.
+//     Si la DB est compromise, MFA TOTP ne protège plus rien de toute façon.
+//
+// Rate-limit : à appliquer côté consumer via `lib/auth-rate-limit.ts` sur le
+// endpoint /verify (max 5 tentatives/15min/userId). On ne ré-implémente pas ici.
+import crypto from 'node:crypto';
+import { authenticator } from 'otplib';
+import { toDataURL as qrToDataURL } from 'qrcode';
+import { hashPassword, comparePassword } from './password.js';
+// ─── otplib config — RFC 6238 défauts ───────────────────────────────────
+authenticator.options = {
+    digits: 6,
+    step: 30, // 30 secondes par fenêtre TOTP
+    window: 1, // accepte la fenêtre courante ± 1 (= ± 30s) pour drift d'horloge
+    // sha1 = RFC 6238 baseline + Google Authenticator support (default otplib).
+};
+// ─── Backup codes ───────────────────────────────────────────────────────
+const BACKUP_CODE_LENGTH = 8;
+const BACKUP_CODES_COUNT = 10;
+/** Génère 10 backup codes alphanum en clair — à montrer UNE FOIS à l'user. */
+export function generateBackupCodes() {
+    return Array.from({ length: BACKUP_CODES_COUNT }, () => generateOneBackupCode());
+}
+function generateOneBackupCode() {
+    // Alphanum sans ambiguïté (pas de O/0, I/1) — UX scan papier.
+    const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+    const bytes = crypto.randomBytes(BACKUP_CODE_LENGTH);
+    let code = '';
+    for (let i = 0; i < BACKUP_CODE_LENGTH; i++) {
+        code += alphabet[bytes[i] % alphabet.length];
+    }
+    // Format groupé : "XXXX-XXXX"
+    return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+/** Hash argon2 chacun des codes — pour persistance one-shot. */
+export async function hashBackupCodes(codes) {
+    return Promise.all(codes.map((c) => hashPassword(normalizeBackupCode(c))));
+}
+/** Normalise (uppercase, trim, retire espaces et dashes) avant hash/verify. */
+function normalizeBackupCode(input) {
+    return input.trim().toUpperCase().replace(/[\s-]+/g, '');
+}
+/**
+ * Démarre l'enrollment :
+ *   1. génère secret + backup codes
+ *   2. produit le QR code
+ *   3. persiste un MfaFactorRecord avec `enabled: false`
+ * L'user doit ensuite scanner le QR + valider un code via `verifyEnrollmentCode`
+ * pour que le factor soit `enabled = true`.
+ */
+export async function enrollTotp(repo, opts) {
+    const secretClear = authenticator.generateSecret();
+    const otpAuthUrl = authenticator.keyuri(opts.accountName, opts.issuer, secretClear);
+    const qrCodeDataUrl = await qrToDataURL(otpAuthUrl, { errorCorrectionLevel: 'M', margin: 1 });
+    const backupCodes = generateBackupCodes();
+    const backupCodesHashed = await hashBackupCodes(backupCodes);
+    // v2.9.1+ : si encrypter fourni, le secret persisté est chiffré ; le secret
+    // retourné dans EnrollResult reste en clair (utilisé pour QR + saisie manuelle).
+    const secretToStore = opts.encrypter
+        ? await opts.encrypter.encrypt(secretClear)
+        : secretClear;
+    const factor = await repo.insert({
+        userId: opts.userId,
+        kind: 'totp',
+        label: opts.label ?? `${opts.issuer} — ${opts.accountName}`,
+        secret: secretToStore,
+        secretEncrypted: !!opts.encrypter,
+        backupCodesHashed,
+        enabled: false,
+        createdAt: new Date(),
+        lastUsedAt: null,
+    });
+    // Le factor retourné conserve le secret tel que stocké (chiffré le cas échéant) ;
+    // on retourne le secretClear séparément.
+    return { factor, secret: secretClear, otpAuthUrl, qrCodeDataUrl, backupCodes };
+}
+/**
+ * Helper interne : déchiffre le secret d'un record selon son flag `secretEncrypted`.
+ * Cohabitation v2.9.0 (clear) ↔ v2.9.1 (encrypted).
+ */
+async function readClearSecret(factor, encrypter) {
+    if (!factor.secretEncrypted)
+        return factor.secret;
+    if (!encrypter) {
+        throw new Error('mfa-totp: factor secret is encrypted but no SecretEncrypter provided to verify call');
+    }
+    return encrypter.decrypt(factor.secret);
+}
+/**
+ * Confirme l'enrollment : l'user a scanné le QR + saisi un code TOTP courant.
+ * Si OK, le factor passe `enabled = true`.
+ */
+export async function verifyEnrollmentCode(repo, args) {
+    const factor = await repo.findById(args.factorId);
+    if (!factor)
+        return { ok: false, reason: 'not_found' };
+    if (factor.enabled)
+        return { ok: false, reason: 'already_enabled' };
+    const secretClear = await readClearSecret(factor, args.encrypter);
+    const valid = authenticator.verify({ token: args.code.replace(/\s/g, ''), secret: secretClear });
+    if (!valid)
+        return { ok: false, reason: 'wrong_code' };
+    await repo.setEnabled(factor.id, true);
+    return { ok: true };
+}
+/**
+ * Vérifie un code TOTP OU un backup code.
+ * Le caller est responsable du rate-limit en amont (cf. lib/auth-rate-limit.ts).
+ */
+export async function verifyMfaCode(repo, args) {
+    const factor = await repo.findActiveTotp(args.userId);
+    if (!factor)
+        return { ok: false, reason: 'no_factor' };
+    // 1) Tente d'abord TOTP courant.
+    const totpClean = args.code.replace(/\s/g, '');
+    if (totpClean.length === 6 && /^\d+$/.test(totpClean)) {
+        const secretClear = await readClearSecret(factor, args.encrypter);
+        const valid = authenticator.verify({ token: totpClean, secret: secretClear });
+        if (valid) {
+            await repo.updateAfterUse(factor.id, {
+                backupCodesHashed: factor.backupCodesHashed,
+                lastUsedAt: new Date(),
+            });
+            const remaining = factor.backupCodesHashed.filter((h) => h !== null).length;
+            return { ok: true, method: 'totp', remainingBackupCodes: remaining };
+        }
+    }
+    // 2) Sinon tente backup code (un par un, hash à hash — argon2 = constant-time).
+    const normalized = normalizeBackupCode(args.code);
+    for (let i = 0; i < factor.backupCodesHashed.length; i++) {
+        const hashed = factor.backupCodesHashed[i];
+        if (hashed === null)
+            continue; // déjà consommé
+        if (await comparePassword(normalized, hashed)) {
+            const updated = [...factor.backupCodesHashed];
+            updated[i] = null;
+            await repo.updateAfterUse(factor.id, { backupCodesHashed: updated, lastUsedAt: new Date() });
+            const remaining = updated.filter((h) => h !== null).length;
+            return { ok: true, method: 'backup_code', remainingBackupCodes: remaining };
+        }
+    }
+    return { ok: false, reason: 'wrong_code' };
+}
+// ─── Disable ────────────────────────────────────────────────────────────
+/**
+ * Désactive le TOTP d'un user. Le caller DOIT exiger une preuve fraîche d'identité
+ * (password ré-entré + code TOTP courant OU backup code) AVANT d'appeler cette
+ * fonction — ce module ne re-vérifie pas, il fait juste la suppression.
+ */
+export async function disableTotp(repo, args) {
+    const factors = await repo.findAllByUser(args.userId);
+    const totps = factors.filter((f) => f.kind === 'totp');
+    await Promise.all(totps.map((f) => repo.delete(f.id)));
+    return { deletedFactorIds: totps.map((f) => f.id) };
+}
+/** Pour l'UI compte / settings. */
+export async function getMfaStatus(repo, userId) {
+    const factor = await repo.findActiveTotp(userId);
+    if (!factor) {
+        const all = await repo.findAllByUser(userId);
+        const pending = all.find((f) => f.kind === 'totp' && !f.enabled);
+        return {
+            totpEnrolled: !!pending,
+            totpEnabled: false,
+            remainingBackupCodes: 0,
+        };
+    }
+    return {
+        totpEnrolled: true,
+        totpEnabled: true,
+        remainingBackupCodes: factor.backupCodesHashed.filter((h) => h !== null).length,
+    };
+}
+// Test-only helper — exporté pour les tests internes du module.
+export const __testing = { normalizeBackupCode };

package/dist/lib/oauth-linking.d.ts

@@ -0,0 +1,69 @@
+import type { ExchangeResult } from './oauth-providers.js';
+export interface OAuthAccountRecord {
+    id: string;
+    userId: string;
+    provider: string;
+    providerId: string;
+    email?: string | null;
+    /** Stocké chiffré côté consumer si on souhaite réutiliser le token (refresh des feeds). */
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    scope?: string | null;
+    linkedAt: Date | string;
+}
+export interface UserLite {
+    id: string;
+    email?: string | null;
+}
+export interface OAuthLinkingRepo {
+    /** Lookup par (provider, providerId) — l'identité de la liaison. */
+    findByProviderAndProviderId(provider: string, providerId: string): Promise<OAuthAccountRecord | null>;
+    /** Toutes les liaisons d'un user (pour /account/security UI). */
+    findByUserId(userId: string): Promise<OAuthAccountRecord[]>;
+    insert(record: Omit<OAuthAccountRecord, 'id'>): Promise<OAuthAccountRecord>;
+    delete(id: string): Promise<void>;
+}
+export interface UserRepo {
+    findByEmail(email: string): Promise<UserLite | null>;
+}
+export interface ResolveLoginConfig {
+    oauthRepo: OAuthLinkingRepo;
+    userRepo: UserRepo;
+    provider: string;
+}
+export type ResolveLoginResult = {
+    kind: 'existing_link';
+    userId: string;
+    oauthAccount: OAuthAccountRecord;
+} | {
+    kind: 'requires_link_confirmation';
+    existingUserId: string;
+    existingEmail: string;
+    profile: ExchangeResult;
+} | {
+    kind: 'create_new';
+    profile: ExchangeResult;
+};
+/**
+ * Décide quoi faire après l'`exchangeCodeForUser`. Ne touche PAS la base utilisateur —
+ * retourne une décision que le consumer applique (créer user, demander confirmation, etc.).
+ */
+export declare function resolveOAuthLogin(config: ResolveLoginConfig, profile: ExchangeResult): Promise<ResolveLoginResult>;
+/**
+ * Crée la liaison OAuth pour un user EXISTANT (déjà authentifié OU dont l'identité
+ * vient d'être confirmée par la confirmation flow). À appeler AUSSI après création d'un
+ * user nouveau (cas `create_new`).
+ */
+export declare function linkOAuthAccount(config: {
+    oauthRepo: OAuthLinkingRepo;
+    provider: string;
+}, args: {
+    userId: string;
+    profile: ExchangeResult;
+    /** Si false (défaut), refuse de créer un doublon (provider, providerId). */
+    allowDuplicate?: boolean;
+}): Promise<OAuthAccountRecord>;
+/** Délier un compte OAuth. Le consumer doit s'assurer qu'il reste au moins un moyen de login (password, autre OAuth, passkey). */
+export declare function unlinkOAuthAccount(config: {
+    oauthRepo: OAuthLinkingRepo;
+}, oauthAccountId: string): Promise<void>;

package/dist/lib/oauth-linking.js

@@ -0,0 +1,70 @@
+// @mostajs/auth — OAuth account linking (v2.7.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Décide quoi faire après un OAuth callback réussi (cf. exchangeCodeForUser) :
+//   1. Si (provider, providerId) déjà lié → log in as that user.
+//   2. Si pas lié, MAIS l'email matche un user existant → REQUIRES_LINK_CONFIRMATION.
+//      ⚠️ Ne JAMAIS lier silencieusement (CVE-class issue, cf. Slack 2020) :
+//      un attaquant pourrait créer un compte Google avec l'email d'une victime,
+//      passer le flow OAuth, et se voir attribué le compte existant si linkage auto.
+//      → Demander confirmation explicite (re-login password / confirm email).
+//   3. Si rien ne matche → créer un user + lier.
+//
+// Le module ne crée PAS le user lui-même : il retourne une décision typée que le
+// consumer (Octonet) traduit en action (création account via @mostajs/orm + audit event).
+/**
+ * Décide quoi faire après l'`exchangeCodeForUser`. Ne touche PAS la base utilisateur —
+ * retourne une décision que le consumer applique (créer user, demander confirmation, etc.).
+ */
+export async function resolveOAuthLogin(config, profile) {
+    // 1. Liaison déjà existante ? Login direct.
+    const existingLink = await config.oauthRepo.findByProviderAndProviderId(config.provider, profile.providerId);
+    if (existingLink) {
+        return { kind: 'existing_link', userId: existingLink.userId, oauthAccount: existingLink };
+    }
+    // 2. Email connu mais pas encore lié ? Demander confirmation, NE PAS lier auto.
+    if (profile.email) {
+        const existingUser = await config.userRepo.findByEmail(profile.email);
+        if (existingUser) {
+            return {
+                kind: 'requires_link_confirmation',
+                existingUserId: existingUser.id,
+                existingEmail: profile.email,
+                profile,
+            };
+        }
+    }
+    // 3. Nouveau user à créer (le consumer s'en charge + appellera linkOAuthAccount ensuite).
+    return { kind: 'create_new', profile };
+}
+/**
+ * Crée la liaison OAuth pour un user EXISTANT (déjà authentifié OU dont l'identité
+ * vient d'être confirmée par la confirmation flow). À appeler AUSSI après création d'un
+ * user nouveau (cas `create_new`).
+ */
+export async function linkOAuthAccount(config, args) {
+    if (!args.allowDuplicate) {
+        const existing = await config.oauthRepo.findByProviderAndProviderId(config.provider, args.profile.providerId);
+        if (existing && existing.userId !== args.userId) {
+            throw new Error(`OAuth account already linked to a different user (provider=${config.provider}, providerId=${args.profile.providerId})`);
+        }
+        if (existing && existing.userId === args.userId) {
+            // Idempotent : déjà lié au bon user.
+            return existing;
+        }
+    }
+    return config.oauthRepo.insert({
+        userId: args.userId,
+        provider: config.provider,
+        providerId: args.profile.providerId,
+        email: args.profile.email ?? null,
+        accessToken: args.profile.accessToken ?? null,
+        refreshToken: args.profile.refreshToken ?? null,
+        scope: args.profile.scope ?? null,
+        linkedAt: new Date(),
+    });
+}
+/** Délier un compte OAuth. Le consumer doit s'assurer qu'il reste au moins un moyen de login (password, autre OAuth, passkey). */
+export async function unlinkOAuthAccount(config, oauthAccountId) {
+    await config.oauthRepo.delete(oauthAccountId);
+}

package/dist/lib/oauth-primitives.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Génère un `code_verifier` 64 chars base64url (= 384 bits d'entropie).
+ *
+ * RFC 7636 §4.1 :
+ *   code_verifier = high-entropy cryptographic random STRING
+ *   ALPHA / DIGIT / "-" / "." / "_" / "~"  (= base64url unpadded sans `=`)
+ *   minLen 43, maxLen 128
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Dérive le `code_challenge` à partir du verifier — méthode S256.
+ *
+ * RFC 7636 §4.2 :
+ *   code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
+ *
+ * La méthode `plain` est volontairement non-supportée (RFC 7636 §7.2 — interdite
+ * en production 2025).
+ */
+export declare function deriveCodeChallenge(verifier: string): string;
+/**
+ * Génère un `state` cryptographiquement aléatoire — 24 bytes = 192 bits.
+ *
+ * RFC 6749 §10.12 :
+ *   The state parameter SHOULD be used to prevent CSRF attacks. The value should
+ *   be unguessable.
+ */
+export declare function generateState(): string;

package/dist/lib/oauth-primitives.js

@@ -0,0 +1,46 @@
+// @mostajs/auth — OAuth2 PKCE primitives (RFC 7636 + RFC 6749 §10.12)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Ce sous-module expose UNIQUEMENT les primitives cryptographiques OAuth (PKCE
+// generators + state CSRF) — sans tirer le module `oauth-providers.ts` complet
+// (qui contient les SPECS Google/GitHub/Microsoft + `exchangeCodeForUser` qui
+// font des `fetch` lourds).
+//
+// Conçu pour être importé par `@mostajs/auth-flow` côté client navigateur/edge,
+// par tout SDK polyglotte qui implémente PKCE, par les tests cross-modules.
+//
+// Stable : ces 3 fonctions n'évoluent pas (RFC fige les algorithmes).
+import crypto from 'node:crypto';
+/**
+ * Génère un `code_verifier` 64 chars base64url (= 384 bits d'entropie).
+ *
+ * RFC 7636 §4.1 :
+ *   code_verifier = high-entropy cryptographic random STRING
+ *   ALPHA / DIGIT / "-" / "." / "_" / "~"  (= base64url unpadded sans `=`)
+ *   minLen 43, maxLen 128
+ */
+export function generateCodeVerifier() {
+    return crypto.randomBytes(48).toString('base64url');
+}
+/**
+ * Dérive le `code_challenge` à partir du verifier — méthode S256.
+ *
+ * RFC 7636 §4.2 :
+ *   code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
+ *
+ * La méthode `plain` est volontairement non-supportée (RFC 7636 §7.2 — interdite
+ * en production 2025).
+ */
+export function deriveCodeChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+/**
+ * Génère un `state` cryptographiquement aléatoire — 24 bytes = 192 bits.
+ *
+ * RFC 6749 §10.12 :
+ *   The state parameter SHOULD be used to prevent CSRF attacks. The value should
+ *   be unguessable.
+ */
+export function generateState() {
+    return crypto.randomBytes(24).toString('base64url');
+}

package/dist/lib/oauth-providers.d.ts

@@ -0,0 +1,92 @@
+import { generateCodeVerifier, deriveCodeChallenge, generateState } from './oauth-primitives.js';
+export { generateCodeVerifier, deriveCodeChallenge, generateState };
+/** Spec d'un provider OAuth2/OIDC. Extensible : un consumer peut fournir sa propre spec. */
+export interface OAuthProviderSpec {
+    id: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    /** Endpoint userinfo. Si omis, on tente de décoder le `id_token` JWT (OIDC). */
+    userInfoEndpoint?: string;
+    /** Scopes par défaut si l'app n'en passe pas (ex: ['openid','email','profile']). */
+    defaultScopes: string[];
+    /** Mapper du userInfo brut vers `{providerId, email, name}`. Souvent provider-specific. */
+    mapProfile: (raw: any) => {
+        providerId: string;
+        email?: string;
+        name?: string;
+    };
+    /** Header `Accept` à passer à `tokenEndpoint`. GitHub veut 'application/json'. */
+    tokenAcceptHeader?: string;
+    /** Header `Authorization` à passer à `userInfoEndpoint`. Default = 'Bearer <access>'. */
+    userInfoAuthHeader?: (accessToken: string) => string;
+}
+/** Lookup d'une spec built-in. Retourne null si l'id n'est pas connu. */
+export declare function getProviderSpec(id: string): OAuthProviderSpec | null;
+/** Pour un IdP OIDC arbitraire — on construit la spec à partir du discovery. */
+export interface OidcDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint?: string;
+    jwks_uri?: string;
+    scopes_supported?: string[];
+}
+/** Fetch le `.well-known/openid-configuration` d'un issuer et construit une spec OIDC. */
+export declare function discoverOidcProvider(issuerUrl: string, fetchImpl?: typeof fetch): Promise<OAuthProviderSpec>;
+export interface OAuthConfig {
+    spec: OAuthProviderSpec;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    /** Scopes additionnels au-delà de `spec.defaultScopes`. */
+    extraScopes?: string[];
+    /** Permet d'injecter un `fetch` custom (utile en tests). */
+    fetchImpl?: typeof fetch;
+}
+export interface AuthorizationStart {
+    /** URL vers laquelle rediriger l'utilisateur. */
+    url: string;
+    /** À persister côté server (ex: dans une session courte) — vérifié au callback contre le `state` retourné. */
+    state: string;
+    /** À persister aussi — utilisé au token exchange. */
+    codeVerifier: string;
+}
+export interface ExchangeResult {
+    providerId: string;
+    email?: string;
+    name?: string;
+    rawProfile: unknown;
+    accessToken: string;
+    refreshToken?: string;
+    /** Secondes jusqu'à expiration de l'access token. */
+    expiresIn?: number;
+    /** id_token brut si OIDC. */
+    idToken?: string;
+    /** Liste des scopes effectivement accordés. */
+    scope?: string;
+}
+/**
+ * Démarre le flow : génère state + PKCE verifier, retourne l'URL d'autorisation.
+ * Le caller doit persister `{ state, codeVerifier }` (ex: cookie httpOnly court) et
+ * comparer au callback.
+ */
+export declare function startAuthorization(config: OAuthConfig, opts?: {
+    state?: string;
+    loginHint?: string;
+}): AuthorizationStart;
+/**
+ * Callback : échange `code` contre access_token, fetch userinfo, retourne le profil.
+ * Le caller a la responsabilité de vérifier que `state` reçu == `state` persisté
+ * (anti-CSRF).
+ */
+export declare function exchangeCodeForUser(config: OAuthConfig, args: {
+    code: string;
+    codeVerifier: string;
+}): Promise<ExchangeResult>;
+/**
+ * Décode (sans vérifier la signature) le payload d'un JWT. Sécurité : à n'utiliser
+ * QUE quand le JWT vient d'un endpoint authentifié de confiance (ex: id_token reçu
+ * directement du tokenEndpoint). Pour vérifier un JWT venant d'un client, utiliser
+ * une lib comme `jose` avec le JWKS du provider.
+ */
+export declare function decodeJwtPayloadUnverified(jwt: string): unknown;