@anteros/core 0.0.39 → 0.0.41

package/lib/audit.ts

@@ -0,0 +1,271 @@
+import fs from "fs/promises";
+import path from "path";
+import { cfg } from "../server/config";
+import type { Tenant } from "../types/tenant";
+import { parseDuration } from "../utils/func";
+import { resolveAuditRetention } from "../database/audit";
+
+/**
+ * Local, append-only backup of the audit trail — one JSONL file per day,
+ * rotated on size and pruned by age. Meant for operators who want a copy of
+ * `_audit_` on the same machine as the logs, independent from MongoDB.
+ */
+export type AuditFileOptions = {
+    /** Target directory — default: `<server.logging.dir>/audit` (`.logs/audit`) */
+    dir?: string;
+    /**
+     * Delete files older than this duration (`'30d'`).
+     * `false` → never prune. Omitted → mirrors `audit.retention` when set, else keeps files forever.
+     */
+    retention?: string | false;
+    /** Rotate when the current file exceeds this size in bytes (default: 50MB) */
+    maxSize?: number;
+};
+
+/** `true` → defaults, `string` → directory shorthand, object → full options */
+export type AuditFileConfig = boolean | string | AuditFileOptions;
+
+type ResolvedAuditFile = {
+    dir: string;
+    retentionMs: number | null;
+    maxSize: number;
+};
+
+type Sink = ResolvedAuditFile & {
+    /** Current file ('' until opened) */
+    file: string;
+    /** `YYYY-MM-DD` of the current file */
+    day: string;
+    size: number;
+    pending: string[];
+    writing: boolean;
+    prunedAt: number;
+    inFlight: Promise<void>;
+};
+
+const DEFAULT_MAX_SIZE = 50 * 1024 * 1024; // 50MB
+const PRUNE_INTERVAL_MS = 5 * 60 * 1000; // prune at most every 5 minutes
+const EXT = '.jsonl';
+
+const sinks = new Map<string, Sink>();
+
+/**
+ * Resolve the file backup settings — **the tenant always wins**,
+ * `server.audit.file` is only the fallback. Returns `null` when disabled.
+ */
+function resolveAuditFile(tenant: Tenant): ResolvedAuditFile | null {
+    const raw: AuditFileConfig | undefined = tenant.audit?.file !== undefined
+        ? tenant.audit.file
+        : cfg.server?.audit?.file
+
+    if (raw === undefined || raw === false) return null
+
+    const options: AuditFileOptions = raw === true
+        ? {}
+        : typeof raw === 'string' ? { dir: raw } : raw
+
+    const dir = options.dir ?? path.join(cfg.server?.logging?.dir ?? '.logs', 'audit')
+
+    // Retention: explicit value wins (including `false`), otherwise the local
+    // copy mirrors the database retention so both follow the same policy.
+    const retention = options.retention !== undefined ? options.retention : resolveAuditRetention(tenant)
+    let retentionMs: number | null = null
+    if (retention !== undefined && retention !== false) {
+        const parsed = parseDuration(retention)
+        if (parsed === null) {
+            console.error(`Invalid audit file retention '${retention}' — expected a duration like '30d' or '24h'`)
+        } else {
+            retentionMs = parsed
+        }
+    }
+
+    return { dir, retentionMs, maxSize: options.maxSize ?? DEFAULT_MAX_SIZE }
+}
+
+function prefix(tenantId: string): string {
+    return `audit-${tenantId}`
+}
+
+function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** `JSON.stringify` that never throws (an activity must never break a request) */
+function safeStringify(value: unknown): string {
+    try {
+        return JSON.stringify(value)
+    } catch {
+        return JSON.stringify({ error: 'unserializable activity' })
+    }
+}
+
+function getSink(key: string, resolved: ResolvedAuditFile): Sink {
+    let sink = sinks.get(key)
+    if (!sink) {
+        sink = {
+            ...resolved,
+            file: '',
+            day: '',
+            size: 0,
+            pending: [],
+            writing: false,
+            prunedAt: 0,
+            inFlight: Promise.resolve(),
+        }
+        sinks.set(key, sink)
+    } else {
+        // Options may change between boots / tests — always latest wins
+        sink.dir = resolved.dir
+        sink.retentionMs = resolved.retentionMs
+        sink.maxSize = resolved.maxSize
+    }
+    return sink
+}
+
+/**
+ * Pick the file `day` should be appended to: `audit-<tenant>-<day>.jsonl`,
+ * then `-1`, `-2`… when the size cap is reached.
+ *
+ * Files of the day are scanned in rotation order and the first one with room is
+ * reused — so a restart mid-day keeps appending to the current file, and the cap
+ * is never exceeded (a single line larger than the cap gets its own file).
+ */
+async function openFile(sink: Sink, tenantId: string, day: string, bytes: number): Promise<void> {
+    await fs.mkdir(sink.dir, { recursive: true })
+
+    const base = `${prefix(tenantId)}-${day}`
+    const re = new RegExp(`^${escapeRegex(base)}(?:-(\\d+))?${escapeRegex(EXT)}$`)
+
+    const candidates: { index: number; name: string; size: number }[] = []
+    try {
+        for (const entry of await fs.readdir(sink.dir)) {
+            const match = entry.match(re)
+            if (!match) continue
+            try {
+                candidates.push({
+                    index: Number(match[1] ?? 0),
+                    name: entry,
+                    size: (await fs.stat(path.join(sink.dir, entry))).size,
+                })
+            } catch { /* vanished between readdir and stat */ }
+        }
+    } catch { /* unreadable dir — treated as empty */ }
+
+    candidates.sort((a, b) => a.index - b.index)
+
+    const target = candidates.find((candidate) => candidate.size + bytes <= sink.maxSize)
+    if (target) {
+        sink.file = path.join(sink.dir, target.name)
+        sink.day = day
+        sink.size = target.size
+        return
+    }
+
+    const next = candidates.length ? candidates[candidates.length - 1]!.index + 1 : 0
+    sink.file = path.join(sink.dir, next === 0 ? `${base}${EXT}` : `${base}-${next}${EXT}`)
+    sink.day = day
+    sink.size = 0
+}
+
+/** Delete this tenant's audit files older than `retentionMs` (by mtime). Returns the removed names. */
+async function pruneAuditFiles(dir: string, tenantId: string, retentionMs: number): Promise<string[]> {
+    const removed: string[] = []
+    try {
+        const re = new RegExp(`^${escapeRegex(prefix(tenantId))}-.*${escapeRegex(EXT)}$`)
+        const cutoff = Date.now() - retentionMs
+
+        for (const entry of await fs.readdir(dir)) {
+            if (!re.test(entry)) continue
+            const full = path.join(dir, entry)
+            try {
+                const stat = await fs.stat(full)
+                if (stat.mtimeMs < cutoff) {
+                    await fs.unlink(full)
+                    removed.push(entry)
+                }
+            } catch { /* already gone */ }
+        }
+    } catch { /* dir missing — nothing to prune */ }
+
+    return removed
+}
+
+async function maybePrune(sink: Sink, tenantId: string): Promise<void> {
+    if (sink.retentionMs === null) return
+    if (Date.now() - sink.prunedAt < PRUNE_INTERVAL_MS) return
+    sink.prunedAt = Date.now()
+    const removed = await pruneAuditFiles(sink.dir, tenantId, sink.retentionMs)
+    if (removed.length) {
+        console.log(`🧹 Audit files pruned (${tenantId}): ${removed.length} file(s)`)
+    }
+}
+
+/**
+ * Serialized per tenant: concurrent callers coalesce their lines into a single
+ * append, order is preserved, and lines are never interleaved.
+ */
+async function drain(key: string, tenantId: string): Promise<void> {
+    const sink = sinks.get(key)
+    if (!sink || sink.writing) return
+    sink.writing = true
+
+    try {
+        while (sink.pending.length) {
+            const lines = sink.pending.splice(0)
+            const batch = lines.join('\n') + '\n'
+            const bytes = Buffer.byteLength(batch)
+            const day = new Date().toISOString().slice(0, 10)
+
+            try {
+                if (!sink.file || sink.day !== day || sink.size + bytes > sink.maxSize) {
+                    await openFile(sink, tenantId, day, bytes)
+                }
+                await fs.appendFile(sink.file, batch)
+            } catch (err) {
+                // Keep the lines for the next call instead of losing them
+                sink.pending.unshift(...lines)
+                throw err
+            }
+
+            sink.size += bytes
+            await maybePrune(sink, tenantId)
+        }
+    } catch (err: any) {
+        console.error(`Audit file write failed (${tenantId})`, err?.message)
+    } finally {
+        sink.writing = false
+    }
+}
+
+/**
+ * Append activities to the tenant's local audit file — opt-in, fire-and-forget:
+ * it never blocks the caller and never throws.
+ */
+function writeAuditFile(tenant: Tenant | null | undefined, activities: unknown[]): void {
+    if (!tenant || !activities?.length) return
+
+    const resolved = resolveAuditFile(tenant)
+    if (!resolved) return
+
+    const key = `${tenant.id}:${resolved.dir}`
+    const sink = getSink(key, resolved)
+    for (const activity of activities) sink.pending.push(safeStringify(activity))
+
+    sink.inFlight = drain(key, tenant.id).catch(() => {})
+}
+
+/** Wait until every pending line is on disk (tests, graceful shutdown). */
+async function flushAuditFile(): Promise<void> {
+    for (let i = 0; i < 20; i++) {
+        const current = [...sinks.values()]
+        await Promise.all(current.map((sink) => sink.inFlight.catch(() => {})))
+        if (!current.some((sink) => sink.writing || sink.pending.length)) return
+    }
+}
+
+export {
+    resolveAuditFile,
+    writeAuditFile,
+    flushAuditFile,
+    pruneAuditFiles
+}

