@astratra/saas-kit 1.4.0 → 1.5.0
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 +42 -0
- package/package.json +2 -2
- package/src/app.js +20 -0
- package/src/index.d.ts +18 -0
package/README.md
CHANGED
|
@@ -111,6 +111,24 @@ 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
|
+
|
|
114
132
|
Le cookie CSRF (`astratra_csrf`) est amorcé automatiquement sur toute
|
|
115
133
|
requête sûre (GET/HEAD/OPTIONS) dès le démarrage de l'app — y compris tes
|
|
116
134
|
propres routes `GET` ajoutées via `extendRoutes` — donc pas besoin de monter
|
|
@@ -159,6 +177,30 @@ d'appeler ton store — email au bon format, champs requis réellement présents
|
|
|
159
177
|
connaît lui-même — le reste du payload (champs propres à ton store) passe
|
|
160
178
|
tel quel, sans schéma imposé.
|
|
161
179
|
|
|
180
|
+
Ça ne couvre que les routes intégrées ci-dessus. Pour tes propres routes
|
|
181
|
+
(via `extendRoutes`), voir « Anti-injection Mongo » juste en dessous —
|
|
182
|
+
appliqué automatiquement, lui, à toute la surface de l'app.
|
|
183
|
+
|
|
184
|
+
## Anti-injection Mongo (par défaut, y compris `extendRoutes`)
|
|
185
|
+
|
|
186
|
+
`createMongoSanitizeMiddleware` (`@astratra/security`) est monté
|
|
187
|
+
automatiquement, sans configuration, sur `req.body`/`req.query`/
|
|
188
|
+
`req.params` — retire toute clé `$...` (opérateur Mongo) ou contenant un
|
|
189
|
+
`.` avant qu'elle n'atteigne une route, **y compris les tiennes** ajoutées
|
|
190
|
+
via `extendRoutes`. Trouvé sur un projet consommateur réel : une route
|
|
191
|
+
personnalisée passait `req.query.date` tel quel dans un filtre Mongoose, et
|
|
192
|
+
`?date[$gt]=` (notation crochet du parseur `qs` d'Express) devenait un
|
|
193
|
+
opérateur Mongo choisi par l'appelant plutôt qu'une simple chaîne — la
|
|
194
|
+
« Validation des entrées » ci-dessus ne protège que les routes intégrées,
|
|
195
|
+
pas le code que tu ajoutes toi-même.
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
createSaasApp({
|
|
199
|
+
// ...
|
|
200
|
+
mongoSanitize: false // désactive complètement, si besoin
|
|
201
|
+
});
|
|
202
|
+
```
|
|
203
|
+
|
|
162
204
|
## Adapters requis
|
|
163
205
|
|
|
164
206
|
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.
|
|
3
|
+
"version": "1.5.0",
|
|
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.
|
|
29
|
+
"@astratra/security": "^1.6.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
|