OAuth2Manager

Présentation

OAuth2Manager est une classe de gestion complète du flux OAuth 2.0 côté Node.js, conçue pour simplifier :

• l’authentification initiale via navigateur,
• l’échange du code contre un token,
• la persistance des tokens,
• le rafraîchissement automatique,
• l’émission d’événements applicatifs.

Elle étend DOMStyleEmitter, ce qui permet d’exposer un cycle de vie événementiel clair (Authorized, Error) exploitable par le reste de l’application.

---

Objectifs

• Centraliser la logique OAuth 2.0
• Automatiser le rafraîchissement des tokens
• Éviter les authentifications manuelles répétées
• Fournir une API simple pour effectuer des requêtes authentifiées
• Notifier l’application via des événements

---

Architecture

• Pattern : Manager + Événementiel
• Persistance : fichier JSON (token.json)
• Flux OAuth : Authorization Code Grant
• Serveur local : Express
• Ouverture navigateur : automatique (open)
• Gestion du refresh : setTimeout

---

Dépendances

import fs from "fs";
import path from "path";
import express from "express";
import open from "open";
import { v4 as uuidv4 } from "uuid";
import { DOMStyleEmitter } from "./DOMStyleEmitter.js";

---

Types et interfaces

Credentials

interface Credentials {
  client_id: string;
  client_secret: string;
  redirect_uris: string[];
  auth_uri: string;
  token_uri: string;
  scopes: string[];
  extra_params: { [key: string]: string };
}

Représente le contenu du fichier de credentials OAuth.

---

TokenData

interface TokenData {
  access_token: string;
  refresh_token?: string;
  expires_in: number;
  token_type: string;
  created_at: number;
  refresh_token_expires_in?: number;
}

Stocke les données de token et leurs métadonnées temporelles.

---

Option

type Option = {
  port: number;
  url: string;
};

Configuration du serveur local OAuth.

---

Initialisation

const manager = new OAuth2Manager(
  "./credentials.json",
  "./token.json",
  { port: 3000, url: "/oauth2callback" }
);

---

Cycle de vie général

run()

Point d’entrée principal du manager.

manager.run();

Comportement :

1. Charge le token existant
2. Vérifie sa validité
3. Rafraîchit si nécessaire
4. Lance l’authentification si aucun token valide
5. Programme le rafraîchissement automatique
6. Émet l’événement Authorized

---

Authentification OAuth

getAuthUrl()

Construit l’URL d’autorisation OAuth avec génération d’un state unique.

const url = manager.getAuthUrl();

Inclut :

• scopes
• redirect URI
• paramètres additionnels (extra_params)

---

Auth()

Démarre le flux OAuth interactif :

• lance un serveur Express local
• ouvre automatiquement le navigateur
• écoute le callback OAuth
• échange le code contre un token
• ferme le serveur après succès ou échec

manager.Auth();

Avertissement

Le serveur se ferme automatiquement après 5 minutes en cas d’inactivité.

---

Gestion des tokens

Chargement

private loadToken()

Charge le token depuis le disque si présent.

---

Sauvegarde

private saveToken(token: TokenData)

Persiste le token et met à jour l’état interne.

---

Vérification d’expiration

isTokenExpired(): boolean
isRefreshTokenExpired(): boolean

Les tokens sont considérés expirés 1 minute avant leur expiration réelle.

---

Rafraîchissement automatique

refreshAccessToken(): Promise<void>

• utilise le refresh_token
• conserve l’ancien refresh token si nécessaire
• reprogramme automatiquement le prochain refresh
• émet Authorized

---

Accès au token

getAccessToken()

const token = await manager.getAccessToken();

• rafraîchit automatiquement si nécessaire
• lève une erreur si aucune autorisation valide n’est disponible

---

Requêtes authentifiées

Request

const response = await manager.Request(
  "https://api.example.com/user",
  { method: "GET" }
);

Ajoute automatiquement l’en-tête :

Authorization: Bearer <access_token>

---

Événements

Grâce à DOMStyleEmitter, OAuth2Manager expose des événements.

Types disponibles

static EventType = {
  Error: "Error",
  Authorized: "Authorized",
};

---

Exemple d’écoute

manager.addEventListener(
  OAuth2Manager.EventType.Authorized,
  () => {
    console.log("Authentification valide");
  }
);

manager.addEventListener(
  OAuth2Manager.EventType.Error,
  () => {
    console.error("Erreur OAuth");
  }
);

---

Sécurité et bonnes pratiques

• Ne jamais versionner credentials.json
• Stocker les tokens hors du dépôt Git
• Restreindre les scopes au strict nécessaire
• Surveiller l’expiration du refresh token
• Utiliser HTTPS en production

---

Limites connues

• Flux OAuth interactif uniquement
• Un seul token géré par instance
• Pas de rotation multi-utilisateur
• Pas de support PKCE (actuellement)

---

Conclusion

OAuth2Manager est une solution clé en main pour gérer OAuth 2.0 dans une application Node.js. Son intégration événementielle, son rafraîchissement automatique et son API simple en font un composant robuste et extensible pour interagir avec des API sécurisées.