@astratra/saas-kit 1.0.2 → 1.1.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
@@ -40,6 +40,8 @@ app.listen(3000);
40
40
  Ça donne immédiatement à un nouveau projet une API fonctionnelle :
41
41
 
42
42
  - `POST /auth/login`
43
+ - `POST /auth/logout`
44
+ - `POST /auth/logout-all`
43
45
  - `GET /auth/me`
44
46
  - `GET /users`
45
47
  - `GET /users/:id`
@@ -51,14 +53,45 @@ app.listen(3000);
51
53
  - `GET /dashboard/summary`
52
54
 
53
55
  Toutes les routes protégées suivent le même ordre de middlewares de
54
- sécurité que la mini-app de démo : request id, CSP (`default-src 'none'` par
55
- défaut, adapté à une API JSON — surchargeable via `options.csp`), parseur
56
- JSON, WAF heuristique, limiteur API, limiteur de login pour `/auth`, auth JWT
57
- pour les modules protégés, puis 404 et gestion d'erreurs.
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.
58
62
 
59
63
  `jwtAlgorithms` vaut `['HS256']` par defaut. `jwtIssuer` et `jwtAudience` sont
60
64
  optionnels, mais recommandes des qu'une app sort du simple developpement local.
61
65
 
66
+ ## Session cookie HttpOnly, CSRF et révocation
67
+
68
+ `POST /auth/login` pose toujours un cookie `HttpOnly` (`astratra_session` par
69
+ défaut) en plus de renvoyer `{ token, user }` en JSON — le cookie sert les
70
+ clients web, le token JSON sert les clients API/mobile. Le nom, `sameSite`,
71
+ `secure`, `path`, `domain` et la durée de vie du cookie se configurent via
72
+ `options.cookie` :
73
+
74
+ ```js
75
+ createSaasApp({
76
+ // ...
77
+ cookie: { name: 'ma_session', sameSite: 'strict' },
78
+ csrf: { headerName: 'x-csrf-token' } // optionnel, défauts déjà sensés
79
+ });
80
+ ```
81
+
82
+ Toutes les routes mutantes protégées (`/users`, `/settings`,
83
+ `/notifications`, `/dashboard`, `/auth/logout(-all)`, `/auth/webauthn/*`)
84
+ exigent un token CSRF (cookie non-`HttpOnly` `astratra_csrf` + header
85
+ `x-csrf-token`) **sauf** pour les clients authentifiés par `Authorization:
86
+ Bearer` (mobile/API — non exposés au CSRF) et `POST /auth/login`
87
+ (pas de session préexistante à protéger).
88
+
89
+ `POST /auth/logout` invalide immédiatement le JWT courant (via un
90
+ `revocationStore` en mémoire fourni par défaut — remplaçable par
91
+ `options.revocationStore` pour une prod multi-instance, ex. Redis).
92
+ `POST /auth/logout-all` invalide tous les JWT actifs de l'utilisateur, pas
93
+ seulement celui de la requête courante.
94
+
62
95
  ## Validation des entrées
63
96
 
64
97
  `POST /auth/login`, `POST /users`, `PATCH /settings/:key` et
@@ -124,6 +157,12 @@ stores mémoire dev-only pour que le starter démarre immédiatement.
124
157
  consommatrice ; le kit ne fournit ni algorithme de mot de passe ni
125
158
  comportement de livraison de notification.
126
159
 
160
+ Si `revocationStore` est omis, `createSaasApp` utilise de la même façon
161
+ `createMemoryRevocationStore()` de `@astratra/security` (pas mémorisé entre
162
+ process, ni partagé entre instances). Pour une prod multi-instance, fournis
163
+ ton propre store implémentant la même interface (Redis, etc.) via
164
+ `options.revocationStore`.
165
+
127
166
  ## Tableau de bord
128
167
 
129
168
  `GET /dashboard/summary` retourne uniquement des stats génériques de
