@astratra/saas-kit 1.1.1 → 1.3.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
@@ -63,6 +63,58 @@ d'erreurs.
63
63
  `jwtAlgorithms` vaut `['HS256']` par defaut. `jwtIssuer` et `jwtAudience` sont
64
64
  optionnels, mais recommandes des qu'une app sort du simple developpement local.
65
65
 
66
+ ## Ajouter tes propres routes
67
+
68
+ `createSaasApp()` termine sa propre pile de middlewares par un
69
+ `notFoundMiddleware`/`errorMiddleware` avant de te rendre l'app. N'ajoute
70
+ donc **pas** tes routes avec `app.get(...)` / `app.use(...)` sur l'objet
71
+ retourné — elles tomberaient systématiquement sur ce 404 interne, puisque
72
+ Express évalue sa pile dans l'ordre d'enregistrement. Passe plutôt
73
+ `options.extendRoutes` : il s'exécute avant ce 404, avec les mêmes instances
74
+ `authMiddleware`/`csrfMiddleware`/`authorizeAdmin` que les routes intégrées.
75
+
76
+ ```js
77
+ const app = createSaasApp({
78
+ // ...
79
+ extendRoutes: (app, { authMiddleware, csrfMiddleware, authorizeAdmin }) => {
80
+ app.get('/api/products', authMiddleware, listProducts);
81
+ app.post('/api/products', authMiddleware, authorizeAdmin, csrfMiddleware, createProduct);
82
+ }
83
+ });
84
+ ```
85
+
86
+ L'app retournée expose aussi directement `app.authMiddleware`,
87
+ `app.csrfMiddleware` et `app.authorizeAdmin`, au cas où tu préfères les
88
+ monter toi-même après coup plutôt que via `extendRoutes`.
89
+
90
+ ## CORS
91
+
92
+ `options.cors` active le CORS pour toute l'app en un seul champ de
93
+ configuration — origines autorisées, credentials, headers/méthodes — sans
94
+ middleware à écrire ni à monter toi-même. Astratra ne fixe pas de liste
95
+ d'origines par défaut (chaque projet a la sienne), mais gère le montage :
96
+ `createCorsMiddleware` (`@astratra/security`) est posé tout en premier,
97
+ avant absolument tout le reste, garantissant que les en-têtes CORS
98
+ s'appliquent à chaque route — y compris la réponse de preflight `OPTIONS` :
99
+
100
+ ```js
101
+ const app = createSaasApp({
102
+ // ...
103
+ cors: { allowedOrigins: [process.env.WEB_ORIGIN] }
104
+ });
105
+ ```
106
+
107
+ S'applique aussi bien aux routes intégrées (`/auth`, `/users`, ...) qu'à
108
+ celles ajoutées via `extendRoutes`. Omets `options.cors` et rien ne change —
109
+ comme avant, à toi de gérer CORS si tu en as besoin.
110
+
111
+ Le cookie CSRF (`astratra_csrf`) est amorcé automatiquement sur toute
112
+ requête sûre (GET/HEAD/OPTIONS) dès le démarrage de l'app — y compris tes
113
+ propres routes `GET` ajoutées via `extendRoutes` — donc pas besoin de monter
114
+ `csrfMiddleware` toi-même sur des routes qui ne font que lire.
115
+ `csrfMiddleware` reste nécessaire sur tes routes mutantes (POST/PATCH/DELETE)
116
+ pour valider le token.
117
+
66
118
  ## Session cookie HttpOnly, CSRF et révocation
67
119
 
68
120
  `POST /auth/login` pose toujours un cookie `HttpOnly` (`astratra_session` par
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/saas-kit",
3
- "version": "1.1.1",
3
+ "version": "1.3.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.1.0",
29
+ "@astratra/security": "^1.3.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,7 +9,9 @@ const {
9
9
  cookieParserMiddleware,
10
10
  createApiLimiter,
11
11
  createAuthMiddleware,
12
+ createCorsMiddleware,
12
13
  createCspMiddleware,
14
+ createCsrfCookiePrimer,
13
15
  createCsrfMiddleware,
14
16
  createLoginLimiter,
15
17
  createMemoryRevocationStore,
@@ -74,8 +76,24 @@ function createSaasApp(options = {}) {
74
76
  const normalized = normalizeOptions(options);
75
77
  const app = express();
76
78
 
79
+ // Astratra imposes no fixed CORS policy — which origins to allow is
80
+ // project-specific — but leaves the primitive available so consumers
81
+ // don't reinvent it. Mounted FIRST, ahead of everything else: CORS
82
+ // headers (including on the OPTIONS preflight response) must be set
83
+ // before any other middleware can short-circuit the request. Omit
84
+ // options.cors and this is a no-op, unchanged from before.
85
+ if (normalized.cors) {
86
+ app.use(createCorsMiddleware(normalized.cors === true ? {} : normalized.cors));
87
+ }
88
+
77
89
  app.use(requestIdMiddleware);
78
90
  app.use(cookieParserMiddleware());
91
+ // Seeds the CSRF cookie on every safe request (GET/HEAD/OPTIONS), globally,
92
+ // before any route — including custom routes mounted via extendRoutes.
93
+ // Without this, a route wiring createCsrfMiddleware only on its mutating
94
+ // handlers issues the cookie in the SAME response that needed it
95
+ // validated, so the client's first mutating request always fails.
96
+ app.use(createCsrfCookiePrimer(normalized.csrf));
79
97
  app.use(createCspMiddleware(normalized.csp));
80
98
  app.use(express.json());
81
99
  app.use(createWafMiddleware(normalized.waf));
@@ -138,6 +156,31 @@ function createSaasApp(options = {}) {
138
156
  usersStore: normalized.usersStore
139
157
  }));
