@astratra/security 0.1.0 → 1.0.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
@@ -1,8 +1,9 @@
1
1
  # @astratra/security
2
2
 
3
- Authentification, autorisation, rate limiting, WAF et WebAuthn/passkeys —
4
- générique et découplé de toute base de données, ORM ou liste de rôles fixe.
5
- Dépend de `@astratra/core`.
3
+ Primitives de sécurité applicative pour l'authentification, l'autorisation,
4
+ le rate limiting, une CSP configurable, un WAF heuristique et
5
+ WebAuthn/passkeys — génériques et découplées de toute base de données, ORM
6
+ ou liste de rôles fixe. Dépend de `@astratra/core`.
6
7
 
7
8
  Partout où un vrai projet a besoin de persistance (révocation de session,
8
9
  stockage de credentials WebAuthn, alerte de brute-force), c'est un
@@ -16,13 +17,24 @@ const { createAuthMiddleware, authorizeRoles } = require('@astratra/security');
16
17
  const authMiddleware = createAuthMiddleware({
17
18
  secret: process.env.JWT_SECRET,
18
19
  legacySecret: process.env.JWT_SECRET_OLD, // optionnel, pour la rotation de clé
20
+ algorithms: ['HS256'], // allowlist explicite
21
+ issuer: 'mon-app', // optionnel, recommande en production
22
+ audience: 'mon-api', // optionnel, recommande en production
19
23
  verifySession: async (decoded) => sessionStore.isActive(decoded) // vérification de révocation optionnelle
20
24
  });
21
25
 
22
26
  app.use('/api', authMiddleware);
23
- app.delete('/api/schools/:id', authorizeRoles('owner', 'admin'), handler);
27
+ app.delete('/api/projects/:id', authorizeRoles('owner', 'admin'), handler);
24
28
  ```
25
29
 
30
+ Par défaut, le middleware limite la vérification à `HS256`. Si ton application
31
+ utilise un autre algorithme, configure explicitement `algorithms`.
32
+
33
+ Si tu extrais le token depuis un cookie, configure le cookie côté application
34
+ avec `HttpOnly`, `Secure` en HTTPS et un `SameSite` adapte. Un cookie JWT peut
35
+ nécessiter une protection CSRF selon tes routes, tes méthodes HTTP et ton
36
+ mode d'authentification.
37
+
26
38
  ## Rate limiting
27
39
 
28
40
  ```js
@@ -42,8 +54,43 @@ const { createWafMiddleware } = require('@astratra/security');
42
54
  app.use(createWafMiddleware({ message: { success: false, message: 'Requête bloquée.' } }));
