---
title: "Référence d'API — nodefony/client — auth"
source: docs/api/core/client-auth.md
url: https://nodefony.github.io/nodefony-core/docs/api/core/client-auth/
---


[Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › client-auth

> Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.6** : 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/client`

`import { … } from "nodefony/client"` — 10 symboles.

### Classes (1)

#### `NodefonyLogin`

```ts
class NodefonyLogin
```

Le **déroulé de connexion** côté navigateur : une machine à états PURE, sans DOM ni framework d'affichage, branchée sur les routes de session du framework. Le pendant de `NodefonySocket` et de `NodefonySse` pour l'authentification.

- `constructor(options?: NodefonyLoginOptions)`
- `readonly getState: () => NodefonyLoginState` — État courant — le même objet tant que rien n'a changé.
- `readonly subscribe: (listener: (state: NodefonyLoginState) => void) => () => void` — Écoute les changements d'état.
- `submitIdentifier(identifier: string): void` — Valide le compte saisi et passe à l'étape `password`.
- `submitPassword(password: string): Promise<NodefonyLoginState>` — Envoie le mot de passe du compte saisi.
- `login(identifier: string, password: string): Promise<NodefonyLoginState>` — Raccourci des formulaires d'un seul écran : compte et mot de passe d'un coup.
- `submitMfaCode(code: string): Promise<NodefonyLoginState>` — Envoie le code du second facteur (TOTP ou code de récupération).
- `loginWithPasskey(): Promise<NodefonyLoginState>` — Connexion par passkey, sans identifiant ni mot de passe.
- `loadProviders(): Promise<readonly NodefonyLoginProvider[]>` — Charge la liste des fournisseurs (une requête, rejouée seulement après échec).
- `startProvider(name: string, from?: string, back?: string): void` — Part chez un fournisseur, en navigation PLEINE PAGE — jamais par `fetch` : le navigateur doit suivre les redirections et revenir avec le cookie de session posé au retour.
- `me(): Promise<NodefonyLoginUser | null>` — Reprend une session existante ; `null` quand il n'y en a pas.
- `logout(): Promise<string | null>` — Ferme la session et revient à l'étape `identifier`.
- `back(): void` — Revient à l'étape `identifier`, en gardant le compte saisi.

### Fonctions (1)

#### `observeLogin`

```ts
function observeLogin(login: NodefonyLogin, onChange: (state: NodefonyLoginState) => void): () => void
```

Relaie l'état d'un `NodefonyLogin` vers un rappel : une fois tout de suite, puis à chaque changement. C'est le seul point d'attache des liaisons `nodefony/{react,vue,svelte,angular}` — même forme que `observeSse`.

### Interfaces (6)

#### `NodefonyLoginError`

```ts
interface NodefonyLoginError
```

Échec classé de la dernière action.

- `readonly kind: LoginErrorKind`
- `readonly message: string` — Message du serveur, relayé TEL QUEL — en particulier le refus uniforme d'un 401, qui ne doit jamais être reformulé : le préciser côté client dirait à un inconnu si le compte existe.
- `readonly status: number | null` — Statut HTTP, `null` quand le serveur n'a pas répondu.
- `readonly retryAt: number | null` — Fin du blocage (millisecondes depuis l'époque) — seulement pour `throttled`.

#### `NodefonyLoginOptions`

```ts
interface NodefonyLoginOptions
```

Réglages de `NodefonyLogin` — tous facultatifs.

- `readonly baseUrl?: string` — Origine du serveur ; vide = même origine que la page.
- `readonly identifier?: string` — Compte prérempli (le dernier utilisé, mémorisé par l'application).
- `readonly fetch?: typeof fetch` — `fetch` à employer ; défaut : celui du navigateur.
- `readonly navigate?: (url: string) => void` — Navigation pleine page vers un fournisseur ; défaut : `location.assign`.
- `readonly passkey?: NodefonyPasskeyAgent | null` — Signataire de passkey ; défaut : l'API WebAuthn native, si elle est complète.
- `readonly now?: () => number` — Horloge (ms) ; défaut : `Date.now`.
- `readonly defaultRetryAfterS?: number` — Attente appliquée quand un 429 ne dit pas combien de temps (secondes).

#### `NodefonyLoginProvider`

```ts
interface NodefonyLoginProvider
```

Fournisseur de connexion, tel que le SERVEUR le présente.

- `readonly name: string`
- `readonly label: string`

#### `NodefonyLoginState`

```ts
interface NodefonyLoginState
```

Photographie du déroulé — un objet NEUF à chaque changement, jamais muté.

- `readonly step: LoginStep`
- `readonly identifier: string` — Compte saisi (ou rendu par le serveur une fois connecté).
- `readonly pending: boolean` — Une requête est en vol : l'écran désactive ses boutons.
- `readonly user: NodefonyLoginUser | null` — Identité de la session, `null` tant qu'elle n'est pas ouverte.
- `readonly mfaMethods: readonly string[]` — Seconds facteurs proposés par le serveur à l'étape `mfa`, réduits à ceux que ce client sait conduire (aujourd'hui `totp`).
- `readonly error: NodefonyLoginError | null`
- `readonly providers: readonly NodefonyLoginProvider[] | null` — Fournisseurs configurés ; `null` tant que `NodefonyLogin.loadProviders` n'a pas répondu.
- `readonly passkeyAvailable: boolean` — Le navigateur sait-il signer avec une passkey ?

#### `NodefonyLoginUser`

```ts
interface NodefonyLoginUser
```

Identité rendue par le serveur une fois la session ouverte.

- `readonly id: number | string`
- `readonly identifier: string` — Identifiant de connexion (login, e-mail, sujet fédéré) — le même que `IUser.identifier`.
- `readonly email?: string`
- `readonly roles: readonly string[]`
- `readonly [field: string]: unknown`

#### `NodefonyPasskeyAgent`

```ts
interface NodefonyPasskeyAgent
```

Ce qui signe un défi WebAuthn. Par défaut, l'API native du navigateur ; injectable pour un test, ou pour une bibliothèque qui couvre les navigateurs anciens.

- `sign(options: unknown): Promise<unknown>` — Fait signer le défi par l'authentificateur de l'utilisateur.

### Types (2)

#### `LoginErrorKind`

```ts
type LoginErrorKind = "credentials" | "throttled" | "network" | "server" | "cancelled" | "unsupported"
```

Nature d'un échec, classée pour que l'écran sache QUOI dire.

#### `LoginStep`

```ts
type LoginStep = "identifier" | "password" | "mfa" | "authenticated"
```

Étape du déroulé de connexion.

---

[← Toutes les références d'API](../../)