140
158
 
159
+ // Exposed so a consumer can reuse the exact same auth/CSRF instances
160
+ // instead of rebuilding duplicates with (easy to get out of sync)
161
+ // options — e.g. `app.use('/api', app.authMiddleware, app.csrfMiddleware)`.
162
+ app.authMiddleware = authMiddleware;
163
+ app.csrfMiddleware = csrfMiddleware;
164
+ app.authorizeAdmin = authorizeAdmin;
165
+
166
+ // createSaasApp() already terminates its own middleware stack with a
167
+ // catch-all 404 + error handler below. Any route registered on `app`
168
+ // AFTER createSaasApp() returns is therefore unreachable — Express
169
+ // evaluates middleware in registration order, and notFoundMiddleware
170
+ // matches every path unconditionally. `extendRoutes` is the supported
171
+ // way to add your own routes: it runs here, before that catch-all.
172
+ //
173
+ // createSaasApp({
174
+ // ...,
175
+ // extendRoutes: (app, { authMiddleware, csrfMiddleware }) => {
176
+ // app.get('/api/products', authMiddleware, asyncHandler(...));
177
+ // app.post('/api/products', authMiddleware, csrfMiddleware, asyncHandler(...));
178
+ // }
179
+ // });
180
+ if (typeof normalized.extendRoutes === 'function') {
181
+ normalized.extendRoutes(app, { authMiddleware, csrfMiddleware, authorizeAdmin, authorizeRoles });
182
+ }
183
+
141
184
  app.use(notFoundMiddleware);
142
185
  app.use(errorMiddleware);
143
186
 
package/src/index.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import type {
2
2
  AuthMiddlewareOptions,
3
+ CorsMiddlewareOptions,
3
4
  CsrfMiddlewareOptions,
4
5
  CspOptions,
5
6
  LoginLimiterOptions,
6
7
  RateLimitOptions,
8
+ RequestHandler,
7
9
  RevocationStore,
8
10
  SessionCookieOptions,
9
11
  WafOptions,
@@ -66,9 +68,22 @@ export interface SaasRoles {
66
68
  export interface SaasApp {
67
69
  use(...handlers: unknown[]): SaasApp;
68
70
  listen?(...args: unknown[]): unknown;
71
+ /** The exact auth middleware instance used by every built-in route — reuse it for your own routes instead of rebuilding a duplicate. */
72
+ authMiddleware: RequestHandler;
73
+ /** The exact CSRF middleware instance used by every built-in mutating route. */
74
+ csrfMiddleware: RequestHandler;
75
+ /** authorizeRoles(...options.roles.adminRoles) — the exact admin-role guard used internally. */
76
+ authorizeAdmin: RequestHandler;
69
77
  [key: string]: unknown;
70
78
  }
71
79
 
80
+ export interface ExtendRoutesContext {
81
+ authMiddleware: RequestHandler;
82
+ csrfMiddleware: RequestHandler;
83
+ authorizeAdmin: RequestHandler;
84
+ authorizeRoles: (...roles: string[]) => RequestHandler;
85
+ }
86
+
72
87
  export interface CreateSaasAppOptions {
73
88
  jwtSecret?: string;
74
89
  legacyJwtSecret?: string;
@@ -87,12 +102,28 @@ export interface CreateSaasAppOptions {
87
102
  publicUserFields?: string[];
88
103
  cookie?: SessionCookieOptions;
89
104
  csrf?: CsrfMiddlewareOptions;
105
+ /**
106
+ * Mounts createCorsMiddleware as the FIRST middleware, ahead of
107
+ * everything else — required for CORS headers to reach the preflight
108
+ * OPTIONS response. `true` uses the default (dev origins only, no
109
+ * explicit allow-list). Omit entirely for no CORS handling (unchanged
110
+ * default behavior).
111
+ */
112
+ cors?: CorsMiddlewareOptions | true;
90
113
  webauthnStore?: WebauthnStore;
91
114
  webauthn?: WebauthnOptions;
92
115
  waf?: WafOptions;
93
116
  csp?: CspOptions;
94
117
  apiRateLimit?: RateLimitOptions;
95
118
  loginRateLimit?: LoginLimiterOptions;
119
+ /**
120
+ * Register your own routes here, not on the returned app after the fact.
121
+ * createSaasApp() ends its own middleware stack with a catch-all 404 +
122
+ * error handler; anything added to the returned app afterward is
123
+ * unreachable. extendRoutes(app, ctx) runs before that catch-all, with
124
+ * the same authMiddleware/csrfMiddleware instances the built-in routes use.
125
+ */
126
+ extendRoutes?: (app: SaasApp, ctx: ExtendRoutesContext) => void;
96
127
  [key: string]: unknown;
97
128
  }
98
129