@anteros/core 0.0.40 → 0.0.42

package/database/mongodbadapter.ts

@@ -1,6 +1,20 @@
 
 import type { Tenant } from "../types/tenant";
 import type { MongoClientOptions, Db, ClientSession, UpdateOptions, UpdateFilter, Document, DeleteResult, ChangeStreamOptions, ChangeStream, ChangeStreamDocument, AnyBulkWriteOperation, BulkWriteOptions, BulkWriteResult, UpdateResult } from "mongodb";
+
+/**
+ * Is a process still running **on this host**? `EPERM` means it exists but belongs
+ * to another user — which still counts as alive.
+ */
+function isProcessAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err: any) {
+        return err?.code === 'EPERM';
+    }
+}
 import { MongoClient, ObjectId, AggregationCursor } from "mongodb";
 import type { FindOptions, findOneOptions } from "../types/mongo";
 import type { FindCallOptions } from "../types/mongo";
@@ -11,6 +25,10 @@ import { AppError, fn } from "../lib/error";
 import { createWorkflow } from "./workflow";
 import { getTenant } from "./tenant";
 import { getCollection, getCollectionKeys } from "./collection"
+import { AUDIT_COLLECTION } from "./audit"
+import { writeAuditFile } from "../lib/audit"
+import { redactPayload } from "../lib/redact"
+import { summarizeAuditResult } from "../lib/auditResult"
 import { encryptFields, encryptUpdate } from "./field.crypto"
 import type { RestActions, BulkUpdateOperation, RestOptions, CursorOptions, TenantCache } from "../types/rest";
 import type Joi from "joi";
@@ -22,6 +40,10 @@ import * as os from 'node:os';
 import { cfg } from '../server/config';
 import { io } from '../server/io';
 import type { Service } from '../types/service';
