mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-06 21:41:42 +02:00
docs: capitaliser les patterns valides du 16 mars
This commit is contained in:
MaksTinyWorkshop
@@ -8,7 +8,7 @@ Ce fichier contient **uniquement** des patterns back-end :
|
||||
|
||||
Objectif : éviter de réinventer la roue et réduire le temps de debug.
|
||||
|
||||
Dernière mise à jour : 12-03-2026
|
||||
Dernière mise à jour : 16-03-2026
|
||||
|
||||
---
|
||||
|
||||
@@ -32,6 +32,11 @@ Dernière mise à jour : 12-03-2026
|
||||
- [Restauration d’achats Stripe en 3 étapes](#pattern-restauration-achats-stripe)
|
||||
- [Mapping explicite de `P2002` Prisma sur update de champ unique](#pattern-prisma-p2002-update-unique)
|
||||
- [Autorisation interne minimale sans RBAC complet](#pattern-autorisation-interne-minimale)
|
||||
- [Anti-énumération sur endpoints auth liés à un email](#pattern-anti-enumeration-auth-email)
|
||||
- [Token à usage unique — génération, hash et invalidation atomique](#pattern-token-usage-unique)
|
||||
- [Guardrails multi-tenant — 403 vs 404 selon la sémantique](#pattern-guardrails-multi-tenant-403-404)
|
||||
- [Repository tenant-aware — `tenantId` obligatoire dans la signature](#pattern-repository-tenant-aware)
|
||||
- [Défense en profondeur — inclure `tenantId` dans les updates](#pattern-tenantid-dans-updates)
|
||||
|
||||
---
|
||||
|
||||
@@ -747,3 +752,176 @@ handlePackWebhookEvent(event): PackWebhookResult | null
|
||||
|
||||
- On préfère 5 patterns solides à 50 “bons conseils”.
|
||||
- Un pattern = une idée actionnable + son cadre d’utilisation.
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-anti-enumeration-auth-email"></a>
|
||||
## Pattern : Anti-énumération sur endpoints auth liés à un email
|
||||
|
||||
- Objectif : empêcher qu’un endpoint auth révèle si un compte existe, n’existe pas ou n’est pas éligible.
|
||||
- Contexte : reset de mot de passe, invitation, vérification de compte, login ou tout flux qui part d’un email utilisateur.
|
||||
- Quand l’utiliser : dès qu’une requête auth touche un identifiant de type email.
|
||||
- Quand l’éviter : jamais sur une surface exposée.
|
||||
- Avantage :
|
||||
- réduit la fuite d’information sur les comptes existants
|
||||
- homogénéise les réponses côté client
|
||||
- se combine bien avec les garde-fous anti-abus
|
||||
- Limites / vigilance :
|
||||
- ne protège pas seul contre le brute-force, à combiner avec du rate-limiting
|
||||
- les logs internes doivent conserver la vraie cause sans l’exposer au client
|
||||
- Validé le : 16-03-2026
|
||||
- Contexte technique : Node.js / auth applicative / API HTTP
|
||||
|
||||
### Implémentation (exemple minimal)
|
||||
|
||||
```txt
|
||||
- retourner la même réponse HTTP 200 qu’un compte existe ou non
|
||||
- ne jamais distinguer "email inconnu", "email connu" ou "compte OAuth-only" dans la réponse
|
||||
- journaliser la cause réelle côté serveur
|
||||
- ajouter un rate-limiting basé sur email + IP
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- Réponse client uniforme pour les cas compte connu/inconnu/non éligible
|
||||
- Aucune fuite d’existence dans le message ou le code d’erreur
|
||||
- Rate-limiting présent sur les endpoints exposés
|
||||
- Logs internes exploitables
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-token-usage-unique"></a>
|
||||
## Pattern : Token à usage unique — génération, hash et invalidation atomique
|
||||
|
||||
- Objectif : standardiser la création et la consommation de tokens sensibles sans stocker de secret brut en base.
|
||||
- Contexte : invitation, reset de mot de passe, vérification d’email, lien magique ou tout token one-shot.
|
||||
- Quand l’utiliser : pour tout token à usage unique transmis à l’utilisateur.
|
||||
- Quand l’éviter : sessions longues ou secrets devant être relus en clair côté serveur.
|
||||
- Avantage :
|
||||
- réduit l’impact d’une fuite de base
|
||||
- garde des tokens URL-safe
|
||||
- favorise une consommation atomique et réutilisable
|
||||
- Limites / vigilance :
|
||||
- la consommation doit rester atomique
|
||||
- la politique d’expiration doit être explicite
|
||||
- Validé le : 16-03-2026
|
||||
- Contexte technique : Node.js `crypto` / Prisma / email ou URL signée
|
||||
|
||||
### Implémentation (exemple minimal)
|
||||
|
||||
```txt
|
||||
- générer le token avec `crypto.randomBytes(32).toString("base64url")`
|
||||
- stocker uniquement le hash SHA-256 du token en base
|
||||
- transmettre le token brut uniquement via URL ou email
|
||||
- recalculer le hash côté serveur lors de la consommation
|
||||
- invalider le token dans une transaction atomique après usage
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- Token brut jamais persisté en base
|
||||
- Hash recalculé côté serveur pour la vérification
|
||||
- Expiration explicite
|
||||
- Invalidation atomique après consommation
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-guardrails-multi-tenant-403-404"></a>
|
||||
## Pattern : Guardrails multi-tenant — 403 vs 404 selon la sémantique
|
||||
|
||||
- Objectif : éviter les fuites d’information inter-tenant tout en gardant une sémantique d’erreur claire.
|
||||
- Contexte : API multi-tenant avec ressources métier isolées et surfaces internes ou opérateur.
|
||||
- Quand l’utiliser : dès qu’une vérification d’appartenance tenant peut soit refuser explicitement l’accès, soit masquer l’existence d’une ressource.
|
||||
- Quand l’éviter : contexte mono-tenant ou endpoints purement internes sans enjeu de fuite.
|
||||
- Avantage :
|
||||
- clarifie la convention de sécurité
|
||||
- évite les réponses incohérentes selon les modules
|
||||
- facilite les tests d’isolation tenant
|
||||
- Limites / vigilance :
|
||||
- la convention doit être documentée et appliquée partout
|
||||
- un mauvais choix entre 403 et 404 peut révéler une information sensible
|
||||
- Validé le : 16-03-2026
|
||||
- Contexte technique : API multi-tenant / HTTP / services métier
|
||||
|
||||
### Implémentation (exemple minimal)
|
||||
|
||||
```txt
|
||||
- `assertTenantMatch(actor, expectedTenantId)` -> 403 quand la ressource est connue mais l’accès refusé
|
||||
- `assertResourceBelongsToTenant(actor, resourceTenantId)` -> 404 quand il faut masquer l’existence d’une ressource d’un autre tenant
|
||||
- documenter la convention dans le module
|
||||
- couvrir les deux sémantiques par des tests dédiés
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- Convention 403 vs 404 documentée
|
||||
- Helpers distincts selon la sémantique métier
|
||||
- Aucune fuite d’existence cross-tenant sur les ressources métier
|
||||
- Tests dédiés sur les deux comportements
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-repository-tenant-aware"></a>
|
||||
## Pattern : Repository tenant-aware — `tenantId` obligatoire dans la signature
|
||||
|
||||
- Objectif : rendre impossible par construction une query non scopée sur un domaine multi-tenant.
|
||||
- Contexte : repositories ou services d’accès aux données sur ressources tenant-scoped.
|
||||
- Quand l’utiliser : dès qu’un domaine métier est massivement filtré par tenant.
|
||||
- Quand l’éviter : domaines réellement globaux ou méthodes volontairement cross-tenant.
|
||||
- Avantage :
|
||||
- force le scoping dès la signature TypeScript
|
||||
- réduit les oublis de filtre tenant dans les call sites
|
||||
- rend les exceptions cross-tenant visibles
|
||||
- Limites / vigilance :
|
||||
- les exceptions cross-tenant doivent être rares et documentées explicitement
|
||||
- ne dispense pas d’un second garde-fou dans les mutations sensibles
|
||||
- Validé le : 16-03-2026
|
||||
- Contexte technique : TypeScript / Prisma / architecture repository
|
||||
|
||||
### Implémentation (exemple minimal)
|
||||
|
||||
```txt
|
||||
- chaque méthode métier tenant-scoped prend `tenantId` en paramètre obligatoire
|
||||
- les méthodes réellement cross-tenant sont nommées et documentées comme exception
|
||||
- les call sites Prisma directs sur ces domaines sont interdits ou supprimés
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- `tenantId` obligatoire sur les méthodes tenant-scoped
|
||||
- Exceptions cross-tenant documentées
|
||||
- Appels directs concurrents à Prisma supprimés
|
||||
- Tests sur scoping tenant au niveau repository
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-tenantid-dans-updates"></a>
|
||||
## Pattern : Défense en profondeur — inclure `tenantId` dans les updates
|
||||
|
||||
- Objectif : éviter une mutation cross-tenant même si un identifiant a été mal résolu en amont.
|
||||
- Contexte : `update` ou `updateMany` sur une ressource tenant-scoped.
|
||||
- Quand l’utiliser : dès qu’une mutation dépend d’un `id` reçu ou résolu dans un flux multi-tenant.
|
||||
- Quand l’éviter : ressources globales non liées à un tenant.
|
||||
- Avantage :
|
||||
- ajoute une seconde barrière côté base
|
||||
- réduit l’impact d’un call site mal scopé
|
||||
- rend la mutation plus sûre sans complexité forte
|
||||
- Limites / vigilance :
|
||||
- ne remplace pas le scoping en lecture ni la vérification d’autorisation
|
||||
- suppose que `tenantId` soit disponible au moment de la mutation
|
||||
- Validé le : 16-03-2026
|
||||
- Contexte technique : Prisma / multi-tenant / mutations métier
|
||||
|
||||
### Implémentation (exemple minimal)
|
||||
|
||||
```txt
|
||||
- préférer `where: { id, tenantId }` à `where: { id }` sur les updates tenant-scoped
|
||||
- appliquer la même règle sur `updateMany` et opérations de révocation
|
||||
- conserver les vérifications métier amont, mais ne pas leur déléguer toute la sécurité
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- `tenantId` présent dans les clauses `where` des updates sensibles
|
||||
- Pas de mutation tenant-scoped basée sur `id` seul
|
||||
- Revue explicite des exceptions documentées
|
||||
|
||||
Reference in New Issue
Block a user