@astratra/saas-kit 1.4.1 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -111,6 +111,43 @@ S'applique aussi bien aux routes intégrées (`/auth`, `/users`, ...) qu'à
111
111
  celles ajoutées via `extendRoutes`. Omets `options.cors` et rien ne change —
112
112
  comme avant, à toi de gérer CORS si tu en as besoin.
113
113
 
114
+ **Derrière un reverse proxy (nginx, un load balancer...)**, passe aussi
115
+ `trustProxy` — sinon Express ignore `X-Forwarded-For` et voit l'IP du proxy
116
+ pour absolument tous les visiteurs, y compris dans les rate limiters
117
+ ci-dessous (`apiRateLimit`, `loginRateLimit`) : un seul client "vu", donc un
118
+ seul quota partagé par tout le monde. Trouvé sur un projet consommateur
119
+ déployé derrière nginx, en production, via le monitoring d'erreurs — pas en
120
+ dev, où il n'y a pas de proxy pour révéler le problème.
121
+
122
+ ```js
123
+ createSaasApp({
124
+ // ...
125
+ trustProxy: 1 // fait confiance à exactement un saut de proxy (nginx)
126
+ });
127
+ ```
128
+
129
+ Non défini par défaut (comportement Express standard, inchangé) — dépend du
130
+ déploiement, Astratra ne peut pas le deviner à ta place.
131
+
132
+ `apiRateLimit`/`loginRateLimit` sont transmis tels quels à
133
+ `createApiLimiter`/`createLoginLimiter` (`@astratra/security`) : pour isoler
134
+ leurs compteurs sur une même instance Redis, fournis un store namespacé via
135
+ `createRedisRateLimitStore({ redisUrl, prefix })` :
136
+
137
+ ```js
138
+ const { createRedisRateLimitStore } = require('@astratra/security');
139
+
140
+ createSaasApp({
141
+ // ...
142
+ apiRateLimit: {
143
+ store: createRedisRateLimitStore({ redisUrl, prefix: 'mon-app:rate:api:' })
144
+ },
145
+ loginRateLimit: {
146
+ store: createRedisRateLimitStore({ redisUrl, prefix: 'mon-app:rate:connexion:' })
147
+ }
148
+ });
149
+ ```
150
+
114
151
  Le cookie CSRF (`astratra_csrf`) est amorcé automatiquement sur toute
115
152
  requête sûre (GET/HEAD/OPTIONS) dès le démarrage de l'app — y compris tes
116
153
  propres routes `GET` ajoutées via `extendRoutes` — donc pas besoin de monter
@@ -159,6 +196,30 @@ d'appeler ton store — email au bon format, champs requis réellement présents
159
196
  connaît lui-même — le reste du payload (champs propres à ton store) passe
160
197
  tel quel, sans schéma imposé.
161
198
 
