@mostajs/auth 2.5.2 → 3.0.2

package/dist/lib/oauth-providers.js

@@ -0,0 +1,192 @@
+// @mostajs/auth — OAuth2 + OIDC provider handlers (v2.7.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Core OAuth2 / OIDC handler avec PKCE (RFC 7636) + state CSRF.
+//
+// Scope v2.7.0 (tête haute — exactement ce qui est livré, pas de stub claims) :
+//
+//   ✅ Generic OAuth2 + PKCE handler
+//   ✅ Provider specs concrets : 'google', 'github', 'microsoft'
+//   ✅ Provider 'generic-oidc' : compatible tout IdP OIDC (issuer URL → discovery)
+//   ❌ apple : nécessite client_secret JWT signé ES256 — porté en v2.7.x si demande
+//   ❌ slack : format de réponse OAuth atypique (slack-specific) — porté en v2.7.x
+//   ❌ discord, facebook : specs faciles, mais on les ajoute quand on a un customer
+//
+// Pas d'inclusion de "8 providers stubs". Trois providers réels + générique OIDC =
+// couverture ~80% des cas. Les autres arriveront un par un quand le besoin existe.
+// PKCE primitives extraites en v2.9.1 vers `lib/oauth-primitives.ts` pour permettre
+// à @mostajs/auth-flow + futurs SDKs polyglottes de les consommer sans tirer les
+// SPECS providers + fetch deps lourdes.
+// Importées + ré-exportées ici pour rétro-compat des consumers v2.7.x / v2.8.x.
+import { generateCodeVerifier, deriveCodeChallenge, generateState, } from './oauth-primitives.js';
+export { generateCodeVerifier, deriveCodeChallenge, generateState };
+const SPECS = {
+    google: {
+        id: 'google',
+        authorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
+        tokenEndpoint: 'https://oauth2.googleapis.com/token',
+        userInfoEndpoint: 'https://openidconnect.googleapis.com/v1/userinfo',
+        defaultScopes: ['openid', 'email', 'profile'],
+        mapProfile: (raw) => ({
+            providerId: String(raw.sub),
+            email: raw.email,
+            name: raw.name ?? [raw.given_name, raw.family_name].filter(Boolean).join(' '),
+        }),
+    },
+    github: {
+        id: 'github',
+        authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+        tokenEndpoint: 'https://github.com/login/oauth/access_token',
+        userInfoEndpoint: 'https://api.github.com/user',
+        defaultScopes: ['read:user', 'user:email'],
+        tokenAcceptHeader: 'application/json',
+        mapProfile: (raw) => ({
+            providerId: String(raw.id),
+            email: raw.email ?? undefined,
+            name: raw.name ?? raw.login,
+        }),
+    },
+    microsoft: {
+        id: 'microsoft',
+        authorizationEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+        tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        userInfoEndpoint: 'https://graph.microsoft.com/v1.0/me',
+        defaultScopes: ['openid', 'email', 'profile', 'User.Read'],
+        mapProfile: (raw) => ({
+            providerId: String(raw.id),
+            email: raw.mail ?? raw.userPrincipalName,
+            name: raw.displayName,
+        }),
+    },
+};
+/** Lookup d'une spec built-in. Retourne null si l'id n'est pas connu. */
+export function getProviderSpec(id) {
+    return SPECS[id] ?? null;
+}
+/** Fetch le `.well-known/openid-configuration` d'un issuer et construit une spec OIDC. */
+export async function discoverOidcProvider(issuerUrl, fetchImpl = fetch) {
+    const url = `${issuerUrl.replace(/\/$/, '')}/.well-known/openid-configuration`;
+    const resp = await fetchImpl(url);
+    if (!resp.ok)
+        throw new Error(`OIDC discovery failed (${resp.status}) at ${url}`);
+    const doc = await resp.json();
+    return {
+        id: 'generic-oidc',
+        authorizationEndpoint: doc.authorization_endpoint,
+        tokenEndpoint: doc.token_endpoint,
+        userInfoEndpoint: doc.userinfo_endpoint,
+        defaultScopes: ['openid', 'email', 'profile'],
+        mapProfile: (raw) => ({
+            providerId: String(raw.sub),
+            email: raw.email,
+            name: raw.name ?? raw.preferred_username,
+        }),
+    };
+}
+/**
+ * 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 function startAuthorization(config, opts) {
+    const state = opts?.state ?? generateState();
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = deriveCodeChallenge(codeVerifier);
+    const scopes = [...config.spec.defaultScopes, ...(config.extraScopes ?? [])];
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: config.clientId,
+        redirect_uri: config.redirectUri,
+        scope: scopes.join(' '),
+        state,
+        code_challenge: codeChallenge,
+        code_challenge_method: 'S256',
+    });
+    if (opts?.loginHint)
+        params.set('login_hint', opts.loginHint);
+    return {
+        url: `${config.spec.authorizationEndpoint}?${params}`,
+        state,
+        codeVerifier,
+    };
+}
+/**
+ * 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 async function exchangeCodeForUser(config, args) {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const tokenBody = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: args.code,
+        redirect_uri: config.redirectUri,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        code_verifier: args.codeVerifier,
+    });
+    const tokenHeaders = {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: config.spec.tokenAcceptHeader ?? 'application/json',
+    };
+    const tokenResp = await fetchImpl(config.spec.tokenEndpoint, {
+        method: 'POST',
+        headers: tokenHeaders,
+        body: tokenBody.toString(),
+    });
+    if (!tokenResp.ok) {
+        const text = await tokenResp.text().catch(() => '');
+        throw new Error(`Token exchange failed (${tokenResp.status}): ${text.slice(0, 200)}`);
+    }
+    const tokenData = await tokenResp.json();
+    if (!tokenData.access_token) {
+        throw new Error(`Token exchange returned no access_token: ${JSON.stringify(tokenData).slice(0, 200)}`);
+    }
+    // userinfo : soit endpoint dédié, soit décodage du id_token (OIDC).
+    let rawProfile;
+    if (config.spec.userInfoEndpoint) {
+        const authHeader = config.spec.userInfoAuthHeader
+            ? config.spec.userInfoAuthHeader(tokenData.access_token)
+            : `Bearer ${tokenData.access_token}`;
+        const userResp = await fetchImpl(config.spec.userInfoEndpoint, {
+            headers: { Authorization: authHeader, Accept: 'application/json' },
+        });
+        if (!userResp.ok) {
+            const text = await userResp.text().catch(() => '');
+            throw new Error(`UserInfo fetch failed (${userResp.status}): ${text.slice(0, 200)}`);
+        }
+        rawProfile = await userResp.json();
+    }
+    else if (tokenData.id_token) {
+        rawProfile = decodeJwtPayloadUnverified(tokenData.id_token);
+    }
+    else {
+        throw new Error('No userinfo endpoint and no id_token — cannot resolve profile');
+    }
+    const mapped = config.spec.mapProfile(rawProfile);
+    return {
+        providerId: mapped.providerId,
+        email: mapped.email,
+        name: mapped.name,
+        rawProfile,
+        accessToken: tokenData.access_token,
+        refreshToken: tokenData.refresh_token,
+        idToken: tokenData.id_token,
+        expiresIn: tokenData.expires_in,
+        scope: tokenData.scope,
+    };
+}
+/**
+ * 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 function decodeJwtPayloadUnverified(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        throw new Error('Invalid JWT format');
+    const payload = parts[1];
+    const decoded = Buffer.from(payload, 'base64url').toString('utf8');
+    return JSON.parse(decoded);
+}

package/dist/lib/password.d.ts

@@ -1,2 +1,19 @@
-export declare function hashPassword(plain: string, rounds?: number): Promise<string>;
+/** Hash en Argon2id. Format : `$argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>` */
+export declare function hashPassword(plain: string): Promise<string>;
+/**
+ * Vérifie un password en détectant l'algo du hash stocké.
+ * Retourne `{ valid, needsRehash }` — `needsRehash=true` si le hash actuel est
+ * en bcrypt legacy (l'app peut alors re-hasher en Argon2id et persister).
+ */
+export declare function comparePasswordWithMeta(plain: string, hashed: string): Promise<{
+    valid: boolean;
+    needsRehash: boolean;
+}>;
+/** Compatibilité ascendante — équivaut à `comparePasswordWithMeta().valid`. */
 export declare function comparePassword(plain: string, hashed: string): Promise<boolean>;
