@anteros/core 0.0.40 → 0.0.42

package/lib/auditResult.ts

@@ -0,0 +1,133 @@
+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
+        case 'agent.generate':
+        case 'agent.stream':
+        case 'agent.object':
+            // The model's answer is never stored — only the envelope that proves the
+            // run happened and what it cost (nothing the caller did not already send).
+            return result ? {
+                finishReason: result.finishReason ?? null,
+                usage: result.usage ?? null,
+                tools: Array.isArray(result.toolCalls)
+                    ? result.toolCalls.map((call: any) => call?.name).filter(Boolean)
+                    : [],
+                steps: Array.isArray(result.steps) ? result.steps.length : null,
+            } : 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 {
@@ -142,14 +159,54 @@ function Middleware(config: GlobalMiddlewareConfig): GlobalMiddlewareConfig {
 }
 
 import type { WorkflowDefinition } from "../types/workflow";
+import type { AgentConfig, AgentTool, AgentToolDefinition } from "../types/agent";
 
 export function Workflow<TData = any>(workflow: WorkflowDefinition<TData>): WorkflowDefinition<TData> {
     return {
         ...workflow,
+        enabled: workflow.enabled ?? true,
         _isWorkflow_: true,
     }
 }
 
+/**
+ * Declares an LLM agent — `{tenant.dir}/agents/**\/*.agent.ts`.
+ *
+ * `id` and `description` are **required**: the id identifies it (and looks it up),
+ * the description says what it is for — it is served by `info` and read by humans.
+ *
+ * @example
+ * ```ts
+ * export default define.Agent({
+ *   id: 'weather',
+ *   description: 'Answers weather questions with a live forecast.',
+ *   instructions: 'You are a concise weather assistant.',
+ *   provider: { model: 'gpt-4o-mini', compatible: 'openai' },
+ *   tools: { forecast },
+ * })
+ * ```
+ */
+function Agent(config: AgentConfig & { id: string; description: string }): AgentConfig {
+    return {
+        ...config,
+        enabled: config.enabled ?? true,
+        _isAgent_: true,
+    }
+}
+
+/**
+ * Declares an agent tool — `define.Tool({ id, description, inputSchema, execute })`.
+ * The `id` is **required** (it is the name the model calls).
+ * A `define.McpTool` is accepted by an agent as-is.
+ */
+function Tool(tool: AgentToolDefinition): AgentToolDefinition {
+    return {
+        ...tool,
+        enabled: tool.enabled ?? true,
+        _isTool_: true,
+    }
+}
+
 
 
 export const define = {
@@ -167,5 +224,9 @@ export const define = {
   Middleware,
   WebSocket,
   McpTool,
-  McpResource
+  McpResource,
+  Lifecycle,
+  Vars,
+  Agent,
+  Tool,
 }

package/lib/endpoints.ts

@@ -0,0 +1,80 @@
+/**
+ * The URL of everything — one place.
+ *
+ * Every framework surface lives under a **single namespace**, `/api/:tenant_id`,
+ * and a **family** segment says what it is:
+ *
+ * | Surface | Route |
+ * | --- | --- |
+ * | Collections (CRUD, actions, login…) | `POST /api/:tenant_id/collections/:collection/:action` |
+ * | Services | `POST /api/:tenant_id/services/:service/:action` |
+ * | Variables | `POST /api/:tenant_id/vars/:action` |
+ * | Upload | `POST /api/:tenant_id/upload/:collection` |
+ * | Files (serve, delete) | `GET\|DELETE /api/:tenant_id/files/:collection/:file` |
+ * | Agents | `POST /api/:tenant_id/agents/:agent/:action` |
+ * | MCP (tools & resources) | `GET\|POST /api/:tenant_id/mcp` |
+ *
+ * Two reasons for the shape. A tenant's own routes (`routes: { prefix: '/api/v1' }`)
+ * are mounted **before** this one, so they always win — and nothing is ambiguous:
+ * a collection may be called `services` or `login` without ever colliding with the
+ * family segment, since a collection always sits under `/collections/`.
+ *
+ * `patterns` is what the server registers (Hono patterns); `endpoints` is what a
+ * client builds — the two are read together, so a path is never written twice.
+ */
+
+/** The family segments — the component right after the tenant id. */
+const FAMILIES = ["collections", "services", "vars", "upload", "files", "agents", "mcp"] as const;
+
+const patterns = {
+    collection: "/api/:tenant_id/collections/:collection/:action",
+    /** The login action of an auth-enabled collection — its own rate limit. */
+    login: "/api/:tenant_id/collections/:collection/login",
+    service: "/api/:tenant_id/services/:service/:action",
+    vars: "/api/:tenant_id/vars/:action",
+    upload: "/api/:tenant_id/upload/:collection",
+    file: "/api/:tenant_id/files/:collection/:file",
+    agent: "/api/:tenant_id/agents/:agent/:action",
+    mcp: "/api/:tenant_id/mcp",
+} as const;
+
+/** One path segment, encoded. */
+function segment(value: string): string {
+    return encodeURIComponent(String(value));
+}
+
+const endpoints = {
+    /** Everything of a collection — `find`, `insertOne`, `login`, a custom action… */
+    collection: (tenant: string, collection: string, action: string) =>
+        `/api/${segment(tenant)}/collections/${segment(collection)}/${segment(action)}`,
+
+    service: (tenant: string, service: string, action: string) =>
+        `/api/${segment(tenant)}/services/${segment(service)}/${segment(action)}`,
+
+    /** Variables — the namespace and the key travel in the body. */
+    vars: (tenant: string, action: string) =>
+        `/api/${segment(tenant)}/vars/${segment(action)}`,
+
+    upload: (tenant: string, collection: string) =>
+        `/api/${segment(tenant)}/upload/${segment(collection)}`,
+
+    /** One file of a file collection — the document id, or its filename. */
+    file: (tenant: string, collection: string, file: string) =>
+        `/api/${segment(tenant)}/files/${segment(collection)}/${segment(file)}`,
+
+    agent: (tenant: string, agent: string, action: string) =>
+        `/api/${segment(tenant)}/agents/${segment(agent)}/${segment(action)}`,
+
+    mcp: (tenant: string) => `/api/${segment(tenant)}/mcp`,
+} as const;
+
+/**
+ * Is this a segment the framework owns? A tenant route mounted at
+ * `/api/:tenant_id/<family>/…` is registered **first** and would shadow the
+ * framework API silently — the route loader warns about it.
+ */
+function isReservedFamily(name: string): boolean {
+    return (FAMILIES as readonly string[]).includes(name);
+}
+
+export { endpoints, FAMILIES, isReservedFamily, patterns, segment };

package/lib/files.ts

@@ -1,7 +1,11 @@
 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";
+import { endpoints } from "./endpoints";
 import { S3Client } from "bun";
 import type { FileCollection } from "../types/file";
 import path from "path";
@@ -13,6 +17,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 +62,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 +143,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 +152,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 +173,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 +189,7 @@ async function transformImage(
     });
   }
 
-  // Encoder dans le format demandé
+  // Encode in the requested format
   let out: Blob;
   switch (format) {
     case 'jpeg':
@@ -236,6 +244,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 +262,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 +292,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 +302,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 +339,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', {
@@ -341,12 +361,12 @@ export async function handleUpload(options: UploadOptions): Promise<FileResult>
   const { path: filepath, size } = await storage.save(tenant_id, collection, file, { id: _id, mimetype, subpath });
 
   // Update MongoDB with actual file info
-  const url = `/files/${tenant_id}/${collection}/${filename}`;
+  const url = endpoints.file(tenant_id, collection, filename);
   try {
     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 +382,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 +429,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 +450,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 +515,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 +550,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);
   }