43
55
  ```
44
56
 
45
- Bloque les patterns SQLi/XSS/traversée de chemin/RCE courants dans
46
- `req.path`, `req.query` et `req.body`.
57
+ Cette couche détecte des patterns évidents SQLi/XSS/traversée de chemin/RCE
58
+ dans `req.path`, `req.query` et `req.body`. Elle ne remplace pas la
59
+ validation des entrées, les requêtes paramétrées, une CSP, la sanitation
60
+ adaptée au contexte, ni un WAF/reverse proxy réseau.
61
+
62
+ ## CSP (Content Security Policy)
63
+
64
+ ```js
65
+ const { createCspMiddleware } = require('@astratra/security');
66
+ app.use(createCspMiddleware());
67
+ ```
68
+
69
+ Sans option, la politique par défaut est `default-src 'none';
70
+ frame-ancestors 'none'; base-uri 'none'` — adaptée à une API qui ne sert que
71
+ du JSON. Pour une app qui sert aussi du HTML/JS (SPA servie par un serveur
72
+ Express, pas juste consommée via fetch), surcharge `directives` :
73
+
74
+ ```js
75
+ app.use(createCspMiddleware({
76
+ directives: {
77
+ 'default-src': ["'self'"],
78
+ 'script-src': ["'self'"],
79
+ 'style-src': ["'self'", "'unsafe-inline'"],
80
+ 'connect-src': ["'self'", 'https://api.mon-app.test']
81
+ }
82
+ }));
83
+ ```
84
+
85
+ `reportOnly: true` envoie `Content-Security-Policy-Report-Only` au lieu de
86
+ bloquer, utile pour tester une politique avant de l'appliquer réellement.
87
+
88
+ Pour une SPA React/Vite consommée séparément (comme `@astratra/saas-kit-ui`),
89
+ la CSP se pose plutôt sur le HTML statique lui-même (balise `<meta
90
+ http-equiv="Content-Security-Policy">` injectée au build, jamais en dev — une
91
+ CSP statique en dev casse le websocket HMR de Vite). Voir
92
+ `examples/dashboard-ui/vite.config.js` pour un exemple qui n'injecte la
93
+ balise que sur `vite build`.
47
94
 
48
95
  ## WebAuthn / passkeys
49
96
 
@@ -61,13 +108,12 @@ const webauthn = createWebauthnService(store, {
61
108
  `updateCredentialCounter`, `saveChallenge`, `consumeChallenge`, et
62
109
  optionnellement `saveRecoveryCodes`/`consumeRecoveryCode` pour les codes de
63
110
  récupération. Aucun Mongoose, aucun rôle fixe autorisé à enregistrer une clé
64
- — ce contrôle d'accès reste à la charge de l'app consommatrice.
111
+ — ce controle d'acces reste a la charge de l'app consommatrice. Avant de
112
+ présenter WebAuthn comme un argument de sécurité fort, prévois une revue de
113
+ sécurité externe sur l'intégration complète.
65
114
 
66
115
  ## Tests
67
116
 
68
117
  ```bash
69
118
  npm test --workspace @astratra/security
