Voici les Spécifications Techniques (PRD) pour la stack de développement globale de Circuy et son système d'authentification/identification.

📄 Spec Technique : Stack Globale & Système d'Authentification (Circuy)

1. Choix de la Stack Technique Globale

L'architecture est découpée en 3 briques indépendantes partageant le même langage ( TypeScript ) pour maximiser la réutilisation des types et des contrats d'API.

                                  ┌───────────────────────────────────┐
                                  │ Extension Chrome (WXT / TS)       │
                                  └─────────────────┬─────────────────┘
                                                    │
┌───────────────────────────────────┐               │ REST / gRPC / WebSockets
│ SDK Client (Vanilla TS / Shepherd)├───────────────┼──────────────────┐
└───────────────────────────────────┘               │                  │
                                                    ▼                  ▼
                                  ┌───────────────────────────────────┐
                                  │ Backend & API (Node.js / Hono)    │
                                  └─────────────────┬─────────────────┘
                                                    │
                                                    ▼
                                  ┌───────────────────────────────────┐
                                  │ Base de données (PostgreSQL)      │
                                  └───────────────────────────────────┘

1.1 Extension Chrome (Éditeur No-Code)

• Langage : TypeScript (Mandatoire pour la communication inter-scripts typée et la manipulation du DOM).
• Framework d'Extension : WXT (Web Extension Tools) .
• Pourquoi : Basé sur Vite, gère nativement le Hot Reloading, le typage strict Manifest V3 et la compilation multi-navigateurs (Chrome, Edge, Firefox, Safari) à partir d'un seul codebase.
• UI de l'Extension (Popup & Panel) : React + Tailwind CSS .

1.2 SDK JS Client (Le script embarqué chez le client)

• Langage : Vanilla TypeScript (Zero dépendance externe lourde).
• Moteur d'UI & Positionnement : Shepherd.js + @floating-ui/dom .
• Bundler : tsup (basé sur esbuild) pour générer un fichier unique minifié < 15 KB (gzippé).
• Isolation : Shadow DOM (mode: 'closed').

1.3 Backend & Infrastructure (API & Cloud Souverain)

• Runtime / Framework : Node.js + Hono (ou Fastify ).
• Pourquoi : Hono offre des performances extrêmes, un support natif de TypeScript et un typage partagé bout en bout (RPC Client/Server).
• Base de données : PostgreSQL avec Drizzle ORM (Léger, ultra-rapide et 100% typé en TypeScript).
• Hébergement Souverain (EU/RGPD) : Scaleway ou OVHcloud (Instances Kapsule / Kubernetes ou Serverless + Object Storage S3 pour la distribution CDN du SDK).

2. Spécification du Système d'Authentification & SSO

Pour offrir une expérience fluide tout en respectant les contraintes strictes des extensions web (Manifest V3) et du RGPD, le système repose sur un Modèle d'Authentification Hybride (SSO / Passkey) basé sur des Tokens JWT courts et Refresh Tokens .

2.1 Les 2 Méthodes de Connexion Supportées

1. SSO OAuth 2.0 / OpenID Connect (OIDC) : Google, Microsoft, GitHub.
2. Passkeys (WebAuthn / FIDO2) : Authentification biométrique (Touch ID, Face ID, Windows Hello).

2.2 Architecture & Flux d'Authentification dans l'Extension

L'authentification par Passkey (WebAuthn) exige un domaine d'origine certifié. Comme l'extension s'exécute sur le protocole chrome-extension://, la meilleure pratique UX/Sécurité consiste à déléguer l'authentification à la plateforme web app.circuy.com via chrome.identity.launchWebAuthFlow.

┌─────────────────┐       1. Clic "Se connecter"       ┌──────────────────┐
│  Extension UI   │───────────────────────────────────►│ Browser Identity │
└─────────────────┘                                    └────────┬─────────┘
        ▲                                                       │
        │                                                       │ 2. Ouvre Pop-up OAuth / WebAuthn
        │                                                       ▼
        │                                              ┌──────────────────┐
        │                                              │  app.circuy.com  │
        │                                              │ (Passkey / SSO)  │
        │                                              └────────┬─────────┘
        │                                                       │
        │         4. Redirection avec Token JWT                 │ 3. Validation Biométrie
        └───────────────────────────────────────────────────────┘    ou Provider OAuth

Déroulement du Flux (Step-by-Step) :

1. Trigger : Le créateur ouvre l'extension Chrome et clique sur "Se connecter via app.circuy.com" .
2. WebAuthFlow : L'extension déclenche chrome.identity.launchWebAuthFlow({ url: 'https://app.circuy.com/auth/extension', interactive: true }).
3. Authentification Web : Une fenêtre modale isolée s'ouvre sur app.circuy.com :

• Option A (Passkey) : L'utilisateur valide son identité via navigator.credentials.get() (Biométrie locale).
• Option B (SSO) : L'utilisateur clique sur Google/GitHub/Microsoft.

4. Génération du Token : Le backend Circuy valide la session et génère un couple de tokens :

• AccessToken (JWT, durée de vie : 15 minutes).
• RefreshToken (Durée de vie : 30 jours, révocable).

5. Callback Extension : La page web redirige vers https://<EXTENSION_ID>.chromiumapp.org/callback#access_token=...&refresh_token=....
6. Stockage Sécurisé : L'extension capture la redirection, extrait les tokens et les stocke dans chrome.storage.local.

2.3 Stockage & Sécurité des Tokens dans l'Extension

Règles de Stockage

• Interdiction : Ne JAMAIS utiliser localStorage (non accessible dans les Service Workers Manifest V3 et vulnérable aux XSS de la page hôte).
• Autorisé : Utiliser exclusivement l'API chrome.storage.local .

// Structure du stockage local de l'extension
interface AuthStorage {
  accessToken: string;
  refreshToken: string;
  user: {
    id: string;
    email: string;
    organizationId: string;
  };
}

Rafraîchissement Automatique (Silent Refresh)

Le Background Service Worker de l'extension intercepte chaque requête vers l'API Backend. Si l'AccessToken est expiré (HTTP 401), il utilise le RefreshToken pour obtenir un nouvel AccessToken de manière transparente sans déconnecter l'utilisateur.

2.4 Synchronisation automatique "Web Dashboard ↔ Extension" (Zero-Click Login)

Si l'utilisateur est déjà connecté sur le Dashboard Web ( app.circuy.com ) , l'extension peut détecter cette session active sans demander à l'utilisateur de se réauthentifier :

1. Lors de l'ouverture de l'extension, le background script interroge le backend /api/v1/auth/me.
2. Grâce à la permission cookies spécifiée dans le Manifest V3 pour le domaine app.circuy.com, l'extension envoie la session active de manière sécurisée.
3. L'utilisateur est connecté instantanément dans l'extension ( Zero Friction ).

3. Matrice de Sécurité & Conformité RGPD