@mostajs/backup 0.2.0 → 0.3.0

package/dist/cjs/index.js

@@ -0,0 +1,395 @@
+"use strict";
+/**
+ * @mostajs/backup — Sauvegarder, vérifier, restaurer. Pour de vrai.
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * Licence : AGPL-3.0-or-later
+ * Niveau : N1 · Compose : archive-box · orm-copy-data · crypto-box · blob-store
+ *
+ * ─── UNE COPIE N'EST PAS UNE SAUVEGARDE ──────────────────────────────────────
+ * `@mostajs/orm-copy-data` TRANSFÈRE (A → B) : pas d'artefact, pas de temps, pas de
+ * vérification. Copier vers une seconde base ne donne pas une sauvegarde mais une RÉPLIQUE :
+ * le jour où quelqu'un supprime 300 tickets par erreur, la suppression se propage fidèlement.
+ * On a recopié le désastre.
+ *
+ * Une SAUVEGARDE est un artefact FIGÉ, DATÉ, VÉRIFIABLE et RESTAURABLE. Ce qui la définit,
+ * ce n'est pas la copie — c'est le TEMPS, l'INTÉGRITÉ et la RESTAURABILITÉ.
+ *
+ * ─── CE QUE CE MODULE N'INVENTE PAS ──────────────────────────────────────────
+ *   données      → @mostajs/orm-copy-data   (13 dialectes, entre bases et formats)
+ *   artefact     → @mostajs/archive-box     (zip + manifeste + empreintes + signature)
+ *   chiffrement  → @mostajs/crypto-box      (flux AEAD, enveloppe X25519)
+ *   dépôt        → @mostajs/blob-store      (disque, S3, tout service S3-compatible)
+ *
+ * Il n'ajoute que ce qu'aucun d'eux n'a : le PÉRIMÈTRE (au-delà des entités ORM : la config,
+ * la licence, les fichiers), la RÉTENTION, le TEST DE RESTAURATION, et la restauration
+ * ATOMIQUE avec retour arrière.
+ *
+ * ─── UN BACKUP JAMAIS RESTAURÉ N'EST PAS UN BACKUP ───────────────────────────
+ * C'est la panne la plus banale du métier : on sauvegarde deux ans, et le jour J l'archive est
+ * inutilisable. D'où `testRestore()` — qui restaure pour de vrai dans une base jetable et
+ * RECOMPTE les entités. Sans lui, on vend une promesse qu'on n'a pas vérifiée.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readManifest = exports.SECRETS_EXCLUS = exports.moduleInfo = void 0;
+exports.createBackup = createBackup;
+exports.storeBackup = storeBackup;
+exports.listBackups = listBackups;
+exports.verifyBackup = verifyBackup;
+exports.restoreBackup = restoreBackup;
+exports.testRestore = testRestore;
+exports.pruneBackups = pruneBackups;
+exports.scheduleBackups = scheduleBackups;
+const archive_box_1 = require("@mostajs/archive-box");
+Object.defineProperty(exports, "readManifest", { enumerable: true, get: function () { return archive_box_1.readManifest; } });
+const orm_copy_data_1 = require("@mostajs/orm-copy-data");
+const crypto_box_1 = require("@mostajs/crypto-box");
+const scheduler_1 = require("@mostajs/scheduler");
+exports.moduleInfo = { name: '@mostajs/backup', version: '0.3.0', level: 'N1' };
+/** Ce que le module NE met JAMAIS dans une archive. */
+exports.SECRETS_EXCLUS = ['JWT_SECRET', 'SGBD_URI', 'DB_PASSWORD', 'token', 'password'];
+/**
+ * Garde-fou : un schéma sans `collection` fait écrire TOUTES les entités dans une seule table —
+ * en SILENCE. L'ORM l'accepte sans broncher : les tickets et les guichets se mélangent, les
+ * colonnes fusionnent, et personne ne s'en aperçoit avant la restauration… chez le client.
+ *
+ * Une sauvegarde silencieusement fausse est pire que pas de sauvegarde du tout. On refuse.
+ */
+function exigerCollections(schemas) {
+    const sans = schemas.filter((s) => !s.collection).map((s) => s.name || '(sans nom)');
+    if (sans.length) {
+        throw new Error(`[backup] schéma(s) sans « collection » : ${sans.join(', ')}. ` +
+            'L\'ORM en dérive le nom de table — sans lui, TOUTES les entités seraient écrites dans la même table, en silence.');
+    }
+}
+const horodatage = (d) => d.toISOString().replace(/[:.]/g, '-');
+/**
+ * Crée une sauvegarde COMPLÈTE : entités + configuration + fichiers.
+ *
+ * Le périmètre dépasse structurellement `orm-copy-data`, qui ne voit QUE les entités de l'ORM.
+ * Une restauration qui rend les tickets mais pas la configuration ni la licence ne remet pas
+ * le cabinet en marche lundi matin.
+ */
+async function createBackup(opts) {
+    exigerCollections(opts.source.schemas);
+    const createdAt = new Date();
+    // 1. Dump des entités : db → JSON en mémoire (via orm-copy-data, on ne réinvente rien).
+    const dump = await dumpEntities(opts.source);
+    const files = [];
+    const counts = {};
+    for (const [entity, rows] of Object.entries(dump)) {
+        counts[entity] = rows.length;
+        files.push({ path: `entities/${entity}.json`, content: JSON.stringify(rows) });
+    }
+    // 2. Le hors-base : sans lui, l'archive n'est pas restaurable en pratique.
+    if (opts.extras?.config !== undefined) {
+        files.push({ path: 'config.json', content: JSON.stringify(opts.extras.config, null, 2) });
+    }
+    for (const f of opts.extras?.files ?? []) {
+        files.push({ path: `files/${f.path}`, content: f.content });
+    }
+    // 3. L'artefact : zip + manifeste + empreintes (+ signature).
+    const built = await (0, archive_box_1.buildArchive)({
+        name: `sauvegarde-${opts.siteId}-${horodatage(createdAt)}`,
+        kind: 'backup',
+        createdBy: opts.createdBy,
+        sourceApp: '@mostajs/backup',
+        files,
+        extra: {
+            siteId: opts.siteId,
+            dialect: opts.source.dialect,
+            counts, // ← la référence du test de restauration
+            entities: Object.keys(counts),
+            total: Object.values(counts).reduce((a, b) => a + b, 0),
+        },
+        signingKey: opts.signingKey,
+        signingPublicKey: opts.signingPublicKey,
+    });
+    // 4. Scellement facultatif : le prestataire conserve sans pouvoir lire.
+    const sealed = !!opts.recipients?.length;
+    const buffer = sealed ? (0, crypto_box_1.seal)(opts.recipients, built.buffer) : built.buffer;
+    return {
+        buffer,
+        plainBuffer: built.buffer, // jamais déposé — sert au test de restauration
+        manifest: built.manifest,
+        counts,
+        sealed,
+        siteId: opts.siteId,
+        createdAt: createdAt.toISOString(),
+        path: `backups/${opts.siteId}/${horodatage(createdAt)}.archive`,
+        size: buffer.length,
+        sha256: (0, crypto_box_1.sha256)(buffer),
+    };
+}
+/** Dump des entités via `orm-copy-data` (source db → writer json en mémoire). */
+async function dumpEntities(source) {
+    const { writeFileSync, mkdtempSync, readFileSync, rmSync } = await Promise.resolve().then(() => __importStar(require('node:fs')));
+    const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
+    const path = await Promise.resolve().then(() => __importStar(require('node:path')));
+    const dir = mkdtempSync(path.join(tmpdir(), 'mostajs-backup-'));
+    const out = path.join(dir, 'dump.json');
+    try {
+        await (0, orm_copy_data_1.copyData)({
+            source: { type: 'db', dialect: source.dialect, uri: source.uri },
+            destinations: [{ type: 'json', file: out }],
+            schemas: source.schemas,
+            options: { batchSize: 500 },
+        });
+        const raw = JSON.parse(readFileSync(out, 'utf8'));
+        return raw.entities ?? {};
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* nettoyage best-effort */ }
+        void writeFileSync;
+    }
+}
+// ─── Dépôt (blob-store : disque, S3, MinIO…) ────────────────────────────────
+async function storeBackup(driver, bucket, backup) {
+    const ref = { bucket, path: backup.path };
+    await driver.put(ref, backup.buffer, {
+        mimeType: 'application/octet-stream',
+        metadata: {
+            siteid: backup.siteId,
+            createdat: backup.createdAt,
+            sealed: String(backup.sealed),
+            sha256: backup.sha256,
+        },
+    });
+    return ref;
+}
+async function listBackups(driver, bucket, siteId) {
+    const res = await driver.list({ bucket, prefix: `backups/${siteId}/`, limit: 1000 });
+    return res.items
+        .map((i) => ({
+        path: i.path,
+        siteId,
+        createdAt: i.modifiedAt.toISOString(),
+        size: i.size,
+        sha256: '',
+        sealed: false,
+    }))
+        .sort((a, b) => (a.path < b.path ? 1 : -1)); // plus récentes d'abord
+}
+/**
+ * Vérifie une archive SANS la restaurer. `privateKey` est requise si elle est scellée.
+ *
+ * `expectedPublicKey` n'est pas un détail : une archive parfaitement valide, SIGNÉE PAR UN
+ * TIERS, reste dangereuse. Sans cette clé, on restaure une base fabriquée par quelqu'un d'autre.
+ */
+async function verifyBackup(buffer, opts = {}) {
+    const zip = unseal(buffer, opts.privateKey);
+    const v = await (0, archive_box_1.verifyArchive)(zip, { expectedPublicKey: opts.expectedPublicKey });
+    const counts = v.manifest?.archiveBox?.extra?.counts ?? {};
+    return { ...v, counts };
+}
+/** Descelle si nécessaire. Une archive scellée sans clé n'est pas lisible — c'est le but. */
+function unseal(buffer, privateKey) {
+    const estScellee = buffer.subarray(0, 5).toString() === 'MJSE1';
+    if (!estScellee)
+        return buffer;
+    if (!privateKey) {
+        throw new Error('[backup] archive SCELLÉE : clé privée requise (le prestataire, lui, ne peut pas l’ouvrir)');
+    }
+    return (0, crypto_box_1.open)(privateKey, buffer);
+}
+/**
+ * Restaure une archive. **Simulation par défaut** : une restauration est destructrice, elle ne
+ * part jamais sans un choix explicite.
+ *
+ * La restauration se termine par un RECOMPTAGE : les entités relues dans la base doivent
+ * correspondre aux compteurs du manifeste. Sans cela, on déclare « restauré » sans savoir.
+ */
+async function restoreBackup(buffer, opts) {
+    exigerCollections(opts.schemas);
+    const dryRun = opts.dryRun !== false;
+    const zip = unseal(buffer, opts.privateKey);
+    // Strict : intégrité ET signature vérifiées AVANT toute écriture.
+    const archive = await (0, archive_box_1.openArchive)(zip, { expectedPublicKey: opts.expectedPublicKey, strict: true });
+    const attendus = archive.manifest.archiveBox.extra?.counts ?? {};
+    const config = archive.files.has('config.json')
+        ? JSON.parse(archive.files.get('config.json').toString('utf8'))
+        : undefined;
+    if (dryRun) {
+        return { dryRun: true, attendus, obtenus: {}, verifie: true, config, ecarts: [] };
+    }
+    // Reconstitution du dump JSON attendu par orm-copy-data.
+    const entities = {};
+    for (const [path, content] of archive.files) {
+        const m = /^entities\/(.+)\.json$/.exec(path);
+        if (m)
+            entities[m[1]] = JSON.parse(content.toString('utf8'));
+    }
+    const { writeFileSync, mkdtempSync, rmSync } = await Promise.resolve().then(() => __importStar(require('node:fs')));
+    const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
+    const nodePath = await Promise.resolve().then(() => __importStar(require('node:path')));
+    const dir = mkdtempSync(nodePath.join(tmpdir(), 'mostajs-restore-'));
+    const src = nodePath.join(dir, 'restore.json');
+    try {
+        writeFileSync(src, JSON.stringify({ entities }));
+        await (0, orm_copy_data_1.copyData)({
+            source: { type: 'json', file: src },
+            destinations: [{ type: 'db', dialect: opts.dialect, uri: opts.uri, createTables: true }],
+            schemas: opts.schemas,
+            options: { batchSize: 500 },
+        });
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+    // RECOMPTAGE — le contrôle qui transforme « restauré » en « restauré ET vérifié ».
+    const obtenus = await dumpEntities({ dialect: opts.dialect, uri: opts.uri, schemas: opts.schemas })
+        .then((d) => Object.fromEntries(Object.entries(d).map(([k, v]) => [k, v.length])));
+    const ecarts = [];
+    for (const [entity, n] of Object.entries(attendus)) {
+        const got = obtenus[entity] ?? 0;
+        if (got !== n)
+            ecarts.push(`${entity} : attendu ${n}, obtenu ${got}`);
+    }
+    return { dryRun: false, attendus, obtenus, verifie: ecarts.length === 0, config, ecarts };
+}
+/**
+ * TEST DE RESTAURATION — restaure dans une base JETABLE et recompte.
+ *
+ * Un backup jamais restauré n'est pas un backup : c'est la panne la plus banale du métier. On
+ * sauvegarde deux ans, et le jour J l'archive est inutilisable. Ce test doit tourner
+ * AUTOMATIQUEMENT — sans lui, on vend une promesse qu'on n'a jamais vérifiée.
+ */
+async function testRestore(buffer, opts) {
+    const { mkdtempSync, rmSync } = await Promise.resolve().then(() => __importStar(require('node:fs')));
+    const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
+    const path = await Promise.resolve().then(() => __importStar(require('node:path')));
+    const dir = mkdtempSync(path.join(tmpdir(), 'mostajs-testrestore-'));
+    const db = path.join(dir, 'jetable.sqlite');
+    try {
+        return await restoreBackup(buffer, {
+            dialect: 'sqljs',
+            uri: db,
+            schemas: opts.schemas,
+            privateKey: opts.privateKey,
+            expectedPublicKey: opts.expectedPublicKey,
+            dryRun: false,
+        });
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * Purge les sauvegardes excédentaires. Retourne CE QUI A ÉTÉ SUPPRIMÉ — jamais en silence :
+ * une purge muette est le meilleur moyen de découvrir trop tard qu'on a effacé la seule copie.
+ */
+async function pruneBackups(driver, bucket, siteId, policy) {
+    const all = await listBackups(driver, bucket, siteId);
+    if (!policy.keepLast || all.length <= policy.keepLast) {
+        return { supprimees: [], conservees: all.map((b) => b.path) };
+    }
+    const conservees = all.slice(0, policy.keepLast);
+    const aSupprimer = all.slice(policy.keepLast);
+    for (const b of aSupprimer)
+        await driver.delete({ bucket, path: b.path });
+    return { supprimees: aSupprimer.map((b) => b.path), conservees: conservees.map((b) => b.path) };
+}
+/**
+ * Planifie les sauvegardes. Compose `@mostajs/scheduler` — on ne réinvente ni la cadence, ni
+ * l'idempotence, ni l'adoption de la période au démarrage.
+ *
+ * ─── DEUX PIÈGES MORTELS, TRAITÉS ICI ────────────────────────────────────────
+ *
+ * 1. **La rétention qui purge après un ÉCHEC.** C'est la façon classique de tout perdre : la
+ *    sauvegarde de ce soir échoue (base verrouillée, disque plein), la rotation s'exécute quand
+ *    même, et elle supprime la plus ancienne des N archives valides. Répétez l'opération N nuits,
+ *    et il ne reste RIEN — alors que chaque nuit « la sauvegarde a tourné ».
+ *    → La purge n'a lieu **QUE** si la nouvelle sauvegarde est créée ET vérifiée.
+ *
+ * 2. **L'échec silencieux.** Un planificateur qui n'a personne pour écouter ses erreurs a l'air
+ *    de fonctionner. On ne s'aperçoit de rien jusqu'au jour où l'on cherche une archive qui
+ *    n'existe pas.
+ *    → `onBackup` est notifié à CHAQUE cycle, succès **comme** échec. C'est le point de
+ *      supervision : branchez-y une alerte, sinon vous ne saurez jamais.
+ */
+function scheduleBackups(opts) {
+    const verifyRestore = opts.verifyRestore !== false;
+    return (0, scheduler_1.createScheduler)({
+        getSchedule: opts.getSchedule,
+        intervalMs: opts.intervalMs,
+        now: opts.now,
+        onTrigger: async () => {
+            let backup;
+            try {
+                backup = await createBackup(opts);
+                await storeBackup(opts.driver, opts.bucket, backup);
+                // Le test de restauration fait partie de la sauvegarde, pas d'une corvée séparée :
+                // une archive non testée n'est pas une archive vérifiée.
+                let restoreTest;
+                if (verifyRestore) {
+                    // On teste l'archive AVANT scellement. Une archive scellée pour le client ne peut pas
+                    // être ouverte par la console — c'est le point du modèle. Tester sur `buffer` exigerait
+                    // donc la clé PRIVÉE du client, exactement ce qu'on refuse de détenir.
+                    restoreTest = await testRestore(backup.plainBuffer, {
+                        schemas: opts.source.schemas,
+                        expectedPublicKey: opts.signingPublicKey,
+                    });
+                    if (!restoreTest.verifie) {
+                        // On NE PURGE PAS : les anciennes archives sont peut-être tout ce qui reste de bon.
+                        throw new Error(`[backup] sauvegarde créée mais NON RESTAURABLE — rétention suspendue. ${restoreTest.ecarts.join(' · ')}`);
+                    }
+                }
+                // Purge — uniquement maintenant, la nouvelle sauvegarde étant créée ET vérifiée.
+                let pruned;
+                if (opts.retention) {
+                    const r = await pruneBackups(opts.driver, opts.bucket, opts.siteId, opts.retention);
+                    pruned = r.supprimees;
+                }
+                opts.onBackup?.({ ok: true, backup, restoreTest, pruned });
+            }
+            catch (error) {
+                // La rétention n'a PAS tourné : c'est le point. Un échec ne doit jamais faire disparaître
+                // une archive valide.
+                opts.onBackup?.({ ok: false, backup, error });
+                throw error; // remonte aussi à `onError` du planificateur
+            }
+        },
+        onError: (e) => { void e; /* déjà remonté par onBackup */ },
+    });
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/index.d.ts

@@ -34,7 +34,7 @@ import type { StorageDriver, ObjectRef } from '@mostajs/blob-store';
 import type { Schedule, Scheduler } from '@mostajs/scheduler';
 export declare const moduleInfo: {
     readonly name: "@mostajs/backup";
-    readonly version: "0.1.0";
+    readonly version: "0.3.0";
     readonly level: "N1";
 };
 /** Ce que le module NE met JAMAIS dans une archive. */

package/dist/index.js

@@ -32,7 +32,7 @@ import { buildArchive, openArchive, verifyArchive, readManifest } from '@mostajs
 import { copyData } from '@mostajs/orm-copy-data';
 import { seal, open as openSealed, sha256 } from '@mostajs/crypto-box';
 import { createScheduler } from '@mostajs/scheduler';
-export const moduleInfo = { name: '@mostajs/backup', version: '0.1.0', level: 'N1' };
+export const moduleInfo = { name: '@mostajs/backup', version: '0.3.0', level: 'N1' };
 /** Ce que le module NE met JAMAIS dans une archive. */
 export const SECRETS_EXCLUS = ['JWT_SECRET', 'SGBD_URI', 'DB_PASSWORD', 'token', 'password'];
 /**

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@mostajs/backup",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sauvegarder, vérifier, restaurer — pour de vrai. Artefact daté, signé, chiffrable par enveloppe. Sauvegardes PLANIFIÉES avec test de restauration automatique et rétention qui ne purge JAMAIS après un échec. Compose archive-box, orm-copy-data, crypto-box, blob-store et scheduler.",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/index.d.ts",
   "license": "AGPL-3.0-or-later",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
-  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
       "default": "./dist/index.js"
     }
   },
@@ -19,7 +22,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
     "test": "bash test-scripts/run-tests.sh",
     "prepublishOnly": "npm run build"
   },
@@ -33,10 +36,10 @@
     "mostajs"
   ],
   "dependencies": {
-    "@mostajs/archive-box": "^0.1.0",
-    "@mostajs/blob-store": "^0.3.0",
-    "@mostajs/crypto-box": "^0.2.0",
-    "@mostajs/orm-copy-data": "^0.4.0",
+    "@mostajs/archive-box": "^0.2.0",
+    "@mostajs/blob-store": "^0.4.0",
+    "@mostajs/crypto-box": "^0.2.1",
+    "@mostajs/orm-copy-data": "^0.5.0",
     "@mostajs/scheduler": "^0.2.0"
   },
   "peerDependencies": {
@@ -54,4 +57,4 @@
     "sql.js": "^1.14.1",
     "typescript": "^5.6.0"
   }
-}
+}