@mostajs/security 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog — @mostajs/security
+## [0.1.0] — 2026-06-18
+### Added
+- Chiffrement au repos AES-256-GCM (`encryptAtRest`/`decryptAtRest`), `sha256`, `hmacSha256`, `randomKey`/`toKey`.
+- `keyFromEnv` (clé via .env), `createCipher`, `encryptedStorage` (wrapper de composition pour @mostajs/storage).
+- 7 tests + exemple §12 (chiffrement au repos d'un document, storage composé). EXTERNALISATION du crypto (§10 #4).

package/README.md

@@ -0,0 +1,14 @@
+# @mostajs/security
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (7 tests verts) · Node-only
+> Crypto réutilisable : **chiffrement au repos** (AES-256-GCM), sha256, HMAC, keyring `.env`. Composé par storage/ged/users/url.
+## Chiffrement au repos (compose storage, sans le modifier)
+```js
+import { createCipher, encryptedStorage, keyFromEnv } from '@mostajs/security';
+const secureStore = encryptedStorage(realStorageDriver, createCipher({ key: keyFromEnv(process.env) }));
+const ref = await secureStore.put(bytes);   // chiffré au repos
+const clear = await secureStore.get(ref.id); // déchiffré à la lecture
+```
+## Lancer
+```bash
+node test-scripts/unit/security.test.mjs && node examples/at-rest/run.mjs
+```

package/docs/00-PROPOSITION-PLAN-SECURITY-18062026.md

@@ -0,0 +1,19 @@
+# @mostajs/security — DEVRULES de bout en bout (§4 + #3 condensés)
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : proposition à discuter (cas C)
+**Priorité** : P0 transverse — **chiffrement au repos** réutilisable par `storage`, `ged`, `users` (biométrie), `url` (HMAC).
+
+## §4 Règle d'or / motivation
+Le **chiffrement au repos** (spec ASSO-SEL §5, Hadhinat docs) était sur le point d'être **noyé dans `@mostajs/storage`**.
+Décision (§10 #4, soupape anti-monolithe) : **EXTERNALISER** dans `@mostajs/security` (responsabilité unique : crypto),
+réutilisé partout. Aujourd'hui la crypto est **dispersée** (`storage` calcule sha256, `url` fait HMAC) → on **consolide**.
+- `storage` = octets (compose security pour chiffrer) · `ged`/`users` = composent security · `url` = HMAC via security.
+
+## §3 Périmètre & API
+**Crypto au repos** : AES-256-GCM (authentifié → détection d'altération). **Hash** : sha256. **Signature** : HMAC-SHA256.
+**Clés** : `keyFromEnv` (`MOSTA_ENCRYPTION_KEY`, via `@mostajs/config`/.env — jamais en dur ; rotation par versionnage de blob).
+**API** : `encryptAtRest(data,key)->{v,iv,tag,ct}` · `decryptAtRest(blob,key)->Buffer` · `sha256(data)` · `hmacSha256(data,secret)` ·
+`randomKey()` · `createCipher({key})->{encrypt,decrypt}` · `encryptedStorage(storage,cipher)` (wrapper qui chiffre au put / déchiffre au get — **storage inchangé**, composition cas B).
+**Composition (§10)** : `@mostajs/config` (clé via .env, souveraineté/résidence pilotée par .env — §11.3 informatif).
+**Jalons** : 0.1 AES-GCM+sha256+HMAC+keyring+wrapper storage · 0.2 rotation de clés (key id) · 1.0 14 livrables.
+**Node-only** (node:crypto). §11.2 : secrets jamais commités ; §11.3 informatif : résidence des clés/données par .env.

package/examples/at-rest/run.mjs

@@ -0,0 +1,14 @@
+// Exemple §12 — chiffrement au repos d'un document GED via @mostajs/security. node examples/at-rest/run.mjs
+import assert from 'node:assert/strict';
+import { createCipher, encryptedStorage, randomKey, sha256 } from '../../src/index.js';
+// driver storage mémoire (mime du vrai @mostajs/storage : { id, checksum, size })
+const disk=new Map();
+const storage={ async put(b){ const id='fs://'+disk.size; disk.set(id,b); return { id, checksum: sha256(b), size:b.length }; }, async get(id){ return disk.get(id); } };
+// composition : storage + security (clé via .env en prod : keyFromEnv)
+const secureStore=encryptedStorage(storage, createCipher({ key: randomKey() }));
+const ref=await secureStore.put(Buffer.from('Compte rendu médical — patient X'));
+// au repos : illisible en clair
+assert.ok(!disk.get(ref.id).toString().includes('patient'), 'octets au repos chiffrés');
+// lecture : déchiffré
+assert.equal((await secureStore.get(ref.id)).toString(), 'Compte rendu médical — patient X');
+console.log('✅ security — chiffrement au repos OK (storage composé, clé .env, AES-256-GCM)');

package/llms.txt

@@ -0,0 +1,15 @@
+# @mostajs/security — fiche LLM
+RÔLE
+  Crypto réutilisable de l'écosystème (responsabilité unique) : chiffrement AU REPOS (AES-256-GCM authentifié),
+  hash sha256, signature HMAC-SHA256, keyring via .env. Composé par storage (encryptedStorage), ged, users, url.
+  Node-only (node:crypto). EXTERNALISÉ pour éviter de noyer le crypto dans storage (§10 #4).
+EXPORTS
+  encryptAtRest(data,key) -> { v,iv,tag,ct } (base64) ; decryptAtRest(blob,key) -> Buffer (throw si altéré/mauvaise clé)
+  sha256(data) -> 'sha256:hex' ; hmacSha256(data,secret) -> hex ; randomKey() -> Buffer(32) ; toKey(hex|base64|Buffer)
+  keyFromEnv(env?,name='MOSTA_ENCRYPTION_KEY') -> Buffer (jamais de clé en dur)
+  createCipher({key}) -> { encrypt(bytes), decrypt(blob) }
+  encryptedStorage(storageDriver, cipher) -> driver enveloppé (chiffre au put / déchiffre au get) — storage INCHANGÉ
+PIÈGES
+  - Clé 32 octets (256-bit), via .env (souveraineté/résidence §11.3). AES-GCM = authentifié → toute altération throw.
+  - Le sha256 d'un FICHIER reste calculé par @mostajs/storage (checksum) ; security.sha256 = hash générique.
+  - Node-only ; ne pas embarquer côté navigateur.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mostajs/security",
+  "version": "0.1.0",
+  "description": "Crypto réutilisable : chiffrement au repos (AES-256-GCM authentifié), sha256, HMAC-SHA256, keyring .env, wrapper encryptedStorage. Composé par storage/ged/users/url.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./crypto": "./src/crypto.js"
+  },
+  "keywords": [
+    "mostajs",
+    "security",
+    "encryption",
+    "at-rest",
+    "aes-gcm",
+    "sha256",
+    "hmac"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/security.test.mjs",
+    "example": "node examples/at-rest/run.mjs"
+  }
+}

package/src/cipher.js

@@ -0,0 +1,18 @@
+// @mostajs/security — cipher + wrapper storage (chiffrement au repos composable). Author: Dr Hamid MADANI <drmdh@msn.com>
+import { encryptAtRest, decryptAtRest, toKey } from './crypto.js';
+export function createCipher({ key }) {
+  const k = toKey(key);
+  return { encrypt: (b) => encryptAtRest(b, k), decrypt: (blob) => decryptAtRest(blob, k) };
+}
+/**
+ * Enveloppe un driver @mostajs/storage pour CHIFFRER au repos sans modifier storage (composition cas B).
+ * put : chiffre → JSON {iv,tag,ct} → délègue à storage ; get : récupère → déchiffre.
+ */
+export function encryptedStorage(storage, cipher) {
+  const putFn = storage.put || storage.createFile || storage.save;
+  return {
+    async put(bytes, opts) { const payload = Buffer.from(JSON.stringify(cipher.encrypt(bytes))); return putFn.call(storage, payload, opts); },
+    async get(ref) { const raw = await storage.get(ref); const blob = JSON.parse(Buffer.from(raw).toString('utf8')); return cipher.decrypt(blob); },
+    _inner: storage,
+  };
+}

package/src/crypto.js

@@ -0,0 +1,28 @@
+// @mostajs/security — primitives crypto (node:crypto). Author: Dr Hamid MADANI <drmdh@msn.com>
+import { randomBytes, createCipheriv, createDecipheriv, createHash, createHmac } from 'node:crypto';
+const ALGO = 'aes-256-gcm';
+
+/** Normalise une clé (Buffer 32o | hex 64 | base64) → Buffer 32 octets. */
+export function toKey(k) {
+  if (Buffer.isBuffer(k)) { if (k.length !== 32) throw new Error('clé: 32 octets requis'); return k; }
+  if (typeof k === 'string') { const b = /^[0-9a-f]{64}$/i.test(k) ? Buffer.from(k, 'hex') : Buffer.from(k, 'base64'); if (b.length !== 32) throw new Error('clé: 32 octets (256-bit) requis'); return b; }
+  throw new Error('clé invalide');
+}
+export const randomKey = () => randomBytes(32);
+
+/** Chiffrement au repos AES-256-GCM (authentifié). → { v, iv, tag, ct } (base64). */
+export function encryptAtRest(data, key) {
+  const k = toKey(key); const iv = randomBytes(12);
+  const c = createCipheriv(ALGO, k, iv);
+  const ct = Buffer.concat([c.update(Buffer.from(data)), c.final()]);
+  return { v: 1, iv: iv.toString('base64'), tag: c.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+/** Déchiffrement ; throw si altéré (auth GCM) ou mauvaise clé. → Buffer. */
+export function decryptAtRest(blob, key) {
+  const k = toKey(key);
+  const d = createDecipheriv(ALGO, k, Buffer.from(blob.iv, 'base64'));
+  d.setAuthTag(Buffer.from(blob.tag, 'base64'));
+  return Buffer.concat([d.update(Buffer.from(blob.ct, 'base64')), d.final()]);
+}
+export const sha256 = (data) => 'sha256:' + createHash('sha256').update(Buffer.from(data)).digest('hex');
+export const hmacSha256 = (data, secret) => createHmac('sha256', secret).update(Buffer.from(data)).digest('hex');

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/security — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { encryptAtRest, decryptAtRest, sha256, hmacSha256, randomKey, toKey } from './crypto.js';
+export { keyFromEnv } from './keyring.js';
+export { createCipher, encryptedStorage } from './cipher.js';

package/src/keyring.js

@@ -0,0 +1,8 @@
+// @mostajs/security — clé via .env (compose @mostajs/config). Author: Dr Hamid MADANI <drmdh@msn.com>
+import { toKey } from './crypto.js';
+/** Lit la clé de chiffrement au repos depuis l'env (jamais en dur). */
+export function keyFromEnv(env = (typeof process !== 'undefined' ? process.env : {}), name = 'MOSTA_ENCRYPTION_KEY') {
+  const v = env[name];
+  if (!v) throw new Error(`${name} absent — définir la clé (32 octets hex/base64) dans .env (souveraineté/résidence §11.3)`);
+  return toKey(v);
+}

package/test-scripts/unit/security.test.mjs

@@ -0,0 +1,38 @@
+// @mostajs/security — tests (DEVRULES §5). node test-scripts/unit/security.test.mjs
+import assert from 'node:assert/strict';
+import { encryptAtRest, decryptAtRest, sha256, hmacSha256, randomKey, createCipher, encryptedStorage, keyFromEnv } from '../../src/index.js';
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+
+await test('chiffrement au repos : aller-retour', ()=>{
+  const key=randomKey(); const blob=encryptAtRest(Buffer.from('dossier médical confidentiel'),key);
+  assert.ok(blob.iv && blob.tag && blob.ct);
+  assert.equal(decryptAtRest(blob,key).toString(),'dossier médical confidentiel');
+});
+await test('détection d\'altération (GCM) → throw', ()=>{
+  const key=randomKey(); const blob=encryptAtRest(Buffer.from('x'),key);
+  const tampered={...blob, ct:Buffer.from('zzzz').toString('base64')};
+  assert.throws(()=>decryptAtRest(tampered,key));
+});
+await test('mauvaise clé → throw', ()=>{
+  const blob=encryptAtRest(Buffer.from('x'),randomKey());
+  assert.throws(()=>decryptAtRest(blob,randomKey()));
+});
+await test('clé invalide rejetée', ()=>{ assert.throws(()=>encryptAtRest('x','tropcourt')); });
+await test('sha256 + hmac déterministes', ()=>{
+  assert.equal(sha256('abc'), sha256('abc'));
+  assert.equal(hmacSha256('msg','secret'), hmacSha256('msg','secret'));
+  assert.notEqual(hmacSha256('msg','a'), hmacSha256('msg','b'));
+});
+await test('keyFromEnv : absente → throw, présente → ok', ()=>{
+  assert.throws(()=>keyFromEnv({}), /absent/);
+  const k=randomKey().toString('hex'); assert.ok(keyFromEnv({ MOSTA_ENCRYPTION_KEY:k }));
+});
+await test('encryptedStorage : chiffre au repos, déchiffre à la lecture (storage inchangé)', async()=>{
+  const blobs=new Map(); const raw=new Map();
+  const storage={ async put(b){ const id='f'+blobs.size; raw.set(id,b); return { id, checksum: sha256(b), size:b.length }; }, async get(id){ return raw.get(id); } };
+  const enc=encryptedStorage(storage, createCipher({key:randomKey()}));
+  const res=await enc.put(Buffer.from('secret au repos'));
+  assert.ok(!raw.get(res.id).toString().includes('secret'), 'au repos = chiffré (pas de clair)');
+  assert.equal((await enc.get(res.id)).toString(),'secret au repos','déchiffré à la lecture');
+});
+console.log(`\n✅ @mostajs/security — ${pass} tests OK`);