70
119
  ```
71
-
72
- 21 tests, aucune vraie base de données ni cérémonie WebAuthn navigateur
73
- requise.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "main": "src/index.js",
6
6
  "types": "src/index.d.ts",
@@ -26,7 +26,7 @@
26
26
  "access": "public"
27
27
  },
28
28
  "dependencies": {
29
- "@astratra/core": "^0.1.0",
29
+ "@astratra/core": "^1.0.0",
30
30
  "@simplewebauthn/server": "^13.1.2",
31
31
  "express-rate-limit": "^7.5.1",
32
32
  "jsonwebtoken": "^9.0.2"
package/src/csp.js ADDED
@@ -0,0 +1,40 @@
1
+ const DEFAULT_DIRECTIVES = {
2
+ 'default-src': ["'none'"],
3
+ 'frame-ancestors': ["'none'"],
4
+ 'base-uri': ["'none'"]
5
+ };
6
+
7
+ function buildHeaderValue(directives) {
8
+ return Object.entries(directives)
9
+ .filter(([, sources]) => Array.isArray(sources) && sources.length > 0)
10
+ .map(([directive, sources]) => `${directive} ${sources.join(' ')}`)
11
+ .join('; ');
12
+ }
13
+
14
+ function mergeDirectives(base, overrides) {
15
+ const merged = { ...base };
16
+ for (const [directive, sources] of Object.entries(overrides || {})) {
17
+ merged[directive] = sources;
18
+ }
19
+ return merged;
20
+ }
21
+
22
+ function createCspMiddleware(options = {}) {
23
+ const directives = mergeDirectives(DEFAULT_DIRECTIVES, options.directives);
24
+ const headerValue = buildHeaderValue(directives);
25
+ const headerName = options.reportOnly
26
+ ? 'Content-Security-Policy-Report-Only'
27
+ : 'Content-Security-Policy';
28
+
29
+ return (req, res, next) => {
30
+ if (headerValue) {
31
+ res.setHeader(headerName, headerValue);
32
+ }
33
+ next();
34
+ };
35
+ }
36
+
37
+ module.exports = {
38
+ createCspMiddleware,
39
+ DEFAULT_CSP_DIRECTIVES: DEFAULT_DIRECTIVES
40
+ };
package/src/index.d.ts CHANGED
@@ -23,6 +23,11 @@ export type Awaitable<T> = T | Promise<T>;
23
23
  export interface AuthMiddlewareOptions<TDecoded = Record<string, unknown>> {
24
24
  secret: string;
25
25
  legacySecret?: string;
26
+ algorithms?: string[];
27
+ issuer?: string;
28
+ audience?: string | string[];
29
+ clockTolerance?: number;
30
+ maxAge?: string | number;
26
31
  message?: unknown;
27
32
  extractToken?: (req: RequestLike) => string | null | undefined;
28
33
  verifySession?: (decoded: TDecoded) => Awaitable<boolean>;
@@ -82,6 +87,16 @@ export interface WafOptions {
82
87
  }
83
88
 
84
89
  export function createWafMiddleware(options?: WafOptions): RequestHandler;
90
+
91
+ export type CspDirectives = Record<string, string[]>;
92
+
93
+ export interface CspOptions {
94
+ directives?: CspDirectives;
95
+ reportOnly?: boolean;
96
+ }
97
+
98
+ export function createCspMiddleware(options?: CspOptions): RequestHandler;
99
+ export const DEFAULT_CSP_DIRECTIVES: CspDirectives;
85
100
  export const WAF_PATTERNS: RegExp[];
86
101
 
87
102
  export const CHALLENGE_TTL_MS: number;
package/src/index.js CHANGED
@@ -2,5 +2,6 @@ module.exports = {
2
2
  ...require('./jwtAuth'),
3
3
  ...require('./rateLimiters'),
4
4
  ...require('./waf'),
5
- ...require('./webauthn')
5
+ ...require('./webauthn'),
6
+ ...require('./csp')
6
7
  };
package/src/jwtAuth.js CHANGED
@@ -10,6 +10,8 @@ const DEFAULT_FORBIDDEN = {
10
10
  message: 'Forbidden.'
11
11
  };
12
12
 
13
+ const DEFAULT_ALGORITHMS = ['HS256'];
14
+
13
15
  const defaultExtractToken = (req) => {
14
16
  const cookieToken = req.cookies && req.cookies.token;
15
17
  if (cookieToken) return cookieToken;
@@ -22,12 +24,20 @@ const defaultExtractToken = (req) => {
22
24
  return null;
23
25
  };
24
26
 
25
- const verifyWithRotation = (token, secret, legacySecret) => {
27
+ const verificationOptionsFrom = (options = {}) => ({
28
+ algorithms: options.algorithms || DEFAULT_ALGORITHMS,
29
+ ...(options.issuer ? { issuer: options.issuer } : {}),
30
+ ...(options.audience ? { audience: options.audience } : {}),
31
+ ...(options.clockTolerance !== undefined ? { clockTolerance: options.clockTolerance } : {}),
32
+ ...(options.maxAge ? { maxAge: options.maxAge } : {})
33
+ });
34
+
35
+ const verifyWithRotation = (token, secret, legacySecret, verificationOptions) => {
26
36
  try {
27
- return jwt.verify(token, secret);
37
+ return jwt.verify(token, secret, verificationOptions);
28
38
  } catch (error) {
29
39
  if (legacySecret && error.name === 'JsonWebTokenError') {
30
- return jwt.verify(token, legacySecret);
40
+ return jwt.verify(token, legacySecret, verificationOptions);
31
41
  }
32
42
  throw error;
33
43
  }
@@ -40,6 +50,7 @@ const createAuthMiddleware = (options = {}) => {
40
50
 
41
51
  const extractToken = options.extractToken || defaultExtractToken;
42
52
  const unauthorizedMessage = options.message || DEFAULT_UNAUTHORIZED;
53
+ const verificationOptions = verificationOptionsFrom(options);
43
54
 
44
55
  return async (req, res, next) => {
45
56
  try {
@@ -48,7 +59,7 @@ const createAuthMiddleware = (options = {}) => {
48
59
  return res.status(401).json(unauthorizedMessage);
49
60
  }
50
61
 
51
- const decoded = verifyWithRotation(token, options.secret, options.legacySecret);
62
+ const decoded = verifyWithRotation(token, options.secret, options.legacySecret, verificationOptions);
52
63
 
53
64
  if (options.verifySession) {
54
65
  const isActive = await options.verifySession(decoded);