@mostajs/certificates 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog — @mostajs/certificates
+## [0.1.0] — 2026-06-18
+### Added
+- Émission + vérification (signature HMAC via @mostajs/security) + révocation + QR + rendu PDF (file-export). 8 tests + exemple §12.

package/README.md

@@ -0,0 +1,11 @@
+# @mostajs/certificates
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (8 tests verts)
+> Certificats/attestations vérifiables : PDF + QR + **signature numérique** (HMAC @mostajs/security). Compose qrpanel/file-export/numbering/storage.
+```js
+import { createCertificates, createMemoryRepositories } from '@mostajs/certificates';
+import { hmacSha256 } from '@mostajs/security';
+const c = createCertificates({ repositories: createMemoryRepositories(), hmac: hmacSha256, secret: env.MOSTA_CERT_SECRET, qr });
+const cert = await c.issue({ subjectId:'eleve', title:'Anglais B1', payload:{niveau:'B1'} });
+const { valid } = await c.verify(cert.no);
+```
+Lancer : `node test-scripts/unit/certificates.test.mjs && node examples/attestation/run.mjs`

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

@@ -0,0 +1,8 @@
+# @mostajs/certificates — DEVRULES de bout en bout (§4 + #3 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C (P2 + P3, générique)
+## §4 / §3
+Certificats/attestations **vérifiables** : génération (PDF) + **QR de vérification** + **signature numérique** (HMAC).
+Autonome/DB-agnostique. **Compose** : security (hmac=signature), qrpanel (QR), file-export (PDF), numbering (n°), storage (archive PDF).
+**Frontière** : la note/niveau = gradebook ; le contenu = training. **API** : `createCertificates({repositories,hmac,secret,qr?,fileExport?,numbering?,storage?})`
+→ `issue({subjectId,title,payload,issuer})`, `verify(no|{no,signature})`, `revoke`, `get/byNo/listBySubject`, `render(id,format)`.
+**Réutilisabilité** : ATC (attestations formation), ASSO-SEL (attestations), tout émetteur. **Jalons** : 0.1 émission+vérif+révoc · 0.2 PDF/QR rendus · 1.0 14 livrables.

package/examples/attestation/run.mjs

@@ -0,0 +1,11 @@
+// Exemple §12 — attestation de formation vérifiable. node examples/attestation/run.mjs
+import assert from 'node:assert/strict';
+import { createCertificates, createMemoryRepositories } from '../../src/index.js';
+import { hmacSha256 } from '../../../mosta-security/src/index.js';
+const c=createCertificates({ repositories:createMemoryRepositories(), hmac:hmacSha256, secret:process.env.MOSTA_CERT_SECRET||'demo-secret',
+  qr:{ generate:(p)=>'https://verify.atc.dz/?c='+encodeURIComponent(p) }, numbering:{ next:()=> 'CERT-2026-'+Math.floor(Math.random()*9999) },
+  fileExport:{ async exportDoc(fmt,doc){ return `(${fmt}) ${doc.title} #${doc.items[0].fields.valeur}`; } } });
+const cert=await c.issue({ subjectId:'Inès Mansouri', title:'Certificat Anglais B1', payload:{ niveau:'B1', score:'78/100' }, issuer:'ATC Smart Campus' });
+const v=await c.verify(cert.no); assert.equal(v.valid,true);
+console.log('✅ certificates —', cert.no, '· QR:', cert.qrCode.slice(0,45)+'…', '· vérif:', v.valid);
+console.log('   PDF:', await c.render(cert.id));

package/llms.txt

@@ -0,0 +1,12 @@
+# @mostajs/certificates — fiche LLM
+RÔLE
+  Certificats vérifiables : émission + QR de vérification + signature numérique (HMAC via @mostajs/security). Autonome/DB-agnostique.
+  Compose (injectés) : security (hmac+secret=signature), qrpanel (QR), file-export (PDF), numbering (n°), storage (archive).
+EXPORTS
+  createCertificates({ repositories, hmac, secret, qr?, fileExport?, numbering?, storage?, now? }) -> api ; createMemoryRepositories(); CertificateSchema
+API
+  issue({subjectId,title,payload,issuer}) -> cert(no,signature,qrCode) ; verify(no|{no,signature}) -> {valid,reason,certificate}
+  revoke(id,{by}) ; get/byNo/listBySubject ; render(id,format='pdf') (compose file-export + storage)
+PIÈGES
+  - signature = hmac(canonical(no,subjectId,title,issuedAt,payload), secret) → toute modif du contenu invalide la vérif.
+  - verify : recalcule la signature + vérifie status≠revoked. secret via .env (@mostajs/config). QR via qrpanel.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/certificates",
+  "version": "0.1.0",
+  "description": "Certificats/attestations vérifiables : génération PDF + QR de vérification + signature numérique (HMAC). DB-agnostique ; compose security/qrpanel/file-export/numbering/storage.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schemas": "./src/schemas.js"
+  },
+  "keywords": [
+    "mostajs",
+    "certificates",
+    "attestation",
+    "qr",
+    "signature",
+    "verification"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/certificates.test.mjs",
+    "example": "node examples/attestation/run.mjs"
+  }
+}

