Référence d'API — @nodefony/security — totp

stable

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#

class MemoryTotpSecretStore implements ITotpSecretStore

• findByUser(userId: string): Promise<ITotpSecret | null> — Secret TOTP de l’utilisateur, ou null si non enrôlé.
• save(secret: ITotpSecret): Promise<void> — Crée ou remplace le secret de l’utilisateur (upsert — ré-enrôlement).
• update(userId: string, patch: TotpSecretUpdate): Promise<void> — Applique un patch partiel (confirmation, anti-rejeu, consommation de codes).
• delete(userId: string): Promise<void> — Supprime le secret de l’utilisateur (désactivation du 2FA).
• listPage(query: ITotpListQuery): Promise<IPage<ITotpEnrollmentSummary>> — {@inheritDoc ITotpSecretStore.listPage}
• countEnrollments(query: ITotpListQuery): Promise<number> — {@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#

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#

function beginTotpEnrollment(deps: ITotpDeps, userId: string, account: string): Promise<ITotpEnrollment>

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#

function confirmTotpEnrollment(deps: ITotpDeps, userId: string, code: string): Promise<ITotpActivation>

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#

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#

function disableTotp(deps: ITotpDeps, userId: string): Promise<void>

Désactive le 2FA (retire le secret et les codes de récupération).

getTotpStoreFactory#

function getTotpStoreFactory(name: string): TotpStoreFactory

Fabrique d’un store par nom, ou undefined si inconnu.

listTotpStores#

function listTotpStores(): string[]

Noms enregistrés (validation boot, introspection Studio, tests).

registerTotpStore#

function registerTotpStore(name: string, factory: TotpStoreFactory): void

Enregistre (ou remplace) la fabrique d’un store de secrets TOTP.

totpCode#

function totpCode(secret: Buffer, opts?: ITotpOptions): string

Calcule le code TOTP courant (RFC 6238 §4) pour un secret donné.

totpStatus#

function totpStatus(deps: ITotpDeps, userId: string): Promise<ITotpStatus>

État 2FA d’un utilisateur (absent / pending / activé + codes restants).

verifyTotpLogin#

function verifyTotpLogin(deps: ITotpDeps, userId: string, code: string): Promise<ITotpLoginResult>

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#

interface ITotpActivation

Résultat de l’activation — codes de récupération clairs, affichés 1×.

• recoveryCodes: string[]

ITotpDeps#

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#

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#

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#

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#

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#

interface TotpStoreSnapshot

Instantané sérialisable de l’état — base de la persistance fichier.

• secrets: ITotpSecret[]

Types (1)#

TotpStoreFactory#

type TotpStoreFactory = (ctx: ITotpStoreFactoryContext) => ITotpSecretStore

Fabrique d’un store de secrets TOTP pour un nom donné.

← Toutes les références d’API