Authentification

Choisir le bon mécanisme

Session web OrbitWake

Après une authentification réussie, OrbitWake crée un token aléatoire de 32 octets encodé en base64url.

Le token brut est envoyé au navigateur dans le cookie :

orbitwake_session

Côté base de données, OrbitWake stocke uniquement le hash SHA-256 du token de session.

Propriétés du cookie

Le cookie de session actuel est configuré avec :

La session stockée côté serveur expire également après 30 jours.

Validation d’une session

Les routes protégées appellent généralement getCurrentUser().

Cette fonction :

1. lit le cookie orbitwake_session ;
2. calcule son hash SHA-256 ;
3. cherche une session correspondante non expirée ;
4. charge l’utilisateur et son workspace principal.

Si le cookie est absent, inconnu ou expiré, la route protégée répond généralement :

401
{
  "error": "Authentication required."
}

Routes d’authentification web

Le routeur actuel expose les actions suivantes sous /api/auth/:action :

Turnstile sur les actions sensibles

Les actions suivantes passent actuellement par la vérification Cloudflare Turnstile :

• sign-up ;
• sign-in ;
• request-password-reset ;
• resend-verification.

Le backend transmet aussi l’adresse IP cliente résolue via Cloudflare ou x-forwarded-for au mécanisme de vérification Turnstile.

Mots de passe

Le mot de passe utilisateur est hashé avec scrypt, un sel aléatoire de 16 octets et une sortie de 64 octets.

La longueur minimale actuelle est de 8 caractères.

Le hash stocké utilise un format interne qui inclut le schéma, le sel et le hash dérivé. Le mot de passe brut n’est pas stocké.

Vérification email

Après inscription, OrbitWake crée un token aléatoire à usage unique pour la vérification email.

Le token :

• est généré à partir de 32 octets aléatoires ;
• est stocké côté serveur sous forme de hash SHA-256 ;
• expire après 30 minutes ;
• est marqué utilisé après consommation.

Une vérification réussie crée aussi une nouvelle session web pour l’utilisateur.

Réinitialisation du mot de passe

Le token de reset suit le même principe : valeur aléatoire côté client, hash SHA-256 côté serveur.

La durée actuelle est de 20 minutes.

Après un reset réussi, OrbitWake supprime toutes les sessions web existantes de l’utilisateur.

Un cooldown de 60 secondes est appliqué avant de recréer certains tokens de vérification ou de reset pour le même compte.

Déconnexion web

POST /api/auth/sign-out :

1. lit le token du cookie courant ;
2. supprime la session serveur correspondante ;
3. réécrit le cookie avec une durée de vie nulle.

Cette déconnexion web ne révoque pas automatiquement une session IDE VS Code déjà pairée.

Authentification ≠ autorisation

Être authentifié ne garantit pas l’accès à toutes les fonctionnalités.

Par exemple, les routes AI peuvent répondre :

403
{
  "error": "OrbitWake AI is not available for this account."
}

Le 401 indique généralement qu’aucune identité valide n’est établie. Le 403 signifie généralement que l’identité est connue mais que l’action n’est pas autorisée dans ce contexte.

Authentification IDE

Les routes Ask et Agent de l’extension VS Code n’utilisent pas le cookie orbitwake_session.

Elles utilisent :

Authorization: Bearer <ide-token>

Le token IDE est généré à partir de 32 octets aléatoires. Le serveur stocke uniquement son hash SHA-256 dans ide_sessions.

Pairing IDE

Le flux est composé de deux étapes :

1. une session web authentifiée crée un pairing code via POST /api/ide/pairing ;
2. VS Code réclame le code via POST /api/ide/pairing/claim.

Le code est à usage unique, expire après 10 minutes et son hash SHA-256 est stocké côté serveur.

Le claim retourne un sessionId, le workspaceId et le token IDE brut.

Validation et révocation IDE

À chaque requête IDE protégée, OrbitWake :

1. lit le Bearer token ;
2. calcule son hash ;
3. cherche une session avec status = active et revoked_at IS NULL ;
4. met à jour last_seen_at.

Les sessions sont listées depuis le web avec :

GET /api/ide/sessions

La révocation utilise :

DELETE /api/ide/sessions/:sessionId

Expiration du token IDE

Dans le runtime actuel, la session IDE ne possède pas de date d’expiration autonome explicitement vérifiée comme la session web.

Elle reste utilisable tant que son statut est actif et qu’elle n’a pas été révoquée.

Cette différence doit être prise en compte lorsque l’on compare session web et session IDE.

Routes sans authentification

Certaines routes sont volontairement publiques, par exemple la recherche de domaine ou certains catalogues/configurations publiques.

L’absence de credential sur une route précise ne signifie pas que les autres routes sous /api/ sont publiques.

Vérifiez toujours le contrat de l’endpoint concerné.

Bearer interne admin

Le repo possède aussi une route interne beta qui lit :

Authorization: Bearer <internal-admin-token>

Le secret attendu provient de la configuration serveur et est comparé en temps constant.

Secrets de webhooks

Les webhooks entrants peuvent utiliser un mécanisme spécifique au provider.

Le webhook Brevo actuel compare par exemple un token fourni dans l’URL avec le secret attendu côté serveur, en utilisant une comparaison en temps constant.

Les secrets de webhook sont destinés à vérifier l’origine d’un callback ; ils ne donnent pas accès à l’API produit.

Ce qui n’est pas une clé API

Appels API depuis le navigateur OrbitWake

Les clients web officiels peuvent appeler les routes protégées dans le contexte de la session OrbitWake, le navigateur envoyant le cookie selon ses règles normales.

La documentation actuelle ne recommande pas de copier ou extraire le cookie pour l’utiliser avec des scripts externes.

Intégrations externes

OrbitWake ne propose pas encore de mécanisme d’authentification public pour applications tierces comparable à une clé API utilisateur ou à un OAuth développeur public.

Pour cette raison, les routes produit actuelles ne doivent pas être présentées comme une API externe stable à consommer avec un script serveur indépendant.

Erreurs d’authentification courantes

Frontières de sécurité à respecter

• ne jamais envoyer le cookie web dans un dépôt, un log ou un service tiers ;
• ne jamais utiliser un token IDE pour appeler des routes web générales ;
• ne jamais exposer un token admin ou webhook dans du JavaScript client ;
• ne jamais stocker un token de pairing ou de reset comme credential permanent ;
• ne pas confondre authentification et autorisation de fonctionnalité.

Limites actuelles

Il n’existe pas encore de clé API publique, OAuth développeur public, scopes API externes ou endpoint public de rotation de clés.

La session web reste orientée produit navigateur, tandis que le Bearer token IDE est une credential spécialisée pour l’éditeur.

Une future API publique devra définir séparément son format de credential, ses scopes, sa rotation, sa révocation et son versioning.

Étape suivante

La page Requêtes détaillera les méthodes HTTP, JSON, paramètres, pièces jointes, idempotency et conventions actuellement observées dans les routes OrbitWake.