199
+ Ça ne couvre que les routes intégrées ci-dessus. Pour tes propres routes
200
+ (via `extendRoutes`), voir « Anti-injection Mongo » juste en dessous —
201
+ appliqué automatiquement, lui, à toute la surface de l'app.
202
+
203
+ ## Anti-injection Mongo (par défaut, y compris `extendRoutes`)
204
+
205
+ `createMongoSanitizeMiddleware` (`@astratra/security`) est monté
206
+ automatiquement, sans configuration, sur `req.body`/`req.query`/
207
+ `req.params` — retire toute clé `$...` (opérateur Mongo) ou contenant un
208
+ `.` avant qu'elle n'atteigne une route, **y compris les tiennes** ajoutées
209
+ via `extendRoutes`. Trouvé sur un projet consommateur réel : une route
210
+ personnalisée passait `req.query.date` tel quel dans un filtre Mongoose, et
211
+ `?date[$gt]=` (notation crochet du parseur `qs` d'Express) devenait un
212
+ opérateur Mongo choisi par l'appelant plutôt qu'une simple chaîne — la
213
+ « Validation des entrées » ci-dessus ne protège que les routes intégrées,
214
+ pas le code que tu ajoutes toi-même.
215
+
216
+ ```js
217
+ createSaasApp({
218
+ // ...
219
+ mongoSanitize: false // désactive complètement, si besoin
220
+ });
221
+ ```
222
+
162
223
  ## Adapters requis
163
224
 
164
225
  Une vraie application en production doit injecter ses propres adapters. Le
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/saas-kit",
3
- "version": "1.4.1",
3
+ "version": "1.5.1",
4
4
  "description": "Reusable backend starter kit that assembles Astratra core, security, and AI packages.",
5
5
  "engines": {
6
6
  "node": ">=20"
@@ -26,7 +26,7 @@
26
26
  "dependencies": {
27
27
  "@astratra/ai": "^1.0.0",
28
28
  "@astratra/core": "^1.0.0",
29
- "@astratra/security": "^1.5.0",
29
+ "@astratra/security": "^1.7.0",
30
30
  "express": "^4.18.3",
31
31
  "express-validator": "^7.3.2",
32
32
  "jsonwebtoken": "^9.0.2"
package/src/app.js CHANGED
@@ -15,6 +15,7 @@ const {
15
15
  createCsrfMiddleware,
16
16
  createLoginLimiter,
17
17
  createMemoryRevocationStore,
18
+ createMongoSanitizeMiddleware,
18
19
  createSecurityAuditLogger,
19
20
  createSecurityHeadersMiddleware,
20
21
  createWafMiddleware,
@@ -78,6 +79,19 @@ function createSaasApp(options = {}) {
78
79
  const normalized = normalizeOptions(options);
79
80
  const app = express();
80
81
 
82
+ // Off by default — whether an app sits behind a reverse proxy (nginx,
83
+ // an ALB...) is a deployment detail Astratra can't guess, and trusting
84
+ // X-Forwarded-For blindly when there's no proxy in front lets a client
85
+ // spoof its own IP straight past the rate limiters below. Found on a real
86
+ // consumer app deployed behind nginx: without this, every visitor shared
87
+ // the same rate-limit bucket (nginx's own loopback IP), because Express
88
+ // never trusted the header carrying the real client IP.
89
+ // `1` = trust exactly one hop (nginx as the sole proxy); see Express's
90
+ // `trust proxy` docs for other topologies (multiple proxies, IP ranges).
91
+ if (normalized.trustProxy !== undefined) {
92
+ app.set('trust proxy', normalized.trustProxy);
93
+ }
94
+
81
95
  // Astratra imposes no fixed CORS policy — which origins to allow is
82
96
  // project-specific — but leaves the primitive available so consumers
83
97
  // don't reinvent it. Mounted FIRST, ahead of everything else: CORS
@@ -111,6 +125,12 @@ function createSaasApp(options = {}) {
111
125
  // needs a project-specific decision), so this is unconditional like CSP.
112
126
  app.use(createSecurityHeadersMiddleware(normalized.securityHeaders));
113
127
  app.use(express.json());
128
+ // Every option here has a safe universal default (no legitimate client
129
+ // ever sends a `$`-prefixed or dotted JSON key), so unconditional like
130
+ // CSP/securityHeaders — pass `mongoSanitize: false` to disable.
131
+ if (normalized.mongoSanitize !== false) {
132
+ app.use(createMongoSanitizeMiddleware(normalized.mongoSanitize === true ? {} : normalized.mongoSanitize));
133
+ }
114
134
  app.use(createWafMiddleware(normalized.waf));
115
135
  app.use(createApiLimiter(normalized.apiRateLimit));
116
136
 
package/src/index.d.ts CHANGED
@@ -4,6 +4,7 @@ import type {
4
4
  CsrfMiddlewareOptions,
5
5
  CspOptions,
6
6
  LoginLimiterOptions,
7
+ MongoSanitizeOptions,
7
8
  RateLimitOptions,
8
9
  RequestHandler,
9
10
  RevocationStore,
@@ -112,8 +113,25 @@ export interface CreateSaasAppOptions {
112
113
  * default behavior).
113
114
  */
114
115
  cors?: CorsMiddlewareOptions | true;
116
+ /**
117
+ * Forwarded to Express's `app.set('trust proxy', value)`. Unset by
118
+ * default (Express trusts nothing beyond the direct socket) — set this
119
+ * explicitly when the app runs behind a reverse proxy (nginx, an ALB...),
120
+ * otherwise every client shares the same rate-limit bucket (the proxy's
121
+ * own IP) instead of one bucket per real visitor. `1` trusts exactly one
122
+ * hop; see Express's `trust proxy` docs for other topologies.
123
+ */
124
+ trustProxy?: boolean | number | string | string[];
115
125
  /** X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, HSTS. Every option has a safe default; mounted unconditionally like csp. */
116
126
  securityHeaders?: SecurityHeadersOptions;
127
+ /**
128
+ * Strips `$`-prefixed/dotted keys from req.body/req.query/req.params
129
+ * before any route (built-in or via extendRoutes) can see them — closes
130
+ * Mongo operator injection by default. Every option has a safe universal
131
+ * default; mounted unconditionally like csp/securityHeaders. Pass `false`
132
+ * to disable.
133
+ */
134
+ mongoSanitize?: MongoSanitizeOptions | boolean;
117
135
  /**
118
136
  * Structured logging for any request ending in 401/403/429 (failed auth,
119
137
  * CSRF/WAF block, rate limit). Mounted by default — pass `false` to