@astratra/saas-kit 1.2.0 → 1.4.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 CHANGED
@@ -53,12 +53,15 @@ app.listen(3000);
53
53
  - `GET /dashboard/summary`
54
54
 
55
55
  Toutes les routes protégées suivent le même ordre de middlewares de
56
- sécurité que la mini-app de démo : request id, parseur de cookies, CSP
57
- (`default-src 'none'` par défaut, adapté à une API JSON — surchargeable via
58
- `options.csp`), parseur JSON, WAF heuristique, limiteur API, limiteur de
59
- login pour `/auth`, auth JWT (cookie ou `Authorization: Bearer`) pour les
60
- modules protégés, CSRF pour les routes mutantes, puis 404 et gestion
61
- d'erreurs.
56
+ sécurité que la mini-app de démo : request id, journal d'événements de
57
+ sécurité (`options.securityAudit`, actif par défaut), parseur de cookies,
58
+ amorçage CSRF, CSP (`default-src 'none'` par défaut, adapté à une API JSON
59
+ — surchargeable via `options.csp`), en-têtes de sécurité standard
60
+ (`options.securityHeaders` — X-Frame-Options, X-Content-Type-Options,
61
+ Referrer-Policy, Permissions-Policy, HSTS en production), parseur JSON, WAF
62
+ heuristique, limiteur API, limiteur de login pour `/auth`, auth JWT (cookie
63
+ ou `Authorization: Bearer`) pour les modules protégés, CSRF pour les routes
64
+ mutantes, puis 404 et gestion d'erreurs.
62
65
 
63
66
  `jwtAlgorithms` vaut `['HS256']` par defaut. `jwtIssuer` et `jwtAudience` sont
64
67
  optionnels, mais recommandes des qu'une app sort du simple developpement local.
@@ -87,6 +90,27 @@ L'app retournée expose aussi directement `app.authMiddleware`,
87
90
  `app.csrfMiddleware` et `app.authorizeAdmin`, au cas où tu préfères les
88
91
  monter toi-même après coup plutôt que via `extendRoutes`.
89
92
 
93
+ ## CORS
94
+
95
+ `options.cors` active le CORS pour toute l'app en un seul champ de
96
+ configuration — origines autorisées, credentials, headers/méthodes — sans
97
+ middleware à écrire ni à monter toi-même. Astratra ne fixe pas de liste
98
+ d'origines par défaut (chaque projet a la sienne), mais gère le montage :
99
+ `createCorsMiddleware` (`@astratra/security`) est posé tout en premier,
100
+ avant absolument tout le reste, garantissant que les en-têtes CORS
101
+ s'appliquent à chaque route — y compris la réponse de preflight `OPTIONS` :
102
+
103
+ ```js
104
+ const app = createSaasApp({
105
+ // ...
106
+ cors: { allowedOrigins: [process.env.WEB_ORIGIN] }
107
+ });
108
+ ```
109
+
110
+ S'applique aussi bien aux routes intégrées (`/auth`, `/users`, ...) qu'à
111
+ celles ajoutées via `extendRoutes`. Omets `options.cors` et rien ne change —
112
+ comme avant, à toi de gérer CORS si tu en as besoin.
113
+
90
114
  Le cookie CSRF (`astratra_csrf`) est amorcé automatiquement sur toute
91
115
  requête sûre (GET/HEAD/OPTIONS) dès le démarrage de l'app — y compris tes
92
116
  propres routes `GET` ajoutées via `extendRoutes` — donc pas besoin de monter
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/saas-kit",
3
- "version": "1.2.0",
3
+ "version": "1.4.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.2.0",
29
+ "@astratra/security": "^1.4.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
@@ -9,11 +9,14 @@ const {
9
9
  cookieParserMiddleware,
10
10
  createApiLimiter,
11
11
  createAuthMiddleware,
12
+ createCorsMiddleware,
12
13
  createCspMiddleware,
13
14
  createCsrfCookiePrimer,
14
15
  createCsrfMiddleware,
15
16
  createLoginLimiter,
16
17
  createMemoryRevocationStore,
18
+ createSecurityAuditLogger,
19
+ createSecurityHeadersMiddleware,
17
20
  createWafMiddleware,
18
21
  DEFAULT_SESSION_COOKIE_NAME
19
22
  } = require('@astratra/security');