+/**
+ * @deprecated Test/audit uniquement. La voie de prod est `hashPassword()`.
+ * Conservé pour permettre d'auditer la migration et écrire des tests qui forcent
+ * un hash bcrypt connu.
+ */
+export declare function hashPasswordBcrypt(plain: string, rounds?: number): Promise<string>;

package/dist/lib/password.js

@@ -1,10 +1,52 @@
-// @mosta/auth — Password hashing wrapper
-// Author: Dr Hamid MADANI drmdh@msn.com
+// @mostajs/auth — Password hashing wrapper (v2.6.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Dual-algorithm support :
+//  - hashPassword() écrit en Argon2id (recommandation OWASP 2025).
+//  - comparePassword() détecte le format (préfixe `$argon2id$` vs `$2b$`/`$2a$`/`$2y$`)
+//    et applique l'algo correspondant — permet une migration lazy : un user qui se
+//    log avec un ancien hash bcrypt voit son hash réécrit en Argon2id si l'app appelle
+//    comparePasswordWithMeta() puis hashPassword() lors d'un login OK (cf. doc 07 Lot 1).
+//  - hashPasswordBcrypt() reste exporté pour test/audit, deprecated.
+//
+// Paramètres Argon2id : OWASP 2025 minimum — m=64 MiB, t=3, p=4 (cf. RFC 9106).
+import { hash as argonHash, verify as argonVerify } from '@node-rs/argon2';
 import bcrypt from 'bcryptjs';