package/src/certificates.js

@@ -0,0 +1,58 @@
+// @mostajs/certificates — certificats vérifiables. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Autonome/DB-agnostique. Compose (injectés) : security (hmac=signature numérique), qrpanel (QR vérif),
+// file-export (rendu PDF), numbering (n° certificat), storage (archivage du PDF).
+
+const canonical = (c) => JSON.stringify({ no: c.no, subjectId: c.subjectId, title: c.title, issuedAt: c.issuedAt, payload: c.payload });
+
+export function createCertificates({ repositories, hmac, secret, qr, fileExport, numbering, storage, now = () => new Date() } = {}) {
+  if (!repositories?.certificates) throw new Error('createCertificates: repositories.certificates requis');
+  const { certificates } = repositories;
+  const no = () => (numbering?.next ? numbering.next('certificate') : `CERT-${now().getFullYear()}-${Math.floor(now().getTime() % 1000000)}`);
+  const sign = (c) => (hmac ? hmac(canonical(c), secret) : undefined);   // signature numérique (compose @mostajs/security)
+
+  const api = {
+    /** Émet un certificat signé + QR de vérification. */
+    async issue({ subjectId, title, payload = {}, issuer } = {}) {
+      if (!subjectId || !title) throw new Error('subjectId et title requis');
+      const draft = { no: no(), subjectId, title, payload, issuer, issuedAt: now(), status: 'valid' };
+      draft.signature = sign(draft);
+      draft.qrCode = qr?.generate ? qr.generate(`${draft.no}|${draft.signature || ''}`) : `CERT:${draft.no}`;
+      return certificates.create(draft);
+    },
+    get: (id) => certificates.findById(id),
+    byNo: async (no) => (await certificates.find((c) => c.no === no))[0] || null,
+    listBySubject: (subjectId) => certificates.find((c) => c.subjectId === subjectId),
+    revoke: async (id, { by } = {}) => certificates.update(id, { status: 'revoked', revokedBy: by, revokedAt: now() }),
+
+    /** Vérifie un certificat (signature recalculée + non révoqué). Accepte no ou {no, signature}. */
+    async verify(input) {
+      const no = typeof input === 'string' ? input : input?.no;
+      const c = await api.byNo(no);
+      if (!c) return { valid: false, reason: 'introuvable' };
+      if (c.status === 'revoked') return { valid: false, reason: 'révoqué', certificate: c };
+      if (hmac) {
+        const expected = sign(c);
+        if (expected !== c.signature) return { valid: false, reason: 'signature invalide', certificate: c };
+        if (typeof input === 'object' && input.signature && input.signature !== c.signature) return { valid: false, reason: 'signature fournie incohérente', certificate: c };
+      }
+      return { valid: true, certificate: c };
+    },
+
+    /** Rendu PDF (compose @mostajs/file-export) + archivage (compose @mostajs/storage), optionnels. */
+    async render(id, format = 'pdf') {
+      const c = await certificates.findById(id); if (!c) throw new Error('certificat introuvable');
+      const doc = { title: c.title, items: [
+        { title: 'N°', fields: { valeur: c.no } },
+        { title: 'Bénéficiaire', fields: { valeur: c.subjectId } },
+        { title: 'Date', fields: { valeur: new Date(c.issuedAt).toISOString().slice(0, 10) } },
+        { title: 'Vérification (QR)', fields: { valeur: c.qrCode } },
+        ...Object.entries(c.payload || {}).map(([k, v]) => ({ title: k, fields: { valeur: String(v) } })),
+      ] };
+      const out = fileExport?.exportDoc ? await fileExport.exportDoc(format, doc) : doc;
+      if (storage?.put && out !== doc) { const ref = await storage.put(Buffer.from(typeof out === 'string' ? out : JSON.stringify(out))); await certificates.update(id, { fileRef: typeof ref === 'string' ? ref : ref.id }); }
+      return out;
+    },
+    repositories,
+  };
+  return api;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/certificates — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createCertificates } from './certificates.js';
+export { createMemoryRepositories } from './memory-repo.js';
+export { CertificateSchema } from './schemas.js';