package/package.json CHANGED
@@ -1,7 +1,10 @@
1
1
  {
2
2
  "name": "@astratra/saas-kit",
3
- "version": "1.0.2",
3
+ "version": "1.1.1",
4
4
  "description": "Reusable backend starter kit that assembles Astratra core, security, and AI packages.",
5
+ "engines": {
6
+ "node": ">=20"
7
+ },
5
8
  "main": "src/index.js",
6
9
  "types": "src/index.d.ts",
7
10
  "type": "commonjs",
@@ -23,7 +26,7 @@
23
26
  "dependencies": {
24
27
  "@astratra/ai": "^1.0.0",
25
28
  "@astratra/core": "^1.0.0",
26
- "@astratra/security": "^1.0.2",
29
+ "@astratra/security": "^1.1.0",
27
30
  "express": "^4.18.3",
28
31
  "express-validator": "^7.3.2",
29
32
  "jsonwebtoken": "^9.0.2"
package/src/app.js CHANGED
@@ -6,11 +6,15 @@ const {
6
6
  } = require('@astratra/core');
7
7
  const {
8
8
  authorizeRoles,
9
+ cookieParserMiddleware,
9
10
  createApiLimiter,
10
11
  createAuthMiddleware,
11
12
  createCspMiddleware,
13
+ createCsrfMiddleware,
12
14
  createLoginLimiter,
13
- createWafMiddleware
15
+ createMemoryRevocationStore,
16
+ createWafMiddleware,
17
+ DEFAULT_SESSION_COOKIE_NAME
14
18
  } = require('@astratra/security');
15
19
  const createAuthRoutes = require('./modules/auth');
16
20
  const createDashboardRoutes = require('./modules/dashboard');
@@ -35,6 +39,7 @@ function normalizeOptions(options = {}) {
35
39
  const jwtAlgorithms = options.jwtAlgorithms || ['HS256'];
36
40
  const usersStore = options.usersStore || createMemoryUsersStore();
37
41
  const settingsStore = options.settingsStore || createMemorySettingsStore();
42
+ const revocationStore = options.revocationStore || createMemoryRevocationStore();
38
43
  const notify = options.notify;
39
44
  const verifyPassword = options.verifyPassword;
40
45
  const roles = { ...DEFAULT_ROLES, ...(options.roles || {}) };
@@ -57,6 +62,7 @@ function normalizeOptions(options = {}) {
57
62
  jwtAudience: options.jwtAudience,
58
63
  usersStore,
59
64
  settingsStore,
65
+ revocationStore,
60
66
  notify,
61
67
  verifyPassword,
62
68
  roles,
@@ -69,11 +75,23 @@ function createSaasApp(options = {}) {
69
75
  const app = express();
70
76
 
71
77
  app.use(requestIdMiddleware);
78
+ app.use(cookieParserMiddleware());
72
79
  app.use(createCspMiddleware(normalized.csp));
73
80
  app.use(express.json());
74
81
  app.use(createWafMiddleware(normalized.waf));
75
82
  app.use(createApiLimiter(normalized.apiRateLimit));
76
83
 
84
+ const sessionCookieName = (normalized.cookie && normalized.cookie.name) || DEFAULT_SESSION_COOKIE_NAME;
85
+ const extractToken = normalized.extractToken || ((req) => {
86
+ const cookieToken = req.cookies && req.cookies[sessionCookieName];
87
+ if (cookieToken) return cookieToken;
88
+ const authorization = req.headers && req.headers.authorization;
89
+ if (authorization && authorization.startsWith('Bearer ')) {
90
+ return authorization.slice('Bearer '.length);
91
+ }
92
+ return null;
93
+ });
94
+
77
95
  const authMiddleware = createAuthMiddleware({
78
96
  secret: normalized.jwtSecret,
79
97
  legacySecret: normalized.legacyJwtSecret,
@@ -81,29 +99,42 @@ function createSaasApp(options = {}) {
81
99
  issuer: normalized.jwtIssuer,
82
100
  audience: normalized.jwtAudience,
83
101
  verifySession: normalized.verifySession,
84
- extractToken: normalized.extractToken
102
+ revocationStore: normalized.revocationStore,
103
+ extractToken
85
104
  });
86
105
  const authorizeAdmin = authorizeRoles(...normalized.roles.adminRoles);
87
106
 
107
+ // Bearer-authenticated clients (mobile/API) aren't vulnerable to CSRF: a browser
108
+ // never auto-attaches an Authorization header cross-site the way it does a cookie.
109
+ const isBearerAuthenticated = (req) => {
110
+ const authorization = req.headers && req.headers.authorization;
111
+ return Boolean(authorization && authorization.startsWith('Bearer '));
112
+ };
113
+ const csrfMiddleware = createCsrfMiddleware({
114
+ ...normalized.csrf,
115
+ skip: (req) => isBearerAuthenticated(req) || (normalized.csrf && normalized.csrf.skip && normalized.csrf.skip(req))
116
+ });
117
+
88
118
  app.use('/auth', createLoginLimiter(normalized.loginRateLimit), createAuthRoutes({
89
119
  ...normalized,
90
- authMiddleware
120
+ authMiddleware,
121
+ csrfMiddleware
91
122
  }));
92
123
 
93
- app.use('/users', authMiddleware, createUsersRoutes({
124
+ app.use('/users', authMiddleware, csrfMiddleware, createUsersRoutes({
94
125
  usersStore: normalized.usersStore,
95
126
  authorizeAdmin,
96
127
  publicUserFields: normalized.publicUserFields
97
128
  }));
98
- app.use('/settings', authMiddleware, createSettingsRoutes({
129
+ app.use('/settings', authMiddleware, csrfMiddleware, createSettingsRoutes({
99
130
  settingsStore: normalized.settingsStore,
100
131
  authorizeAdmin
101
132
  }));
102
- app.use('/notifications', authMiddleware, createNotificationsRoutes({
133
+ app.use('/notifications', authMiddleware, csrfMiddleware, createNotificationsRoutes({
103
134
  notify: normalized.notify,
104
135
  authorizeAdmin
105
136
  }));
106
- app.use('/dashboard', authMiddleware, createDashboardRoutes({
137
+ app.use('/dashboard', authMiddleware, csrfMiddleware, createDashboardRoutes({
107
138
  usersStore: normalized.usersStore
108
139
  }));
109
140
 
package/src/index.d.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  import type {
2
2
  AuthMiddlewareOptions,
3
+ CsrfMiddlewareOptions,
3
4
  CspOptions,
4
5
  LoginLimiterOptions,
5
6
  RateLimitOptions,
7
+ RevocationStore,
8
+ SessionCookieOptions,
6
9
  WafOptions,
7
10
  WebauthnOptions,
8
11
  WebauthnStore
@@ -78,9 +81,12 @@ export interface CreateSaasAppOptions {
78
81
  notify: (userId: string, notification: NotificationPayload) => Awaitable<unknown>;
79
82
  verifyPassword: (user: SaasUser, password: string) => Awaitable<boolean>;
80
83
  verifySession?: AuthMiddlewareOptions['verifySession'];
84
+ revocationStore?: RevocationStore;
81
85
  extractToken?: AuthMiddlewareOptions['extractToken'];
82
86
  roles?: SaasRoles;
83
87
  publicUserFields?: string[];
88
+ cookie?: SessionCookieOptions;
89
+ csrf?: CsrfMiddlewareOptions;
84
90
  webauthnStore?: WebauthnStore;
85
91
  webauthn?: WebauthnOptions;
86
92
  waf?: WafOptions;
@@ -1,8 +1,9 @@
1
1
  const express = require('express');
2
+ const crypto = require('crypto');
2
3
  const jwt = require('jsonwebtoken');
3
4
  const { body } = require('express-validator');
4
5
  const { apiResponse, AppError, asyncHandler, validateMiddleware } = require('@astratra/core');
5
- const { createWebauthnService } = require('@astratra/security');
6
+ const { clearSessionCookie, createWebauthnService, setSessionCookie } = require('@astratra/security');
6
7
  const { pickPublicUser } = require('../utils');
7
8
 
8
9
  const loginValidation = [
@@ -10,6 +11,33 @@ const loginValidation = [
10
11
  body('password').notEmpty().withMessage('password is required')
11
12
  ];
12
13
 
14
+ const JWT_EXPIRY_UNITS_MS = {
15
+ s: 1000,
16
+ m: 60 * 1000,
17
+ h: 60 * 60 * 1000,
18
+ d: 24 * 60 * 60 * 1000
19
+ };
20
+
21
+ const maxAgeMsFromJwtExpiresIn = (jwtExpiresIn) => {
22
+ if (jwtExpiresIn === undefined || jwtExpiresIn === null) return undefined;
23
+ if (typeof jwtExpiresIn === 'number') return jwtExpiresIn * 1000;
24
+
25
+ const match = String(jwtExpiresIn).trim().match(/^(\d+)([smhd])$/);
26
+ if (!match) return undefined;
27
+ return Number(match[1]) * JWT_EXPIRY_UNITS_MS[match[2]];
28
+ };
29
+
30
+ const cookieOptionsFrom = (options) => {
31
+ const cookieOptions = { ...(options.cookie || {}) };
32
+ if (cookieOptions.maxAgeMs === undefined) {
33
+ const maxAgeMs = maxAgeMsFromJwtExpiresIn(options.jwtExpiresIn || '1h');
34
+ if (maxAgeMs !== undefined) {
35
+ cookieOptions.maxAgeMs = maxAgeMs;
36
+ }
37
+ }
38
+ return cookieOptions;
39
+ };
40
+
13
41
  function createAuthRoutes(options) {
14
42
  const router = express.Router();
15
43
  const {
@@ -20,6 +48,8 @@ function createAuthRoutes(options) {
20
48
  webauthnStore,
21
49
  webauthn
22
50
  } = options;
51
+ const cookieOptions = cookieOptionsFrom(options);
52
+ const csrfMiddleware = options.csrfMiddleware || ((req, res, next) => next());
23
53
 
24
54
  router.post('/login', validateMiddleware(loginValidation), asyncHandler(async (req, res) => {
25
55
  const user = await usersStore.findByEmail(req.body.email);
@@ -29,39 +59,57 @@ function createAuthRoutes(options) {
29
59
  }
30
60
 
31
61
  const publicUser = pickPublicUser(user, publicUserFields);
32
- const token = jwt.sign(publicUser, jwtSecret, {
62
+ const jti = crypto.randomUUID();
63
+ const token = jwt.sign({ ...publicUser, jti }, jwtSecret, {
33
64
  expiresIn: options.jwtExpiresIn || '1h',
34
65
  algorithm: options.jwtAlgorithms[0],
35
66
  ...(options.jwtIssuer ? { issuer: options.jwtIssuer } : {}),
36
67
  ...(options.jwtAudience ? { audience: options.jwtAudience } : {})
37
68
  });
69
+ setSessionCookie(res, token, cookieOptions);
38
70
  return apiResponse(res, 200, 'Login successful', { token, user: publicUser });
39
71
  }));
40
72
 
73
+ router.post('/logout', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
74
+ if (options.revocationStore && req.user && req.user.jti) {
75
+ await options.revocationStore.revoke(req.user.jti, req.user.exp * 1000);
76
+ }
77
+ clearSessionCookie(res, cookieOptions);
78
+ return res.status(200).json({ success: true });
79
+ }));
80
+
81
+ router.post('/logout-all', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
82
+ if (options.revocationStore && req.user && req.user.id && typeof options.revocationStore.revokeAllForUser === 'function') {
83
+ await options.revocationStore.revokeAllForUser(req.user.id, Date.now());
84
+ }
85
+ clearSessionCookie(res, cookieOptions);
86
+ return res.status(200).json({ success: true });
87
+ }));
88
+
41
89
  router.get('/me', options.authMiddleware, (req, res) => (
42
90
  apiResponse(res, 200, 'Current user', pickPublicUser(req.user, publicUserFields))
43
91
  ));
44
92
 
45
93
  if (webauthnStore) {
46
- router.post('/webauthn/register/options', options.authMiddleware, asyncHandler(async (req, res) => {
94
+ router.post('/webauthn/register/options', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
47
95
  const service = createWebauthnService(webauthnStore, webauthn);
48
96
  const data = await service.getRegistrationOptions(req, req.user.id, req.user.email || req.user.id);
49
97
  return apiResponse(res, 200, 'WebAuthn registration options', data);
50
98
  }));
51
99
 
52
- router.post('/webauthn/register/verify', options.authMiddleware, asyncHandler(async (req, res) => {
100
+ router.post('/webauthn/register/verify', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
53
101
  const service = createWebauthnService(webauthnStore, webauthn);
54
102
  const data = await service.verifyRegistration(req.user.id, req.body.response, req.body.deviceName);
55
103
  return apiResponse(res, 200, 'WebAuthn registration verified', data);
56
104
  }));
57
105
 
58
- router.post('/webauthn/authenticate/options', options.authMiddleware, asyncHandler(async (req, res) => {
106
+ router.post('/webauthn/authenticate/options', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
59
107
  const service = createWebauthnService(webauthnStore, webauthn);
60
108
  const data = await service.getAuthenticationOptions(req, req.user.id);
61
109
  return apiResponse(res, 200, 'WebAuthn authentication options', data);
62
110
  }));
63
111
 
64
- router.post('/webauthn/authenticate/verify', options.authMiddleware, asyncHandler(async (req, res) => {
112
+ router.post('/webauthn/authenticate/verify', options.authMiddleware, csrfMiddleware, asyncHandler(async (req, res) => {
65
113
  const service = createWebauthnService(webauthnStore, webauthn);
66
114
  const verified = await service.verifyAuthentication(req.user.id, req.body.response);
67
115
  return apiResponse(res, 200, 'WebAuthn authentication verified', { verified });