@mostajs/auth 2.5.1 → 3.0.2

package/dist/lib/auth-events.js

@@ -0,0 +1,37 @@
+// @mostajs/auth — Auth event emission for audit (v2.6.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Émet des événements typés à chaque étape sensible (login, logout, password change,
+// MFA, token rotation, replay detection, etc.). Le consumer branche un emitter
+// adossé à `@mostajs/audit` ou n'importe quel sink (fichier, syslog, Kafka).
+//
+// Le module ne *décide pas* de la persistance — il définit le vocabulaire et le payload.
+// Permet à `@mostajs/audit` de stocker, et à un middleware d'alerter en temps réel
+// (ex: 5 logins KO en 1 min sur le même email → notify admin).
+/** No-op : utilisé par défaut si le consumer ne branche pas d'audit. */
+export const noopAuthEventEmitter = {
+    emit() { },
+};
+/**
+ * Wrapper safe : encapsule l'`emit` du consumer dans un try/catch + non-blocking.
+ * Une faille de l'audit ne doit JAMAIS faire échouer le flow auth utilisateur
+ * (un emit qui crash → on log, on continue).
+ */
+export function wrapEmitter(emitter) {
+    return {
+        emit(event) {
+            try {
+                const r = emitter.emit({ ts: new Date(), ...event });
+                if (r && typeof r.catch === 'function') {
+                    ;
+                    r.catch((err) => {
+                        console.error('[mostajs/auth] audit emit failed (async):', err);
+                    });
+                }
+            }
+            catch (err) {
+                console.error('[mostajs/auth] audit emit failed (sync):', err);
+            }
+        },
+    };
+}

package/dist/lib/auth-rate-limit.d.ts

@@ -0,0 +1,80 @@
+export interface BucketState {
+    tokens: number;
+    lastRefillMs: number;
+}
+export interface RateLimitStore {
+    /** Lecture atomique du bucket. Retourne null si inexistant. */
+    get(key: string): Promise<BucketState | null>;
+    /** Écriture atomique. TTL court (= 2× le temps de remplissage complet). */
+    set(key: string, state: BucketState, ttlSec: number): Promise<void>;
+}
+export interface RateLimitOptions {
+    /** Capacité max du bucket (= burst). */
+    capacity: number;
+    /** Tokens regagnés par seconde. */
+    refillPerSec: number;
+    /** Coût d'une opération (défaut 1). Permet d'en facturer 10 pour les opérations chères. */
+    cost?: number;
+}
+export interface RateLimitResult {
+    ok: boolean;
+    /** Nombre de tokens restants après la décision. */
+    remaining: number;
+    /** Si `ok=false`, secondes à attendre avant qu'un token soit disponible. */
+    retryAfter: number;
+}
+/** Store in-memory par défaut. Process-local — pas adapté multi-instance. */
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    private map;
+    private gcEveryMs;
+    private lastGcMs;
+    get(key: string): Promise<BucketState | null>;
+    set(key: string, state: BucketState, ttlSec: number): Promise<void>;
+    private maybeGc;
+}
+export interface AuthRateLimiter {
+    tryConsume(args: {
+        key: string;
+    } & RateLimitOptions): Promise<RateLimitResult>;
+}
+/**
+ * Crée un rate-limiter token-bucket.
+ *
+ * @param config.store - Store partagé. Défaut: `MemoryRateLimitStore` avec warning.
+ * @param config.warnIfMemoryFallback - Si true (défaut), log une fois le warning au boot.
+ */
+export declare function createAuthRateLimiter(config?: {
+    store?: RateLimitStore;
+    warnIfMemoryFallback?: boolean;
+}): AuthRateLimiter;
+/**
+ * Presets recommandés OWASP — points de départ raisonnables, à ajuster selon
+ * le profil de trafic du tenant.
+ */
+export declare const RATE_LIMIT_PRESETS: {
+    /** /login : 10 tentatives → puis 1 token / 6 secondes. Couvre login + magic-link. */
+    readonly loginByIp: {
+        readonly capacity: 10;
+        readonly refillPerSec: number;
+    };
+    /** /login : 5 tentatives par email → 1 token / 60 secondes. Anti-credential-stuffing ciblé. */
+    readonly loginByEmail: {
+        readonly capacity: 5;
+        readonly refillPerSec: number;
+    };
+    /** /register : 3 par IP → 1 token / 5 minutes. Anti-spam comptes. */
+    readonly registerByIp: {
+        readonly capacity: 3;
+        readonly refillPerSec: number;
+    };
+    /** /reset : 3 par email → 1 token / 5 minutes. */
+    readonly resetByEmail: {
+        readonly capacity: 3;
+        readonly refillPerSec: number;
+    };
+    /** /magic-link : 5 par email → 1 token / 5 minutes. Anti email-bombing. */
+    readonly magicLinkByEmail: {
+        readonly capacity: 5;
+        readonly refillPerSec: number;
+    };
+};

