@mostajs/auth 2.5.2 → 3.1.0

package/dist/lib/anon-token.js

@@ -0,0 +1,69 @@
+// @mostajs/auth — Anonymous token primitives — v3.1.0+
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Pour les questionnaires / pages publiques `visibility=public-anon` qui
+// veulent retrouver les réponses entre sessions sans demander d'email.
+// Le module fournit uniquement les **primitives** : génération d'un token
+// aléatoire et formatage d'un email synthétique stable. Le **stockage du
+// cookie** est laissé au consumer car la signature dépend du framework
+// (Next.js `cookies()`, Express `res.cookie()`, etc.).
+//
+// Design clé :
+//   - 16 bytes de hasard cryptographique → 32 chars hex. Suffisant contre
+//     la collision (probabilité < 2⁻⁶⁴ pour 10⁹ tokens).
+//   - Email synthétique de la forme `anon-<token12>@<scope>.anon.local` :
+//     stable, reconnaissable comme anon dans les exports / dashboards,
+//     non-routable (TLD `.local` réservé) → impossible d'envoyer un mail
+//     dessus par accident.
+//   - Aucune dépendance externe — uniquement `node:crypto`.
+import { randomBytes } from 'node:crypto';
+/**
+ * Génère un nouveau token anonyme — 32 caractères hexadécimaux issus de
+ * 16 bytes de `randomBytes` (CSPRNG).
+ */
+export function generateAnonToken() {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * Formate un email synthétique stable pour un token + un scope.
+ * Le scope évite qu'un même token "fuite" inter-projets *(domaine
+ * différent → email différent → respondent distinct par projet)*.
+ *
+ * Le résultat est non-routable (`.anon.local`) — pas de risque
+ * d'envoi mail par accident.
+ *
+ * @example
+ *   anonEmail('a1b2c3d4e5f6', 'survey-2026')
+ *   → 'anon-a1b2c3d4e5f6@survey-2026.anon.local'
+ */
+export function anonEmail(token, scope) {
+    const t = String(token ?? '').slice(0, 12);
+    const s = String(scope ?? 'default').toLowerCase().replace(/[^a-z0-9-]+/g, '-');
+    return `anon-${t}@${s}.anon.local`;
+}
+/**
+ * Vrai si l'email donné a la forme générée par `anonEmail` — utile
+ * pour repérer les respondents anonymes dans les dashboards / exports
+ * sans avoir à stocker un flag séparé *(quoique le flag reste une
+ * bonne pratique pour la requête DB)*.
+ */
+export function isAnonEmail(email) {
+    if (!email)
+        return false;
+    return /^anon-[a-f0-9]{12}@[a-z0-9-]+\.anon\.local$/.test(email);
+}
+/**
+ * Convention de nom du cookie à utiliser. Le consumer reste libre de
+ * choisir le sien, mais cette constante factorise la pratique courante.
+ */
+export const ANON_COOKIE_DEFAULT_NAME = 'anon_tk';
+/**
+ * Options de cookie recommandées (utilisées par les implémentations
+ * Next/Express). Le consumer applique celles-ci à son cookie store.
+ */
+export const ANON_COOKIE_DEFAULT_OPTIONS = {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 60 * 60 * 24 * 365, // 1 an
+};

package/dist/lib/auth-events.d.ts

@@ -0,0 +1,40 @@
+export type AuthEventKind = 'login.success' | 'login.failure' | 'logout' | 'register' | 'password.changed' | 'password.reset.requested' | 'password.reset.completed' | 'password.rehash' | 'email.verification.sent' | 'email.verification.confirmed' | 'magic_link.requested' | 'magic_link.consumed' | 'mfa.enrolled' | 'mfa.verified' | 'mfa.failure' | 'mfa.disabled' | 'webauthn.registered' | 'webauthn.authenticated' | 'oauth.linked' | 'oauth.unlinked' | 'refresh.issued' | 'refresh.rotated' | 'refresh.revoked' | 'refresh.replay_detected' | 'rate_limit.hit' | 'account.deleted' | 'account.exported' | 'device_flow.requested' | 'device_flow.approved' | 'device_flow.denied' | 'device_flow.expired' | 'device_flow.consumed' | 'device_flow.brute_force' | 'pkce.requested' | 'pkce.consumed' | 'pkce.denied' | 'pkce.bad_verifier';
+export interface AuthEvent {
+    kind: AuthEventKind;
+    /** Sujet (user account) — null pour les événements pré-auth (rate-limit, etc.). */
+    userId?: string | null;
+    /** Email cible si relevant (login KO sans userId connu, magic-link request). */
+    email?: string | null;
+    /** IP de l'appel HTTP (extraite par le consumer depuis les headers). */
+    ip?: string | null;
+    userAgent?: string | null;
+    /** Timestamp UTC ; le consumer peut écraser pour back-fill / replay. */
+    ts?: Date;
+    /** Payload libre — par convention :
+     *   - login.failure:           `{ reason: 'wrong_password' | 'unknown_user' | 'inactive' | 'mfa_required' }`
+     *   - mfa.failure:             `{ reason: 'wrong_code' | 'expired' }`
+     *   - rate_limit.hit:          `{ endpoint, retryAfter }`
+     *   - device_flow.requested:   `{ clientId, scopes, deviceCode }`
+     *   - device_flow.approved:    `{ clientId, deviceCode, accountId }`
+     *   - device_flow.denied:      `{ clientId, deviceCode, accountId? }`
+     *   - device_flow.expired:     `{ clientId, deviceCode, expiresInSec }`
+     *   - device_flow.consumed:    `{ clientId, deviceCode, accountId, scopes }`
+     *   - device_flow.brute_force: `{ ip, attempts, windowSec }`
+     *   - pkce.requested:          `{ clientId, scopes, redirectUri, state }`
+     *   - pkce.consumed:           `{ clientId, accountId, scopes }`
+     *   - pkce.denied:             `{ clientId, redirectUri, accountId? }`
+     *   - pkce.bad_verifier:       `{ clientId, redirectUri, ip }` ← attaque potentielle
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface AuthEventEmitter {
+    emit(event: AuthEvent): void | Promise<void>;
+}
+/** No-op : utilisé par défaut si le consumer ne branche pas d'audit. */
+export declare const noopAuthEventEmitter: AuthEventEmitter;
+/**
+ * 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 declare function wrapEmitter(emitter: AuthEventEmitter): AuthEventEmitter;

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