create-snapify-app 0.0.0-stage → 1.1.0

package/template/server/modules/marketplace.ts

@@ -0,0 +1,178 @@
+/**
+ * Snapify
+ * © 2026 NOVALABS WEB DESIGN — Tunisie
+ * Contact : contact@novalabs.tn · +216 24 734 647
+ * Tous droits réservés. Toute reproduction, modification ou diffusion sans autorisation écrite est interdite.
+ */
+/**
+ * Catalogue de la marketplace : distant si MARKETPLACE_URL est défini (HTTPS uniquement),
+ * sinon le catalogue local du dossier marketplace/. L'empreinte SHA-256 annoncée par le
+ * catalogue est contrôlée au téléchargement ; l'authenticité repose sur la signature du paquet.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { MODULE_ID_PATTERN, SEMVER_PATTERN } from '../../sdk/index';
+import { MAX_PACKAGE_BYTES, PackageError, sha256 } from '../../sdk/package';
+import type { CatalogEntry } from './types';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LOCAL_DIR = path.resolve(__dirname, '../../marketplace');
+const MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+const CACHE_MS = 5 * 60 * 1000;
+
+export interface Catalog {
+  source: 'local' | 'remote';
+  url?: string;
+  error?: string;
+  modules: CatalogEntry[];
+}
+
+let cached: { at: number; catalog: Catalog } | null = null;
+
+async function fetchLimited(url: URL, maxBytes: number, timeoutMs: number): Promise<Buffer> {
+  if (url.protocol !== 'https:') throw new PackageError('Seules les adresses HTTPS sont acceptées');
+  const res = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new PackageError(`Marketplace indisponible (HTTP ${res.status})`);
+  if (Number(res.headers.get('content-length') || 0) > maxBytes) throw new PackageError('Réponse trop volumineuse');
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length > maxBytes) throw new PackageError('Réponse trop volumineuse');
+  return buf;
+}
+
+function sanitize(raw: unknown): CatalogEntry[] {
+  const list = (raw as { modules?: unknown })?.modules;
+  if (!Array.isArray(list)) throw new PackageError('Catalogue invalide');
+  return list.filter((e): e is CatalogEntry => {
+    const m = e as CatalogEntry;
+    return (
+      !!m &&
+      typeof m.id === 'string' &&
+      MODULE_ID_PATTERN.test(m.id) &&
+      typeof m.version === 'string' &&
+      SEMVER_PATTERN.test(m.version) &&
+      typeof m.name === 'string' &&
+      typeof m.package === 'string' &&
+      /^[a-f0-9]{64}$/.test(m.sha256) &&
+      Array.isArray(m.permissions) &&
+      typeof m.engines?.snapify === 'string' &&
+      (m.kind === undefined || m.kind === 'module' || m.kind === 'theme') &&
+      (m.screenshot === undefined || (typeof m.screenshot === 'string' && m.screenshot.length < 300)) &&
+      (m.gallery === undefined || (Array.isArray(m.gallery) && m.gallery.every((g) => typeof g === 'string' && g.length < 300))) &&
+      (m.priceMillimes === undefined || (typeof m.priceMillimes === 'number' && m.priceMillimes >= 0))
+    );
+  });
+}
+
+const SCREENSHOT_NAME = /^[a-z0-9.-]+\.(jpg|png|webp)$/;
+const GALLERY_FILE = /^[a-z0-9.-]+\.(jpg|png|webp)$/;
+const MODULE_DIR = /^[a-z0-9.-]+$/;
+
+/** URL affichable d'une capture du catalogue : servie localement, ou HTTPS du catalogue distant. */
+export function screenshotUrl(catalog: Catalog, entry: CatalogEntry): string | undefined {
+  if (!entry.screenshot) return undefined;
+  if (catalog.source === 'remote' && catalog.url && !catalog.error) {
+    try {
+      const url = new URL(entry.screenshot, catalog.url);
+      return url.protocol === 'https:' ? url.href : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const name = path.basename(entry.screenshot);
+  return SCREENSHOT_NAME.test(name) ? `/_marketplace/screenshots/${name}` : undefined;
+}
+
+/** URLs des captures galerie (catalogue local ou distant). */
+export function galleryUrls(catalog: Catalog, entry: CatalogEntry): string[] {
+  if (!entry.gallery?.length) return [];
+  return entry.gallery
+    .map((g) => {
+      if (catalog.source === 'remote' && catalog.url && !catalog.error) {
+        try {
+          const url = new URL(g, catalog.url);
+          return url.protocol === 'https:' ? url.href : '';
+        } catch {
+          return '';
+        }
+      }
+      // gallery/<moduleId>/<file>
+      const parts = g.replace(/^\/+/, '').split('/');
+      if (parts[0] !== 'gallery' || parts.length !== 3) return '';
+      const [, moduleId, file] = parts;
+      if (!MODULE_DIR.test(moduleId) || !GALLERY_FILE.test(file)) return '';
+      return `/_marketplace/gallery/${moduleId}/${file}`;
+    })
+    .filter(Boolean);
+}
+
+/** Capture d'écran du catalogue local (`marketplace/screenshots/`). */
+export async function localScreenshot(name: string): Promise<Buffer | null> {
+  if (!SCREENSHOT_NAME.test(name)) return null;
+  return fs.readFile(path.join(LOCAL_DIR, 'screenshots', name)).catch(() => null);
+}
+
+/** Image de galerie locale (`marketplace/gallery/<moduleId>/<file>`). */
+export async function localGalleryImage(moduleId: string, file: string): Promise<Buffer | null> {
+  if (!MODULE_DIR.test(moduleId) || !GALLERY_FILE.test(file)) return null;
+  const abs = path.resolve(LOCAL_DIR, 'gallery', moduleId, file);
+  if (!abs.startsWith(path.join(LOCAL_DIR, 'gallery') + path.sep)) return null;
+  return fs.readFile(abs).catch(() => null);
+}
+
+async function localCatalog(): Promise<CatalogEntry[]> {
+  try {
+    return sanitize(JSON.parse(await fs.readFile(path.join(LOCAL_DIR, 'catalog.json'), 'utf8')));
+  } catch {
+    return [];
+  }
+}
+
+export async function getCatalog(force = false): Promise<Catalog> {
+  if (!force && cached && Date.now() - cached.at < CACHE_MS) return cached.catalog;
+  const remote = process.env.MARKETPLACE_URL?.trim();
+  let catalog: Catalog;
+  if (remote) {
+    try {
+      const buf = await fetchLimited(new URL(remote), MAX_CATALOG_BYTES, 15_000);
+      catalog = { source: 'remote', url: remote, modules: sanitize(JSON.parse(buf.toString('utf8'))) };
+    } catch (e) {
+      catalog = {
+        source: 'local',
+        url: remote,
+        error: `Catalogue distant inaccessible (${e instanceof Error ? e.message : 'erreur'}) : affichage du catalogue local.`,
+        modules: await localCatalog(),
+      };
+    }
+  } else {
+    catalog = { source: 'local', modules: await localCatalog() };
+  }
+  cached = { at: Date.now(), catalog };
+  return catalog;
+}
+
+export async function downloadPackage(id: string): Promise<Buffer> {
+  const catalog = await getCatalog();
+  const entry = catalog.modules.find((m) => m.id === id);
+  if (!entry) throw new PackageError('Élément absent du catalogue');
+  let buf: Buffer;
+  if (catalog.source === 'remote') {
+    buf = await fetchLimited(new URL(entry.package, catalog.url), MAX_PACKAGE_BYTES, 60_000);
+  } else {
+    const file = path.resolve(LOCAL_DIR, entry.package);
+    if (!file.startsWith(LOCAL_DIR + path.sep)) throw new PackageError('Chemin de paquet invalide');
+    buf = await fs.readFile(file);
+  }
+  if (sha256(buf) !== entry.sha256) throw new PackageError('Le paquet téléchargé ne correspond pas à l’empreinte du catalogue');
+  return buf;
+}
+
+/** Paquet du catalogue local (installation initiale des modules officiels, sans réseau). */
+export async function localPackage(id: string): Promise<Buffer | null> {
+  const entry = (await localCatalog()).find((m) => m.id === id);
+  if (!entry) return null;
+  const file = path.resolve(LOCAL_DIR, entry.package);
+  if (!file.startsWith(LOCAL_DIR + path.sep)) return null;
+  const buf = await fs.readFile(file).catch(() => null);
+  return buf && sha256(buf) === entry.sha256 ? buf : null;
+}

package/template/server/modules/outbound.ts

@@ -0,0 +1,178 @@
+/**
+ * Sorties réseau contrôlées pour les modules (`net:outbound`, `net:ftp`).
+ * Anti-SSRF : pas de localhost, IPs privées, metadata cloud, ni ports sensibles.
+ */
+import dns from 'dns/promises';
+import net from 'net';
+import { Client } from 'basic-ftp';
+
+const BLOCKED_PORTS = new Set([22, 23, 25, 445, 3389, 5432, 6379, 11211, 27017]);
+
+function isPrivateIp(ip: string): boolean {
+  if (net.isIPv6(ip)) {
+    const v = ip.toLowerCase();
+    return (
+      v === '::1' ||
+      v.startsWith('fc') ||
+      v.startsWith('fd') ||
+      v.startsWith('fe80') ||
+      v === '::' ||
+      v.startsWith('::ffff:127.') ||
+      v.startsWith('::ffff:10.') ||
+      v.startsWith('::ffff:192.168.') ||
+      /^::ffff:172\.(1[6-9]|2\d|3[0-1])\./.test(v)
+    );
+  }
+  const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(ip);
+  if (!m) return true;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  if (a === 10 || a === 127 || a === 0 || a === 100) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+export async function assertSafeOutboundUrl(raw: string | URL, opts?: { allowHttp?: boolean }): Promise<URL> {
+  let u: URL;
+  try {
+    u = typeof raw === 'string' ? new URL(raw) : raw;
+  } catch {
+    throw new Error('Adresse invalide');
+  }
+  const allowHttp = opts?.allowHttp !== false;
+  if (u.protocol === 'https:') {
+    /* ok */
+  } else if (u.protocol === 'http:' && allowHttp) {
+    /* ok — WordPress legacy */
+  } else {
+    throw new Error('Seules les adresses http(s) publiques sont autorisées');
+  }
+  if (u.username || u.password) throw new Error('Identifiants dans l’URL interdits');
+  const host = u.hostname.toLowerCase();
+  if (!host || host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal')) {
+    throw new Error('Hôte local interdit');
+  }
+  if (net.isIP(host) && isPrivateIp(host)) throw new Error('Adresse IP privée interdite');
+  const port = u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80;
+  if (BLOCKED_PORTS.has(port) || port < 1 || port > 65535) throw new Error('Port non autorisé');
+
+  let records: { address: string }[];
+  try {
+    records = await dns.lookup(host, { all: true, verbatim: true });
+  } catch {
+    throw new Error(`Impossible de résoudre ${host}`);
+  }
+  if (!records.length) throw new Error(`Hôte introuvable : ${host}`);
+  for (const r of records) {
+    if (isPrivateIp(r.address)) throw new Error('La destination résout vers un réseau privé (bloqué)');
+  }
+  return u;
+}
+
+/** Fetch avec redirections limitées, chaque hop re-validé (anti-SSRF). */
+export async function outboundFetch(url: string, init?: RequestInit, maxRedirects = 3): Promise<Response> {
+  let current = await assertSafeOutboundUrl(url);
+  for (let i = 0; i <= maxRedirects; i++) {
+    const res = await fetch(current, {
+      ...init,
+      redirect: 'manual',
+      signal: init?.signal ?? AbortSignal.timeout(12_000),
+    });
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get('location');
+      if (!loc || i === maxRedirects) throw new Error('Trop de redirections');
+      current = await assertSafeOutboundUrl(new URL(loc, current));
+      continue;
+    }
+    return res;
+  }
+  throw new Error('Trop de redirections');
+}
+
+function assertFtpHost(host: string) {
+  const h = host.trim().toLowerCase();
+  if (!h || h === 'localhost' || h.endsWith('.local')) throw new Error('Hôte FTP interdit');
+  if (net.isIP(h) && isPrivateIp(h)) throw new Error('IP FTP privée interdite');
+  return h;
+}
+
+export async function ftpList(opts: {
+  host: string;
+  port?: number;
+  user: string;
+  password: string;
+  secure?: boolean;
+  path?: string;
+}): Promise<string[]> {
+  const host = assertFtpHost(opts.host);
+  if (net.isIP(host)) {
+    /* already checked */
+  } else {
+    const records = await dns.lookup(host, { all: true });
+    for (const r of records) if (isPrivateIp(r.address)) throw new Error('FTP vers réseau privé bloqué');
+  }
+  const client = new Client(30_000);
+  try {
+    await client.access({
+      host,
+      port: opts.port || (opts.secure ? 990 : 21),
+      user: String(opts.user || '').slice(0, 120),
+      password: String(opts.password || '').slice(0, 200),
+      secure: opts.secure ? 'implicit' : false,
+    });
+    const list = await client.list(opts.path || '/');
+    return list.map((f) => f.name).slice(0, 500);
+  } finally {
+    client.close();
+  }
+}
+
+export async function ftpReadText(opts: {
+  host: string;
+  port?: number;
+  user: string;
+  password: string;
+  secure?: boolean;
+  path: string;
+  maxBytes?: number;
+}): Promise<string> {
+  const host = assertFtpHost(opts.host);
+  if (!net.isIP(host)) {
+    const records = await dns.lookup(host, { all: true });
+    for (const r of records) if (isPrivateIp(r.address)) throw new Error('FTP vers réseau privé bloqué');
+  }
+  const remote = String(opts.path || '');
+  if (!remote.startsWith('/') || remote.includes('..')) throw new Error('Chemin FTP invalide');
+  const max = Math.min(Math.max(opts.maxBytes || 2_000_000, 1024), 5_000_000);
+  const client = new Client(30_000);
+  try {
+    await client.access({
+      host,
+      port: opts.port || (opts.secure ? 990 : 21),
+      user: String(opts.user || '').slice(0, 120),
+      password: String(opts.password || '').slice(0, 200),
+      secure: opts.secure ? 'implicit' : false,
+    });
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const { Writable } = await import('stream');
+    const writable = new Writable({
+      write(chunk, _enc, cb) {
+        size += chunk.length;
+        if (size > max) {
+          cb(new Error('Fichier FTP trop volumineux'));
+          return;
+        }
+        chunks.push(Buffer.from(chunk));
+        cb();
+      },
+    });
+    await client.downloadTo(writable, remote);
+    return Buffer.concat(chunks).toString('utf8');
+  } finally {
+    client.close();
+  }
+}

package/template/server/modules/purchases.ts

@@ -0,0 +1,149 @@
+/**
+ * Snapify — achat de modules officiels depuis le backoffice (Flouci + licence)
+ * © 2026 NOVALABS WEB DESIGN — Tunisie
+ */
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import type { LicensePayload, SignedLicense } from '../../sdk/index';
+import { encodeLicenseKey, sign } from '../../sdk/package';
+import { HttpError } from '../http';
+import { generatePayment } from '../platform/flouci';
+import { TRUSTED_KEYS } from './trust';
+import { getCatalog } from './marketplace';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FILE = path.resolve(__dirname, '../../data/module-purchases.json');
+
+export type ModulePurchase = {
+  id: string;
+  moduleId: string;
+  moduleName: string;
+  amountMillimes: number;
+  status: 'pending' | 'paid' | 'failed';
+  paymentId?: string;
+  licenseKey?: string;
+  createdAt: string;
+  paidAt?: string;
+  buyerEmail?: string;
+};
+
+async function load(): Promise<ModulePurchase[]> {
+  try {
+    return JSON.parse(await fs.readFile(FILE, 'utf8')) as ModulePurchase[];
+  } catch {
+    return [];
+  }
+}
+
+async function save(rows: ModulePurchase[]) {
+  await fs.mkdir(path.dirname(FILE), { recursive: true });
+  await fs.writeFile(FILE, JSON.stringify(rows, null, 2));
+}
+
+async function signingKey(): Promise<{ pem: string; kid: string }> {
+  const raw = process.env.SNAPIFY_SIGNING_KEY;
+  const kid = process.env.SNAPIFY_SIGNING_KID || 'novalabs-2026';
+  if (!raw) throw new HttpError(503, 'Signature impossible : SNAPIFY_SIGNING_KEY manquante.');
+  if (!TRUSTED_KEYS[kid]) throw new HttpError(503, `Clé « ${kid} » absente des clés de confiance.`);
+  const file = raw.startsWith('~/') ? path.join(os.homedir(), raw.slice(2)) : raw;
+  return { pem: await fs.readFile(file, 'utf8'), kid };
+}
+
+function issuePaidLicense(moduleId: string, licensee: string, key: { pem: string; kid: string }): SignedLicense {
+  const payload: LicensePayload = {
+    v: 1,
+    licenseId: `paid-${moduleId}-${crypto.randomUUID().slice(0, 8)}`,
+    moduleId,
+    licensee: licensee.slice(0, 120) || 'Acheteur Snapify',
+    plan: 'standard',
+    domains: ['*'],
+    issuedAt: new Date().toISOString(),
+    expiresAt: null,
+  };
+  return { payload, signature: sign(payload, key.pem, key.kid) };
+}
+
+/** Prix catalogue (millimes) — défaut 49 DT si payant sans prix. */
+export function catalogPriceMillimes(entry: { pricing: string; priceMillimes?: number }): number {
+  if (entry.pricing !== 'paid') return 0;
+  const n = Number(entry.priceMillimes);
+  return Number.isFinite(n) && n > 0 ? Math.round(n) : 49_000;
+}
+
+export async function startModuleCheckout(input: {
+  moduleId: string;
+  publicBase: string;
+  buyerEmail?: string;
+}) {
+  const catalog = await getCatalog();
+  const entry = catalog.modules.find((m) => m.id === input.moduleId && (m.kind ?? 'module') === 'module');
+  if (!entry) throw new HttpError(404, 'Module introuvable dans le catalogue');
+  if (entry.pricing !== 'paid') throw new HttpError(400, 'Ce module est gratuit — installez-le directement.');
+
+  const amountMillimes = catalogPriceMillimes(entry);
+  const id = crypto.randomUUID();
+  const trackingId = `module_${id}`;
+  const base = input.publicBase.replace(/\/+$/, '');
+  const successLink = `${base}/administrator/marketplace?purchase=ok&module=${encodeURIComponent(entry.id)}&pid=${id}`;
+  const failLink = `${base}/administrator/marketplace?purchase=fail&module=${encodeURIComponent(entry.id)}`;
+
+  const payment = await generatePayment({
+    amountMillimes,
+    trackingId,
+    successLink,
+    failLink,
+    webhook: `${base}/api/platform/flouci/webhook`,
+  });
+
+  const rows = await load();
+  const purchase: ModulePurchase = {
+    id,
+    moduleId: entry.id,
+    moduleName: entry.name,
+    amountMillimes,
+    status: 'pending',
+    paymentId: payment.paymentId,
+    createdAt: new Date().toISOString(),
+    buyerEmail: input.buyerEmail,
+  };
+  rows.unshift(purchase);
+  await save(rows.slice(0, 500));
+
+  return { purchase, paymentLink: payment.link, paymentId: payment.paymentId };
+}
+
+export async function markModulePurchasePaid(paymentId: string): Promise<ModulePurchase | null> {
+  const rows = await load();
+  let order =
+    rows.find((r) => r.paymentId === paymentId) ||
+    (paymentId.startsWith('mock_module_') ? rows.find((r) => r.id === paymentId.slice('mock_module_'.length)) : null) ||
+    null;
+  if (!order && paymentId.startsWith('mock_')) {
+    const tracking = paymentId.slice(5);
+    if (tracking.startsWith('module_')) order = rows.find((r) => r.id === tracking.slice('module_'.length)) || null;
+  }
+  if (!order) return null;
+  if (order.status === 'paid' && order.licenseKey) return order;
+
+  const key = await signingKey();
+  const license = issuePaidLicense(order.moduleId, order.buyerEmail || order.moduleName, key);
+  order.status = 'paid';
+  order.paidAt = new Date().toISOString();
+  order.licenseKey = encodeLicenseKey(license);
+  if (!order.paymentId) order.paymentId = paymentId;
+  await save(rows);
+  console.log(`[module-purchase] payé : ${order.moduleId} · ${order.id}`);
+  return order;
+}
+
+export async function getModulePurchase(id: string) {
+  return (await load()).find((r) => r.id === id) || null;
+}
+
+export async function latestPaidLicenseForModule(moduleId: string) {
+  const rows = await load();
+  return rows.find((r) => r.moduleId === moduleId && r.status === 'paid' && r.licenseKey) || null;
+}

package/template/server/modules/records.ts

@@ -0,0 +1,168 @@
+/**
+ * Snapify
+ * © 2026 NOVALABS WEB DESIGN — Tunisie
+ * Contact : contact@novalabs.tn · +216 24 734 647
+ * Tous droits réservés. Toute reproduction, modification ou diffusion sans autorisation écrite est interdite.
+ */
+/**
+ * Collections d'enregistrements des modules (`ctx.db.collection()`) : documents JSON dans
+ * `module_records`, isolés par module et par collection. Les filtres sont traduits en SQL
+ * paramétré ; seuls des noms de champs simples sont acceptés.
+ */
+import crypto from 'crypto';
+import { and, eq, inArray, sql, type SQL } from 'drizzle-orm';
+import { db } from '../db/client';
+import { moduleRecords } from '../db/schema';
+import type { Collection, FindQuery, RecordFilter, StoredRecord } from '../../sdk/index';
+
+const COLLECTION_PATTERN = /^[a-z][a-z0-9_-]{0,39}$/;
+const FIELD_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,40}$/;
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_RECORD_BYTES = 256 * 1024;
+const MAX_RECORDS_PER_COLLECTION = 100_000;
+const META = { id: moduleRecords.id, createdAt: moduleRecords.createdAt, updatedAt: moduleRecords.updatedAt } as const;
+
+const ACCENTS_FROM = 'àáâãäåçèéêëìíîïñòóôõöùúûüýÿ';
+const ACCENTS_TO = 'aaaaaaceeeeiiiinooooouuuuyy';
+export const fold = (s: string) => s.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+type Row = typeof moduleRecords.$inferSelect;
+
+function toRecord<T>(row: Row): StoredRecord<T> {
+  return { ...(row.data as T), id: row.id, createdAt: row.createdAt.toISOString(), updatedAt: row.updatedAt.toISOString() };
+}
+
+function fieldExpr(field: string, numeric = false): SQL {
+  if (field in META) return sql`${META[field as keyof typeof META]}`;
+  if (!FIELD_PATTERN.test(field)) throw new Error(`champ invalide : ${field}`);
+  return numeric ? sql`(${moduleRecords.data}->>${field})::numeric` : sql`(${moduleRecords.data}->>${field})`;
+}
+
+function filterSql(f: RecordFilter): SQL {
+  const numeric = typeof f.value === 'number';
+  const col = fieldExpr(f.field, numeric);
+  const v = f.value;
+  switch (f.op) {
+    case 'eq':
+      return f.field in META ? sql`${col} = ${v}` : sql`${moduleRecords.data} @> ${JSON.stringify({ [f.field]: v })}::jsonb`;
+    case 'ne':
+      return sql`(${col} IS DISTINCT FROM ${numeric ? v : String(v)})`;
+    case 'gt':
+      return sql`${col} > ${v}`;
+    case 'gte':
+      return sql`${col} >= ${v}`;
+    case 'lt':
+      return sql`${col} < ${v}`;
+    case 'lte':
+      return sql`${col} <= ${v}`;
+    case 'in': {
+      const list = Array.isArray(v) ? v.slice(0, 500).map(String) : [];
+      if (!list.length) return sql`false`;
+      return sql`${fieldExpr(f.field)} IN (${sql.join(list.map((x) => sql`${x}`), sql`, `)})`;
+    }
+    case 'contains':
+      return sql`${moduleRecords.data} @> ${JSON.stringify({ [f.field]: [v] })}::jsonb`;
+    case 'exists':
+      return v === false ? sql`NOT (${moduleRecords.data} ? ${f.field})` : sql`${moduleRecords.data} ? ${f.field}`;
+    default:
+      throw new Error(`opérateur inconnu : ${String(f.op)}`);
+  }
+}
+
+function whereSql(moduleId: string, collection: string, q: Pick<FindQuery, 'where' | 'filters' | 'search'> = {}): SQL {
+  const parts: SQL[] = [eq(moduleRecords.moduleId, moduleId), eq(moduleRecords.collection, collection)];
+  if (q.where && Object.keys(q.where).length) {
+    for (const k of Object.keys(q.where)) if (!FIELD_PATTERN.test(k)) throw new Error(`champ invalide : ${k}`);
+    parts.push(sql`${moduleRecords.data} @> ${JSON.stringify(q.where)}::jsonb`);
+  }
+  for (const f of q.filters ?? []) parts.push(filterSql(f));
+  const text = q.search?.text ? fold(q.search.text.trim()).slice(0, 100) : '';
+  if (text && q.search?.fields.length) {
+    const like = `%${text.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+    const ors = q.search.fields.slice(0, 10).map((f) => sql`translate(lower(coalesce(${fieldExpr(f)}, '')), ${ACCENTS_FROM}, ${ACCENTS_TO}) LIKE ${like}`);
+    parts.push(sql`(${sql.join(ors, sql` OR `)})`);
+  }
+  return and(...parts)!;
+}
+
+function serialize(data: unknown): Record<string, unknown> {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('un enregistrement doit être un objet');
+  const { id: _id, createdAt: _c, updatedAt: _u, ...rest } = data as Record<string, unknown>;
+  const json = JSON.stringify(rest);
+  if (Buffer.byteLength(json) > MAX_RECORD_BYTES) throw new Error('enregistrement trop volumineux (256 Ko max.)');
+  return JSON.parse(json);
+}
+
+export function createCollection<T>(moduleId: string, name: string): Collection<T> {
+  if (!COLLECTION_PATTERN.test(name)) throw new Error(`[module:${moduleId}] nom de collection invalide : ${name}`);
+  const scope = and(eq(moduleRecords.moduleId, moduleId), eq(moduleRecords.collection, name))!;
+  const byId = (id: string) => and(scope, eq(moduleRecords.id, id))!;
+  const validId = (id: unknown): id is string => typeof id === 'string' && ID_PATTERN.test(id);
+
+  const find: Collection<T>['find'] = async (q = {}) => {
+    const where = whereSql(moduleId, name, q);
+    const limit = Math.min(500, Math.max(1, Math.floor(q.limit ?? 100)));
+    const offset = Math.max(0, Math.floor(q.offset ?? 0));
+    const order = (q.orderBy?.length ? q.orderBy : [{ field: 'createdAt', dir: 'desc' as const }])
+      .slice(0, 3)
+      .map((o) => (o.dir === 'asc' ? sql`${fieldExpr(o.field, o.numeric)} ASC NULLS LAST` : sql`${fieldExpr(o.field, o.numeric)} DESC NULLS LAST`));
+    const [rows, [{ total }]] = await Promise.all([
+      db.select().from(moduleRecords).where(where).orderBy(...order, sql`${moduleRecords.id}`).limit(limit).offset(offset),
+      db.select({ total: sql<number>`count(*)::int` }).from(moduleRecords).where(where),
+    ]);
+    return { items: rows.map((r) => toRecord<T>(r)), total };
+  };
+
+  return {
+    async get(id) {
+      if (!validId(id)) return null;
+      const [row] = await db.select().from(moduleRecords).where(byId(id));
+      return row ? toRecord<T>(row) : null;
+    },
+    async getMany(ids) {
+      const list = [...new Set(ids.filter(validId))].slice(0, 500);
+      if (!list.length) return [];
+      const rows = await db.select().from(moduleRecords).where(and(scope, inArray(moduleRecords.id, list)));
+      const map = new Map(rows.map((r) => [r.id, toRecord<T>(r)]));
+      return list.map((id) => map.get(id)).filter((r): r is StoredRecord<T> => !!r);
+    },
+    find,
+    async findOne(where) {
+      const { items } = await find({ where, limit: 1 });
+      return items[0] ?? null;
+    },
+    async count(q = {}) {
+      const [{ total }] = await db.select({ total: sql<number>`count(*)::int` }).from(moduleRecords).where(whereSql(moduleId, name, q));
+      return total;
+    },
+    async insert(data, opts = {}) {
+      const id = opts.id ?? crypto.randomBytes(9).toString('base64url');
+      if (!validId(id)) throw new Error('identifiant d’enregistrement invalide');
+      const [{ n }] = await db.select({ n: sql<number>`count(*)::int` }).from(moduleRecords).where(scope);
+      if (n >= MAX_RECORDS_PER_COLLECTION) throw new Error(`collection ${name} pleine (${MAX_RECORDS_PER_COLLECTION} enregistrements)`);
+      const now = new Date();
+      const [row] = await db
+        .insert(moduleRecords)
+        .values({ moduleId, collection: name, id, data: serialize(data), createdAt: now, updatedAt: now })
+        .returning();
+      return toRecord<T>(row);
+    },
+    async update(id, patch) {
+      if (!validId(id)) return null;
+      const [current] = await db.select().from(moduleRecords).where(byId(id));
+      if (!current) return null;
+      const data = serialize({ ...(current.data as object), ...(patch as object) });
+      const [row] = await db.update(moduleRecords).set({ data, updatedAt: new Date() }).where(byId(id)).returning();
+      return row ? toRecord<T>(row) : null;
+    },
+    async delete(id) {
+      if (!validId(id)) return false;
+      const rows = await db.delete(moduleRecords).where(byId(id)).returning({ id: moduleRecords.id });
+      return rows.length > 0;
+    },
+  };
+}
+
+export async function deleteModuleRecords(moduleId: string) {
+  await db.delete(moduleRecords).where(eq(moduleRecords.moduleId, moduleId));
+}