package/dist/lib/auth-rate-limit.js

@@ -0,0 +1,100 @@
+// @mostajs/auth — Rate limiting middleware (v2.6.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Token bucket par clé (typ. IP+endpoint, ou email+endpoint).
+// Storage agnostique :
+//  - Défaut : in-memory `Map` (process-local, single-instance only).
+//  - Production multi-instance : passer un `RateLimitStore` adossé à Redis
+//    (le consumer fournit l'implémentation — DI cohérent avec le reste du module).
+//
+// Usage typique :
+//   const rl = createAuthRateLimiter({ store: redisStore })
+//   const allowed = await rl.tryConsume({ key: `login:${ip}`, capacity: 10, refillPerSec: 1 })
+//   if (!allowed.ok) return Response.json({ error: 'rate_limited', retryAfter: allowed.retryAfter }, { status: 429 })
+/** Store in-memory par défaut. Process-local — pas adapté multi-instance. */
+export class MemoryRateLimitStore {
+    map = new Map();
+    gcEveryMs = 60_000;
+    lastGcMs = Date.now();
+    async get(key) {
+        this.maybeGc();
+        const v = this.map.get(key);
+        if (!v)
+            return null;
+        if (v.expiresAtMs < Date.now()) {
+            this.map.delete(key);
+            return null;
+        }
+        return v.state;
+    }
+    async set(key, state, ttlSec) {
+        this.map.set(key, { state, expiresAtMs: Date.now() + ttlSec * 1000 });
+    }
+    maybeGc() {
+        const now = Date.now();
+        if (now - this.lastGcMs < this.gcEveryMs)
+            return;
+        this.lastGcMs = now;
+        for (const [k, v] of this.map) {
+            if (v.expiresAtMs < now)
+                this.map.delete(k);
+        }
+    }
+}
+/**
+ * Crée un rate-limiter token-bucket.
+ *
+ * @param config.store - Store partagé. Défaut: `MemoryRateLimitStore` avec warning.
+ * @param config.warnIfMemoryFallback - Si true (défaut), log une fois le warning au boot.
+ */
+export function createAuthRateLimiter(config) {
+    let store = config?.store;
+    if (!store) {
+        store = new MemoryRateLimitStore();
+        if (config?.warnIfMemoryFallback !== false) {
+            console.warn('[mostajs/auth] createAuthRateLimiter: using in-memory store ' +
+                '(single-process). Provide a Redis-backed store for multi-instance deployments.');
+        }
+    }
+    const s = store;
+    async function tryConsume({ key, capacity, refillPerSec, cost = 1, }) {
+        const now = Date.now();
+        const prev = (await s.get(key)) ?? { tokens: capacity, lastRefillMs: now };
+        // Refill basé sur le temps écoulé depuis la dernière modification.
+        const elapsedSec = Math.max(0, (now - prev.lastRefillMs) / 1000);
+        const refilled = Math.min(capacity, prev.tokens + elapsedSec * refillPerSec);
+        if (refilled < cost) {
+            const deficit = cost - refilled;
+            const retryAfter = Math.ceil(deficit / refillPerSec);
+            // On persiste le state refilled pour ne pas perdre l'avancée du remplissage.
+            await s.set(key, { tokens: refilled, lastRefillMs: now }, ttlForCapacity(capacity, refillPerSec));
+            return { ok: false, remaining: Math.floor(refilled), retryAfter };
+        }
+        const next = { tokens: refilled - cost, lastRefillMs: now };
+        await s.set(key, next, ttlForCapacity(capacity, refillPerSec));
+        return { ok: true, remaining: Math.floor(next.tokens), retryAfter: 0 };
+    }
+    return { tryConsume };
+}
+/** TTL = 2× le temps qu'il faudrait pour remplir le bucket à fond. Évite la fuite. */
+function ttlForCapacity(capacity, refillPerSec) {
+    if (refillPerSec <= 0)
+        return 3600;
+    return Math.max(60, Math.ceil((capacity / refillPerSec) * 2));
+}
+/**
+ * Presets recommandés OWASP — points de départ raisonnables, à ajuster selon
+ * le profil de trafic du tenant.
+ */
+export const RATE_LIMIT_PRESETS = {
+    /** /login : 10 tentatives → puis 1 token / 6 secondes. Couvre login + magic-link. */
+    loginByIp: { capacity: 10, refillPerSec: 1 / 6 },
+    /** /login : 5 tentatives par email → 1 token / 60 secondes. Anti-credential-stuffing ciblé. */
+    loginByEmail: { capacity: 5, refillPerSec: 1 / 60 },
+    /** /register : 3 par IP → 1 token / 5 minutes. Anti-spam comptes. */
+    registerByIp: { capacity: 3, refillPerSec: 1 / 300 },
+    /** /reset : 3 par email → 1 token / 5 minutes. */
+    resetByEmail: { capacity: 3, refillPerSec: 1 / 300 },
+    /** /magic-link : 5 par email → 1 token / 5 minutes. Anti email-bombing. */
+    magicLinkByEmail: { capacity: 5, refillPerSec: 1 / 300 },
+};