-const DEFAULT_ROUNDS = 12;
-export async function hashPassword(plain, rounds = DEFAULT_ROUNDS) {
-    return bcrypt.hash(plain, rounds);
+const ARGON2ID_OPTIONS = {
+    memoryCost: 65536,
+    timeCost: 3,
+    parallelism: 4,
+};
+const BCRYPT_DEFAULT_ROUNDS = 12;
+/** Hash en Argon2id. Format : `$argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>` */
+export async function hashPassword(plain) {
+    return argonHash(plain, ARGON2ID_OPTIONS);
+}
+/**
+ * Vérifie un password en détectant l'algo du hash stocké.
+ * Retourne `{ valid, needsRehash }` — `needsRehash=true` si le hash actuel est
+ * en bcrypt legacy (l'app peut alors re-hasher en Argon2id et persister).
+ */
+export async function comparePasswordWithMeta(plain, hashed) {
+    if (!hashed)
+        return { valid: false, needsRehash: false };
+    if (hashed.startsWith('$argon2')) {
+        const valid = await argonVerify(hashed, plain).catch(() => false);
+        return { valid, needsRehash: false };
+    }
+    const valid = await bcrypt.compare(plain, hashed);
+    return { valid, needsRehash: valid };
 }
+/** Compatibilité ascendante — équivaut à `comparePasswordWithMeta().valid`. */
 export async function comparePassword(plain, hashed) {
-    return bcrypt.compare(plain, hashed);
+    const { valid } = await comparePasswordWithMeta(plain, hashed);
+    return valid;
+}
+/**
+ * @deprecated Test/audit uniquement. La voie de prod est `hashPassword()`.
+ * Conservé pour permettre d'auditer la migration et écrire des tests qui forcent
+ * un hash bcrypt connu.
+ */
+export async function hashPasswordBcrypt(plain, rounds = BCRYPT_DEFAULT_ROUNDS) {
+    return bcrypt.hash(plain, rounds);
 }

package/dist/lib/refresh-tokens.d.ts

@@ -0,0 +1,74 @@
+/** Format persisté en DB (le `token` plaintext n'est jamais stocké). */
+export interface RefreshTokenRecord {
+    id: string;
+    userId: string;
+    /** SHA-256 hex du token plaintext. Index unique — la lookup se fait dessus. */
+    tokenHash: string;
+    expiresAt: Date | string;
+    createdAt: Date | string;
+    /** ID du refresh token qui a remplacé celui-ci (set par `rotate`). */
+    replacedBy?: string | null;
+    /** Timestamp de révocation explicite (logout, password change, etc.). */
+    revokedAt?: Date | string | null;
+    ip?: string | null;
+    userAgent?: string | null;
+}
+/** Repository d'accès — à implémenter par le consumer (ex: via @mostajs/orm). */
+export interface RefreshTokenRepo {
+    insert(record: Omit<RefreshTokenRecord, 'id'>): Promise<RefreshTokenRecord>;
+    findByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    setReplacedBy(id: string, replacedById: string): Promise<void>;
+    revokeById(id: string): Promise<void>;
+    /** Révoque tous les tokens d'un user (sur password change, logout-all, etc.). */
+    revokeAllByUser(userId: string): Promise<void>;
+    /** Cleanup périodique des tokens expirés (cron / job). */
+    deleteExpired(now: Date): Promise<number>;
+}
+export interface RefreshTokenConfig {
+    repo: RefreshTokenRepo;
+    /** TTL d'un refresh token (défaut 30 jours). */
+    ttlSec?: number;
+    /** Hook appelé quand une rotation détecte un replay (token déjà rotaté ré-utilisé).
+     *  Use-case : signaler à l'audit log + révoquer toute la chaîne user. */
+    onReplayDetected?: (record: RefreshTokenRecord) => Promise<void>;
+}
+export interface IssuedRefreshToken {
+    /** Plaintext à retourner au client (cookie ou body). Ne sera plus jamais accessible. */
+    token: string;
+    record: RefreshTokenRecord;
+}
+/**
+ * Émet un nouveau refresh token et persiste son hash.
+ * Appelé après login OK, ou comme étape finale de `rotate`.
+ */
+export declare function issueRefreshToken(config: RefreshTokenConfig, ctx: {
+    userId: string;
+    ip?: string;
+    userAgent?: string;
+}): Promise<IssuedRefreshToken>;
+export type RotateResult = {
+    ok: true;
+    issued: IssuedRefreshToken;
+    oldRecord: RefreshTokenRecord;
+} | {
+    ok: false;
+    reason: 'not_found' | 'expired' | 'revoked' | 'replay';
+};
+/**
+ * Vérifie + rotation : ancien token marqué `replacedBy`, nouveau émis.
+ * Détection de replay : si l'ancien a déjà un `replacedBy`, c'est qu'il a été
+ * utilisé une 2ᵉ fois → token volé. On déclenche `onReplayDetected` (typiquement :
+ * révocation totale de la chaîne user + alerte audit).
+ */
+export declare function rotateRefreshToken(config: RefreshTokenConfig, tokenPlaintext: string, ctx?: {
+    ip?: string;
+    userAgent?: string;
+}): Promise<RotateResult>;
+/** Révoque un refresh token (logout single-device). */
+export declare function revokeRefreshToken(config: RefreshTokenConfig, tokenPlaintext: string): Promise<{
+    revoked: boolean;
+}>;
+/** Révoque tous les tokens d'un user (logout-all, password change, account compromise). */
+export declare function revokeAllUserRefreshTokens(config: RefreshTokenConfig, userId: string): Promise<void>;
+/** Helper pour tests / consumer qui veut vérifier un token sans rotation. */
+export declare function _hashToken(plaintext: string): string;

package/dist/lib/refresh-tokens.js

@@ -0,0 +1,94 @@
+// @mostajs/auth — Refresh tokens with rotation (v2.6.0+)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Refresh tokens rotatifs : à chaque rotation le précédent est marqué `replacedBy`,
+// permettant la détection d'attaque "replay" (un attaquant qui ré-utilise un refresh
+// token déjà rotaté → on révoque toute la chaîne descendante côté server).
+//
+// Le token plaintext n'est JAMAIS stocké — seul `tokenHash` (SHA-256) l'est.
+// Le client garde le plaintext en cookie httpOnly+Secure ou en secure storage SDK.
+//
+// Storage agnostique : le consumer fournit un `RefreshTokenRepo` (DI) — typiquement
+// adossé à `@mostajs/orm` côté Octonet, ou n'importe quel store côté app cliente.
+import crypto from 'node:crypto';
+const DEFAULT_TTL_SEC = 30 * 24 * 3600; // 30 jours
+/** Token plaintext : 256 bits aléatoires en base64url. */
+function generateToken() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+function hashToken(plaintext) {
+    return crypto.createHash('sha256').update(plaintext).digest('hex');
+}
+/**
+ * Émet un nouveau refresh token et persiste son hash.
+ * Appelé après login OK, ou comme étape finale de `rotate`.
+ */
+export async function issueRefreshToken(config, ctx) {
+    const token = generateToken();
+    const tokenHash = hashToken(token);
+    const ttl = config.ttlSec ?? DEFAULT_TTL_SEC;
+    const now = new Date();
+    const record = await config.repo.insert({
+        userId: ctx.userId,
+        tokenHash,
+        expiresAt: new Date(now.getTime() + ttl * 1000),
+        createdAt: now,
+        replacedBy: null,
+        revokedAt: null,
+        ip: ctx.ip ?? null,
+        userAgent: ctx.userAgent ?? null,
+    });
+    return { token, record };
+}
+/**
+ * Vérifie + rotation : ancien token marqué `replacedBy`, nouveau émis.
+ * Détection de replay : si l'ancien a déjà un `replacedBy`, c'est qu'il a été
+ * utilisé une 2ᵉ fois → token volé. On déclenche `onReplayDetected` (typiquement :
+ * révocation totale de la chaîne user + alerte audit).
+ */
+export async function rotateRefreshToken(config, tokenPlaintext, ctx) {
+    if (!tokenPlaintext)
+        return { ok: false, reason: 'not_found' };
+    const tokenHash = hashToken(tokenPlaintext);
+    const old = await config.repo.findByHash(tokenHash);
+    if (!old)
+        return { ok: false, reason: 'not_found' };
+    if (old.revokedAt)
+        return { ok: false, reason: 'revoked' };
+    if (new Date(old.expiresAt) < new Date())
+        return { ok: false, reason: 'expired' };
+    if (old.replacedBy) {
+        // Replay attack : token déjà rotaté ré-utilisé.
+        if (config.onReplayDetected) {
+            await config.onReplayDetected(old).catch(() => { });
+        }
+        await config.repo.revokeAllByUser(old.userId).catch(() => { });
+        return { ok: false, reason: 'replay' };
+    }
+    const issued = await issueRefreshToken(config, {
+        userId: old.userId,
+        ip: ctx?.ip,
+        userAgent: ctx?.userAgent,
+    });
+    await config.repo.setReplacedBy(old.id, issued.record.id);
+    return { ok: true, issued, oldRecord: old };
+}
+/** Révoque un refresh token (logout single-device). */
+export async function revokeRefreshToken(config, tokenPlaintext) {
+    if (!tokenPlaintext)
+        return { revoked: false };
+    const tokenHash = hashToken(tokenPlaintext);
+    const r = await config.repo.findByHash(tokenHash);
+    if (!r || r.revokedAt)
+        return { revoked: false };
+    await config.repo.revokeById(r.id);
+    return { revoked: true };
+}
+/** Révoque tous les tokens d'un user (logout-all, password change, account compromise). */
+export async function revokeAllUserRefreshTokens(config, userId) {
+    await config.repo.revokeAllByUser(userId);
+}
+/** Helper pour tests / consumer qui veut vérifier un token sans rotation. */
+export function _hashToken(plaintext) {
+    return hashToken(plaintext);
+}

package/dist/lib/remote-credentials-provider.d.ts

@@ -46,10 +46,5 @@ export declare function createRemoteCredentialsProvider(config: RemoteCredential
             type: string;
         };
     };
