--- title: "Référence d'API — @nodefony/security — totp" source: docs/api/security/totp.md url: https://nodefony.github.io/nodefony-core/docs/api/security/totp/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/security`](../) › totp > Générée depuis les déclarations de types publiées de `@nodefony/security` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `@nodefony/security` `import { … } from "@nodefony/security"` — 20 symboles. ### Classes (1) #### `MemoryTotpSecretStore` ```ts class MemoryTotpSecretStore implements ITotpSecretStore ``` - `findByUser(userId: string): Promise` — Secret TOTP de l'utilisateur, ou `null` si non enrôlé. - `save(secret: ITotpSecret): Promise` — Crée ou remplace le secret de l'utilisateur (upsert — ré-enrôlement). - `update(userId: string, patch: TotpSecretUpdate): Promise` — Applique un patch partiel (confirmation, anti-rejeu, consommation de codes). - `delete(userId: string): Promise` — Supprime le secret de l'utilisateur (désactivation du 2FA). - `listPage(query: ITotpListQuery): Promise>` — {@inheritDoc ITotpSecretStore.listPage} - `countEnrollments(query: ITotpListQuery): Promise` — {@inheritDoc ITotpSecretStore.countEnrollments} - `snapshot(): TotpStoreSnapshot` — Instantané sérialisable de l'état courant (pour la persistance fichier). - `restore(snapshot: TotpStoreSnapshot): void` — Remplace l'état par celui d'un instantané. ### Fonctions (11) #### `base32Decode` ```ts function base32Decode(input: string): Buffer ``` Décode une chaîne base32 RFC 4648 → octets. Tolérant : ignore espaces, tirets et padding `=`, insensible à la casse (un secret peut être saisi à la main par l'utilisateur). Lève si un caractère hors alphabet est rencontré. #### `beginTotpEnrollment` ```ts function beginTotpEnrollment(deps: ITotpDeps, userId: string, account: string): Promise ``` Démarre l'enrôlement : génère un secret aléatoire, le **chiffre** au repos et l'enregistre en attente de confirmation (`confirmedAt: null`). Retourne le secret en clair (base32 + URI) — **seul moment** où il est exposé. Idempotent : un nouvel appel écrase un enrôlement non confirmé (re-scan du QR). #### `confirmTotpEnrollment` ```ts function confirmTotpEnrollment(deps: ITotpDeps, userId: string, code: string): Promise ``` Confirme l'enrôlement : vérifie un 1ᵉʳ code généré par l'app, **active** le 2FA et génère les codes de récupération (retournés clairs 1×, hachés au repos). Le step de confirmation est marqué consommé (anti-rejeu). Lève si aucun enrôlement n'est en cours, s'il est déjà confirmé, ou si le code est invalide (reste pending). #### `deriveTotpKey` ```ts function deriveTotpKey(material: string | Buffer): Buffer ``` Dérive la clé AES-256 du domaine TOTP via HKDF-SHA256 (RFC 5869). Déterministe (clé lisible cross-pod). Délègue à `deriveKey` avec le contexte figé du domaine TOTP. #### `disableTotp` ```ts function disableTotp(deps: ITotpDeps, userId: string): Promise ``` Désactive le 2FA (retire le secret et les codes de récupération). #### `getTotpStoreFactory` ```ts function getTotpStoreFactory(name: string): TotpStoreFactory ``` Fabrique d'un store par nom, ou `undefined` si inconnu. #### `listTotpStores` ```ts function listTotpStores(): string[] ``` Noms enregistrés (validation boot, introspection Studio, tests). #### `registerTotpStore` ```ts function registerTotpStore(name: string, factory: TotpStoreFactory): void ``` Enregistre (ou remplace) la fabrique d'un store de secrets TOTP. #### `totpCode` ```ts function totpCode(secret: Buffer, opts?: ITotpOptions): string ``` Calcule le code TOTP courant (RFC 6238 §4) pour un secret donné. #### `totpStatus` ```ts function totpStatus(deps: ITotpDeps, userId: string): Promise ``` État 2FA d'un utilisateur (absent / pending / activé + codes restants). #### `verifyTotpLogin` ```ts function verifyTotpLogin(deps: ITotpDeps, userId: string, code: string): Promise ``` Vérifie un second facteur au login : d'abord un code TOTP (fenêtre ±window, **anti-rejeu** via `lastUsedStep`), à défaut un code de récupération (consommé, usage unique). Retourne `ok: false` si le 2FA n'est pas activé ou si rien ne correspond — **jamais d'exception** (chemin d'authentification). ### Interfaces (7) #### `ITotpActivation` ```ts interface ITotpActivation ``` Résultat de l'activation — codes de récupération **clairs**, affichés 1×. - `recoveryCodes: string[]` #### `ITotpDeps` ```ts interface ITotpDeps ``` Dépendances résolues d'une opération TOTP — **injectées** (store, clé de chiffrement, horloge) pour rendre toute la logique métier testable sans kernel ni serveur. `TotpService` les résout au boot puis délègue ici (même esprit que le verdict neutre d'idempotence). - `store: ITotpSecretStore` - `key: Buffer` — Clé AES-256 de (dé)chiffrement du secret au repos (dérivée par le service). - `now: () => number` — Horloge en ms — injectable pour les tests ; runtime = `Date.now`. - `issuer: string` - `algorithm: TotpAlgorithm` - `digits: number` - `period: number` - `window: number` - `recoveryCodesCount: number` #### `ITotpEnrollment` ```ts interface ITotpEnrollment ``` Données d'enrôlement présentées **une seule fois** (QR + saisie manuelle). - `secretBase32: string` — Secret en base32 (scanné via le QR ou saisi à la main). - `otpauthUri: string` — URI `otpauth://` encodé dans le QR code. #### `ITotpLoginResult` ```ts interface ITotpLoginResult ``` Résultat d'une vérification de second facteur au login. - `ok: boolean` - `method?: "totp" | "recovery"` — Méthode ayant validé (utile pour l'audit). #### `ITotpStatus` ```ts interface ITotpStatus ``` État 2FA d'un utilisateur (UI self-service / Studio). - `enabled: boolean` — 2FA activé (enrôlement confirmé). - `pending: boolean` — Enrôlement commencé, pas encore confirmé. - `recoveryCodesRemaining: number` — Codes de récupération restants (non consommés). #### `ITotpStoreFactoryContext` ```ts interface ITotpStoreFactoryContext ``` Registre de **fabriques de stores de secrets TOTP** — résout un nom (`memory`, `file`, `drizzle`, `mongoose`, `redis`…) vers une instance, SANS coupler le cœur à un backend en dur. - `readonly container: Container` — Container DI — résolution de services (ORM, redis…). - `readonly config: ISecurityConfig` — Config sécurité validée + gelée. #### `TotpStoreSnapshot` ```ts interface TotpStoreSnapshot ``` Instantané sérialisable de l'état — base de la persistance fichier. - `secrets: ITotpSecret[]` ### Types (1) #### `TotpStoreFactory` ```ts type TotpStoreFactory = (ctx: ITotpStoreFactoryContext) => ITotpSecretStore ``` Fabrique d'un store de secrets TOTP pour un nom donné. --- [← Toutes les références d'API](../../)