@astratra/security 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 CHANGED
@@ -67,6 +67,31 @@ n'est jamais actif tout seul dans ce package. `@astratra/saas-kit` le monte
67
67
  par défaut sur ses routes protégées, avec bypass automatique pour les
68
68
  clients `Authorization: Bearer`.
69
69
 
70
+ **Piège classique** : si tu ne montes `createCsrfMiddleware` que sur tes
71
+ routes mutantes (POST/PATCH/DELETE — le réflexe naturel), la toute première
72
+ requête mutante d'un client émet elle-même le cookie CSRF *dans sa propre
73
+ réponse* — le client ne peut jamais l'avoir lu à temps, donc elle échoue
74
+ systématiquement avec `403 Invalid CSRF token`, même avec des identifiants
75
+ valides. Le cookie doit exister *avant* la première requête mutante.
76
+
77
+ `createCsrfCookiePrimer(options)` résout ça : il amorce le cookie sur toute
78
+ requête sûre (GET/HEAD/OPTIONS) sans jamais valider de token, à monter une
79
+ seule fois, globalement, avant toutes les routes.
80
+
81
+ ```js
82
+ app.use(cookieParserMiddleware());
83
+ app.use(createCsrfCookiePrimer()); // amorce le cookie sur tout GET, avant les routes
84
+
85
+ // ensuite, comme avant : createCsrfMiddleware() valide sur tes routes mutantes
86
+ app.use('/api', authMiddleware, createCsrfMiddleware({
87
+ skip: (req) => Boolean(req.headers.authorization?.startsWith('Bearer '))
88
+ }));
89
+ ```
90
+
91
+ Les deux vérifient le cookie déjà mis en file sur la même réponse avant d'en
92
+ émettre un nouveau — les monter tous les deux sur la même requête ne pose
93
+ jamais deux cookies différents.
94
+
70
95
  ## Révocation de session JWT
71
96
 
72
97
  ```js
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "1.1.1",
3
+ "version": "1.2.0",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "engines": {
6
6
  "node": ">=20"
package/src/csrf.js CHANGED
@@ -47,6 +47,26 @@ const cookieValue = (req, name) => {
47
47
  return parsed[name];
48
48
  };
49
49
 
50
+ // A Set-Cookie queued earlier in the SAME response (e.g. by
51
+ // createCsrfCookiePrimer running ahead of a route's own createCsrfMiddleware)
52
+ // never shows up in req.cookies — that only reflects cookies the client sent
53
+ // on THIS request. Without this check, two CSRF-aware middlewares on one
54
+ // request/response pair would each mint and queue their own token.
55
+ const queuedCookieValue = (res, name) => {
56
+ if (typeof res.getHeader !== 'function') return undefined;
57
+ const current = res.getHeader('Set-Cookie');
58
+ if (!current) return undefined;
59
+ const cookies = Array.isArray(current) ? current : [current];
60
+ for (const cookie of cookies) {
61
+ const [pair] = String(cookie).split(';');
62
+ const index = pair.indexOf('=');
63
+ if (index !== -1 && pair.slice(0, index).trim() === name) {
64
+ return pair.slice(index + 1).trim();
65
+ }
66
+ }
67
+ return undefined;
68
+ };
69
+
50
70
  const headerValue = (req, name) => {
51
71
  if (typeof req.get === 'function') return req.get(name);
52
72
  const headers = req.headers || {};
@@ -77,7 +97,7 @@ const createCsrfMiddleware = (options = {}) => {
77
97
  return next();
78
98
  }
79
99
 
80
- let token = cookieValue(req, cookieName);
100
+ let token = cookieValue(req, cookieName) || queuedCookieValue(res, cookieName);
81
101
  if (!token) {
82
102
  token = crypto.randomBytes(32).toString('hex');
83
103
  setCsrfCookie(res, token, { ...options, name: cookieName });
@@ -96,7 +116,40 @@ const createCsrfMiddleware = (options = {}) => {
96
116
  };
97
117
  };
98
118
 
119
+ /**
120
+ * Issues the CSRF cookie on any safe request (GET/HEAD/OPTIONS) without
121
+ * ever validating a token. Meant to be mounted once, globally, ahead of
122
+ * all routes — so the double-submit cookie exists by the time a client
123
+ * makes its first mutating request, regardless of which routes happen to
124
+ * mount `createCsrfMiddleware` themselves.
125
+ *
126
+ * Without this, a route that only wires `createCsrfMiddleware` on its
127
+ * mutating handlers (POST/PATCH/DELETE) issues the cookie in the SAME
128
+ * response as the request that needed it validated — the client can never
129
+ * have read it in time, so the very first mutating request always fails
130
+ * with "Invalid CSRF token."
131
+ */
132
+ const createCsrfCookiePrimer = (options = {}) => {
133
+ const cookieName = options.name || DEFAULT_CSRF_COOKIE_NAME;
134
+
135
+ return (req, res, next) => {
136
+ const method = String(req.method || 'GET').toUpperCase();
137
+ if (!SAFE_METHODS.has(method)) {
138
+ return next();
139
+ }
140
+ if (options.skip && options.skip(req)) {
141
+ return next();
142
+ }
143
+ if (!cookieValue(req, cookieName) && !queuedCookieValue(res, cookieName)) {
144
+ const token = crypto.randomBytes(32).toString('hex');
145
+ setCsrfCookie(res, token, { ...options, name: cookieName });
146
+ }
147
+ return next();
148
+ };
149
+ };
150
+
99
151
  module.exports = {
100
152
  DEFAULT_CSRF_COOKIE_NAME,
101
- createCsrfMiddleware
153
+ createCsrfMiddleware,
154
+ createCsrfCookiePrimer
102
155
  };
package/src/index.d.ts CHANGED
@@ -75,6 +75,14 @@ export interface CsrfMiddlewareOptions {
75
75
 
76
76
  export function createCsrfMiddleware(options?: CsrfMiddlewareOptions): RequestHandler;
77
77
 
78
+ /**
79
+ * Issues the CSRF cookie on safe requests (GET/HEAD/OPTIONS) without ever
80
+ * validating a token. Mount once, globally, ahead of all routes so the
81
+ * double-submit cookie exists before a client's first mutating request —
82
+ * see createCsrfMiddleware's README section on double-submit CSRF.
83
+ */
84
+ export function createCsrfCookiePrimer(options?: Pick<CsrfMiddlewareOptions, 'name' | 'sameSite' | 'secure' | 'path' | 'domain' | 'skip'>): RequestHandler;
85
+
78
86
  export interface RateLimitStore {
79
87
  init?(options: unknown): unknown;
80
88
  increment?(...args: unknown[]): unknown;