@@ -75,7 +78,27 @@ function createSaasApp(options = {}) {
75
78
  const normalized = normalizeOptions(options);
76
79
  const app = express();
77
80
 
81
+ // Astratra imposes no fixed CORS policy — which origins to allow is
82
+ // project-specific — but leaves the primitive available so consumers
83
+ // don't reinvent it. Mounted FIRST, ahead of everything else: CORS
84
+ // headers (including on the OPTIONS preflight response) must be set
85
+ // before any other middleware can short-circuit the request. Omit
86
+ // options.cors and this is a no-op, unchanged from before.
87
+ if (normalized.cors) {
88
+ app.use(createCorsMiddleware(normalized.cors === true ? {} : normalized.cors));
89
+ }
90
+
78
91
  app.use(requestIdMiddleware);
92
+ // Every request that ends in 401/403/429 (failed auth, CSRF/WAF block,
93
+ // rate limit) gets a structured log line — none of those layers logged
94
+ // anything anywhere before this, so an attack attempt was invisible
95
+ // until it succeeded. Mounted early so req.id is already set; observes
96
+ // the response rather than hooking each layer individually, so where
97
+ // exactly it sits in the stack otherwise doesn't matter. Pass
98
+ // options.securityAudit: false to disable.
99
+ if (normalized.securityAudit !== false) {
100
+ app.use(createSecurityAuditLogger(normalized.securityAudit === true ? {} : normalized.securityAudit));
101
+ }
79
102
  app.use(cookieParserMiddleware());
80
103
  // Seeds the CSRF cookie on every safe request (GET/HEAD/OPTIONS), globally,
81
104
  // before any route — including custom routes mounted via extendRoutes.
@@ -84,6 +107,9 @@ function createSaasApp(options = {}) {
84
107
  // validated, so the client's first mutating request always fails.
85
108
  app.use(createCsrfCookiePrimer(normalized.csrf));
86
109
  app.use(createCspMiddleware(normalized.csp));
110
+ // Every option here has a safe universal default (unlike CORS, nothing
111
+ // needs a project-specific decision), so this is unconditional like CSP.
112
+ app.use(createSecurityHeadersMiddleware(normalized.securityHeaders));
87
113
  app.use(express.json());
88
114
  app.use(createWafMiddleware(normalized.waf));
89
115
  app.use(createApiLimiter(normalized.apiRateLimit));
package/src/index.d.ts CHANGED
@@ -1,11 +1,14 @@
1
1
  import type {
2
2
  AuthMiddlewareOptions,
3
+ CorsMiddlewareOptions,
3
4
  CsrfMiddlewareOptions,
4
5
  CspOptions,
5
6
  LoginLimiterOptions,
6
7
  RateLimitOptions,
7
8
  RequestHandler,
8
9
  RevocationStore,
10
+ SecurityAuditLoggerOptions,
11
+ SecurityHeadersOptions,
9
12
  SessionCookieOptions,
10
13
  WafOptions,
11
14
  WebauthnOptions,
@@ -101,6 +104,23 @@ export interface CreateSaasAppOptions {
101
104
  publicUserFields?: string[];
102
105
  cookie?: SessionCookieOptions;
103
106
  csrf?: CsrfMiddlewareOptions;
107
+ /**
108
+ * Mounts createCorsMiddleware as the FIRST middleware, ahead of
109
+ * everything else — required for CORS headers to reach the preflight
110
+ * OPTIONS response. `true` uses the default (dev origins only, no
111
+ * explicit allow-list). Omit entirely for no CORS handling (unchanged
112
+ * default behavior).
113
+ */
114
+ cors?: CorsMiddlewareOptions | true;
115
+ /** X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, HSTS. Every option has a safe default; mounted unconditionally like csp. */
116
+ securityHeaders?: SecurityHeadersOptions;
117
+ /**
118
+ * Structured logging for any request ending in 401/403/429 (failed auth,
119
+ * CSRF/WAF block, rate limit). Mounted by default — pass `false` to
120
+ * disable, `true` or an options object to customize (custom `log` sink,
121
+ * different `statusCodes`).
122
+ */
123
+ securityAudit?: SecurityAuditLoggerOptions | boolean;
104
124
  webauthnStore?: WebauthnStore;
105
125
  webauthn?: WebauthnOptions;
106
126
  waf?: WafOptions;