package/lib/auditResult.ts

@@ -0,0 +1,120 @@
+import { cfg } from "../server/config";
+
+/**
+ * What an audit entry keeps of an operation's **result** (default: `summary`).
+ *
+ * - `summary` → the **generated identifiers** (`_id` / `insertedIds`), plus the
+ *               operational counters (`matchedCount`, `deletedCount`,
+ *               `nIndexesWas`, …). Never a document.
+ * - `none`    → the identifiers only.
+ * - `full`    → the raw result as returned by the operation (documents included).
+ */
+export type AuditResults = 'none' | 'summary' | 'full'
+
+/** Cap on the identifiers kept for a batch insert — the count stays exact */
+const IDS_MAX = 100
+
+const COUNTER_KEYS = [
+    'acknowledged',
+    'matchedCount',
+    'modifiedCount',
+    'upsertedCount',
+    'upsertedId',
+    'insertedCount',
+    'deletedCount',
+    'insertedIds',
+    'upsertedIds',
+]
+
+// Default state (`results` unset = `summary`) — a sentinel like `undefined`
+// would be indistinguishable from the real, unset configuration.
+let cachedConfig: unknown = undefined
+let cachedMode: AuditResults = 'summary'
+
+function auditResultsMode(): AuditResults {
+    const configured = cfg.server?.audit?.results
+    if (configured !== cachedConfig) {
+        cachedConfig = configured
+        cachedMode = configured === 'full' || configured === 'none' ? configured : 'summary'
+    }
+    return cachedMode
+}
+
+/** Generated identifiers of an operation whose result is a document — never the document */
+function identifiers(action: string, result: any): any {
+    // `insertOne`, `updateOne`, `findOneAndUpdate` and a file `upload` all return
+    // the document (created / updated / resulting) — only its `_id` may enter the trail.
+    if (action === 'insertOne' || action === 'updateOne' || action === 'findOneAndUpdate' || action === 'upload') {
+        return result?._id ? { _id: result._id } : null
+    }
+    if (action === 'insertMany') {
+        const ids = Array.isArray(result)
+            ? result.map((doc) => doc?._id).filter((id) => typeof id === 'string')
+            : []
+        return {
+            count: ids.length,
+            ...(ids.length ? { insertedIds: ids.slice(0, IDS_MAX) } : {}),
+            ...(ids.length > IDS_MAX ? { truncated: true } : {}),
+        }
+    }
+    return null
+}
+
+/** Pick the counter keys actually present in a driver result */
+function counters(result: any): any {
+    const out: any = {}
+    for (const key of COUNTER_KEYS) {
+        if (result?.[key] !== undefined) out[key] = result[key]
+    }
+    return Object.keys(out).length ? out : null
+}
+
+/**
+ * Reduce an operation's result to what the audit trail may store.
+ * `operation.input` already holds the parameters (and, for writes, the change
+ * itself) — the result is only useful as *proof the operation had an effect*.
+ */
+function summarizeAuditResult(action: string, result: any): any {
+    const mode = auditResultsMode()
+    if (mode === 'full') return result ?? null
+    if (result === null || result === undefined) return null
+
+    if (mode === 'none') return identifiers(action, result)
+
+    switch (action) {
+        case 'insertOne':
+        case 'insertMany':
+        case 'updateOne':
+        case 'findOneAndUpdate':
+        case 'upload':
+            // Document-returning operations: identifiers only
+            return identifiers(action, result)
+        case 'updateMany':
+        case 'bulkWrite':
+        case 'bulkUpdate':
+            return counters(result)
+        case 'deleteOne':
+        case 'deleteFile':
+            // `deleteOne` returns the deleted document — keep only "it happened"
+            return { deleted: true }
+        case 'deleteMany':
+            return counters(result)
+        case 'countDocuments':
+            return typeof result === 'number' ? result : null
+        case 'dropCollection':
+            return typeof result === 'boolean' ? result : null
+        case 'dropIndex':
+            return typeof result === 'string' ? result : null
+        case 'dropIndexes':
+            return result?.nIndexesWas !== undefined ? { nIndexesWas: result.nIndexesWas } : null
+        default:
+            // Anything unknown: a document must never be stored.
+            return null
+    }
+}
+
+export {
+    IDS_MAX,
+    auditResultsMode,
+    summarizeAuditResult,
+}