package/dist/lib/credentials-verify.d.ts

@@ -13,6 +13,19 @@ export interface CredentialsVerifyConfig {
     resolveRole?: (user: any) => string | Promise<string>;
     /** Custom display name. Default: "<firstName> <lastName>" trimmed → email. */
     resolveName?: (user: any) => string;
+    /**
+     * v3.0.2+ — Optionnel : résolveur de l'`accountId` (frontière de tenancy
+     * Octonet) pour le user authentifié. Si fourni, l'`accountId` est inclus
+     * dans la response sanitisée → propagé jusqu'à NextAuth côté client via
+     * `createRemoteCredentialsProvider`.
+     *
+     * Pattern recommandé côté Octonet :
+     *   import { resolveUserAccountId } from '@mostajs/rbac/lib/account-resolver'
+     *   resolveAccountId: (user) => resolveUserAccountId(dialect, user.id, user.email)
+     *
+     * Si non fourni → `accountId` absent de la response (rétro-compat v2.5.x→v3.0.1).
+     */
+    resolveAccountId?: (user: any) => string | null | Promise<string | null>;
 }
 /**
  * Build a Web standard Request → Response handler that verifies (email, password)

package/dist/lib/credentials-verify.js

@@ -78,6 +78,19 @@ export function createCredentialsVerifyHandler(config) {
             }
             const role = await resolveRole(user);
             const name = resolveName(user);
+            // v3.0.2+ : si un resolver d'accountId est fourni, on l'inclut dans la response.
+            // Pattern recommandé côté Octonet : resolveUserAccountId(dialect, user.id, user.email).
+            // Sans resolver → champ absent (rétro-compat v2.5.x → v3.0.1).
+            let accountId;
+            if (config.resolveAccountId) {
+                try {
+                    accountId = await config.resolveAccountId(user);
+                }
+                catch (e) {
+                    console.warn('[auth/verify] resolveAccountId failed (non-fatal):', e?.message || e);
+                    accountId = null;
+                }
+            }
             return Response.json({
                 ok: true,
                 user: {
@@ -85,6 +98,7 @@ export function createCredentialsVerifyHandler(config) {
                     email: user.email,
                     name,
                     role,
+                    ...(accountId ? { accountId } : {}),
                 },
             });
         }

package/dist/lib/magic-link.d.ts

@@ -0,0 +1,88 @@
+export interface MagicLinkPayload {
+    /** Email cible — la résolution userId se fait au verify (le user peut avoir été supprimé entre-temps). */
+    email: string;
+    /** Nonce unique single-use. */
+    nonce: string;
+    /** Unix seconds expiration. */
+    exp: number;
+    /** Optionnel : intent — useful pour distinguer /auth/login vs /auth/recover-password. */
+    intent?: 'login' | 'recover';
+}
+export interface MagicLinkNonceRepo {
+    /** Persiste le nonce avec son expiration. Throw si déjà existant. */
+    insert(args: {
+        nonce: string;
+        email: string;
+        expiresAt: Date;
+    }): Promise<void>;
+    /** Consume atomiquement : retourne true si le nonce existait ET n'était pas expiré, et le supprime. */
+    consume(nonce: string): Promise<boolean>;
+    /** Cleanup périodique (job/cron). */
+    deleteExpired(now: Date): Promise<number>;
+}
+export interface UserLite {
+    id: string;
+    email: string;
+    status?: string;
+}
+export interface UserLookup {
+    findByEmail(email: string): Promise<UserLite | null>;
+}
+export interface MagicLinkConfig {
+    /** Secret HMAC (≥ 32 bytes). Idéalement le même `AUTH_SECRET` que le reste du module. */
+    secret: string;
+    /** TTL du lien (défaut 15 min). */
+    ttlSec?: number;
+    /** Repo nonce single-use. */
+    nonceRepo: MagicLinkNonceRepo;
+    /** Lookup user par email. */
+    userRepo: UserLookup;
+    /** Hook envoi email. Le consumer formate le mail comme il veut. */
+    sendEmail: (args: {
+        to: string;
+        magicUrl: string;
+        expiresAt: Date;
+    }) => Promise<void>;
+    /** Base URL frontend qui sait gérer le callback. Ex: 'https://app.example.com/auth/magic'. */
+    baseUrl: string;
+}
+export interface RequestMagicLinkArgs {
+    email: string;
+    intent?: 'login' | 'recover';
+    /** Optionnel : metadata logguée (ip, ua) — propagée via le sendEmail si voulu. */
+    meta?: Record<string, string>;
+}
+export type RequestMagicLinkResult = {
+    ok: true;
+    expiresAt: Date;
+} | {
+    ok: false;
+    reason: 'unknown_email' | 'inactive_user';
+};
+/**
+ * Émet un magic link et l'envoie par email.
+ *
+ * **Important** : on retourne `unknown_email` quand le compte n'existe pas plutôt
+ * que d'envoyer silencieusement OK comme certains autres modules (la divergence
+ * permet à l'app cliente d'afficher un message neutre `"si l'email existe, un lien
+ * a été envoyé"` en convertissant `ok=false` en HTTP 200 — anti-énumération côté
+ * caller). Le rate-limit côté consumer protège du brute-force.
+ */
+export declare function requestMagicLink(config: MagicLinkConfig, args: RequestMagicLinkArgs): Promise<RequestMagicLinkResult>;
+export type VerifyMagicLinkResult = {
+    ok: true;
+    userId: string;
+    email: string;
+    intent?: 'login' | 'recover';
+} | {
+    ok: false;
+    reason: 'malformed' | 'bad_signature' | 'expired' | 'consumed' | 'unknown_user' | 'inactive_user';
+};
+/**
+ * Vérifie un magic-link token. Single-use (nonce consommé atomiquement).
+ *
+ * Le consumer, sur `ok: true`, ouvre la session (JWT cookie) et renvoie l'user.
+ */
+export declare function verifyMagicLink(config: MagicLinkConfig, token: string): Promise<VerifyMagicLinkResult>;
+/** Helper exporté pour tests / introspection — décode SANS vérifier la signature. */
+export declare function _peekToken(token: string): MagicLinkPayload | null;

