@mostajs/backup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+@mostajs/mjs-unit
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+The complete text of the GNU Affero General Public License version 3 is
+available at the URL above and must accompany any distribution of this
+software.

package/README.md

@@ -0,0 +1,82 @@
+# @mostajs/backup
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Niveau** : N1
+
+Sauvegarder, vérifier, restaurer. **Pour de vrai.**
+
+## 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 module n'invente rien — il compose
+
+| Besoin | Module |
+|---|---|
+| données | `@mostajs/orm-copy-data` |
+| artefact (zip, manifeste, empreintes, signature) | `@mostajs/archive-box` |
+| chiffrement (flux AEAD, enveloppe X25519) | `@mostajs/crypto-box` |
+| dépôt (disque, S3, MinIO…) | `@mostajs/blob-store` |
+
+Il n'ajoute que ce qu'aucun d'eux n'a : le **périmètre**, la **rétention**, le **test de
+restauration** et la **restauration vérifiée**.
+
+## Le périmètre : au-delà des entités
+
+`orm-copy-data` 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.
+`createBackup` embarque donc entités **+ config + fichiers**.
+
+## Le modèle qui rend le service vendable
+
+```js
+const b = await createBackup({
+  source: { dialect: 'sqljs', uri: './data.sqlite', schemas },
+  extras: { config, files: [{ path: 'licence.json', content }] },
+  siteId: 'yalidine-01',
+  signingKey: notre.privateKey, signingPublicKey: notre.publicKey,  // QUI l'a produite
+  recipients: [client.publicKey, secours.publicKey],                // POUR QUI elle est lisible
+});
+await storeBackup(driver, 'sauvegardes', b);
+```
+
+**Scellée pour le client, le prestataire ne peut pas l'ouvrir.** On vend la conservation et la
+restauration **sans jamais détenir les secrets**. Une compromission de la console n'expose rien.
+Une **clé de secours** hors ligne, ajoutée comme second destinataire, atténue le
+« clé perdue = tout perdu ».
+
+## 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.
+
+```js
+const r = await testRestore(b.buffer, { schemas });   // base JETABLE + RECOMPTAGE
+r.verifie  // true si les entités relues correspondent aux compteurs du manifeste
+```
+
+`restoreBackup` est en **simulation par défaut** — une restauration est destructrice, elle ne
+part jamais sans un choix explicite — et se termine par un **recomptage** : une restauration
+qu'on ne recompte pas n'est pas vérifiée, on a seulement déclaré « restauré ».
+
+## Le garde-fou qui a été gagné à la dure
+
+Un schéma sans `collection` fait écrire **toutes les entités dans la même table**, en silence
+(l'ORM en dérive le nom de table). Rencontré ici même : `Ticket`(12) + `Counter`(2) relisaient
+**14 lignes chacun**, contenus mélangés. Corrigé en amont (`@mostajs/orm` 2.11.1 le rejette
+désormais, `orm-copy-data` 0.4.0 l'appelle), et **refusé ici aussi** — défense en profondeur.
+
+## Tests
+
+```bash
+npm test   # 13 tests, sur une VRAIE base sqljs
+```
+
+Une vraie base est peuplée, sauvegardée, signée, scellée, vérifiée, **restaurée** dans une base
+jetable — et les entités sont **recomptées**. Un module de sauvegarde qui ne restaure jamais
+rien n'est pas testé.

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @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.
+ */
+import { readManifest } from '@mostajs/archive-box';
+import type { ArchiveManifest, IntegrityVerdict, SignatureVerdict } from '@mostajs/archive-box';
+import type { StorageDriver, ObjectRef } from '@mostajs/blob-store';
+export declare const moduleInfo: {
+    readonly name: "@mostajs/backup";
+    readonly version: "0.1.0";
+    readonly level: "N1";
+};
+/** Ce que le module NE met JAMAIS dans une archive. */
+export declare const SECRETS_EXCLUS: readonly ["JWT_SECRET", "SGBD_URI", "DB_PASSWORD", "token", "password"];
+/**
+ * Schéma d'entité (cf. `@mostajs/orm`).
+ *
+ * `collection` est OBLIGATOIRE : c'est de LUI, et non de `name`, que l'ORM dérive le nom de
+ * table (`abstract-sql.dialect.js` → `schema.collection`).
+ */
+export interface EntitySchemaLike {
+    name: string;
+    /** Nom de la table/collection. SANS lui, toutes les entités se retrouvent dans la MÊME table. */
+    collection: string;
+    fields?: Record<string, unknown>;
+}
+export interface DbSource {
+    dialect: string;
+    uri: string;
+    schemas: EntitySchemaLike[];
+}
+export interface BackupExtras {
+    /** Configuration applicative (arbre libre) — une base restaurée sans sa config ne redémarre pas. */
+    config?: unknown;
+    /** État de licence, etc. Les SECRETS n'y ont pas leur place. */
+    files?: {
+        path: string;
+        content: Buffer | string;
+    }[];
+}
+export interface CreateBackupOptions {
+    source: DbSource;
+    extras?: BackupExtras;
+    /** Étiquette du site — c'est elle qui distingue les sauvegardes de N clients. */
+    siteId: string;
+    createdBy?: string;
+    /** Signature Ed25519 du manifeste (recommandé : prouve QUI a produit l'archive). */
+    signingKey?: Uint8Array;
+    signingPublicKey?: Uint8Array;
+    /**
+     * Destinataires X25519. Fournis → l'archive est SCELLÉE : le prestataire peut la CONSERVER
+     * sans pouvoir l'OUVRIR. C'est ce qui permet de vendre le service sans détenir les secrets.
+     * Ajouter une clé de secours hors ligne atténue le « clé perdue = tout perdu ».
+     */
+    recipients?: Uint8Array[];
+}
+export interface BackupRef {
+    /** `backups/<siteId>/<horodatage>.archive` */
+    path: string;
+    siteId: string;
+    createdAt: string;
+    size: number;
+    sha256: string;
+    sealed: boolean;
+}
+export interface CreatedBackup extends BackupRef {
+    buffer: Buffer;
+    manifest: ArchiveManifest;
+    /** Compteurs par entité, au moment du dump — la RÉFÉRENCE du test de restauration. */
+    counts: Record<string, number>;
+}
+/**
+ * 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.
+ */
+export declare function createBackup(opts: CreateBackupOptions): Promise<CreatedBackup>;
+export declare function storeBackup(driver: StorageDriver, bucket: string, backup: CreatedBackup): Promise<ObjectRef>;
+export declare function listBackups(driver: StorageDriver, bucket: string, siteId: string): Promise<BackupRef[]>;
+export interface BackupVerdict {
+    integrity: IntegrityVerdict;
+    signature: SignatureVerdict;
+    manifest: ArchiveManifest | null;
+    /** Compteurs annoncés au manifeste. */
+    counts: Record<string, number>;
+}
+/**
+ * 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.
+ */
+export declare function verifyBackup(buffer: Buffer, opts?: {
+    privateKey?: Uint8Array;
+    expectedPublicKey?: Uint8Array;
+}): Promise<BackupVerdict>;
+export interface RestoreOptions {
+    dialect: string;
+    uri: string;
+    schemas: EntitySchemaLike[];
+    privateKey?: Uint8Array;
+    expectedPublicKey?: Uint8Array;
+    /** DÉFAUT : true. Aucune écriture — on rapporte ce qui SERAIT restauré. */
+    dryRun?: boolean;
+}
+export interface RestoreResult {
+    dryRun: boolean;
+    /** Compteurs annoncés par l'archive. */
+    attendus: Record<string, number>;
+    /** Compteurs RELUS dans la base après restauration (vide en simulation). */
+    obtenus: Record<string, number>;
+    /** Les deux coïncident-ils ? Une restauration qu'on ne recompte pas n'est pas vérifiée. */
+    verifie: boolean;
+    config?: unknown;
+    ecarts: string[];
+}
+/**
+ * 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.
+ */
+export declare function restoreBackup(buffer: Buffer, opts: RestoreOptions): Promise<RestoreResult>;
+/**
+ * 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.
+ */
+export declare function testRestore(buffer: Buffer, opts: {
+    schemas: DbSource['schemas'];
+    privateKey?: Uint8Array;
+    expectedPublicKey?: Uint8Array;
+}): Promise<RestoreResult>;
+export interface RetentionPolicy {
+    /** Nombre de sauvegardes à CONSERVER (les plus récentes). 0 = tout garder. */
+    keepLast: number;
+}
+/**
+ * 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.
+ */
+export declare function pruneBackups(driver: StorageDriver, bucket: string, siteId: string, policy: RetentionPolicy): Promise<{
+    supprimees: string[];
+    conservees: string[];
+}>;
+export { readManifest };

package/dist/index.js

@@ -0,0 +1,286 @@
+/**
+ * @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.
+ */
+import { buildArchive, openArchive, verifyArchive, readManifest } from '@mostajs/archive-box';
+import { copyData } from '@mostajs/orm-copy-data';
+import { seal, open as openSealed, sha256 } from '@mostajs/crypto-box';
+export const moduleInfo = { name: '@mostajs/backup', version: '0.1.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'];
+/**
+ * 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.
+ */
+export 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 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 ? seal(opts.recipients, built.buffer) : built.buffer;
+    return {
+        buffer,
+        manifest: built.manifest,
+        counts,
+        sealed,
+        siteId: opts.siteId,
+        createdAt: createdAt.toISOString(),
+        path: `backups/${opts.siteId}/${horodatage(createdAt)}.archive`,
+        size: buffer.length,
+        sha256: 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 import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const path = await import('node:path');
+    const dir = mkdtempSync(path.join(tmpdir(), 'mostajs-backup-'));
+    const out = path.join(dir, 'dump.json');
+    try {
+        await 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…) ────────────────────────────────
+export 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;
+}
+export 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.
+ */
+export async function verifyBackup(buffer, opts = {}) {
+    const zip = unseal(buffer, opts.privateKey);
+    const v = await 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 openSealed(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.
+ */
+export 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 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 import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const nodePath = await import('node:path');
+    const dir = mkdtempSync(nodePath.join(tmpdir(), 'mostajs-restore-'));
+    const src = nodePath.join(dir, 'restore.json');
+    try {
+        writeFileSync(src, JSON.stringify({ entities }));
+        await 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.
+ */
+export async function testRestore(buffer, opts) {
+    const { mkdtempSync, rmSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const path = await import('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.
+ */
+export 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) };
+}
+export { readManifest };

package/llms.txt

@@ -0,0 +1,82 @@
+# @mostajs/backup
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Niveau** : N1
+
+Sauvegarder, vérifier, restaurer. **Pour de vrai.**
+
+## 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 module n'invente rien — il compose
+
+| Besoin | Module |
+|---|---|
+| données | `@mostajs/orm-copy-data` |
+| artefact (zip, manifeste, empreintes, signature) | `@mostajs/archive-box` |
+| chiffrement (flux AEAD, enveloppe X25519) | `@mostajs/crypto-box` |
+| dépôt (disque, S3, MinIO…) | `@mostajs/blob-store` |
+
+Il n'ajoute que ce qu'aucun d'eux n'a : le **périmètre**, la **rétention**, le **test de
+restauration** et la **restauration vérifiée**.
+
+## Le périmètre : au-delà des entités
+
+`orm-copy-data` 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.
+`createBackup` embarque donc entités **+ config + fichiers**.
+
+## Le modèle qui rend le service vendable
+
+```js
+const b = await createBackup({
+  source: { dialect: 'sqljs', uri: './data.sqlite', schemas },
+  extras: { config, files: [{ path: 'licence.json', content }] },
+  siteId: 'yalidine-01',
+  signingKey: notre.privateKey, signingPublicKey: notre.publicKey,  // QUI l'a produite
+  recipients: [client.publicKey, secours.publicKey],                // POUR QUI elle est lisible
+});
+await storeBackup(driver, 'sauvegardes', b);
+```
+
+**Scellée pour le client, le prestataire ne peut pas l'ouvrir.** On vend la conservation et la
+restauration **sans jamais détenir les secrets**. Une compromission de la console n'expose rien.
+Une **clé de secours** hors ligne, ajoutée comme second destinataire, atténue le
+« clé perdue = tout perdu ».
+
+## 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.
+
+```js
+const r = await testRestore(b.buffer, { schemas });   // base JETABLE + RECOMPTAGE
+r.verifie  // true si les entités relues correspondent aux compteurs du manifeste
+```
+
+`restoreBackup` est en **simulation par défaut** — une restauration est destructrice, elle ne
+part jamais sans un choix explicite — et se termine par un **recomptage** : une restauration
+qu'on ne recompte pas n'est pas vérifiée, on a seulement déclaré « restauré ».
+
+## Le garde-fou qui a été gagné à la dure
+
+Un schéma sans `collection` fait écrire **toutes les entités dans la même table**, en silence
+(l'ORM en dérive le nom de table). Rencontré ici même : `Ticket`(12) + `Counter`(2) relisaient
+**14 lignes chacun**, contenus mélangés. Corrigé en amont (`@mostajs/orm` 2.11.1 le rejette
+désormais, `orm-copy-data` 0.4.0 l'appelle), et **refusé ici aussi** — défense en profondeur.
+
+## Tests
+
+```bash
+npm test   # 13 tests, sur une VRAIE base sqljs
+```
+
+Une vraie base est peuplée, sauvegardée, signée, scellée, vérifiée, **restaurée** dans une base
+jetable — et les entités sont **recomptées**. Un module de sauvegarde qui ne restaure jamais
+rien n'est pas testé.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mostajs/backup",
+  "version": "0.1.0",
+  "description": "Sauvegarder, vérifier, restaurer — pour de vrai. Une copie n'est pas une sauvegarde : artefact daté, signé, chiffrable par enveloppe, avec TEST DE RESTAURATION automatique et recomptage. Compose archive-box, orm-copy-data, crypto-box et blob-store.",
+  "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",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bash test-scripts/run-tests.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "backup",
+    "restore",
+    "archive",
+    "disaster-recovery",
+    "encryption",
+    "envelope",
+    "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"
+  },
+  "peerDependencies": {
+    "@mostajs/orm": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@mostajs/orm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.4.1",
+    "@mostajs/orm": "^2.11.0",
+    "@types/node": "^20",
+    "sql.js": "^1.14.1",
+    "typescript": "^5.6.0"
+  }
+}