package/lib/define.ts

@@ -8,6 +8,8 @@ import type { Service } from "../types/service";
 import type { WebSocketHandler } from "../types/websocket";
 import type { TenantMiddlewareConfig, GlobalMiddlewareConfig } from "../types/middleware";
 import type { McpTool, McpResource } from "../types/mcp";
+import type { Lifecycle } from "../types/lifecycle";
+import type { VarDefinition } from "../types/vars";
 import { file } from "bun";
 function Server(config: ServerConfig) {
     config.server = {
@@ -100,6 +102,21 @@ function Script(config: Script) {
     }
 }
 
+function Lifecycle(config: Lifecycle): Lifecycle {
+    return {
+        ...config,
+        enabled: config.enabled ?? true,
+        _isLifecycle_: true,
+    }
+}
+
+function Vars(config: VarDefinition): VarDefinition {
+    return {
+        ...config,
+        _isVars_: true,
+    }
+}
+
 
 function Route(route: Route): Route {
     return {
@@ -167,5 +184,7 @@ export const define = {
   Middleware,
   WebSocket,
   McpTool,
-  McpResource
+  McpResource,
+  Lifecycle,
+  Vars
 }

package/lib/files.ts

@@ -1,4 +1,7 @@
 import { getFileCollection } from "../database/file";
+import { getTenant } from "../database/tenant";
+import { writeDeleteMarkers } from "../database/deleteLog";
+import { toBson } from "../utils/func";
 import { useRest } from "../database/rest";
 import { cfg } from "../server/config";
 import { AppError } from "./error";
@@ -13,6 +16,10 @@ import { ObjectId } from "mongodb";
 
 export type FileResult = {
   _id: string;
+  /** ISO string — set on upload */
+  createdAt: string;
+  /** ISO string — refreshed when the metadata is completed */
+  updatedAt: string;
   _file: {
     filename: string;
     name: string;
@@ -54,7 +61,7 @@ export function createDiskStorage(baseDir?: string): FileStorage {
       const filename = `${meta.id}${ext}`;
       const filepath = path.join(dir, filename);
       const buffer = await file.arrayBuffer();
-      // Faille 17: 'wx' — fail if file already exists (no silent overwrite)
+      // Flaw 17: 'wx' — fail if file already exists (no silent overwrite)
       await fs.writeFile(filepath, new Uint8Array(buffer), { flag: 'wx' });
       const outPath = subpath ? `${subpath}/${filename}` : `${tenant_id}/${collection}/${filename}`;
       return { path: outPath, size: buffer.byteLength };
@@ -135,7 +142,7 @@ async function transformImage(
   const format = options.format || 'webp';
   const quality = options.quality ?? 80;
 
-  // Faille 20: validate params (reject NaN / out-of-range)
+  // Flaw 20: validate params (reject NaN / out-of-range)
   if (!Number.isFinite(quality) || quality < 1 || quality > 100) {
     throw new AppError('Invalid quality parameter', { code: 'INVALID_TRANSFORM', status: 400 });
   }
@@ -144,7 +151,7 @@ async function transformImage(
     throw new AppError('Invalid width/height parameter', { code: 'INVALID_TRANSFORM', status: 400 });
   }
 
-  // Convertir ReadableStream en Uint8Array si nécessaire
+  // Convert a ReadableStream to a Uint8Array if needed
   let buffer: Uint8Array;
   if (input instanceof Uint8Array) {
     buffer = input;
@@ -165,13 +172,13 @@ async function transformImage(
     }
   }
 
-  // Faille 20: only transform real images (magic bytes check)
+  // Flaw 20: only transform real images (magic bytes check)
   const detected = detectMimeFromBuffer(buffer);
   if (!detected || !detected.startsWith('image/')) {
     throw new AppError('Not an image file', { code: 'NOT_AN_IMAGE', status: 400 });
   }
 
-  // Utiliser Bun.Image (natif, zéro dépendance)
+  // Use Bun.Image (native, zero dependencies)
   const img = new Bun.Image(buffer);
 
   if (options.width || options.height) {
@@ -181,7 +188,7 @@ async function transformImage(
     });
   }
 
-  // Encoder dans le format demandé
+  // Encode in the requested format
   let out: Blob;
   switch (format) {
     case 'jpeg':
@@ -236,6 +243,7 @@ export function getStorageForCollection(slug: string, tenant_id: string): FileSt
  * Handle a file upload for a given collection.
  */
 export async function handleUpload(options: UploadOptions): Promise<FileResult> {
+  const startedAt = Date.now();
   const { collection, tenant_id, file, data } = options;
 
   const col = getFileCollection(collection, tenant_id);
@@ -253,7 +261,7 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     });
   }
 
-  // Faille 4: validate magic bytes — don't trust client-declared Content-Type
+  // Flaw 4: validate magic bytes — don't trust client-declared Content-Type
   const fullBuffer = new Uint8Array(await file.arrayBuffer());
   const probe = fullBuffer.subarray(0, 4096);
   const detected = detectMimeFromBuffer(probe);
@@ -283,6 +291,9 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     });
   }
 
+  // Timestamps (ISO strings) — stored and returned in the response
+  const now = new Date()
+
   // Insert metadata first to get the MongoDB auto-generated ObjectId
   let _id: string;
   try {
@@ -290,6 +301,8 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     // Form-data / JSON always sends IDs as strings, but MongoDB expects
     // ObjectId for fields that reference other collections.
     const insertDoc: Record<string, any> = {
+      createdAt: now,
+      updatedAt: now,
       _file: {
         filename: '',
         name: file.name,
@@ -325,7 +338,13 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
       }
     }
     const rest = new useRest({ tenant_id, internal: false, useHook: false, useCustomApi: false });
-    const result = await rest.db.collection(collection).insertOne(insertDoc);
+    // Convert the custom fields exactly like a regular collection insert
+    // (ISO date strings → Date, hex ids → ObjectId, …) so file metadata matches
+    // the collections' storage types. `_file` is framework-generated and must
+    // stay untouched (a filename could otherwise look like a date or an ObjectId).
+    const { _file, ...fields } = insertDoc;
+    const stored = { _file, ...toBson<Record<string, any>>(fields, { col } as any) };
+    const result = await rest.db.collection(collection).insertOne(stored as any);
     _id = String(result.insertedId);
   } catch (err) {
     throw new AppError('Failed to save file metadata', {
@@ -346,7 +365,7 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     const rest = new useRest({ tenant_id, internal: true, useHook: false, useCustomApi: false });
     await rest.db.collection(collection).updateOne(
       { _id: new ObjectId(_id) },
-      { $set: { '_file.filename': filename, '_file.size': size, '_file.url': url } },
+      { $set: { '_file.filename': filename, '_file.size': size, '_file.url': url, updatedAt: new Date() } },
     );
   } catch (err) {
     await storage.delete(tenant_id, collection, _id, filename, subpath).catch(() => {});
@@ -362,8 +381,26 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
     });
   }
 
+  // Audit the upload — the file metadata and the generated id, never the stored
+  // document (see the Audit page: parameters only). `internal` is taken from the
+  // request context, so an HTTP upload is logged as such.
+  try {
+    await new useRest({ tenant_id, internal: false, useHook: false, useCustomApi: false }).audit.log({
+      action: 'upload',
+      collection,
+      input: {
+        file: { name: file.name, mimetype, size },
+        fields: Object.keys(data ?? {}),
+      },
+      result: { _id },
+      duration: Date.now() - startedAt,
+    });
+  } catch { /* auditing must never fail an upload */ }
+
   return {
     _id,
+    createdAt: now.toISOString(),
+    updatedAt: now.toISOString(),
     _file: {
       filename,
       name: file.name,
@@ -391,7 +428,7 @@ export async function handleServe(
   const stream = await storage.getStream(tenant_id, collection, fileId, filename, subpath);
   if (!stream) return null;
 
-  // Faille 10: serve the MIME validated at upload time (content-checked),
+  // Flaw 10: serve the MIME validated at upload time (content-checked),
   // not re-derived from the extension.
   let mimetype: string | undefined;
   try {
@@ -412,7 +449,7 @@ export async function handleServe(
     return { stream: new ReadableStream({ start(controller) { controller.enqueue(data); controller.close(); } }), mimetype: newMime, size: data.length };
   }
 
-  // Faille 4: SVG is served as an attachment (never inline) to prevent stored XSS
+  // Flaw 4: SVG is served as an attachment (never inline) to prevent stored XSS
   if (isSvg) {
     return { stream, mimetype, attachment: true };
   }
@@ -477,6 +514,7 @@ export async function handleDelete(
   collection: string,
   fileId: string,
 ): Promise<void> {
+  const startedAt = Date.now();
   const storage = getStorageForCollection(collection, tenant_id);
   const col = getFileCollection(collection, tenant_id);
   const subpath = col?.storage?.path || undefined;
@@ -511,6 +549,21 @@ export async function handleDelete(
     await rest.db.collection(collection).deleteOne({
       _id: (ObjectId.isValid(fileId) ? new ObjectId(fileId) : fileId) as any,
     });
+    // This path bypasses the collection hooks — record a tombstone explicitly so the
+    // deletion propagates when the file collection opted into replication.
+    if (col?.replication?.enabled) {
+      const db = getTenant(tenant_id)?.database?.db;
+      if (db) await writeDeleteMarkers(db, tenant_id, collection, [fileId]);
+    }
+    // Audited like any other delete: the id and the stored filename, nothing else.
+    // (`internal` is taken from the request context, so an HTTP call is logged as such.)
+    await rest.audit.log({
+      action: 'deleteFile',
+      collection,
+      input: { id: fileId, filename },
+      result: { deleted: true },
+      duration: Date.now() - startedAt,
+    });
   } catch (err: any) {
     console.error('Failed to delete file metadata:', err?.message || err);
   }