-    authorize(credentials: any): Promise<{
-        id: any;
-        email: any;
-        name: any;
-        role: any;
-    } | null>;
+    authorize(credentials: any): Promise<any>;
 };

package/dist/lib/remote-credentials-provider.js

@@ -116,6 +116,20 @@ export function createRemoteCredentialsProvider(config) {
                 email: user.email,
                 name: user.name,
                 role: user.role,
+                // v3.0.2+ : si Octonet renvoie accountId (via createCredentialsVerifyHandler
+                // configuré avec `resolveAccountId`), on le propage tel quel à NextAuth.
+                // Le consumer (app NextAuth) doit ensuite le propager dans ses callbacks
+                // jwt+session pour qu'il soit visible côté `auth(req)` :
+                //
+                //   async jwt({ token, user }) {
+                //     if (user?.accountId) token.accountId = (user as any).accountId
+                //     return token
+                //   },
+                //   async session({ session, token }) {
+                //     ;(session.user as any).accountId = token.accountId
+                //     return session
+                //   },
+                ...(user.accountId ? { accountId: user.accountId } : {}),
             };
         },
     };

package/dist/lib/webauthn.d.ts

@@ -0,0 +1,159 @@
+import type { PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, AuthenticationResponseJSON, AuthenticatorTransportFuture } from '@simplewebauthn/types';
+export interface WebAuthnCredentialRecord {
+    /** PK opaque côté DB. */
+    id: string;
+    /** User propriétaire — clé d'isolation tenant. */
+    userId: string;
+    /** Credential ID retourné par WebAuthn (base64url). Index unique global recommandé. */
+    credentialId: string;
+    /** Public key COSE encodée base64url (≤ 200 bytes typiquement). */
+    publicKey: string;
+    /** Compteur anti-replay — RFC : strictement croissant côté authenticator. */
+    counter: number;
+    /**
+     * Transports déclarés par l'authenticator (`'usb'|'nfc'|'ble'|'internal'|'hybrid'|'cable'`).
+     * Sert à hint l'UI de login (touch-vs-QR).
+     */
+    transports?: AuthenticatorTransportFuture[];
+    /** Label affiché à l'user dans les settings ("YubiKey 5C", "iCloud Passkey"). */
+    deviceName?: string;
+    /**
+     * Type d'usage prévu. Le module l'utilise pour discriminer les listes :
+     *   - `primary` : utilisable comme primary login (signInWithPasskey)
+     *   - `factor`  : utilisable comme 2nd factor (verifyAsFactor)
+     *   - `both`    : utilisable des deux manières (default user choice)
+     */
+    usage: 'primary' | 'factor' | 'both';
+    createdAt: Date | string;
+    lastUsedAt?: Date | string | null;
+}
+export interface WebAuthnCredentialRepo {
+    insert(record: Omit<WebAuthnCredentialRecord, 'id'>): Promise<WebAuthnCredentialRecord>;
+    findById(id: string): Promise<WebAuthnCredentialRecord | null>;
+    findByCredentialId(credentialId: string): Promise<WebAuthnCredentialRecord | null>;
+    findByUser(userId: string): Promise<WebAuthnCredentialRecord[]>;
+    /** Met à jour counter + lastUsedAt après un verify réussi. */
+    updateAfterUse(id: string, args: {
+        counter: number;
+        lastUsedAt: Date;
+    }): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export interface WebAuthnChallengeStore {
+    /** Persiste un challenge avec TTL court — clé par session opaque (cookie / sid). */
+    put(key: string, challenge: string, expiresAt: Date): Promise<void>;
+    /** Lit + supprime atomiquement (replay protection). */
+    consume(key: string): Promise<{
+        challenge: string;
+    } | null>;
+}
+export interface WebAuthnConfig {
+    /** RP ID = eTLD+1 (ex: 'example.com'). NE PAS inclure de port ni de path. */
+    rpID: string;
+    /** Nom du service affiché à l'authenticator (ex: 'Octonet'). */
+    rpName: string;
+    /**
+     * Origines HTTPS acceptées (ex: ['https://app.example.com', 'https://auth.example.com']).
+     * Doit inclure toutes les origines depuis lesquelles le browser peut initier la cérémonie.
+     */
+    expectedOrigins: string[];
+    /** TTL d'un challenge en secondes (default 300 = 5 min). */
+    challengeTtlSec?: number;
+    /**
+     * Type d'attestation requis (`'none'` par défaut — passkeys grand-public ;
+     * `'direct'` pour FIDO2 entreprise / hardware key avec cert chain).
+     */
+    attestationType?: 'none' | 'direct' | 'enterprise';
+    /** authenticatorAttachment requis (default: aucune contrainte). */
+    authenticatorAttachment?: 'platform' | 'cross-platform';
+    /** residentKey requis ('required' = passkey discoverable ; 'preferred' = OK). */
+    residentKey?: 'required' | 'preferred' | 'discouraged';
+    /** userVerification requis (default 'preferred'). */
+    userVerification?: 'required' | 'preferred' | 'discouraged';
+}
+export interface StartRegistrationArgs {
+    config: WebAuthnConfig;
+    challengeStore: WebAuthnChallengeStore;
+    /** Clé de session opaque (cookie sid, etc.) pour stocker le challenge transient. */
+    sessionKey: string;
+    user: {
+        id: string;
+        /** Nom utilisé par l'authenticator (typiquement email). */
+        name: string;
+        /** Display-name (ex: "Alice Dupont"). */
+        displayName: string;
+    };
+    /** Pour exclure de la sélection les credentials déjà enregistrés (anti double-enroll). */
+    existingCredentials?: WebAuthnCredentialRecord[];
+}
+export declare function startRegistration(args: StartRegistrationArgs): Promise<PublicKeyCredentialCreationOptionsJSON>;
+export interface VerifyRegistrationArgs {
+    config: WebAuthnConfig;
+    challengeStore: WebAuthnChallengeStore;
+    sessionKey: string;
+    userId: string;
+    response: RegistrationResponseJSON;
+    /** Label saisi par l'user pour ce device ("YubiKey", "iPhone 15"). */
+    deviceName?: string;
+    /** Usage prévu (default: 'both'). */
+    usage?: 'primary' | 'factor' | 'both';
+}
+export type VerifyRegistrationResult = {
+    ok: true;
+    record: WebAuthnCredentialRecord;
+} | {
+    ok: false;
+    reason: 'no_challenge' | 'verification_failed';
+};
+export declare function finishRegistration(repo: WebAuthnCredentialRepo, args: VerifyRegistrationArgs): Promise<VerifyRegistrationResult>;
+export interface StartAuthenticationArgs {
+    config: WebAuthnConfig;
+    challengeStore: WebAuthnChallengeStore;
+    sessionKey: string;
+    /**
+     * Si on connaît l'user (login après email entré), on peut limiter aux credentials
+     * de cet user. Sinon (conditional UI / autofill), laisser undefined → discoverable.
+     */
+    allowedCredentials?: WebAuthnCredentialRecord[];
+}
+export declare function startAuthentication(args: StartAuthenticationArgs): Promise<PublicKeyCredentialRequestOptionsJSON>;
+export interface VerifyAuthenticationArgs {
+    config: WebAuthnConfig;
+    challengeStore: WebAuthnChallengeStore;
+    sessionKey: string;
+    response: AuthenticationResponseJSON;
+    /** Mode attendu : refuse si le credential trouvé n'est pas compatible. */
+    expectedUsage: 'primary' | 'factor';
+}
+export type VerifyAuthenticationResult = {
+    ok: true;
+    userId: string;
+    credentialId: string;
+    method: 'webauthn';
+} | {
+    ok: false;
+    reason: 'no_challenge' | 'unknown_credential' | 'wrong_usage' | 'verification_failed' | 'counter_mismatch';
+};
+/**
+ * Vérifie une réponse d'authentification — utilisable en primary OU 2nd factor selon
+ * `expectedUsage`. Le caller décide ensuite quoi faire avec le `userId` retourné.
+ */
+export declare function finishAuthentication(repo: WebAuthnCredentialRepo, args: VerifyAuthenticationArgs): Promise<VerifyAuthenticationResult>;
+export interface PasskeyListItem {
+    id: string;
+    deviceName?: string;
+    usage: 'primary' | 'factor' | 'both';
+    createdAt: Date | string;
+    lastUsedAt?: Date | string | null;
+    /** Nombre de transports — peut hint à l'UI le type d'authenticator. */
+    transports?: AuthenticatorTransportFuture[];
+}
+export declare function listPasskeys(repo: WebAuthnCredentialRepo, userId: string): Promise<PasskeyListItem[]>;
+/** Le caller DOIT exiger une preuve fraîche d'identité avant d'appeler — on supprime point. */
+export declare function removePasskey(repo: WebAuthnCredentialRepo, args: {
+    credentialId: string;
+    userId: string;
+}): Promise<{
+    ok: boolean;
+    reason?: 'not_found' | 'not_owner';
+}>;