+import { createVars } from "./vars";
+import type { TenantVars } from "../types/vars";
+import { createAgents } from "../lib/agents";
+import { createApi } from "../lib/api";
 
 class MongoRest {
     client!: MongoClient;
@@ -126,7 +148,7 @@ class MongoRest {
                     validationResult = partialSchema.validate(options.update.$setOnInsert, { allowUnknown: false })
                 }
 
-                // Faille 9: updateOne/updateMany — unflatten dot-notation ("address.zip") before Joi validation
+                // Flaw 9: updateOne/updateMany — unflatten dot-notation ("address.zip") before Joi validation
                 if ((options.action == 'updateOne' || options.action == 'updateMany') && options.update?.$set) {
                     const unflattened = func.unflattenKeys(options.update.$set)
                     validationResult = partialSchema.validate(unflattened, { allowUnknown: false })
@@ -157,6 +179,15 @@ class MongoRest {
         return options.data;
     }
 
+    /**
+     * Context handed to a collection hook. `agents` is the tenant-scoped registry,
+     * bound to `this` — so a hook runs an agent exactly like it reads a collection:
+     * `await agents.get('support')?.generate(...)`.
+     */
+    #hookCtx(action: any, meta: any) {
+        return { rest: this, io, action, meta, agents: createAgents(this.tenant_id, this), api: createApi(this) };
+    }
+
     async #logActivity(data: {
         action: string,
         collection: string,
@@ -185,10 +216,14 @@ class MongoRest {
             core_version: cfg.version ?? restMeta?.core_version,
         }
 
-        // Determine collection type
-        const colMeta = cfg.collections?.find(c => c.slug === data.collection && c._tenant_ === this.tenant_id)
-            ?? cfg.fileCollections?.find(c => c.slug === data.collection && c._tenant_ === this.tenant_id)
-        const collectionType = colMeta && 'type' in colMeta ? colMeta.type : colMeta ? 'file' : undefined
+        // Determine collection type — a file collection is 'file'; a declared
+        // document collection is 'document' unless it explicitly declares a
+        // `type`. Never inferred from the absence of a declaration.
+        const fileCol = cfg.fileCollections?.find(c => c.slug === data.collection && c._tenant_ === this.tenant_id)
+        const docCol = cfg.collections?.find(c => c.slug === data.collection && c._tenant_ === this.tenant_id)
+        const collectionType: ActivityInput['operation']['collectionType'] = fileCol
+            ? 'file'
+            : docCol ? (docCol.type ?? 'document') : undefined
 
         const activity: ActivityInput = {
             internal: requestCtxStorage.get<boolean>('internal') ?? this.#internal,
@@ -202,7 +237,7 @@ class MongoRest {
                 collectionType,
                 status: data.error ? 'error' : 'success',
                 input: data.input,
-                result: data.result,
+                result: summarizeAuditResult(data.action, data.result),
                 error: data.error ?? null,
                 duration: data.duration,
                 transaction: this.session?.inTransaction?.() ?? false,
@@ -219,13 +254,49 @@ class MongoRest {
         collection: string,
         input: any,
         fn: () => Promise<T>,
-        options?: { invalidate?: boolean | string[] }
+        options?: {
+            invalidate?: boolean | string[]
+            /**
+             * `false` → the result is **not** stored in the audit entry
+             * (`operation.result` stays `null`). Used by reads and custom actions,
+             * whose payload is arbitrary, potentially huge or sensitive — the trail
+             * records *who did what, with which parameters, when*.
+             * Default: `true`.
+             */
+            includeResult?: boolean
+            /**
+             * `false` → on error, log it and rethrow the **original** error as-is.
+             * Default: `true` (non-`AppError` errors are wrapped in `INTERNAL_API_ERROR`).
+             */
+            wrapErrors?: boolean
+            /**
+             * `true` (default) → the audit entry is written **before** the operation
+             * returns, so a successful mutation can never lose its trace. Reads pass
+             * `false` to avoid an extra round-trip.
+             */
+            awaitAudit?: boolean
+        }
     ): Promise<T> {
         const start = Date.now()
+        const includeResult = options?.includeResult ?? true
+        const wrapErrors = options?.wrapErrors ?? true
+        const awaitAudit = options?.awaitAudit ?? true
+        const log = async (entry: {
+            action: string
+            collection: string
+            input?: any
+            result?: any
+            error?: { message: string; code: string }
+            duration: number
+        }) => {
+            const promise = this.#logActivity(entry)
+            if (awaitAudit) await promise
+            else promise.catch(() => { })
+        }
         try {
             const result = await fn()
             const duration = Date.now() - start
-            this.#logActivity({ action, collection, input, result, duration })
+            await log({ action, collection, input, result: includeResult ? result : null, duration })
             // Writes invalidate the collection's query cache (and its $include dependents).
             // An array of ids = targeted invalidation (only queries containing those ids),
             // `true` = clear the whole collection namespace.
@@ -235,7 +306,8 @@ class MongoRest {
             return result
         } catch (err: any) {
             const duration = Date.now() - start
-            this.#logActivity({ action, collection, input, error: { message: err?.message, code: err?.code || 'INTERNAL_API_ERROR' }, duration })
+            await log({ action, collection, input, result: null, error: { message: err?.message, code: err?.code || 'INTERNAL_API_ERROR' }, duration })
+            if (!wrapErrors) throw err
             throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
         }
     }
@@ -245,6 +317,24 @@ class MongoRest {
         return dbInvalidate(collection, this.tenant_id, ids)
     }
 
+    /**
+     * Audit a read operation — `find`, `findOne`, `aggregate`.
+     *
+     * Reads are logged with their **parameters only** (filters, pipeline, options):
+     * `operation.result` is always `null`. What a query returned is huge, redundant
+     * with the collection itself, and often a privacy leak — the audit trail answers
+     * "who read what, with which filter, when", not "what did they see".
+     */
+    async #executeReadWithAudit<T>(
+        action: string,
+        collection: string,
+        input: any,
+        fn: () => Promise<T>
+    ): Promise<T> {
+        // Reads stay fire-and-forget: they must not pay for an extra round-trip
+        return this.#executeWithAudit(action, collection, input, fn, { includeResult: false, awaitAudit: false })
+    }
+
     async connect(options?: {
         uri?: string;
         options?: MongoClientOptions;
@@ -271,60 +361,64 @@ class MongoRest {
 
     @CheckIfCollectionExists()
     async watch(collection: string, pipeline: any[], options: ChangeStreamOptions): Promise<ChangeStream> {
-        const col = getCollection(collection, this.#tenant.id) as Collection
-        const isSafe = func.isSafeAggregatePipeline(pipeline);
-        if (!isSafe.isSafe) {
-            throw isSafe.error;
-        }
-        pipeline = await func.buildInput(pipeline)
-        pipeline = func.toBson(pipeline, { col })
-        return await this.db.collection(collection).watch(pipeline, {
-            allowDiskUse: true,
-            session: this.session,
-            ...options
-        })
+        // Audited with the parameters only — the change stream itself is a live object
+        return this.#executeWithAudit('watch', collection, { pipeline, options }, async () => {
+            const col = getCollection(collection, this.#tenant.id) as Collection
+            const isSafe = func.isSafeAggregatePipeline(pipeline);
+            if (!isSafe.isSafe) {
+                throw isSafe.error;
+            }
+            pipeline = await func.buildInput(pipeline)
+            pipeline = func.toBson(pipeline, { col })
+            return await this.db.collection(collection).watch(pipeline, {
+                allowDiskUse: true,
+                session: this.session,
+                ...options
+            })
+        }, { includeResult: false, awaitAudit: false })
     }
 
     @LogSlowQuery()
     @CheckIfCollectionExists()
     async aggregate(collection: string, pipeline: any[]): Promise<Document[]> {
         const action = 'aggregate' as ActionsApiList
-        try {
-
-            const col = getCollection(collection, this.#tenant.id) as Collection
-            // Faille 12: restrict $lookup targets to this tenant's declared collections
-            const allowedCollections = [
-                ...(cfg.collections ?? [])
-                    .filter(c => c._tenant_ === this.tenant_id)
-                    .map(c => c.slug),
-                ...(cfg.fileCollections ?? [])
-                    .filter(fc => fc._tenant_ === this.tenant_id)
-                    .map(fc => fc.slug),
-                '_activities_', '_locks_', '_workflows_',
-            ];
-            const isSafe = func.isSafeAggregatePipeline(pipeline, allowedCollections);
-            if (!isSafe.isSafe) {
-                throw isSafe.error;
-            }
-            pipeline = func.toBson(pipeline, { col })
-            const meta: any = { action, collection, pipeline }
-            if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
-            }
+        return this.#executeReadWithAudit(action, collection, { pipeline }, async () => {
+            try {
+                const col = getCollection(collection, this.#tenant.id) as Collection
+                // Flaw 12: restrict $lookup targets to this tenant's declared collections
+                const allowedCollections = [
+                    ...(cfg.collections ?? [])
+                        .filter(c => c._tenant_ === this.tenant_id)
+                        .map(c => c.slug),
+                    ...(cfg.fileCollections ?? [])
+                        .filter(fc => fc._tenant_ === this.tenant_id)
+                        .map(fc => fc.slug),
+                    AUDIT_COLLECTION, '_locks_', '_workflows_',
+                ];
+                const isSafe = func.isSafeAggregatePipeline(pipeline, allowedCollections);
+                if (!isSafe.isSafe) {
+                    throw isSafe.error;
+                }
+                pipeline = func.toBson(pipeline, { col })
+                const meta: any = { action, collection, pipeline }
+                if (col.hooks?.beforeOperation) {
+                    await col.hooks.beforeOperation(this.#hookCtx(action, meta))
+                }
 
-            let result = await this.db.collection(collection).aggregate(pipeline, {
-                session: this.session,
-                allowDiskUse: true,
-            }).toArray()
-            result = func.toJson(result)
-            meta.result = result
+                let result = await this.db.collection(collection).aggregate(pipeline, {
+                    session: this.session,
+                    allowDiskUse: true,
+                }).toArray()
+                result = func.toJson(result)
+                meta.result = result
 
-            await col.hooks?.afterOperation?.({ rest: this, io, action, meta })
+                await col.hooks?.afterOperation?.(this.#hookCtx(action, meta))
 
-            return result as any[]
-        } catch (err: any) {
-            throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
-        }
+                return result as any[]
+            } catch (err: any) {
+                throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
+            }
+        })
     }
 
     /**
@@ -359,6 +453,10 @@ class MongoRest {
      */
     @CheckIfCollectionExists()
     async *findStream<T = any>(collection: string, params: FindOptions = {}, options: CursorOptions = {}): AsyncGenerator<any> {
+        // The entry is written when the stream ends (completion, error, or early
+        // `break`/`return()` — which triggers the `finally` below). Parameters only.
+        const start = Date.now();
+        let failure: any = null;
         const pageSize = options.pageSize;
         // Page mode counts by default (opt-out with withCount: false); per-doc mode counts only when withCount: true
         const withCount = pageSize ? options.withCount !== false : options.withCount === true;
@@ -410,7 +508,18 @@ class MongoRest {
                     }
                 }
             }
+        } catch (err: any) {
+            failure = err
+            throw err
         } finally {
+            this.#logActivity({
+                action: 'findStream',
+                collection,
+                input: { params, options },
+                result: null,
+                error: failure ? { message: failure?.message, code: failure?.code || 'INTERNAL_API_ERROR' } : undefined,
+                duration: Date.now() - start,
+            })
             await cursor.close().catch(() => {})
         }
     }
@@ -427,11 +536,15 @@ class MongoRest {
      */
     @CheckIfCollectionExists()
     async *aggregateStream<T = any>(collection: string, pipeline: any[] = [], options: CursorOptions = {}): AsyncGenerator<any> {
+        // The entry is written when the stream ends (completion, error, or early
+        // `break`/`return()` — which triggers the `finally` below). Parameters only.
+        const start = Date.now();
+        let failure: any = null;
         const col = getCollection(collection, this.#tenant.id) as Collection
         const allowedCollections = [
             ...(cfg.collections ?? []).filter((c) => c._tenant_ === this.tenant_id).map((c) => c.slug),
             ...(cfg.fileCollections ?? []).filter((fc) => fc._tenant_ === this.tenant_id).map((fc) => fc.slug),
-            '_activities_', '_locks_', '_workflows_',
+            AUDIT_COLLECTION, '_locks_', '_workflows_',
         ];
         const isSafe = func.isSafeAggregatePipeline(pipeline, allowedCollections);
         if (!isSafe.isSafe) {
@@ -466,7 +579,18 @@ class MongoRest {
                     yield value
                 }
             }
+        } catch (err: any) {
+            failure = err
+            throw err
         } finally {
+            this.#logActivity({
+                action: 'aggregateStream',
+                collection,
+                input: { pipeline, options },
+                result: null,
+                error: failure ? { message: failure?.message, code: failure?.code || 'INTERNAL_API_ERROR' } : undefined,
+                duration: Date.now() - start,
+            })
             await cursor.close().catch(() => {})
         }
     }
@@ -475,77 +599,81 @@ class MongoRest {
     @CheckIfCollectionExists()
     async find(collection: string, params: FindOptions = {}, options: FindCallOptions = {}): Promise<Document[]> {
         const action = 'find' as ActionsApiList
-        try {
-            // Real query — hooks + pipeline + toArray
-            const run = async (): Promise<Document[]> => {
-                const col = getCollection(collection, this.#tenant.id) as Collection
-                let pipeline = func.buildPipeline(params, { col: col })
-                pipeline = await func.buildInput(pipeline, { rest: this })
-                pipeline = func.toBson(pipeline, { col })
+        return this.#executeReadWithAudit(action, collection, { params, options }, async () => {
+            try {
+                // Real query — hooks + pipeline + toArray
+                const run = async (): Promise<Document[]> => {
+                    const col = getCollection(collection, this.#tenant.id) as Collection
+                    let pipeline = func.buildPipeline(params, { col: col })
+                    pipeline = await func.buildInput(pipeline, { rest: this })
+                    pipeline = func.toBson(pipeline, { col })
+
+                    const meta: any = { action, collection, params, options }
+                    if (col.hooks?.beforeOperation) {
+                        await col.hooks.beforeOperation(this.#hookCtx(action, meta))
+                    }
 
-                const meta: any = { action, collection, params, options }
-                if (col.hooks?.beforeOperation) {
-                    await col.hooks.beforeOperation({ rest: this, io, action, meta })
-                }
+                    let result = await this.db.collection(collection).aggregate(pipeline, {
+                        session: this.session,
+                        allowDiskUse: true
+                    }).toArray()
+                    result = func.toJson(result)
+                    meta.result = result
 
-                let result = await this.db.collection(collection).aggregate(pipeline, {
-                    session: this.session,
-                    allowDiskUse: true
-                }).toArray()
-                result = func.toJson(result)
-                meta.result = result
+                    if (col.hooks?.afterOperation) {
+                        await col.hooks.afterOperation(this.#hookCtx(action, meta))
+                    }
 
-                if (col.hooks?.afterOperation) {
-                    await col.hooks.afterOperation({ rest: this, io, action, meta })
+                    return result as any[]
                 }
 
-                return result as any[]
-            }
-
-            // Cache-first when `useCache: true` — served from the query cache, populated on miss
-            if (options.useCache === true) {
-                return await dbGetOrSet(collection, this.tenant_id, params, options, run)
+                // Cache-first when `useCache: true` — served from the query cache, populated on miss
+                if (options.useCache === true) {
+                    return await dbGetOrSet(collection, this.tenant_id, params, options, run)
+                }
+                return await run()
+            } catch (err: any) {
+                throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
             }
-            return await run()
-        } catch (err: any) {
-            throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
-        }
+        })
     }
 
     @LogSlowQuery()
     @CheckIfCollectionExists()
     async findOne(collection: string, _id: string, params?: findOneOptions): Promise<any> {
         const action = 'findOne' as ActionsApiList
-        try {
-            const col = getCollection(collection, this.#tenant.id) as Collection
-            let pipeline = func.buildPipeline({
-                ...params,
-                $match: { _id },
-                $limit: 1
-            }, { col: col })
-            pipeline = await func.buildInput(pipeline, { rest: this })
-            pipeline = func.toBson(pipeline, { col })
+        return this.#executeReadWithAudit(action, collection, { id: _id, params }, async () => {
+            try {
+                const col = getCollection(collection, this.#tenant.id) as Collection
+                let pipeline = func.buildPipeline({
+                    ...params,
+                    $match: { _id },
+                    $limit: 1
+                }, { col: col })
+                pipeline = await func.buildInput(pipeline, { rest: this })
+                pipeline = func.toBson(pipeline, { col })
 
-            const meta: any = { action, collection, params, id: _id }
-            if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
-            }
+                const meta: any = { action, collection, params, id: _id }
+                if (col.hooks?.beforeOperation) {
+                    await col.hooks.beforeOperation(this.#hookCtx(action, meta))
+                }
 
-            let result = (await this.db.collection(collection).aggregate(pipeline, {
-                session: this.session,
-                allowDiskUse: true
-            }).toArray()).at(0) ?? null
-            result = func.toJson(result)
-            meta.result = result
+                let result = (await this.db.collection(collection).aggregate(pipeline, {
+                    session: this.session,
+                    allowDiskUse: true
+                }).toArray()).at(0) ?? null
+                result = func.toJson(result)
+                meta.result = result
 
-            if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
-            }
+                if (col.hooks?.afterOperation) {
+                    await col.hooks.afterOperation(this.#hookCtx(action, meta))
+                }
 
-            return result
-        } catch (err: any) {
-            throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
-        }
+                return result
+            } catch (err: any) {
+                throw err instanceof AppError ? err : new AppError(err?.message || 'Internal server error', { code: 'INTERNAL_API_ERROR', status: 500 })
+            }
+        })
     }
 
     @LogSlowQuery()
@@ -562,7 +690,7 @@ class MongoRest {
 
             const meta: any = { action, collection, data }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
             meta.data = this._validate({ collection, action: action, data: meta.data })
@@ -578,7 +706,7 @@ class MongoRest {
             const result: T & { _id: string } = { ...func.toJson(meta.data as any), _id: (inserted.insertedId as ObjectId).toHexString() }
             meta.result = result
             if (col?.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -605,7 +733,7 @@ class MongoRest {
 
             const meta: any = { action, collection, data: dataInput }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
             meta.data = this._validate({ collection, action: action, data: meta.data })
@@ -624,7 +752,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as (T & { _id: string })[]
@@ -651,7 +779,7 @@ class MongoRest {
 
             const meta: any = { action, collection, update, id: _id }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const data = await this.db.collection(collection).findOneAndUpdate(
@@ -664,7 +792,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -718,7 +846,7 @@ class MongoRest {
 
             const meta: any = { action, collection, filter, update }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const data = await this.db.collection(collection).findOneAndUpdate(
@@ -734,7 +862,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as Document | null
@@ -760,7 +888,7 @@ class MongoRest {
 
             const meta: any = { action, collection, update, ids: _ids }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const result = await this.db.collection(collection).updateMany(
@@ -771,7 +899,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as UpdateResult
@@ -788,7 +916,7 @@ class MongoRest {
 
             const meta: any = { action, collection, id: _id }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             let result = await this.db.collection(collection).findOneAndDelete(
@@ -799,7 +927,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -817,7 +945,7 @@ class MongoRest {
 
             const meta: any = { action, collection, ids: _ids }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             let result: DeleteResult = await this.db.collection(collection).deleteMany(
@@ -828,7 +956,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -973,49 +1101,64 @@ class MongoRest {
     }
 
     async runAction<T = any>(collection: string, action: string, data?: any): Promise<T> {
-        const col = getCollection(collection, this.#tenant.id)
-        if (!col) {
-            throw new AppError(`Collection '${collection}' not found`, { code: 'COLLECTION_NOT_FOUND', status: 500 })
-        }
-
-        if (!Object.hasOwn(col?.actions ?? {}, action)) {
-            throw new AppError(`Action '${action}' not found on collection '${collection}'`, { code: 'ACTION_NOT_FOUND', status: 500 })
-        }
+        // Audited like any other operation: the custom action **name** and its
+        // `data` are recorded, the returned payload never is (`includeResult: false`).
+        // `wrapErrors: false` — a custom action's own error must reach the caller unchanged.
+        return this.#executeWithAudit('runAction', collection, { action, data }, async () => {
+            const col = getCollection(collection, this.#tenant.id)
+            if (!col) {
+                throw new AppError(`Collection '${collection}' not found`, { code: 'COLLECTION_NOT_FOUND', status: 500 })
+            }
 
-        const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
+            if (!Object.hasOwn(col?.actions ?? {}, action)) {
+                throw new AppError(`Action '${action}' not found on collection '${collection}'`, { code: 'ACTION_NOT_FOUND', status: 500 })
+            }
 
-        return await col.actions?.[action]?.({
-            rest: this,
-            io,
-            data,
-            error: fn.error,
-            jwt: func.jwt,
-            token: token ?? { value: null, decoded: null, provided: false, expired: false },
-        } as any)
+            const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
+
+            return await col.actions?.[action]?.({
+                rest: this,
+                io,
+                agents: createAgents(this.tenant_id, this),
+                api: createApi(this),
+                data,
+                error: fn.error,
+                jwt: func.jwt,
+                token: token ?? { value: null, decoded: null, provided: false, expired: false },
+            } as any)
+        }, { includeResult: false, wrapErrors: false })
     }
 
     async runService<T = any>(service: string, action: string, data?: any): Promise<T> {
-        const serviceInstance = cfg.services?.find(s => s.name === service && s._tenant_ === this.tenant_id) as Service | undefined
-        if (!serviceInstance) {
-            throw new AppError(`Service '${service}' not found`, { code: 'SERVICE_NOT_FOUND', status: 500 })
-        }
-        if (!serviceInstance.enabled) {
-            throw new AppError(`Service '${service}' is not enabled`, { code: 'SERVICE_NOT_ENABLED', status: 500 })
-        }
-        if (!Object.hasOwn(serviceInstance.actions, action) || !serviceInstance.actions?.[action]) {
-            throw new AppError(`Action '${action}' not found on service '${service}'`, { code: 'SERVICE_ACTION_NOT_FOUND', status: 500 })
-        }
-
-        const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
+        // Audited like `runAction`: the service name (`collection`), the invoked
+        // action and its `data` are recorded — never the returned payload.
+        // `internal` tells whether the call came from server-side code or the route.
+        // `wrapErrors: false` — a service's own error must reach the caller unchanged.
+        return this.#executeWithAudit('runService', service, { action, data }, async () => {
+            const serviceInstance = cfg.services?.find(s => s.name === service && s._tenant_ === this.tenant_id) as Service | undefined
+            if (!serviceInstance) {
+                throw new AppError(`Service '${service}' not found`, { code: 'SERVICE_NOT_FOUND', status: 500 })
+            }
+            if (!serviceInstance.enabled) {
+                throw new AppError(`Service '${service}' is not enabled`, { code: 'SERVICE_NOT_ENABLED', status: 500 })
+            }
+            if (!Object.hasOwn(serviceInstance.actions, action) || !serviceInstance.actions?.[action]) {
+                throw new AppError(`Action '${action}' not found on service '${service}'`, { code: 'SERVICE_ACTION_NOT_FOUND', status: 500 })
+            }
 
-        return await serviceInstance.actions?.[action]?.({
-            data,
-            error: fn.error,
-            io,
-            jwt: func.jwt,
-            token: token ?? { value: null, decoded: null, provided: false, expired: false },
-            rest: this,
-        } as any)
+            const token = requestCtxStorage.get<{ value: string | null, decoded: Record<string, unknown> | null, provided: boolean, expired: boolean }>('token')
+
+            return await serviceInstance.actions?.[action]?.({
+                data,
+                error: fn.error,
+                io,
+                agents: createAgents(this.tenant_id, this),
+                api: createApi(this),
+                jwt: func.jwt,
+                token: token ?? { value: null, decoded: null, provided: false, expired: false },
+                rest: this,
+            } as any)
+        }, { includeResult: false, wrapErrors: false })
     }
 
     async stats() {
@@ -1101,12 +1244,59 @@ class MongoRest {
 
     get audit() {
         return {
+            /**
+             * Log an audit entry the way the framework does (same envelope: trace,
+             * request, meta, `internal`, redaction, result policy).
+             *
+             * @example
+             * await rest.audit.log({ action: 'export', collection: 'orders', input: { from, to } })
+             */
+            log: async (entry: {
+                action: string;
+                collection: string;
+                input?: any;
+                result?: any;
+                error?: { message: string; code?: string } | null;
+                duration?: number;
+            }): Promise<void> => {
+                await this.#logActivity({
+                    action: entry.action,
+                    collection: entry.collection,
+                    input: entry.input,
+                    result: entry.result,
+                    error: entry.error
+                        ? { message: entry.error.message, code: entry.error.code ?? 'INTERNAL_API_ERROR' }
+                        : undefined,
+                    duration: entry.duration ?? 0,
+                })
+            },
             addActivities: async (activities: ActivityInput[]) => {
-                await this.db.collection('_activities_').insertMany(activities)
+                // Single choke point for the audit trail: every payload is redacted
+                // here (`server.audit.redact`), whatever wrote the entry — including a
+                // direct `rest.audit.addActivities()` call. Never store a password,
+                // token or secret in clear, in `_audit_` or in the local file.
+                const entries = activities.map((activity) => ({
+                    ...activity,
+                    // `request` (headers, query string) is attacker-controlled too — it
+                    // carries `x-api-key`, `?token=…`, … just like a payload
+                    request: redactPayload(activity?.request),
+                    meta: redactPayload(activity?.meta),
+                    operation: {
+                        ...activity?.operation,
+                        input: redactPayload(activity?.operation?.input),
+                        result: redactPayload(activity?.operation?.result),
+                    },
+                }))
+                await this.db.collection(AUDIT_COLLECTION).insertMany(entries)
                     .then(e => e)
                     .catch(err => {
                         console.error('Error inserting activities', err)
                     })
+                // Local append-only backup (opt-in) — fire-and-forget, never fatal.
+                // Runs after the insert on purpose: `insertMany` mutates the documents
+                // with the `_id` generated by MongoDB, so every line of the local file
+                // can be joined back to the `_audit_` collection.
+                writeAuditFile(getTenant(this.tenant_id), entries)
             },
             getActivities: async (opts = {
                 $match: {},
@@ -1114,7 +1304,7 @@ class MongoRest {
             }) => {
 
                 let pipeline = func.buildPipeline(opts)
-                return await this.db.collection('_activities_').aggregate(pipeline).toArray()
+                return await this.db.collection(AUDIT_COLLECTION).aggregate(pipeline).toArray()
             }
         }
     }
@@ -1151,6 +1341,19 @@ class MongoRest {
         };
     }
 
+    /**
+     * Tenant-scoped key/value store — like Redis, MongoDB-backed (durable, no TTL).
+     * Meant for configuration-like values (`rest.cache` is for ephemeral data).
+     *
+     * @example
+     * await rest.vars.set('config', 'licence', 'RDX00');
+     * const licence = await rest.vars.get('config', 'licence');
+     * await rest.vars.del('config', 'licence');
+     */
+    get vars(): TenantVars {
+        return createVars(this.tenant_id);
+    }
+
     /**
      * Acquire a distributed lock for this tenant.
      * Uses MongoDB atomic findOneAndUpdate with upsert.
@@ -1161,39 +1364,71 @@ class MongoRest {
         const now = Date.now();
         const expiresAt = now + ttlMs;
         const id = `${this.tenant_id}:${name}`;
-
-        try {
-            const result = await this.db.collection('_locks_').findOneAndUpdate(
-                { _id: id as any, expiresAt: { $lt: now } },
-                { $set: { tid: this.tenant_id, name, acquiredAt: now, expiresAt } },
-                { upsert: true, returnDocument: 'after' }
-            );
-            if (!result) {
-                throw new AppError(`Lock '${name}' is already held by another node`, {
-                    code: 'LOCK_ACQUISITION_FAILED',
-                    status: 409
-                });
+        const hostname = os.hostname();
+        const col = this.db.collection('_locks_');
+
+        // A lock is free when it expired, or when it is held by a process that is
+        // gone **on this host** (Bun `reusePort` / forked processes: a crashed
+        // worker must not block a run for the whole TTL). A remote owner cannot be
+        // probed — its TTL is the only guarantee.
+        const stale = (lock: any): boolean => {
+            if ((lock.expiresAt ?? 0) < now) return true;
+            if (lock.hostname === hostname && typeof lock.pid === 'number') {
+                if (lock.pid === process.pid) return false; // ours: not stale
+                return !isProcessAlive(lock.pid);
             }
-        } catch (err: any) {
-            if (err instanceof AppError) throw err;
-            // E11000 duplicate key = another node holds a valid lock
-            if (err?.code === 11000) {
-                throw new AppError(`Lock '${name}' is already held by another node`, {
-                    code: 'LOCK_ACQUISITION_FAILED',
-                    status: 409
-                });
+            return false;
+        };
+
+        const claim = async (): Promise<boolean> => {
+            const existing: any = await col.findOne({ _id: id as any });
+
+            if (!existing) {
+                try {
+                    await col.insertOne({
+                        _id: id as any,
+                        tid: this.tenant_id,
+                        name,
+                        acquiredAt: now,
+                        expiresAt,
+                        pid: process.pid,
+                        hostname,
+                    } as any);
+                    return true;
+                } catch (err: any) {
+                    if (err?.code === 11000) return false; // another node won the race
+                    throw err;
+                }
             }
-            throw err;
+
+            if (!stale(existing)) return false;
+
+            // Compare-and-set on `expiresAt` (+ owner pid): another node may take it
+            // over in the same instant, only one of us matches
+            const res = await col.updateOne(
+                { _id: id as any, expiresAt: existing.expiresAt ?? null, pid: existing.pid ?? null },
+                { $set: { tid: this.tenant_id, name, acquiredAt: now, expiresAt, pid: process.pid, hostname } },
+            );
+            return (res.matchedCount ?? 0) > 0;
+        };
+
+        if (!(await claim())) {
+            throw new AppError(`Lock '${name}' is already held by another node`, {
+                code: 'LOCK_ACQUISITION_FAILED',
+                status: 409,
+            });
         }
     }
 
     /**
-     * Release a distributed lock.
+     * Release a distributed lock — only when **we** own it: another node may have
+     * taken it over after our process was considered gone.
      */
     async unlock(name: string): Promise<void> {
         await this.db.collection('_locks_').deleteOne({
             tid: this.tenant_id,
             name,
+            $or: [{ pid: process.pid }, { pid: { $exists: false } }],
         });
     }