# FriRSS — inventaire des fonctionnalités **Ce fichier est la mémoire du projet.** Il recense tout ce que FriRSS sait faire, où chaque chose vit dans le code, et les pièges qui ont déjà coûté du temps. Il sert deux usages : éviter de casser ou de réinventer une fonctionnalité existante, et servir de source à la documentation utilisateur. **À mettre à jour dans le même commit que toute fonctionnalité ajoutée, retirée ou modifiée.** `src/lib/featuresDoc.test.ts` échoue si une route serveur, une variable d'environnement ou une famille de traductions n'est pas mentionnée ici. > **Ce que le test ne peut pas voir** : il attrape les **oublis d'ajout**, pas > les descriptions devenues fausses. Une fonctionnalité dont le comportement > change sans changer de route ni de clé i18n passera au travers. La prose reste > sous responsabilité humaine. --- ## Architecture en bref Frontend React 19 + Vite 6, servi par nginx. Backend Express + SQLite (`better-sqlite3`), compilé par `tsc` vers `server-dist/`. Une seule image Docker embarque les deux. Tous les appels à FreshRSS passent par le proxy backend `/api/proxy` — même origine, donc pas de CORS. Le jeton greader est obtenu à l'ajout du serveur et à chaque changement de son mot de passe API (`ClientLogin` depuis le navigateur, `src/api/auth.ts`) ; une fois enregistré, il ne revient plus jamais du serveur au navigateur. FriRSS ne stocke aucun article : la source de vérité reste FreshRSS, interrogée via son **API Google Reader**. La base SQLite ne contient que des comptes, des connexions serveur et des préférences (~68 Ko). --- ## Authentification et comptes ### Comptes FriRSS Comptes locaux avec mot de passe, session par JWT conservé en `localStorage` (décision documentée dans `SECURITY.md`). Le premier compte créé devient administrateur. **Une déconnexion n'efface que la session de son onglet** (1.8.0, `authStore.multitab.test.ts`, et les réglages en attente dans `prefsSync.stopSync`) : un onglet resté sur un ancien compte, déconnecté par un 401, effaçait le jeton, le serveur actif et les réglages en attente du compte qu'un autre onglet avait ouvert depuis. - **Où** : `server/routes/auth.ts`, `src/components/Login/Login.tsx`, `src/stores/authStore.ts` - **Session fermée par le serveur : l'écran le dit** (1.9.0, `Login.sessionEnded.test.tsx`) : quand un 401 de notre middleware ferme la session (`endsCurrentSession`, intercepteurs de `src/api/client.ts` et `src/api/backend.ts`), la déconnexion porte la raison `'session_ended'`, le store lève `sessionEnded`, et l'écran de connexion affiche `login.sessionEnded` (« Votre session a été fermée par le serveur ») dans la zone d'erreur. Sans deviner la cause (expirée, révoquée, mot de passe changé ailleurs). Une déconnexion voulue ne dit rien ; la connexion suivante efface le drapeau. Avant, on revenait à l'écran sans un mot. - **Connexion sans fuite de noms** (1.8.0) : un nom inconnu coûte le même bcrypt qu'un nom connu (`DUMMY_HASH`), et « Account disabled » (403) n'est répondu qu'après le BON mot de passe. Avant, la réponse et son délai (~250 ms de moins) disaient à n'importe qui quels noms existent et lesquels sont désactivés. Un compte local **sans hachage** passe aussi par le factice (même délai) mais n'est jamais valide : le mot de passe du factice est écrit en clair dans ce dépôt public, et il ouvrait la session. - **Valeurs du client en temps linéaire** (1.8.0, `server/validate.ts`, `server/test/inputBounds.test.ts`) : `isValidEmail` (254 caractères au plus, domaine découpé par ses points sans chevauchement) et `stripTrailingSlashes` (une boucle) remplacent `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` et `/\/+$/`, quadratiques : un `@` suivi de 300 000 points gelait l'instance 72 s pour UNE inscription, sans compte ; une rafale de barres dans l'URL d'un serveur gelait à l'enregistrement puis à chaque requête proxifiée. L'URL d'un serveur doit en outre être en http(s) et tenir en 2 048 caractères (`normalizeServerUrl`, 400 sinon). **Ne pas réintroduire de quantificateur suivi d'une ancre de fin sur une valeur venue du client.** - **Types vérifiés avant usage** (1.9.0, `server/test/requestShapes.test.ts`) : connexion et changement de mot de passe exigent des chaînes. Un objet ou un tableau levait dans SQLite ou bcrypt : un 500 et une ligne « Internal server error » au journal pour une faute du client ; c'est un 400. - **Limites « par adresse » regroupées par /56 en IPv6** (1.8.0, `rateLimitIpKey`) : connexion, inscription et sauvegardes. Depuis que nginx transmet l'adresse réelle, un client IPv6 changeait d'adresse dans sa /64 à chaque essai et recevait un seau neuf : force brute illimitée, et un bcrypt par essai sur le thread principal (`server/test/rateLimitIpv6.test.ts`). - **Inscriptions réussies bornées** (1.8.0, `registerLimiter`, `server/test/registerLimits.test.ts`) : 5 comptes par heure et par adresse (/56 en IPv6). `authLimiter` ne compte que les échecs : une fois les inscriptions ouvertes, une seule adresse créait autant de comptes qu'elle voulait. Les refus (nom pris, champ invalide) ne comptent pas. Placé AVANT `authLimiter` : ses 429 entameraient sinon la limite de connexion de l'adresse. Son 429 porte `code: 'too_many_accounts'`, affiché `login.errorTooManyAccounts` (« réessayez dans une heure ») : « quelques minutes » faisait réessayer pour le même refus. Derrière un proxy dont les clients partagent une adresse (voir *Atteindre FriRSS par le reverse proxy*), ils partagent aussi ce plafond. - **Longueurs d'un compte** (1.8.0, `accountFieldError`, `server/validate.ts`) : nom ≤ 64 caractères, nom affiché ≤ 128, mot de passe ≤ 1 024, et des chaînes (`['a','b','c']` passait le contrôle de longueur minimale). Inscription, création et modification par l'admin, changement et réinitialisation du mot de passe, 400 sinon. L'adresse l'était déjà (254, `isValidEmail`). Les noms provisionnés par le SSO ne passent pas par là : ils viennent du fournisseur. - **Rôle d'un compte** : `admin` ou `user`, chaîne vide comprise — `""` passait les gardes `role && …` et `COALESCE` l'écrivait, ce qui laissait une instance sans administrateur. - **Premier compte = un seul admin** (1.8.0) : le compte de comptes est relu APRÈS le hachage, sans `await` jusqu'à l'insertion. Deux inscriptions simultanées sur une base vide devenaient toutes deux admin (`server/test/registerRace.test.ts`). - **Réglages** : inscriptions ouvertes/fermées (Préférences → Administration) - **Fermée par défaut** : depuis la 1.4.4, une instance neuve refuse les inscriptions. Le **premier** compte reste toujours autorisé (`count === 0` est exempté), sans quoi une instance neuve serait inaccessible à son propre installateur ; les suivants demandent un geste explicite de l'administrateur. Le défaut précédent (`true`) laissait n'importe qui créer un compte sur une instance neuve exposée publiquement — et un compte est ce qui donne accès au proxy sortant. - **Piège** : `INSERT OR IGNORE` sur `settings` — changer ce défaut ne touche que les bases **neuves**. Une instance existante garde la valeur enregistrée, ce qui est le comportement voulu : personne ne se fait fermer la porte par une mise à jour. - **Piège — un 401 ne dit pas de quelle couche il vient.** Le compte FriRSS et le serveur FreshRSS rattaché sont deux authentifications indépendantes, et le proxy relaie le statut amont tel quel. Les intercepteurs de **deux** clients, `src/api/client.ts` (FreshRSS via le proxy) et `src/api/backend.ts` (API FriRSS), ne déconnectent donc que sur les 401 de **notre** middleware, reconnus par `isBackendAuthFailure` (`src/lib/loginErrors.ts`) — voir « Serveurs FreshRSS ». `backend.ts` déconnectait avant sur tout 401 : un mauvais mot de passe actuel au changement de mot de passe (« Current password is incorrect ») éjectait l'utilisateur. La déconnexion volontaire après une restauration (`BackupBlock.tsx`) reste, elle, explicite. - **Changer son mot de passe** (1.8.0) : Préférences › Général, section « Compte » (`AccountSection.tsx`), **comptes locaux seulement** — un compte SSO le change chez son fournisseur. Mot de passe actuel, nouveau, confirmation ; le minimum (6) et l'égalité des deux saisies sont vérifiés avant l'appel, et chaque refus a son message (`preferences.account.*` : actuel faux = 401 qui ne déconnecte pas, trop d'essais = 429). Le serveur ferme les **autres** sessions du compte, ce que l'aide annonce. **Piège** : les réponses de connexion et d'inscription locales n'envoyaient pas `auth_provider` (seul `/me`, lu au retour SSO, l'incluait) ; elles l'envoient depuis la 1.8.0, et un champ **absent** est lu comme local — une session ouverte avant ne l'a pas, et ne doit pas perdre la section. La route existait sans écran depuis 0d3d327 (août 2026, wrapper client retiré) : seul un administrateur pouvait réinitialiser un mot de passe. Elle a sa propre limite, **par compte** (`passwordLimiter`, 10 échecs / 15 min, après `requireAuth`) : un mot de passe actuel se devine depuis une session restée ouverte. La réussite s'annonce dans une région `role="status"` montée en permanence (vide, `sr-only`, au repos) et s'efface dès qu'on retape ; un champ `autocomplete="username"` caché porte le nom du compte, pour que les gestionnaires de mots de passe sachent à quel compte rattacher le nouveau. Tests : `GeneralTab.password.test.tsx`, bloc `change-password` de `server/test/api.test.ts` (sa limite est propre au compte, elle n'entame pas celle de la connexion). ### SSO / OIDC Connexion par fournisseur OIDC en complément des comptes locaux, ou mise en avant seule (mode « SSO uniquement ») : le formulaire local est alors **masqué, pas refusé** — la connexion par mot de passe reste possible côté serveur, volontairement, comme filet si le fournisseur tombe (`SECURITY.md` le dit aussi). - **Où** : `server/oidc.ts`, `server/routes/auth.ts` (`/oidc/*`), `src/lib/shouldHideLocalLogin.ts` - **Le fournisseur décide de qui entre** : une première connexion SSO crée un compte pour toute identité qu'il laisse passer, **quel que soit le réglage des inscriptions** (qui ne gouverne que le formulaire local). Écrit dans `SECURITY.md` en 1.8.0 : restreindre l'application FriRSS dans le fournisseur (Authentik : groupe ou politique). - **Retour du fournisseur borné** (1.8.0, `server/test/oidcCallback.test.ts`) : `GET /api/auth/oidc/callback` est anonyme. Sans borne, un seul `state` et un cookie fourni par l'appelant faisaient envoyer autant de `POST /token` qu'on voulait, `client_secret` compris : FriRSS relayait vers le fournisseur depuis sa propre adresse, et une protection qui bannit l'émetteur des échecs coupait le SSO de toute l'instance. Deux bornes : 30 retours par adresse (/56 en IPv6) et par 15 minutes (`oidcCallbackLimiter`, qui compte TOUT : ses issues sont des redirections, `authLimiter` n'y verrait rien), et un `state` à usage unique (son `jti`, gardé en mémoire jusqu'à son expiration, comme les tickets de liaison). Le `state` est consommé juste avant l'échange du code : un rappel sans `verifier` ne coûte rien au fournisseur et ne l'use pas. Au-delà de la limite : redirection vers `#oidc_error=too_many`, pas un 429 (le navigateur aurait affiché du JSON) ; le client le dit `login.errorTooMany` (`oidcErrorKey`, et dans le message de liaison depuis le compte). ⚠️ Limite connue : le seau compte tout, même un appel vide. À adresse partagée, un anonyme peut donc l'épuiser et bloquer les vrais retours, comme pour la limite de connexion par adresse ; sans repli en mode SSO seul, hors `?local=1`. Un `state` émis avant la mise à jour n'a pas de `jti` et répond `invalid_state`. - **Rattacher un compte existant : depuis le compte seulement** (1.8.0, décision du propriétaire). Préférences › Général › Compte, « Lier à {fournisseur} » (comptes locaux, SSO actif, pas encore liés) : `POST /api/auth/oidc/link` (authentifié, **mot de passe actuel exigé**, même plafond par compte que le changement de mot de passe) rend l'URL du fournisseur, dont l'état signé porte `link: `. **Le retour ne rattache rien** : il remet un ticket signé de 5 min (`#oidc_link_ticket=…`, `uid` + `sub` + `jti`), à usage unique (`usedLinkTickets`, en mémoire : un redémarrage l'oublie, l'échéance de 5 min reste), que le client valide par `POST /api/auth/oidc/link/complete` depuis une session du compte qui a lancé la liaison (403 `link_mismatch` sinon, 409 `already_linked` si l'identité est liée ailleurs). Aucune session n'est ouverte. Pourquoi les deux (seconde relecture 1.8.0) : sans mot de passe, une session volée rattachait l'identité de l'attaquant, qui survivait au changement de mot de passe ; et le retour n'est lié au navigateur que par des cookies, qu'un site voisin du même domaine peut déposer — l'attaquant lançait SA liaison, la victime revenait du fournisseur dans ce navigateur, et son identité allait sur le compte de l'attaquant. **Délier** : le titulaire (« Délier », `DELETE /api/auth/oidc/link`) ou l'admin (🔗, `DELETE /api/admin/users/:id/sso`, après confirmation), comptes locaux seulement — un compte qui n'a que le SSO se fermerait. **Délier ferme les sessions** : toutes les autres du titulaire, toutes celles du compte pour l'admin (sauf la sienne). Rien ne dit quelle session vient du SSO, et une identité rattachée à tort (par l'e-mail, avant 1.8.0) gardait sinon la sienne jusqu'à 30 jours (`oidcLink.test.ts`). La liste de l'administration montre « Local + SSO » (`sso_linked`). Un compte lié garde son mot de passe et `auth_provider = 'local'`. `sso_linked` (connexion, `/me`) dit s'il l'est. Le bloc SSO de la section Compte est séparé du changement de mot de passe par un filet et son propre intitulé : à 320 px, son aide se lisait comme la suite du mot de passe. **Retiré** : le rattachement d'office, à la première connexion SSO, au compte local qui portait la même adresse e-mail — sans exiger qu'elle soit vérifiée (Authentik envoie `email_verified=false` par défaut) : qui inscrivait l'adresse de l'admin dans son profil chez le fournisseur recevait une session admin. Une telle connexion répond désormais `#oidc_error=link_required` (« connectez-vous avec le mot de passe, puis liez »), sans créer de doublon ; en mode « SSO uniquement », le formulaire local apparaît alors (`shouldHideLocalLogin`, `linkRequired`). **Limite connue, assumée** : avec les inscriptions ouvertes, un compte local créé avec l'adresse de quelqu'un qui viendra plus tard par SSO bloque sa première connexion (`link_required`) ; l'admin débloque. Tests : `server/test/oidcLink.test.ts` (fournisseur simulé), `GeneralTab.password.test.tsx`, `AdminTab.confirm.test.tsx`, `oidcFragment.test.ts`. - **`redirect_uri` sans `X-Forwarded-Host`** (1.8.0) : sans `FRIRSS_BASE_URL`, l'hôte vient de `Host` seul, que nginx transmet avec son port (`$http_host` : `$host` perdait le port, et le SSO cassait derrière un proxy sur un port non standard). `Host` vient lui aussi du client : seule l'URI enregistrée chez le fournisseur protège ; derrière un reverse proxy, `FRIRSS_BASE_URL` fixe l'adresse. `X-Forwarded-Host` n'est plus lu : il n'était qu'une seconde façon de dicter le `redirect_uri` signé. Le schéma vient de `X-Forwarded-Proto`, que nginx relaie désormais depuis le proxy amont (voir « nginx »). Le journal du retour SSO n'écrit plus l'adresse e-mail, seulement si elle existe. - **Spec** : `docs/superpowers/specs/2026-08-15-sso-only-mode-design.md` - **Piège** : une URL « break-glass » permet de revenir au formulaire local si le SSO tombe. Sans elle, un OIDC cassé enferme dehors l'administrateur. - **Retour SSO tolérant aux pannes réseau** (`src/lib/oidcReturn.ts`, `completeOidcReturn`, appelé par `App.tsx`) : après la redirection, le jeton est posé puis `getMe()` lit l'utilisateur. Une erreur réseau ou un 5xx est réessayé quatre fois (attentes de 1, 2, 4 puis 8 s) au lieu de renvoyer aussitôt à l'écran de connexion ; notre 401 de session invalide, ou tout autre 4xx (jeton inutilisable), déconnecte tout de suite. Après le dernier échec, l'écran de connexion affiche `login.errorUnavailable` (via la prop `oidcError` de `Login`, valeur `unavailable`) ; toute autre valeur garde `login.errorSso`. Chaque lecture y a son propre délai, court : **15 s** (`OIDC_GETME_TIMEOUT_MS`), pas les 75 s par défaut — avec un serveur muet, l'échec final tombait au bout de ≈ 6,5 min et déconnectait une session que l'utilisateur avait pu poursuivre ; pire cas désormais 90 s. `/api/auth/me` ne fait aucun appel amont, la règle « le serveur répond avant le client » tient. **Garde de session** : avant `setAuth`, `logout` ou l'annonce d'échec, le jeton du store doit être encore celui qu'on termine (`currentToken`) ; sinon (déconnexion ou autre connexion pendant les réessais) la boucle s'arrête sans rien toucher — elle ressuscitait la session fermée, ou déconnectait celle d'un autre. La garde ne suffisait pas seule : le 401 d'un `getMe` parti avec l'ancien jeton passait d'abord par l'intercepteur, qui fermait la session ouverte entre-temps. Depuis la 1.8.0, les deux intercepteurs ne déconnectent que si le jeton envoyé est encore celui du store (`endsCurrentSession`, `src/lib/loginErrors.ts`). - **Piège** (1.6.1, issue #23) : le callback lit les cookies de l'hôte avec un parseur maison (`server/cookies.ts`, `parseCookieHeader()`), et cet hôte porte aussi les cookies des **autres** services posés sur le même domaine (Authelia derrière SWAG, par exemple). Une seule valeur avec une séquence `%` invalide faisait lever `URIError: URI malformed` à `decodeURIComponent` et échouer TOUT le callback. Une valeur indécodable est maintenant gardée brute : elle n'est jamais la nôtre (`oidc_verifier` et `oidc_nonce` sont encodés par Express). Test : `server/cookies.test.ts`. - **L'hôte de l'émetteur est de confiance pour la garde anti-SSRF** (1.6.1). Tout appel sortant du flux passe par `oidcFetch()` (`server/oidc.ts`) = `fetchUpstream` avec `trustedHosts: [hôte de l'émetteur]` : découverte, échange du code et `userinfo` — ces deux derniers étaient des `fetch` nus, hors garde, pour des URL dictées par le document de découverte. La confiance s'arrête à l'hôte nommé : un saut de redirection vers un autre hôte privé reste refusé. **Piège corrigé** : en split-DNS, le nom public du fournisseur se résout en IP privée (le reverse proxy) depuis le conteneur, et la garde de la 1.4.4 refusait la découverte — `login_failed` sans explication, sept semaines en prod sans que personne ne le voie, le JWT courant n'expirant pas. Le contournement d'alors (`PROXY_INTERNAL_HOSTS`) reste valable mais n'est plus nécessaire. Décision et coût écrits dans `SECURITY.md`. Tests : `server/oidc.test.ts`, `server/routes/proxy.test.ts` (`trustedHosts`), `server/test/api.test.ts` (découverte). ### Écran de connexion Trois étapes : compte FriRSS, puis serveur FreshRSS, puis identifiants FreshRSS. Animation de connexion configurable (aucune / portail / scanline). - **Où** : `src/components/Login/` (`Login.tsx`, `LoginTransition.tsx`, `MatrixRain.tsx`) - **Couleur d'erreur fixe** (1.8.0) : `.login-error` (#f87171), pas `--danger`. La carte est sombre quel que soit le thème, et le rouge foncé des thèmes clairs (Papier, Riso, Contraste) y tombait à 2,7:1 (`loginErrorContrast.test.ts` exige 4,5:1). - **Voir le mot de passe** (1.4.5) : la bascule vit dans le composant partagé `InputField`, donc les quatre champs de mot de passe de l'écran l'ont d'un coup. `aria-pressed` porte l'état. - **Copie** (1.4.5) : en mode connexion, le sous-titre disait « Connexion » entre « Bienvenue sur FriRSS » et le bouton « Se connecter » — trois fois la même chose, dont deux inutiles. Il dit maintenant ce que l'application EST (`login.tagline`). En inscription et en restauration le sous-titre portait une vraie information : il la garde. `login.loginTitle` est devenue morte et a été retirée des 9 locales — `i18nCoverage.test.ts` l'a signalée. - **Pas fait** : la composition en deux colonnes sur grand écran, proposée par la revue d'interface. La branche de restauration est imbriquée dans le même bloc d'en-tête que le titre, donc la refonte les emporterait ensemble ; à reprendre avec cette contrainte en tête. --- ## Serveurs FreshRSS Plusieurs connexions FreshRSS par utilisateur, avec un serveur par défaut et un basculement rapide. Le jeton greader est **chiffré en base** (AES-256-GCM) et injecté côté serveur par le proxy ; une fois le serveur ajouté, il ne revient plus jamais au navigateur (seule sa présence est exposée, `has_token`). - **Un serveur n'est enregistré qu'une fois** (1.9.0, `serverIdentity`, `server/routes/servers.ts`) : le doublon (409) se juge sur l'origine analysée — schéma, hôte en minuscules, port par défaut omis — et le chemin sans barre finale, pour le même utilisateur FreshRSS ; à l'ajout comme à la modification d'adresse. La chaîne brute laissait passer `:443`, `:80` ou une majuscule : deux portées hors ligne et deux files pour un seul FreshRSS. L'adresse enregistrée reste celle qui a été saisie. Une modification qui garde l'identité (nom, nouveaux identifiants) n'est pas contrôlée : des jumeaux ajoutés avant 1.9.0 restent modifiables, sinon on ne pouvait plus leur donner un nouveau mot de passe d'API. - **Changer le mot de passe API d'un serveur existant** (1.8.0, `ServerCredentialsForm`, `servers.changeCredentials`) : dans la ligne dépliée du serveur, à côté de Renommer (l'un ou l'autre ouvert, pour que le focus ait toujours son bouton où revenir). Utilisateur affiché **en lecture seule**, mot de passe API, l'aide habituelle ; FreshRSS éprouve d'abord les identifiants (ClientLogin, erreurs de `serverConnectErrorKey`), puis `PUT /api/servers/:id` reçoit le seul `freshrssToken`. Deux étapes, deux messages : un échec de cet enregistrement dit `servers.errorGeneric`, pas « échec de connexion à FreshRSS », qui vient d'accepter. Échap ne ferme rien pendant l'envoi : envoyé par le bouton, qui se désactive, le focus passe au formulaire, sinon il tombait sur `` et l'Échap des Préférences fermait tout ; après un refus il revient au mot de passe. ⚠️ L'utilisateur ne change pas : un autre utilisateur sur le même serveur garderait la même portée hors ligne, et la file, les listes du premier seraient servies au second — un autre utilisateur est un autre serveur à ajouter, qui a sa propre portée et, avec Redis, ses propres clés de cache (la clé porte l'id du serveur, voir « Cache Redis » ; avant 1.9.0, deux serveurs à la même adresse partageaient leurs listes en cache). Le serveur **garde son identifiant**, donc sa portée hors ligne : jusque-là, le seul moyen était de le supprimer puis de le rajouter, et les actions en attente ne repartaient plus. Serveur actif : un rejeu encore en vol sous l'ancien jeton est attendu (il reposerait le refus), puis `replayRefusedByServer` tombe et la file repart ; le jeton d'écriture, tenu par le serveur, suit seul les nouveaux identifiants. Région de statut montée en permanence ; Échap ferme ; le focus revient au bouton. Le bandeau de refus (`connection.refusedByServer`) y renvoie avec les vrais libellés de chaque langue (`OfflineBanner.test.tsx` le vérifie). ⚠️ Limite : une connexion héritée (`synthetic`, sans enregistrement en base) ne se déplie pas et n'a donc pas ce bouton. - **Où** : `server/routes/servers.ts`, `server/crypto.ts`, `src/components/Preferences/servers/` (gestion complète), `src/components/ServerSwitcher/` (sélecteur), `src/lib/serverList.ts` (logique partagée). - **Champs bornés** (1.8.0, `serverFieldError`, `serverBounds.test.ts`) : nom et identifiant FreshRSS de 200 caractères au plus, jetons de 1 024, chaînes seulement, 50 serveurs par compte (400 sinon) — cinq serveurs nommés de 4 Mo passaient. **La relève compte dans le seau par minute** du proxy (`FRIRSS_PROXY_RATE_LIMIT`) : elle y échappait, test du jeton maître compris. Le test du jeton maître (`RefreshTokenField`) ne dit « refusé » (`testFail`) que sur un 401, un 403, ou sa forme réelle : un mauvais jeton ne reçoit pas un 403 de FreshRSS mais un **302** (`Minz_Error::error`) vers `?c=error&code=403` depuis la 1.30.2, vers `?c=error` sans code avant (il reste en session), ou vers `?c=auth`. `isRefusalRedirect` (`server/routes/servers.ts`) relit ces formes comme un 403, et laisse un autre code ou une autre page en 302 non concluant. ⚠️ Mesuré sur un vrai FreshRSS : les tests moquaient un `answered 403` qui n'arrive jamais, et « Tester » ne disait plus « refusé » à personne. Un 429 affiche `preferences.refresh.testRateLimited`, une absence de tâche, de réponse ou une autre erreur `testInconclusive`, un enregistrement raté `servers.errorGeneric` : tous disaient « Le jeton a été refusé » d'un jeton peut-être bon. - **Changer l'adresse ou le compte d'un serveur exige un nouveau jeton** (1.8.0) : `PUT /api/servers/:id` refuse (400) une autre ORIGINE (schéma, hôte, port) ou un autre `freshrssUser` sans `freshrssToken` dans la même requête, et oublie alors le jeton maître sauf s'il est fourni aussi. Avant, les deux jetons suivaient la nouvelle URL : le proxy y attachait le jeton greader, la relève le jeton maître en clair dans l'URL — une session FriRSS suffisait à les convertir en identifiants FreshRSS durables. Un changement de chemin sur la même origine garde les jetons — **limite connue, assumée** (2026-10-29) : le jeton peut alors suivre un autre chemin du même hôte, qui le recevait déjà. Le client n'envoie jamais d'URL par cette route (renommage, jeton maître, et jeton greader neuf par « Changer le mot de passe API », sans changer d'utilisateur). - **Portée du jeton — piège** : le proxy n'attache le jeton greader qu'aux cibles dont l'**origine analysée** vaut celle du serveur, le chemin étant comparé avec une frontière explicite (`targetBelongsToServer`, `server/routes/proxy.ts`). Une comparaison par préfixe de chaîne — ce qu'elle était jusqu'à la 1.4.4 — acceptait `https://serveur.tld.tiers.tld/` et `https://serveur.tld@tiers.tld/`, deux hôtes étrangers. Ce n'est pas théorique : les URL d'images d'articles et de favicons viennent du **contenu des flux**, et `src/api/client.ts` attache `X-Server-Id` à toutes ses requêtes sans distinction — celui qui publie un flux choisit donc la cible. - **Échec du rattachement — ce que l'écran a le droit de dire** : `serverConnectErrorKey()` (`src/lib/loginErrors.ts`) ne nomme que les causes réellement vérifiées, et rien d'autre : - **403 + `Target host not allowed`** → notre garde anti-SSRF a refusé une cible privée ; le message renvoie à `PROXY_INTERNAL_HOSTS`. - **401 qui n'est pas l'un des nôtres** → FreshRSS a refusé les identifiants ; le message rappelle que le mot de passe d'**API** se définit à part de celui du compte. `greader.php` répond le même 401 `Unauthorized!` pour un mot de passe faux **et** pour un mot de passe d'API jamais défini : le message couvre donc les deux. - Tout le reste — hôte injoignable, coupure réseau, et le 400 d'un nom d'utilisateur inconnu — garde le générique `login.errorServer`. Ce 400 est partagé avec notre propre « cible absente » : deux causes, un statut, donc aucune nommée. - **Pourquoi** : le proxy relaie le **statut amont tel quel**, donc un 403 peut aussi bien venir de FreshRSS que de nous ; seul le corps distingue les deux. Avant la 1.4.6, le `catch` de `Login.tsx` jetait l'erreur sans la lire et affichait « connexion impossible » pour tout. Héberger FreshRSS sur une IP privée — le cas majoritaire — produisait donc le message le moins exploitable, sans jamais mentionner la variable qui débloque (issue #8). - **Piège** : le marqueur est écrit des deux côtés d'une frontière que le typage ne traverse pas. `loginErrors.test.ts` relit `server/routes/proxy.ts` pour vérifier qu'il correspond encore ; sans lui, une reformulation côté serveur ferait repasser l'écran au message générique **en silence**, sans qu'aucun test de comportement ne rougisse. - **Le tri des 401 se fait par exclusion, et c'est délibéré.** `/api/proxy` répond aussi 401 quand le JWT **FriRSS** a expiré, avant même de joindre FreshRSS. On écarte donc les nôtres (`BACKEND_AUTH_MARKERS`) au lieu de reconnaître ceux de FreshRSS : nos messages vivent dans ce dépôt et sont vérifiables contre la dérive, ceux de FreshRSS non. Un quatrième message ajouté à `server/middleware/auth.ts` sans être listé ferait accuser le mot de passe de l'utilisateur alors que sa session a simplement expiré — `loginErrors.test.ts` relit le middleware et rougit dans ce cas. - **Pas de déconnexion parasite**, à deux verrous. `src/api/auth.ts` utilise **axios nu**, pas le client de `src/api/client.ts` : le rattachement d'un serveur ne passe donc pas du tout par l'intercepteur. Et depuis la 1.4.8, cet intercepteur ne déconnecte plus sur **tout** 401 : il n'agit que sur les nôtres (`isBackendAuthFailure`, même `BACKEND_AUTH_MARKERS`) — critère repris par `src/api/backend.ts` depuis la 1.8.0, qui ajoute un troisième verrou aux deux : le 401 doit répondre au jeton **encore en place** (`endsCurrentSession` compare l'en-tête `Authorization` de la requête au store) — une requête partie avant un retour SSO ou un renouvellement ne ferme pas la session suivante. Un 401 de FreshRSS — session expirée là-bas, mot de passe d'API changé — traversait tout le reste de l'application (listes, favicons, extraction) et fermait la session FriRSS : une panne d'une couche déconnectait de l'autre. Un corps illisible (`responseType` binaire des images) n'est **pas** attribué à FriRSS : ne rien affirmer coûte une requête en erreur, se tromper coûte la session. - **Les deux sites d'appel comptent** : `Login.tsx` (première connexion) et `AddServerDialog.tsx` (Préférences → ajouter un serveur) mènent au même échec et partagent la fonction. - **Deux endroits, un seul complet** : Préférences → Flux liste les serveurs et porte toutes les actions — basculer, ajouter, renommer, définir par défaut, supprimer, et le jeton maître de chaque serveur. La barre du haut ne fait que basculer ; son `+` et son clic droit sont des raccourcis vers Préférences, ils n'exécutent rien. - **Jeton par serveur** : le jeton maître se configure et s'éprouve depuis la ligne de n'importe quel serveur, sans y basculer — les routes sont adressées par `/:id`. Le drapeau global `hasRefreshToken` ne décrit que le serveur actif : `RefreshTokenField` ne l'écrit que depuis la ligne de celui-ci. - **Affichage immédiat, revalidation derrière** : la liste s'affiche dès que des serveurs sont déjà en mémoire (`shouldShowServerList()` dans `src/lib/serverList.ts`), et le rechargement court en arrière-plan. Le squelette ne sert plus qu'au démarrage à froid — indispensable, car `displayServers()` fabrique une ligne synthétique à partir de `serverUrl` quand la liste est vide : rendue trop tôt, elle se ferait passer pour un compte hérité et une panne réseau affirmerait que l'utilisateur n'a qu'un serveur ingérable. Un échec de chargement se dit toujours, même quand des données connues restent affichées. - **Piège corrigé le 2026-08-26** : la gestion vivait uniquement dans `ServerSwitcher`, qui ne se monte que si la barre du haut est visible — la masquer emportait la bascule avec elle. Pire, renommer, définir par défaut et supprimer passaient par `onContextMenu`, que Safari iOS n'émet pas : trois actions sur cinq n'existaient pas dans la PWA installée. - **Piège subsistant** : la connexion FreshRSS sans enregistrement en base (première connexion, comptes anciens) s'affiche en entrée synthétique, en lecture seule et non dépliable. Elle n'a pas d'identifiant en base : aucune action de gestion ne peut la viser. --- ## Navigation et mise en page ### Barre latérale Catégories repliables, flux avec favicon et compteur de non-lus, entrées fixes (Tous, Non lus, Favoris, À lire plus tard), étiquettes, réordonnancement par glisser-déposer, masquage des flux entièrement lus. Déposer un article de la liste sur une étiquette, une catégorie de favoris, Favoris ou « À lire plus tard » l'y classe — **à la souris seulement** (au doigt, l'appui long ouvre le menu ; voir *Menu d'un article*, piège Chrome Android). - **Où** : `src/components/Sidebar/Sidebar.tsx`, `src/stores/uiStore.ts` - **« Ajouter un flux » dans le tiroir du téléphone** (1.9.0) : le libellé est **dans** le bouton, contre son « + », à droite de la ligne ; toute la pastille « Ajouter un flux + » se touche. Seul à gauche, il suivait l'icône œil (« masquer les flux lus ») et semblait la nommer, le « + » restant au bout de la ligne. Sur ordinateur et tablette, le « + » reste une icône seule. Test : `Sidebar.addFeedLabel.test.tsx` ; mesuré à 320 px (tiroir de 272 px) dans les dix langues : une ligne, 6 px entre le libellé et le « + ». - **Compte et « ⋯ » d'une ligne de flux échangés par le CSS** (1.8.0) : les deux sont rendus, et `.sidebar-feed-item:hover` sous `@media (hover: hover)` montre « ⋯ » à la place du compte. Un état JavaScript de survol (`onMouseEnter` / `onMouseLeave`) se coinçait : un `mouseleave` perdu cachait le compte pour de bon (vu : 111 non lus masqués, la souris ailleurs), et au doigt une tape émet `mouseenter` sans `mouseleave` — sur tablette, le flux touché perdait son compte. Au doigt, le menu s'ouvre par l'appui long ; « ⋯ » n'y apparaît plus. - **Menu d'un flux** — renommer, ouvrir le site, extraction automatique, se désabonner. Trois chemins : le clic droit, le bouton ⋯ révélé au survol, et **un appui long de 500 ms au doigt** (`useLongPress`, le même que partout : voir *Menu d'un article*). Ses entrées (`ContextMenuItem`) font 44 pt de haut au doigt (`.context-menu-item`, comme celles du menu d'un article), contre 40 px avant. ⚠️ **L'appui long n'est pas un agrément, il était indispensable.** Jusqu'à la 1.4.11, ces quatre actions n'avaient AUCUN chemin tactile : le ⋯ ne paraît qu'au survol, et le clic droit n'existe pas au doigt. L'extraction automatique par flux, mise en avant, ne se réglait donc que depuis un bureau. Confirmé sur appareil par le propriétaire avant correction. ⚠️ **Pourquoi pas simplement montrer le ⋯ au doigt**, comme le font `.article-card__actions` et `.prefs-row-action` sous `@media (hover: none)` : ici le ⋯ **occupe l'emplacement du compteur de non-lus** (un carré fixe de 24×20 qui évite tout saut de mise en page). L'afficher en permanence masquerait le compteur — l'information la plus utile de la barre latérale. - Le geste s'annule dès que le doigt dépasse la tolérance de 8 px (sinon un défilement de la barre ouvrirait un menu), sur `touchcancel` et sur un second doigt ; un tremblement en deçà ne l'annule pas. Il est inerte en mode organisation, où la ligne se glisse. Et le clic qui le termine est avalé, sans quoi le flux se chargerait derrière le menu. - ⚠️ **Chrome Android émet `contextmenu` AVANT le minuteur** (mesuré sur émulateur, délai système 400 ms : à ~491 ms, trois fois sur trois) : transmis au gestionnaire du clic droit, il ouvrait le menu au point du doigt, puis le minuteur le rouvrait au rectangle de la ligne — le menu sautait sous le doigt (jusqu'à la 1.7.0). Désormais `claimContextMenu()` fait aboutir l'appui tout de suite, avec la même ancre que le minuteur, et absorbe un `contextmenu` qui arriverait après (voir *Menu d'un article*). - **Faiblesse assumée** : rien ne signale le geste. Même situation que l'appui long de classement d'un article, sans l'équivalent de la barre latérale pour le faire découvrir. - **Tests** : `src/components/Sidebar/FeedItem.longpress.test.tsx`. - **Les compteurs de non-lus se lisent avec leur nom** : le badge d'un flux, d'une ligne spéciale (Non lus, Tous les flux) et d'une catégorie de flux porte un libellé pluriel (`sidebar.unreadCount`, « 3 673 non lus ») — en `aria-label` dans un bouton, en **texte masqué** (`sr-only`, chiffre visible `aria-hidden`) pour le compte d'une catégorie ou d'une étiquette (`CategoryBadge`) : celui d'une catégorie est hors de son bouton, et un `aria-label` sur un simple y est ignoré par beaucoup de lecteurs d'écran, qui ne lisaient que « 70 » ; le lecteur d'écran annonçait sinon « Non lus3673 », le chiffre collé au nom. Aucun effet visuel — à condition que le badge soit **positionné** (`relative`) : le texte masqué est en position absolue, et sans parent positionné il se rapportait à la page, échappait au rognage de la barre latérale et allongeait le document (2 649 px pour 747 de haut). La page entière devenait défilable : une molette au-dessus d'une zone fixe ou l'ouverture des Préférences remontait toute l'app, laissant une bande blanche (corrigé en 1.8.0). Le badge gris d'une étiquette (et celui d'un groupe d'étiquettes, qui en additionne les enfants) se lit **« N articles »** (`sidebar.itemCount`), pas « non lus » : `getStreamItemCount` interroge `/stream/items/ids` sans filtre `xt`, donc le chiffre est le **total** de l'étiquette, lus compris. Depuis la 1.9.1, une étiquette peut aussi porter la **pastille des flux** avec ses non-lus (`LabelCounts`, réglage « Afficher les non-lus des étiquettes », voir *Compteurs de Favoris, d'À lire plus tard et des étiquettes*). Tests : `src/components/Sidebar/FeedItem.badge.test.tsx`, `LabelBadge.test.tsx` et `LabelBadge.unread.test.tsx`. ⚠️ **Le menu s'ouvrait hors écran, et le geste paraissait donc inopérant.** `FeedContextMenu` portait le commentaire « keep menu in viewport » au-dessus d'un `left: x, top: y` brut : l'intention était écrite, jamais implémentée. Le tiroir mobile fait `min(360, 85 %)` — 331 px sur un iPhone de 390 — et le menu s'ancre au bord droit de la ligne, pour une largeur minimale de 236 px : il s'ouvrait de 331 à 567. `clampToViewport()` (`src/lib/`) le ramène, après mesure, la hauteur dépendant du mode et la largeur du plus long libellé traduit. Vaut aussi au clic droit près du bord d'une fenêtre étroite. ⚠️ **La fermeture au clic en dehors écoutait `mousedown`**, que iOS n'émet pas avant le `click` : une tape à côté laissait le menu ouvert. Passée à `pointerdown`. ⚠️ **L'appui long déclenchait aussi la sélection de texte d'iOS** : le titre du flux se surlignait en bleu, poignées comprises, par-dessus le menu. `.sidebar-feed-item` porte donc `-webkit-touch-callout: none` **et** `user-select: none` — la première seule laisse le surlignage, la seconde seule laisse la bulle système. ⚠️ **La rangée « Disposition de ce flux » débordait du menu** et se faisait couper par son `overflow: hidden` : le libellé traduit et les quatre boutons ne tiennent pas dans 236 px. Elle passe à la ligne (`flex-wrap`) plutôt que d'imposer un menu plus large partout. ⚠️ **Le menu était rendu DANS le tiroir, qui le rognait** (vu le 2026-10-14 sur iPhone à 320 px, reproduit sur l'émulateur Android à 320 px). Le tiroir mobile est `fixed`, transformé (glissement) et `overflow: hidden` : un `position: fixed` rendu dedans s'ancre au tiroir, et `clampToViewport()` recalait sur la **fenêtre** — 76 → 312 px dans un tiroir de 272. Les lignes dont le sélecteur tient à droite du libellé (« Article complet auto », « Ordre de ce flux », 225 → 299 px) étaient coupées ; celle de la disposition passait à la ligne et restait visible à gauche. Le menu est maintenant rendu par **portail sous ``**, comme `ArticleContextMenu`, en `width: max-content` (mesure indépendante de `left`, donc recalage exact) plafonné à la fenêtre moins deux marges. Test : `FeedContextMenu.portal.test.tsx`. - **Liens du pied** (1.4.5) : étoile GitHub et soutien (BuyMeACoffee), à côté de l'engrenage des préférences. Discrets (opacité 0,4), éclairés au survol : c'est une application qu'on ouvre vingt fois par jour, un appel au soutien visible en permanence y deviendrait pesant. - **Une rangée séparée a été essayée puis abandonnée** : mal placée. Les deux liens sont revenus dans le pied. - **Le libellé cède, les icônes non.** À la largeur minimale (160 px), trois icônes et « Se déconnecter » ne tiennent pas ensemble et l'engrenage sortait du cadre : le texte est tronqué (`truncate min-w-0`) et les icônes portent `flex-shrink-0`. À la largeur par défaut, tout tient. - La règle de 44 pt du pied mobile vise `button` **et `a`** : ces liens sont des ancres, et la règle les laissait à 27 px au doigt. - **Pas de lien « proposer une idée » dans l'application** — essayé, retiré. Les modèles d'issue restent sur GitHub (`.github/ISSUE_TEMPLATE/` : rapport de bug, idée, plus des liens vers les discussions FreshRSS et le signalement privé de vulnérabilité) et servent à qui ouvre une issue depuis le dépôt. ### Dispositions Trois colonnes, deux colonnes (liste seule), ou **grille**. La disposition est globale, mais surchargeable **par flux**. - **Où** : `src/lib/effectiveLayout.ts` — toujours résoudre par `effectiveLayout()` (surcharge du flux ?? global), jamais en lisant `panelLayout` directement - **Spec** : `docs/superpowers/specs/2026-08-18-grid-view-design.md` ### Taille des cartes de la grille Trois réglages dans **Préférences › Apparence › Tailles**, section « Grille », sous les tailles de texte (demandés dans l'issue #26) : **Largeur des cartes** (curseur de 160 à 480 px, au pixel près, défaut 240), **Remplir la ligne** (interrupteur, activé par défaut) et **Format d'image** (16:9, 4:3, 1:1 ou 3:4 en portrait, défaut 16:9 ; le 3:4 a suivi en 1.9.0, demandé dans la même issue). Les défauts reproduisent exactement la grille d'avant. - **Où** : `src/lib/gridCards.ts` (bornes, normaliseurs, `gridCardStyle()`, `gridClassName()`, testés), `uiStore.gridCardWidth` / `gridImageRatio` / `gridCardFill` / `resetGridCards`, `GridCardsSection` dans `AppearanceTab.tsx`, les deux `.article-grid` d'`ArticleList.tsx`, `index.css` - **Remplir la ligne, activé** (la grille d'origine) : la largeur est un minimum, les cartes s'élargissent pour remplir la ligne (`auto-fill` + `minmax`). ⚠️ Le curseur n'agit alors que **par paliers** : entre deux nombres de colonnes, il ne change rien à l'écran (dans une grille de 1 011 px intérieurs, hors des 14 px de marge de chaque côté, écart de 14 px : 5 colonnes jusqu'à 191 px, 4 cartes de 242 px de 192 à 242, 3 de 327 px de 243 à 327). C'est ce qu'a relevé le propriétaire au premier essai, et la raison de l'interrupteur. - **Remplir la ligne, désactivé** (`.article-grid--fixed`) : chaque carte mesure exactement la largeur choisie, la fenêtre ne décide que du nombre de colonnes, et la place restante se partage des deux côtés (`justify-content: center`, moins d'une demi-carte de chaque côté). Le curseur agit à chaque pixel. - **Un seul curseur pour tous les écrans** : sous 768 px, la largeur est réduite d'un tiers (`--grid-card-min-mobile`, 240 → 160 comme avant), et la grille **remplit toujours** la largeur, interrupteur ou non : une carte de taille exacte flotterait au milieu d'un écran de 300 px. La règle du média vient après `--fixed` dans `index.css` pour l'emporter. `min(…, 100%)` borne en plus la colonne à la largeur disponible : à 480 px (320 sur téléphone), une liste plus étroite affiche une carte par ligne au lieu de déborder à l'horizontale. - **Synchronisés, communs à tous les thèmes** : ce sont des réglages de l'interface (`UI_SYNC_KEYS`), pas du thème, contrairement aux tailles de texte de la même page. Changer de thème ne les touche pas ; « Réinitialiser les tailles » les remet aussi aux défauts (remplissage compris). Toute valeur hors bornes (client ancien, valeur trafiquée) retombe sur le défaut. - **Pas de format « original »**, assumé : des images de hauteurs différentes casseraient l'alignement des rangées — ce serait une autre vue, pas un réglage. **Rien par flux** non plus, pour ne pas alourdir le menu du flux. - **L'aperçu en haut de la page montre la liste, pas la grille** : la grille derrière le panneau sert d'aperçu. - **Curseurs nommés** (1.8.0) : tous ceux de la page Tailles (`FontRow`) relient leur `