@mostajs/blob-store 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (c) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+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/>.
+
+COMMERCIAL LICENSE
+
+For organizations that cannot comply with the AGPL open-source requirements,
+a commercial license is available. Contact: drmdh@msn.com
+
+The commercial license allows you to:
+- Use the software in proprietary/closed-source projects
+- Modify without publishing your source code
+- Get priority support and SLA
+
+Contact: Dr Hamid MADANI <drmdh@msn.com>

package/README.md

@@ -0,0 +1,63 @@
+# @mostajs/blob-store
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+**Niveau** : N0 (primitif) · **Zéro dépendance**
+
+Ranger des octets. Rien d'autre.
+
+Contrat `StorageDriver` — `put` / `get` / `delete` / `exists` / `stat` / `list` — avec flux,
+métadonnées, `etag`, checksum SHA-256 et création atomique (`ifNotExists`).
+
+## Pourquoi ce module existe
+
+Ce code vivait dans `@mostajs/storage`. Il y était **déjà pur** — aucun import d'ORM, de RBAC
+ni de data-plug — mais **prisonnier** : `@mostajs/storage` déclare `@mostajs/orm`,
+`@mostajs/data-plug` et `@mostajs/config` en dépendances. Importer le seul driver traînait donc
+tout l'ORM derrière. Impossible d'obtenir « juste des octets ».
+
+Extrait ici, il devient une brique réellement réutilisable :
+
+| Consommateur | Ce qu'il en fait |
+|---|---|
+| `@mostajs/storage` | octets **+** métadonnées en base **+** RBAC (ré-exporte d'ici — aucune rupture) |
+| `@mostajs/archive-box` | les octets d'une archive |
+| `@mostajs/backup` | les octets d'une sauvegarde, locale ou externalisée |
+
+Le module ignore délibérément ce que les octets représentent. C'est ce qui le rend malléable.
+
+## Usage
+
+```js
+import { FilesystemDriver, StorageError } from '@mostajs/blob-store';
+
+const driver = new FilesystemDriver({ rootDir: '/var/data/blobs' });
+
+const { size, checksum } = await driver.put(
+  { bucket: 'backups', path: '2026-07-13.zip' },
+  bytes,
+  { mimeType: 'application/zip' },
+);
+
+const obj = await driver.get({ bucket: 'backups', path: '2026-07-13.zip' });
+// obj.stream, obj.size, obj.mimeType, obj.etag
+```
+
+Erreurs **typées** (jamais nues) : `StorageError` avec un `code` (`not_found`, `invalid_path`,
+`access_denied`…) et `STORAGE_ERROR_HTTP` pour le mapping HTTP.
+
+## Pilotes
+
+- **`FilesystemDriver`** — disque local. Sanitise les chemins (le `..` est refusé : un driver
+  de stockage est une surface d'attaque).
+- **`CachingDriver`** — décorateur de cache devant un driver d'origine.
+- **S3** — à venir (voir la feuille de route ; `@mostajs/storage` promettait « FS / S3 » sans
+  jamais livrer S3 : la dette est soldée **ici**, pour que tous les consommateurs en profitent).
+
+## Tests
+
+```bash
+npm test   # 10 tests mjs-unit, sur un VRAI répertoire temporaire
+```
+
+Un test de stockage qui n'écrit rien ne prouve rien : les tests exercent le disque réel, avec
+un vecteur SHA-256 **vérifié indépendamment** (et non recopié depuis le pilote lui-même).

package/dist/driver.d.ts

@@ -0,0 +1,58 @@
+import type { ObjectRef, PutObjectResult } from './types.js';
+/** Source de bytes acceptée par `put` — Buffer, Uint8Array ou Web ReadableStream. */
+export type PutBody = Uint8Array | Buffer | ReadableStream<Uint8Array>;
+export interface PutOptions {
+    /** Type MIME stocké côté driver (ex: en S3 metadata, en xattr FS). */
+    mimeType: string;
+    /** Métadonnées libres (clé/valeur, strings) — propagées au driver. */
+    metadata?: Record<string, string>;
+    /** Taille connue d'avance (utile pour S3 multipart). */
+    size?: number;
+    /** Si true, refuse de remplacer un objet existant (atomic create). */
+    ifNotExists?: boolean;
+}
+export interface GetObjectResult {
+    /** Stream Web standard pour pipeline efficace. */
+    stream: ReadableStream<Uint8Array>;
+    size: number;
+    mimeType: string;
+    etag: string;
+    metadata?: Record<string, string>;
+}
+export interface StatResult {
+    size: number;
+    mimeType: string;
+    etag: string;
+    metadata?: Record<string, string>;
+    /** Date de dernière modification côté driver. */
+    modifiedAt: Date;
+}
+/**
+ * Contrat driver. Tous les chemins sont des paths logiques `<bucket>/<path>` ;
+ * le driver est libre de les traduire (FS = arborescence sur disque, S3 = key).
+ */
+export interface StorageDriver {
+    readonly id: string;
+    put(ref: ObjectRef, body: PutBody, opts: PutOptions): Promise<PutObjectResult>;
+    get(ref: ObjectRef): Promise<GetObjectResult>;
+    delete(ref: ObjectRef): Promise<void>;
+    exists(ref: ObjectRef): Promise<boolean>;
+    stat(ref: ObjectRef): Promise<StatResult>;
+    /**
+     * Liste paginée des objets d'un bucket sous un préfixe donné. Retourne `nextCursor`
+     * si plus de résultats sont disponibles.
+     */
+    list(args: {
+        bucket: string;
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: {
+            path: string;
+            size: number;
+            modifiedAt: Date;
+        }[];
+        nextCursor?: string;
+    }>;
+}

package/dist/driver.js

@@ -0,0 +1,7 @@
+// @mostajs/storage — Driver interface (FS / S3-compat / R2 / B2 / …)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Surface minimale qu'un driver doit implémenter. Volontairement étroite — on garde
+// la même signature pour FS local et S3-compat distant, ce qui permet à l'app cliente
+// de swap d'un backend à l'autre sans changer le code de @mostajs/storage core.
+export {};

package/dist/drivers/caching.d.ts

@@ -0,0 +1,71 @@
+import type { StorageDriver, PutBody, PutOptions, GetObjectResult, StatResult } from '../driver.js';
+import type { ObjectRef, PutObjectResult } from '../types.js';
+/** Traduit un objet en URL d'origine. `null`/`undefined` ⇒ objet purement local (pas d'origine). */
+export interface OriginResolver {
+    (ref: ObjectRef): string | URL | null | undefined;
+}
+export interface CachingDriverConfig {
+    /** Driver de persistance sous-jacent (FilesystemDriver, S3Driver…). */
+    base: StorageDriver;
+    /** Résolution ref → URL d'origine. */
+    origin: OriginResolver;
+    /** Âge max (ms) avant re-pull. 0 = ne périme jamais. Défaut 0. */
+    ttlMs?: number;
+    /** Ne jamais sortir sur le réseau. Défaut false. */
+    offline?: boolean;
+    /** Origine KO + copie présente (même périmée) ⇒ servir la copie. Défaut true. */
+    staleOnError?: boolean;
+    /** MIME par défaut si l'origine n'expose pas de Content-Type exploitable. Défaut 'application/octet-stream'. */
+    defaultMimeType?: string;
+    /** En-têtes ajoutés à chaque requête d'origine (ex. User-Agent conforme à la policy d'origine). */
+    headers?: Record<string, string>;
+    /** Injection de fetch (tests / proxy). Défaut: fetch global. */
+    fetchImpl?: typeof fetch;
+    /** Timeout (ms) d'une requête d'origine. Défaut 15000. */
+    timeoutMs?: number;
+}
+/** État d'une lecture vis-à-vis du cache (exposé via `GetObjectResult.metadata['x-cache']`). */
+export type CacheStatus = 'HIT' | 'MISS' | 'REFRESH' | 'FORCED' | 'STALE-OFFLINE' | 'STALE-FALLBACK' | 'SKIP';
+export declare class CachingDriver implements StorageDriver {
+    readonly id: string;
+    private base;
+    private origin;
+    private ttlMs;
+    private offline;
+    private staleOnError;
+    private defaultMimeType;
+    private headers;
+    private fetchImpl;
+    private timeoutMs;
+    /** Déduplication intra-process des pulls en vol (best-effort). */
+    private inflight;
+    constructor(config: CachingDriverConfig);
+    put(ref: ObjectRef, body: PutBody, opts: PutOptions): Promise<PutObjectResult>;
+    delete(ref: ObjectRef): Promise<void>;
+    exists(ref: ObjectRef): Promise<boolean>;
+    stat(ref: ObjectRef): Promise<StatResult>;
+    list(args: {
+        bucket: string;
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: {
+            path: string;
+            size: number;
+            modifiedAt: Date;
+        }[];
+        nextCursor?: string;
+    }>;
+    get(ref: ObjectRef): Promise<GetObjectResult>;
+    /** Re-pull inconditionnel depuis l'origine + re-store. Sert la « mise à jour forcée ». */
+    refresh(ref: ObjectRef): Promise<PutObjectResult>;
+    /** Garantit présence/fraîcheur sans renvoyer les bytes (warmers / pré-téléchargement en masse). */
+    prefetch(ref: ObjectRef): Promise<CacheStatus>;
+    private statOrNull;
+    /** Pull origine + put base, avec déduplication intra-process des requêtes concomitantes. */
+    private pull;
+    private fetchOrigin;
+    private withStatus;
+    private asStorageError;
+}

package/dist/drivers/caching.js

@@ -0,0 +1,178 @@
+// @mostajs/storage — CachingDriver (cache read-through / origin-pull)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// License: AGPL-3.0-or-later
+//
+// Driver DÉCORATEUR : enrobe n'importe quel `StorageDriver` de base (FS, S3…) et lui
+// ajoute une sémantique de cache read-through sur une ORIGINE HTTP résolue par
+// l'appelant. La persistance reste 100 % déléguée au base (DI, swappable FS→S3) ;
+// la connaissance métier (ce que vaut une URL d'origine) est injectée via `origin`.
+// storage ne dépend donc d'AUCUN domaine appelant.
+//
+// Conception : docs/DESIGN-CACHING-DRIVER.md.
+//
+// Politique de fraîcheur :
+//   - miss        → pull origine + store (MISS)
+//   - périmé/TTL  → re-pull + re-store (REFRESH)
+//   - refresh()   → re-pull inconditionnel (FORCED)
+//   - offline     → jamais de réseau : sert le cache même périmé (STALE-OFFLINE) ou not_found
+//   - staleOnError→ origine KO mais copie présente : sert la copie (STALE-FALLBACK)
+import { StorageError } from '../types.js';
+const refKey = (ref) => `${ref.bucket}/${ref.path}`;
+export class CachingDriver {
+    id;
+    base;
+    origin;
+    ttlMs;
+    offline;
+    staleOnError;
+    defaultMimeType;
+    headers;
+    fetchImpl;
+    timeoutMs;
+    /** Déduplication intra-process des pulls en vol (best-effort). */
+    inflight = new Map();
+    constructor(config) {
+        if (!config?.base)
+            throw new StorageError('driver_error', 'CachingDriver: `base` driver requis');
+        if (typeof config.origin !== 'function')
+            throw new StorageError('driver_error', 'CachingDriver: `origin` resolver requis');
+        this.base = config.base;
+        this.origin = config.origin;
+        this.ttlMs = config.ttlMs ?? 0;
+        this.offline = config.offline ?? false;
+        this.staleOnError = config.staleOnError ?? true;
+        this.defaultMimeType = config.defaultMimeType ?? 'application/octet-stream';
+        this.headers = config.headers ?? {};
+        this.fetchImpl = config.fetchImpl ?? fetch;
+        this.timeoutMs = config.timeoutMs ?? 15_000;
+        this.id = `caching(${this.base.id})`;
+    }
+    // ── Délégation pure au base ────────────────────────────────────────────────
+    put(ref, body, opts) { return this.base.put(ref, body, opts); }
+    delete(ref) { return this.base.delete(ref); }
+    exists(ref) { return this.base.exists(ref); }
+    stat(ref) { return this.base.stat(ref); }
+    list(args) { return this.base.list(args); }
+    // ── Lecture read-through ───────────────────────────────────────────────────
+    async get(ref) {
+        const present = await this.statOrNull(ref);
+        const fresh = present !== null && (this.ttlMs === 0 || (Date.now() - present.modifiedAt.getTime()) < this.ttlMs);
+        // Frais, ou hors-ligne avec une copie : on sert le cache.
+        // En offline on n'a PAS pu vérifier l'origine → toujours STALE-OFFLINE (même si « frais »
+        // par TTL). HIT n'est légitime qu'en ligne ET frais.
+        if (present !== null && (fresh || this.offline)) {
+            return this.withStatus(await this.base.get(ref), (fresh && !this.offline) ? 'HIT' : 'STALE-OFFLINE');
+        }
+        // Hors-ligne sans copie : rien à servir.
+        if (this.offline)
+            throw new StorageError('not_found', `Objet non caché (offline): ${refKey(ref)}`);
+        // En ligne, absent ou périmé → pull origine.
+        const url = this.origin(ref);
+        if (url == null) {
+            if (present !== null)
+                return this.withStatus(await this.base.get(ref), 'STALE-OFFLINE');
+            throw new StorageError('not_found', `Pas d'origine pour ${refKey(ref)}`);
+        }
+        try {
+            await this.pull(ref, url);
+            return this.withStatus(await this.base.get(ref), present !== null ? 'REFRESH' : 'MISS');
+        }
+        catch (e) {
+            if (this.staleOnError && present !== null) {
+                return this.withStatus(await this.base.get(ref), 'STALE-FALLBACK');
+            }
+            throw this.asStorageError(e, ref);
+        }
+    }
+    // ── Hors-contrat : mise à jour & pré-chauffe ───────────────────────────────
+    /** Re-pull inconditionnel depuis l'origine + re-store. Sert la « mise à jour forcée ». */
+    async refresh(ref) {
+        if (this.offline)
+            throw new StorageError('driver_error', `refresh impossible en mode offline: ${refKey(ref)}`);
+        const url = this.origin(ref);
+        if (url == null)
+            throw new StorageError('not_found', `Pas d'origine pour ${refKey(ref)}`);
+        return this.pull(ref, url, /*force*/ true);
+    }
+    /** Garantit présence/fraîcheur sans renvoyer les bytes (warmers / pré-téléchargement en masse). */
+    async prefetch(ref) {
+        const present = await this.statOrNull(ref);
+        const fresh = present !== null && (this.ttlMs === 0 || (Date.now() - present.modifiedAt.getTime()) < this.ttlMs);
+        if (fresh)
+            return 'SKIP';
+        if (this.offline) {
+            if (present !== null)
+                return 'STALE-OFFLINE';
+            throw new StorageError('not_found', `Objet non caché (offline): ${refKey(ref)}`);
+        }
+        const url = this.origin(ref);
+        if (url == null) {
+            if (present !== null)
+                return 'STALE-OFFLINE';
+            throw new StorageError('not_found', `Pas d'origine pour ${refKey(ref)}`);
+        }
+        try {
+            await this.pull(ref, url);
+            return present !== null ? 'REFRESH' : 'MISS';
+        }
+        catch (e) {
+            if (this.staleOnError && present !== null)
+                return 'STALE-FALLBACK';
+            throw this.asStorageError(e, ref);
+        }
+    }
+    // ── Internes ───────────────────────────────────────────────────────────────
+    async statOrNull(ref) {
+        try {
+            return await this.base.stat(ref);
+        }
+        catch (e) {
+            if (e instanceof StorageError && e.code === 'not_found')
+                return null;
+            // exists() en repli si le base lève autrement
+            if (!(await this.base.exists(ref)))
+                return null;
+            throw e;
+        }
+    }
+    /** Pull origine + put base, avec déduplication intra-process des requêtes concomitantes. */
+    pull(ref, url, force = false) {
+        const k = refKey(ref);
+        if (!force) {
+            const running = this.inflight.get(k);
+            if (running)
+                return running;
+        }
+        const job = (async () => {
+            const { bytes, mimeType } = await this.fetchOrigin(url);
+            return this.base.put(ref, bytes, { mimeType });
+        })();
+        this.inflight.set(k, job);
+        return job.finally(() => { if (this.inflight.get(k) === job)
+            this.inflight.delete(k); });
+    }
+    async fetchOrigin(url) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url, { headers: this.headers, signal: ac.signal });
+            if (!res.ok) {
+                throw new StorageError(res.status === 404 ? 'not_found' : 'driver_error', `Origine ${res.status} pour ${url}`, { status: res.status });
+            }
+            const mimeType = (res.headers.get('content-type') || '').split(';')[0].trim() || this.defaultMimeType;
+            const bytes = Buffer.from(await res.arrayBuffer());
+            return { bytes, mimeType };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    withStatus(r, status) {
+        return { ...r, metadata: { ...(r.metadata ?? {}), 'x-cache': status } };
+    }
+    asStorageError(e, ref) {
+        if (e instanceof StorageError)
+            return e;
+        return new StorageError('driver_error', `Pull origine échoué pour ${refKey(ref)}: ${e?.message ?? e}`);
+    }
+}

package/dist/drivers/filesystem.d.ts

@@ -0,0 +1,33 @@
+import type { StorageDriver, PutBody, PutOptions, GetObjectResult, StatResult } from '../driver.js';
+import type { ObjectRef, PutObjectResult } from '../types.js';
+export interface FilesystemDriverConfig {
+    /** Répertoire racine où sont stockés tous les buckets. Doit exister & être writable. */
+    rootDir: string;
+}
+export declare class FilesystemDriver implements StorageDriver {
+    private config;
+    readonly id = "filesystem";
+    private rootResolved;
+    constructor(config: FilesystemDriverConfig);
+    /** Resolve un (bucket, path) en absolute fs path, en garantissant qu'on reste sous rootDir. */
+    private resolveSafe;
+    put(ref: ObjectRef, body: PutBody, opts: PutOptions): Promise<PutObjectResult>;
+    get(ref: ObjectRef): Promise<GetObjectResult>;
+    delete(ref: ObjectRef): Promise<void>;
+    exists(ref: ObjectRef): Promise<boolean>;
+    stat(ref: ObjectRef): Promise<StatResult>;
+    list(args: {
+        bucket: string;
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        items: {
+            path: string;
+            size: number;
+            modifiedAt: Date;
+        }[];
+        nextCursor?: string;
+    }>;
+    private readMeta;
+}

package/dist/drivers/filesystem.js

@@ -0,0 +1,211 @@
+// @mostajs/storage — Filesystem driver (self-host)
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Driver local : `<rootDir>/<bucket>/<path>`. Les métadonnées (mimeType, etag, custom)
+// sont stockées dans un sidecar JSON `<...>.meta.json` à côté du fichier — simple,
+// portable, lisible. Le checksum sha256 est calculé au stream-write (pas de re-read).
+//
+// Sécurité du path :
+//   - Refuse `..` dans bucket ou path → StorageError('invalid_path').
+//   - Refuse les paths absolus côté input.
+//   - Vérifie après resolve que le résultat est sous rootDir (anti symlink escape).
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import { StorageError } from '../types.js';
+const META_SUFFIX = '.meta.json';
+function sanitizeSegment(seg, kind) {
+    if (!seg || seg === '.' || seg === '..') {
+        throw new StorageError('invalid_path', `Empty or dotted ${kind}: '${seg}'`);
+    }
+    if (seg.includes('\0')) {
+        throw new StorageError('invalid_path', `Null byte in ${kind}`);
+    }
+    if (path.isAbsolute(seg)) {
+        throw new StorageError('invalid_path', `${kind} must not be absolute`);
+    }
+    // Empêche tout '..' segment dans le chemin (même au milieu).
+    for (const part of seg.split(/[\\/]/)) {
+        if (part === '..') {
+            throw new StorageError('invalid_path', `${kind} contains traversal '..': '${seg}'`);
+        }
+    }
+    return seg;
+}
+export class FilesystemDriver {
+    config;
+    id = 'filesystem';
+    rootResolved;
+    constructor(config) {
+        this.config = config;
+        this.rootResolved = path.resolve(config.rootDir);
+    }
+    /** Resolve un (bucket, path) en absolute fs path, en garantissant qu'on reste sous rootDir. */
+    resolveSafe(ref) {
+        sanitizeSegment(ref.bucket, 'bucket');
+        sanitizeSegment(ref.path, 'path');
+        const candidate = path.resolve(this.rootResolved, ref.bucket, ref.path);
+        const rel = path.relative(this.rootResolved, candidate);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new StorageError('invalid_path', 'Resolved path escapes rootDir', {
+                rootDir: this.rootResolved,
+                bucket: ref.bucket,
+                path: ref.path,
+            });
+        }
+        return candidate;
+    }
+    async put(ref, body, opts) {
+        const abs = this.resolveSafe(ref);
+        if (opts.ifNotExists && fsSync.existsSync(abs)) {
+            throw new StorageError('access_denied', `Object already exists at ${ref.bucket}/${ref.path}`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        const hash = crypto.createHash('sha256');
+        let size = 0;
+        // Écriture atomique : fichier temporaire .tmp puis rename.
+        const tmpPath = `${abs}.tmp-${process.pid}-${Date.now()}`;
+        const out = fsSync.createWriteStream(tmpPath);
+        const writeBuffer = (chunk) => {
+            hash.update(chunk);
+            size += chunk.byteLength;
+            return new Promise((res, rej) => {
+                out.write(chunk, (err) => (err ? rej(err) : res()));
+            });
+        };
+        try {
+            if (body instanceof Uint8Array || Buffer.isBuffer(body)) {
+                await writeBuffer(body);
+            }
+            else {
+                // Web ReadableStream → async iteration
+                for await (const chunk of body) {
+                    await writeBuffer(chunk);
+                }
+            }
+            await new Promise((res, rej) => out.end((err) => (err ? rej(err) : res())));
+        }
+        catch (e) {
+            await fs.unlink(tmpPath).catch(() => { });
+            throw new StorageError('driver_error', `FS write failed: ${e.message}`);
+        }
+        await fs.rename(tmpPath, abs);
+        const checksum = hash.digest('hex');
+        const etag = checksum.slice(0, 32);
+        // Sidecar metadata
+        const meta = {
+            mimeType: opts.mimeType,
+            etag,
+            checksum,
+            size,
+            metadata: opts.metadata ?? {},
+            modifiedAt: new Date().toISOString(),
+        };
+        await fs.writeFile(abs + META_SUFFIX, JSON.stringify(meta, null, 2), 'utf8');
+        return { ref, size, etag, checksum };
+    }
+    async get(ref) {
+        const abs = this.resolveSafe(ref);
+        const meta = await this.readMeta(abs).catch((e) => {
+            if (e.code === 'ENOENT') {
+                throw new StorageError('not_found', `Object not found: ${ref.bucket}/${ref.path}`);
+            }
+            throw e;
+        });
+        const nodeStream = fsSync.createReadStream(abs);
+        // Conversion Node Readable → Web ReadableStream
+        const stream = Readable.toWeb(nodeStream);
+        return {
+            stream,
+            size: meta.size,
+            mimeType: meta.mimeType,
+            etag: meta.etag,
+            metadata: meta.metadata,
+        };
+    }
+    async delete(ref) {
+        const abs = this.resolveSafe(ref);
+        await fs.unlink(abs).catch((e) => {
+            const code = e.code;
+            if (code === 'ENOENT')
+                return; // idempotent
+            throw new StorageError('driver_error', `FS unlink failed: ${e.message}`);
+        });
+        await fs.unlink(abs + META_SUFFIX).catch(() => { });
+    }
+    async exists(ref) {
+        const abs = this.resolveSafe(ref);
+        try {
+            await fs.access(abs);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stat(ref) {
+        const abs = this.resolveSafe(ref);
+        let st;
+        try {
+            st = await fs.stat(abs);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                throw new StorageError('not_found', `Object not found: ${ref.bucket}/${ref.path}`);
+            }
+            throw e;
+        }
+        const meta = await this.readMeta(abs).catch(() => null);
+        return {
+            size: st.size,
+            mimeType: meta?.mimeType ?? 'application/octet-stream',
+            etag: meta?.etag ?? '',
+            metadata: meta?.metadata,
+            modifiedAt: st.mtime,
+        };
+    }
+    async list(args) {
+        sanitizeSegment(args.bucket, 'bucket');
+        const bucketDir = path.resolve(this.rootResolved, args.bucket);
+        const limit = Math.max(1, Math.min(args.limit ?? 100, 1000));
+        const items = [];
+        async function walk(dir, relPath = '') {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return;
+                throw e;
+            }
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                const full = path.join(dir, entry.name);
+                const rel = relPath ? path.join(relPath, entry.name) : entry.name;
+                if (entry.isDirectory()) {
+                    await walk(full, rel);
+                }
+                else if (entry.isFile() && !entry.name.endsWith(META_SUFFIX)) {
+                    if (args.prefix && !rel.startsWith(args.prefix))
+                        continue;
+                    if (args.cursor && rel <= args.cursor)
+                        continue;
+                    if (items.length >= limit)
+                        return;
+                    const st = await fs.stat(full);
+                    items.push({ path: rel, size: st.size, modifiedAt: st.mtime });
+                }
+            }
+        }
+        await walk(bucketDir);
+        const nextCursor = items.length === limit ? items[items.length - 1].path : undefined;
+        return { items, nextCursor };
+    }
+    async readMeta(abs) {
+        const raw = await fs.readFile(abs + META_SUFFIX, 'utf8');
+        return JSON.parse(raw);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @mostajs/blob-store — Ranger des octets. Rien d'autre.
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * Licence : AGPL-3.0-or-later
+ * Niveau : N0 (primitif) · ZÉRO dépendance
+ *
+ * Contrat `StorageDriver` (put/get/delete/exists/stat/list) + pilotes.
+ *
+ * POURQUOI CE MODULE EXISTE
+ * Ce code vivait dans `@mostajs/storage`. Il y était déjà pur — aucun import d'ORM, de RBAC
+ * ni de data-plug — mais PRISONNIER : `@mostajs/storage` déclare `@mostajs/orm`,
+ * `@mostajs/data-plug` et `@mostajs/config` en dépendances. Importer le seul driver traînait
+ * donc tout l'ORM derrière. Impossible d'obtenir « juste des octets ».
+ *
+ * Extrait ici, il devient une brique réellement réutilisable :
+ *   - `@mostajs/storage`   → octets + métadonnées en base + RBAC   (ré-exporte d'ici)
+ *   - `@mostajs/archive-box` → octets d'une archive
+ *   - `@mostajs/backup`      → octets d'une sauvegarde (locale ou externalisée)
+ *
+ * Le module ignore délibérément ce que les octets représentent. C'est ce qui le rend malléable.
+ */
+export type { ObjectRef, PutObjectResult } from './types.js';
+export { StorageError, STORAGE_ERROR_HTTP } from './types.js';
+export type { StorageDriver, PutBody, PutOptions, GetObjectResult, StatResult, } from './driver.js';
+export { FilesystemDriver } from './drivers/filesystem.js';
+export { CachingDriver } from './drivers/caching.js';
+export declare const moduleInfo: {
+    readonly name: "@mostajs/blob-store";
+    readonly version: "0.1.0";
+    readonly level: "N0";
+};

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @mostajs/blob-store — Ranger des octets. Rien d'autre.
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * Licence : AGPL-3.0-or-later
+ * Niveau : N0 (primitif) · ZÉRO dépendance
+ *
+ * Contrat `StorageDriver` (put/get/delete/exists/stat/list) + pilotes.
+ *
+ * POURQUOI CE MODULE EXISTE
+ * Ce code vivait dans `@mostajs/storage`. Il y était déjà pur — aucun import d'ORM, de RBAC
+ * ni de data-plug — mais PRISONNIER : `@mostajs/storage` déclare `@mostajs/orm`,
+ * `@mostajs/data-plug` et `@mostajs/config` en dépendances. Importer le seul driver traînait
+ * donc tout l'ORM derrière. Impossible d'obtenir « juste des octets ».
+ *
+ * Extrait ici, il devient une brique réellement réutilisable :
+ *   - `@mostajs/storage`   → octets + métadonnées en base + RBAC   (ré-exporte d'ici)
+ *   - `@mostajs/archive-box` → octets d'une archive
+ *   - `@mostajs/backup`      → octets d'une sauvegarde (locale ou externalisée)
+ *
+ * Le module ignore délibérément ce que les octets représentent. C'est ce qui le rend malléable.
+ */
+export { StorageError, STORAGE_ERROR_HTTP } from './types.js';
+export { FilesystemDriver } from './drivers/filesystem.js';
+export { CachingDriver } from './drivers/caching.js';
+export const moduleInfo = { name: '@mostajs/blob-store', version: '0.1.0', level: 'N0' };

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** Pointeur vers un objet stocké. */
+export interface ObjectRef {
+    bucket: string;
+    path: string;
+}
+/** Forme retournée à l'upload : taille + ETag/checksum côté driver. */
+export interface PutObjectResult {
+    ref: ObjectRef;
+    size: number;
+    /** ETag tel que retourné par le driver (FS = sha256 hex tronqué, S3 = vrai ETag). */
+    etag: string;
+    /** sha256 complet hex. Calculé par défaut côté driver FS ; configurable côté S3. */
+    checksum: string;
+}
+/**
+ * Erreur typée du module (jamais nues — facilite le mapping HTTP côté appelant).
+ *
+ * Le nom `StorageError` et la liste complète des codes sont CONSERVÉS tels quels : c'est
+ * ce qui permet à @mostajs/storage de les ré-exporter sans casser un seul consommateur.
+ * Deux codes (`tenant_violation`, `signature_*`) relèvent de la couche au-dessus et non de
+ * l'octet ; les garder ici est le prix — assumé — d'une extraction NON CASSANTE.
+ */
+export declare class StorageError extends Error {
+    code: 'not_found' | 'access_denied' | 'invalid_path' | 'invalid_mime' | 'too_large' | 'tenant_violation' | 'signature_invalid' | 'signature_expired' | 'driver_error';
+    details?: Record<string, unknown> | undefined;
+    constructor(code: 'not_found' | 'access_denied' | 'invalid_path' | 'invalid_mime' | 'too_large' | 'tenant_violation' | 'signature_invalid' | 'signature_expired' | 'driver_error', message: string, details?: Record<string, unknown> | undefined);
+}
+/** Mapping HTTP des codes `StorageError`. */
+export declare const STORAGE_ERROR_HTTP: Record<StorageError['code'], number>;

package/dist/types.js

@@ -0,0 +1,44 @@
+// @mostajs/blob-store — Types niveau OCTET
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+// Licence : AGPL-3.0-or-later
+//
+// EXTRAIT de @mostajs/storage (0.2.0) — types transplantés À L'IDENTIQUE, sans retouche.
+//
+// Ce module ne connaît QUE des octets : ranger, relire, lister, supprimer. Il ignore
+// délibérément ce qu'ils représentent. C'est ce qui le rend réutilisable partout —
+// @mostajs/storage (métadonnées en base + RBAC), @mostajs/archive-box (archives) et
+// @mostajs/backup s'en servent sans qu'aucun n'impose ses dépendances aux autres.
+//
+// NB : `FileMeta` (la row File en base, avec son `accountId` d'isolation multi-tenant)
+// N'EST PAS ici. C'est une métadonnée applicative, pas un octet : elle reste dans
+// @mostajs/storage, avec l'ORM et le RBAC qui vont avec.
+/**
+ * Erreur typée du module (jamais nues — facilite le mapping HTTP côté appelant).
+ *
+ * Le nom `StorageError` et la liste complète des codes sont CONSERVÉS tels quels : c'est
+ * ce qui permet à @mostajs/storage de les ré-exporter sans casser un seul consommateur.
+ * Deux codes (`tenant_violation`, `signature_*`) relèvent de la couche au-dessus et non de
+ * l'octet ; les garder ici est le prix — assumé — d'une extraction NON CASSANTE.
+ */
+export class StorageError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'StorageError';
+    }
+}
+/** Mapping HTTP des codes `StorageError`. */
+export const STORAGE_ERROR_HTTP = {
+    not_found: 404,
+    access_denied: 403,
+    invalid_path: 400,
+    invalid_mime: 415,
+    too_large: 413,
+    tenant_violation: 403,
+    signature_invalid: 401,
+    signature_expired: 410,
+    driver_error: 502,
+};

package/llms.txt

@@ -0,0 +1,35 @@
+# @mostajs/blob-store — 0.1.0
+Auteur : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · Niveau N0 · ZÉRO dépendance
+
+RÔLE
+  Ranger des octets. Contrat StorageDriver + pilotes. Ignore ce que les octets représentent.
+  EXTRAIT de @mostajs/storage (qui le ré-exporte — extraction non cassante, 110/110 tests verts).
+
+API
+  import { FilesystemDriver, CachingDriver, StorageError, STORAGE_ERROR_HTTP } from '@mostajs/blob-store'
+  sous-chemins : /driver · /types · /drivers/filesystem · /drivers/caching
+
+  StorageDriver
+    put(ref, body, opts)  -> { ref, size, etag, checksum }   opts: { mimeType, metadata?, size?, ifNotExists? }
+    get(ref)              -> { stream, size, mimeType, etag, metadata? }
+    delete(ref)           -> void
+    exists(ref)           -> boolean
+    stat(ref)             -> { size, mimeType, etag, metadata? }
+    list({bucket,prefix?,limit?,cursor?}) -> { items: [{path,size,modifiedAt}], nextCursor? }
+
+  ObjectRef        { bucket, path }
+  PutObjectResult  { ref, size, etag, checksum }   checksum = sha256 hex
+  StorageError     code: not_found | access_denied | invalid_path | invalid_mime | too_large
+                       | tenant_violation | signature_invalid | signature_expired | driver_error
+  FilesystemDriver new FilesystemDriver({ rootDir })   — refuse '..' (path traversal)
+  CachingDriver    décorateur de cache devant un driver d'origine
+
+CE QUI N'EST PAS ICI
+  FileMeta (row File en base, accountId multi-tenant) reste dans @mostajs/storage : c'est une
+  métadonnée applicative, pas un octet. La séparation est le point du module.
+
+CONSOMMATEURS
+  @mostajs/storage (octets + ORM + RBAC) · @mostajs/archive-box · @mostajs/backup
+
+TESTS
+  npm test   10 tests mjs-unit sur un vrai répertoire temporaire (sha256 vérifié indépendamment)

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mostajs/blob-store",
+  "version": "0.1.0",
+  "description": "Ranger des octets — contrat StorageDriver (put/get/delete/exists/stat/list) + pilotes filesystem et caching. Primitive N0, zéro dépendance. Extrait de @mostajs/storage.",
+  "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"
+    },
+    "./driver": {
+      "types": "./dist/driver.d.ts",
+      "import": "./dist/driver.js",
+      "default": "./dist/driver.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./drivers/filesystem": {
+      "types": "./dist/drivers/filesystem.d.ts",
+      "import": "./dist/drivers/filesystem.js",
+      "default": "./dist/drivers/filesystem.js"
+    },
+    "./drivers/caching": {
+      "types": "./dist/drivers/caching.d.ts",
+      "import": "./dist/drivers/caching.js",
+      "default": "./dist/drivers/caching.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bash test-scripts/run-tests.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "storage",
+    "object-storage",
+    "blob",
+    "driver",
+    "filesystem",
+    "s3",
+    "zero-dep",
+    "mostajs"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.1",
+    "@types/node": "^20.19.43",
+    "typescript": "^5.6.0"
+  }
+}