package/src/memory-repo.js

@@ -0,0 +1,7 @@
+// @mostajs/certificates — repos mémoire. Author: Dr Hamid MADANI <drmdh@msn.com>
+function coll(){ const m=new Map(); return {
+  async create(d){ const id=d.id||globalThis.crypto.randomUUID(); const now=new Date(); const r={id,createdAt:now,updatedAt:now,...d}; m.set(id,r); return {...r}; },
+  async findById(id){ const r=m.get(id); return r?{...r}:null; },
+  async update(id,p){ const r=m.get(id); if(!r)return null; const x={...r,...p,updatedAt:new Date()}; m.set(id,x); return {...x}; },
+  async find(f=()=>true){ return [...m.values()].filter(f).map(r=>({...r})); } }; }
+export function createMemoryRepositories(){ return { certificates:coll() }; }

package/src/schemas.js

@@ -0,0 +1,6 @@
+// @mostajs/certificates — schéma (EntitySchema @mostajs/orm). Author: Dr Hamid MADANI <drmdh@msn.com>
+export const CertificateSchema = { name:'Certificate', collection:'certificates', timestamps:true, fields:{
+  no:{type:'string',unique:true}, subjectId:{type:'string',required:true}, title:{type:'string',required:true},
+  payload:{type:'json',default:()=>({})}, issuer:{type:'string'}, issuedAt:{type:'date',default:'now'},
+  signature:{type:'string',default:null}, qrCode:{type:'string',default:null}, fileRef:{type:'string',default:null},
+  status:{type:'string',enum:['valid','revoked'],default:'valid'} }, indexes:[{fields:{subjectId:'asc'}},{fields:{no:'asc'}}] };

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

@@ -0,0 +1,36 @@
+// @mostajs/certificates — tests (DEVRULES §5). node test-scripts/unit/certificates.test.mjs
+import assert from 'node:assert/strict';
+import { createCertificates, createMemoryRepositories } from '../../src/index.js';
+import { hmacSha256 } from '../../../mosta-security/src/index.js';   // signature numérique = @mostajs/security
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const mk=(o={})=>createCertificates({ repositories:createMemoryRepositories(), hmac:hmacSha256, secret:'cle-test', qr:{generate:(p)=>'QR:'+p}, ...o });
+
+await test('émission : no + signature + QR', async()=>{
+  const c=mk(); const cert=await c.issue({subjectId:'eleve1',title:'Anglais B1',payload:{niveau:'B1'},issuer:'ATC'});
+  assert.ok(cert.no && cert.signature && cert.qrCode.startsWith('QR:'));
+});
+await test('vérification : valide', async()=>{
+  const c=mk(); const cert=await c.issue({subjectId:'e',title:'X'});
+  const v=await c.verify(cert.no); assert.equal(v.valid,true);
+});
+await test('vérification : signature altérée → invalide', async()=>{
+  const c=mk(); const cert=await c.issue({subjectId:'e',title:'X'});
+  await c.repositories.certificates.update(cert.id,{title:'FALSIFIÉ'});  // altère le contenu signé
+  const v=await c.verify(cert.no); assert.equal(v.valid,false); assert.match(v.reason,/signature/);
+});
+await test('révocation → invalide', async()=>{
+  const c=mk(); const cert=await c.issue({subjectId:'e',title:'X'});
+  await c.revoke(cert.id,{by:'admin'}); const v=await c.verify(cert.no);
+  assert.equal(v.valid,false); assert.equal(v.reason,'révoqué');
+});
+await test('introuvable', async()=>{ assert.equal((await mk().verify('CERT:none')).valid,false); });
+await test('subjectId/title requis', async()=>{ await assert.rejects(()=>mk().issue({title:'x'}),/requis/); });
+await test('rendu PDF (compose file-export)', async()=>{
+  const exp=[]; const c=mk({ fileExport:{ async exportDoc(fmt,doc){exp.push(fmt);return 'cert.pdf';} } });
+  const cert=await c.issue({subjectId:'e',title:'Dipl'}); assert.equal(await c.render(cert.id),'cert.pdf'); assert.equal(exp[0],'pdf');
+});
+await test('listBySubject', async()=>{
+  const c=mk(); await c.issue({subjectId:'s1',title:'A'}); await c.issue({subjectId:'s1',title:'B'});
+  assert.equal((await c.listBySubject('s1')).length,2);
+});
+console.log(`\n✅ @mostajs/certificates — ${pass} tests OK`);