package/dist/lib/magic-link.js

@@ -0,0 +1,125 @@
+// @mostajs/auth — Magic link login (passwordless email) — Lot 3 / v2.8.0+
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Flow :
+//   1. requestMagicLink({ email })           → token signé HMAC + persist nonce + envoi email
+//   2. l'utilisateur clique le lien          → /auth/magic?token=<...>
+//   3. verifyMagicLink({ token })            → vérifie sig + TTL + single-use, retourne userId
+//      (le consumer ouvre la session JWT/cookie ensuite, comme après un login password OK)
+//
+// Design clé :
+//   - Le token est un JWT-like signé HMAC : header.payload.signature (canon stable).
+//   - Single-use garanti par un nonceRepo (DI) : chaque token a un nonce unique persisté ;
+//     verify supprime le nonce (ou le marque consumed) — un replay → not_found.
+//   - TTL court (15 min par défaut), pas de prolongation.
+//   - Rate-limit appliqué côté consumer (cf. RATE_LIMIT_PRESETS.magicLinkByEmail dans
+//     auth-rate-limit.ts) — anti email-bombing.
+//   - L'audit emit `magic_link.requested` + `magic_link.consumed` (cf. auth-events.ts).
+import crypto from 'node:crypto';
+const DEFAULT_TTL_SEC = 15 * 60;
+function generateNonce() {
+    return crypto.randomBytes(18).toString('base64url');
+}
+function canonicalString(p) {
+    // Ordre stable, encode strict — les changements de format invalident la signature.
+    const parts = [
+        `email=${encodeURIComponent(p.email)}`,
+        `nonce=${p.nonce}`,
+        `exp=${p.exp}`,
+    ];
+    if (p.intent)
+        parts.push(`intent=${p.intent}`);
+    return parts.join('&');
+}
+function signToken(secret, payload) {
+    const canon = canonicalString(payload);
+    const sig = crypto.createHmac('sha256', secret).update(canon).digest('base64url');
+    // Format auto-contenu : payload-base64url + signature
+    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    return `${payloadB64}.${sig}`;
+}
+function decodeToken(token) {
+    const parts = token.split('.');
+    if (parts.length !== 2)
+        throw new Error('Invalid token format');
+    const [payloadB64, sig] = parts;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+    if (typeof payload.email !== 'string' || typeof payload.nonce !== 'string' || typeof payload.exp !== 'number') {
+        throw new Error('Invalid token payload shape');
+    }
+    return { payload, sig };
+}
+/**
+ * Émet un magic link et l'envoie par email.
+ *
+ * **Important** : on retourne `unknown_email` quand le compte n'existe pas plutôt
+ * que d'envoyer silencieusement OK comme certains autres modules (la divergence
+ * permet à l'app cliente d'afficher un message neutre `"si l'email existe, un lien
+ * a été envoyé"` en convertissant `ok=false` en HTTP 200 — anti-énumération côté
+ * caller). Le rate-limit côté consumer protège du brute-force.
+ */
+export async function requestMagicLink(config, args) {
+    const user = await config.userRepo.findByEmail(args.email);
+    if (!user)
+        return { ok: false, reason: 'unknown_email' };
+    if (user.status && user.status !== 'active')
+        return { ok: false, reason: 'inactive_user' };
+    const ttl = config.ttlSec ?? DEFAULT_TTL_SEC;
+    const exp = Math.floor(Date.now() / 1000) + ttl;
+    const nonce = generateNonce();
+    const expiresAt = new Date(exp * 1000);
+    await config.nonceRepo.insert({ nonce, email: args.email, expiresAt });
+    const token = signToken(config.secret, { email: args.email, nonce, exp, intent: args.intent });
+    const magicUrl = `${config.baseUrl}?token=${encodeURIComponent(token)}`;
+    await config.sendEmail({ to: args.email, magicUrl, expiresAt });
+    return { ok: true, expiresAt };
+}
+/**
+ * Vérifie un magic-link token. Single-use (nonce consommé atomiquement).
+ *
+ * Le consumer, sur `ok: true`, ouvre la session (JWT cookie) et renvoie l'user.
+ */
+export async function verifyMagicLink(config, token) {
+    let parsed;
+    try {
+        parsed = decodeToken(token);
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+    const { payload, sig } = parsed;
+    // 1. Vérification signature en temps constant.
+    const expectedSig = crypto.createHmac('sha256', config.secret)
+        .update(canonicalString(payload))
+        .digest('base64url');
+    const sigBuf = Buffer.from(sig, 'base64url');
+    const expBuf = Buffer.from(expectedSig, 'base64url');
+    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
+        return { ok: false, reason: 'bad_signature' };
+    }
+    // 2. Expiration
+    if (payload.exp < Math.floor(Date.now() / 1000)) {
+        return { ok: false, reason: 'expired' };
+    }
+    // 3. Single-use atomique
+    const consumed = await config.nonceRepo.consume(payload.nonce);
+    if (!consumed) {
+        return { ok: false, reason: 'consumed' };
+    }
+    // 4. User toujours valide
+    const user = await config.userRepo.findByEmail(payload.email);
+    if (!user)
+        return { ok: false, reason: 'unknown_user' };
+    if (user.status && user.status !== 'active')
+        return { ok: false, reason: 'inactive_user' };
+    return { ok: true, userId: user.id, email: user.email, intent: payload.intent };
+}
+/** Helper exporté pour tests / introspection — décode SANS vérifier la signature. */
+export function _peekToken(token) {
+    try {
+        return decodeToken(token).payload;
+    }
+    catch {
+        return null;
+    }
+}

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 {};