@astratra/saas-kit 1.1.1 → 1.2.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 +31 -0
- package/package.json +2 -2
- package/src/app.js +32 -0
- package/src/index.d.ts +22 -0
package/README.md
CHANGED
|
@@ -63,6 +63,37 @@ 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
|
+
Le cookie CSRF (`astratra_csrf`) est amorcé automatiquement sur toute
|
|
91
|
+
requête sûre (GET/HEAD/OPTIONS) dès le démarrage de l'app — y compris tes
|
|
92
|
+
propres routes `GET` ajoutées via `extendRoutes` — donc pas besoin de monter
|
|
93
|
+
`csrfMiddleware` toi-même sur des routes qui ne font que lire.
|
|
94
|
+
`csrfMiddleware` reste nécessaire sur tes routes mutantes (POST/PATCH/DELETE)
|
|
95
|
+
pour valider le token.
|
|
96
|
+
|
|
66
97
|
## Session cookie HttpOnly, CSRF et révocation
|
|
67
98
|
|
|
68
99
|
`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.
|
|
3
|
+
"version": "1.2.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.2.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
|
@@ -10,6 +10,7 @@ const {
|
|
|
10
10
|
createApiLimiter,
|
|
11
11
|
createAuthMiddleware,
|
|
12
12
|
createCspMiddleware,
|
|
13
|
+
createCsrfCookiePrimer,
|
|
13
14
|
createCsrfMiddleware,
|
|
14
15
|
createLoginLimiter,
|
|
15
16
|
createMemoryRevocationStore,
|
|
@@ -76,6 +77,12 @@ function createSaasApp(options = {}) {
|
|
|
76
77
|
|
|
77
78
|
app.use(requestIdMiddleware);
|
|
78
79
|
app.use(cookieParserMiddleware());
|
|
80
|
+
// Seeds the CSRF cookie on every safe request (GET/HEAD/OPTIONS), globally,
|
|
81
|
+
// before any route — including custom routes mounted via extendRoutes.
|
|
82
|
+
// Without this, a route wiring createCsrfMiddleware only on its mutating
|
|
83
|
+
// handlers issues the cookie in the SAME response that needed it
|
|
84
|
+
// validated, so the client's first mutating request always fails.
|
|
85
|
+
app.use(createCsrfCookiePrimer(normalized.csrf));
|
|
79
86
|
app.use(createCspMiddleware(normalized.csp));
|
|
80
87
|
app.use(express.json());
|
|
81
88
|
app.use(createWafMiddleware(normalized.waf));
|
|
@@ -138,6 +145,31 @@ function createSaasApp(options = {}) {
|
|
|
138
145
|
usersStore: normalized.usersStore
|
|
139
146
|
}));
|
|
140
147
|
|
|
148
|
+
// Exposed so a consumer can reuse the exact same auth/CSRF instances
|
|
149
|
+
// instead of rebuilding duplicates with (easy to get out of sync)
|
|
150
|
+
// options — e.g. `app.use('/api', app.authMiddleware, app.csrfMiddleware)`.
|
|
151
|
+
app.authMiddleware = authMiddleware;
|
|
152
|
+
app.csrfMiddleware = csrfMiddleware;
|
|
153
|
+
app.authorizeAdmin = authorizeAdmin;
|
|
154
|
+
|
|
155
|
+
// createSaasApp() already terminates its own middleware stack with a
|
|
156
|
+
// catch-all 404 + error handler below. Any route registered on `app`
|
|
157
|
+
// AFTER createSaasApp() returns is therefore unreachable — Express
|
|
158
|
+
// evaluates middleware in registration order, and notFoundMiddleware
|
|
159
|
+
// matches every path unconditionally. `extendRoutes` is the supported
|
|
160
|
+
// way to add your own routes: it runs here, before that catch-all.
|
|
161
|
+
//
|
|
162
|
+
// createSaasApp({
|
|
163
|
+
// ...,
|
|
164
|
+
// extendRoutes: (app, { authMiddleware, csrfMiddleware }) => {
|
|
165
|
+
// app.get('/api/products', authMiddleware, asyncHandler(...));
|
|
166
|
+
// app.post('/api/products', authMiddleware, csrfMiddleware, asyncHandler(...));
|
|
167
|
+
// }
|
|
168
|
+
// });
|
|
169
|
+
if (typeof normalized.extendRoutes === 'function') {
|
|
170
|
+
normalized.extendRoutes(app, { authMiddleware, csrfMiddleware, authorizeAdmin, authorizeRoles });
|
|
171
|
+
}
|
|
172
|
+
|
|
141
173
|
app.use(notFoundMiddleware);
|
|
142
174
|
app.use(errorMiddleware);
|
|
143
175
|
|
package/src/index.d.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type {
|
|
|
4
4
|
CspOptions,
|
|
5
5
|
LoginLimiterOptions,
|
|
6
6
|
RateLimitOptions,
|
|
7
|
+
RequestHandler,
|
|
7
8
|
RevocationStore,
|
|
8
9
|
SessionCookieOptions,
|
|
9
10
|
WafOptions,
|
|
@@ -66,9 +67,22 @@ export interface SaasRoles {
|
|
|
66
67
|
export interface SaasApp {
|
|
67
68
|
use(...handlers: unknown[]): SaasApp;
|
|
68
69
|
listen?(...args: unknown[]): unknown;
|
|
70
|
+
/** The exact auth middleware instance used by every built-in route — reuse it for your own routes instead of rebuilding a duplicate. */
|
|
71
|
+
authMiddleware: RequestHandler;
|
|
72
|
+
/** The exact CSRF middleware instance used by every built-in mutating route. */
|
|
73
|
+
csrfMiddleware: RequestHandler;
|
|
74
|
+
/** authorizeRoles(...options.roles.adminRoles) — the exact admin-role guard used internally. */
|
|
75
|
+
authorizeAdmin: RequestHandler;
|
|
69
76
|
[key: string]: unknown;
|
|
70
77
|
}
|
|
71
78
|
|
|
79
|
+
export interface ExtendRoutesContext {
|
|
80
|
+
authMiddleware: RequestHandler;
|
|
81
|
+
csrfMiddleware: RequestHandler;
|
|
82
|
+
authorizeAdmin: RequestHandler;
|
|
83
|
+
authorizeRoles: (...roles: string[]) => RequestHandler;
|
|
84
|
+
}
|
|
85
|
+
|
|
72
86
|
export interface CreateSaasAppOptions {
|
|
73
87
|
jwtSecret?: string;
|
|
74
88
|
legacyJwtSecret?: string;
|
|
@@ -93,6 +107,14 @@ export interface CreateSaasAppOptions {
|
|
|
93
107
|
csp?: CspOptions;
|
|
94
108
|
apiRateLimit?: RateLimitOptions;
|
|
95
109
|
loginRateLimit?: LoginLimiterOptions;
|
|
110
|
+
/**
|
|
111
|
+
* Register your own routes here, not on the returned app after the fact.
|
|
112
|
+
* createSaasApp() ends its own middleware stack with a catch-all 404 +
|
|
113
|
+
* error handler; anything added to the returned app afterward is
|
|
114
|
+
* unreachable. extendRoutes(app, ctx) runs before that catch-all, with
|
|
115
|
+
* the same authMiddleware/csrfMiddleware instances the built-in routes use.
|
|
116
|
+
*/
|
|
117
|
+
extendRoutes?: (app: SaasApp, ctx: ExtendRoutesContext) => void;
|
|
96
118
|
[key: string]: unknown;
|
|
97
119
|
}
|
|
98
120
|
|