@anteros/core 0.0.40 → 0.0.42

package/lib/redact.ts

@@ -0,0 +1,117 @@
+import { cfg } from "../server/config";
+
+/**
+ * Keys whose value is replaced by `[redacted]` before an audit entry is stored
+ * (in `_audit_` **and** in the local file backup), at any depth.
+ *
+ * Override with `server.audit.redact: ['…']`, disable with `server.audit.redact: false`.
+ */
+const DEFAULT_REDACT_KEYS = [
+    'password',
+    'passwd',
+    'pwd',
+    'token',
+    'auth_token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'authorization',
+    'apikey',
+    'api_key',
+    'key',
+    'secret',
+    'cookie',
+    'session_id',
+    'otp',
+    'pin',
+]
+
+const REDACTED = '[redacted]'
+
+/** Depth guard — a pathological payload must never cost more than a bounded walk */
+const MAX_DEPTH = 8
+
+// Cache initialised for the default state (`redact` unset) — a sentinel like
+// `undefined` would be indistinguishable from the real, unset configuration.
+let cachedConfig: unknown = undefined
+let cachedKeys: Set<string> | null = new Set(DEFAULT_REDACT_KEYS.map((key) => key.toLowerCase()))
+
+/** Lower-cased redaction keys, or `null` when redaction is disabled */
+function redactKeys(): Set<string> | null {
+    const configured = cfg.server?.audit?.redact
+    if (configured !== cachedConfig) {
+        cachedConfig = configured
+        cachedKeys = configured === false
+            ? null
+            : new Set((configured ?? DEFAULT_REDACT_KEYS).map((key) => key.toLowerCase()))
+    }
+    return cachedKeys
+}
+
+/**
+ * Is this key sensitive? Exact match, case-insensitive, `-`/`.` normalised to `_`
+ * (`api-key` → `api_key`), plus the usual header prefix (`x-api-key` → `api_key`).
+ *
+ * Deliberately **not** a substring match: `key` must not match `monkey`.
+ */
+function isSensitiveKey(name: string, keys: Set<string>): boolean {
+    const normalized = name.toLowerCase().replace(/[-.]/g, '_')
+    if (keys.has(normalized)) return true
+    if (normalized.startsWith('x_')) return keys.has(normalized.slice(2))
+    return false
+}
+
+/**
+ * Replace the value of every sensitive key (see `isSensitiveKey`), at any depth.
+ * Arrays are traversed; **non-plain objects** (`Date`, `ObjectId`, `Buffer`,
+ * `Map`…) are left untouched so stored types are never altered.
+ *
+ * Returns the **same reference** when nothing matched — the common case (no
+ * sensitive key in the payload) costs the walk but no allocation.
+ */
+function redact(value: any, keys: Set<string>, depth = 0): any {
+    if (value === null || typeof value !== 'object' || depth > MAX_DEPTH) return value
+
+    if (Array.isArray(value)) {
+        let changed = false
+        const out = value.map((item) => {
+            const next = redact(item, keys, depth + 1)
+            if (next !== item) changed = true
+            return next
+        })
+        return changed ? out : value
+    }
+
+    const proto = Object.getPrototypeOf(value)
+    if (proto !== Object.prototype && proto !== null) return value
+
+    let changed = false
+    const out: Record<string, any> = {}
+    for (const [name, item] of Object.entries(value)) {
+        if (isSensitiveKey(name, keys)) {
+            out[name] = REDACTED
+            changed = true
+            continue
+        }
+        const next = redact(item, keys, depth + 1)
+        if (next !== item) changed = true
+        out[name] = next
+    }
+    return changed ? out : value
+}
+
+/** Redact an audit payload — `input`, `result`, `meta` or `request` */
+function redactPayload(value: any): any {
+    const keys = redactKeys()
+    if (!keys || value === undefined || value === null) return value
+    return redact(value, keys)
+}
+
+export {
+    DEFAULT_REDACT_KEYS,
+    REDACTED,
+    redactKeys,
+    isSensitiveKey,
+    redactPayload,
+    redact,
+}

package/lib/routes.ts

@@ -1,5 +1,6 @@
 import { Glob } from "bun"
 import { cfg } from "../server/config"
+import { isReservedFamily } from "./endpoints"
 import path from "path"
 import fs from "fs/promises"
 
@@ -25,6 +26,18 @@ async function loadRoutes() {
                             _tenant_: tenant.id,
                             _prefix_: tenant.routes?.prefix,
                         })
+
+                        // A route mounted under a family segment the framework owns
+                        // (`/api/v1/vars/x`) is registered first and would shadow the
+                        // framework API silently — say it out loud.
+                        const path = String(routeModule.default.path ?? '');
+                        const family = path.replace(/^\/+/, '').split('/')[0];
+                        if (family && isReservedFamily(family)) {
+                            console.warn(
+                                `Route '${tenant.routes?.prefix}${path}' of tenant '${tenant.id}' shadows the `
+                                + `framework '/api/…/${family}/…' API: rename it or change the route prefix.`,
+                            );
+                        }
                     }
                 }
             }
@@ -41,4 +54,4 @@ async function loadRoutes() {
 
 export {
     loadRoutes
-}
+}

package/lib/scriptWorker.ts

@@ -3,6 +3,8 @@ import { useRest } from "../database/rest";
 import { syncTenants } from "../database/tenant";
 import { syncCollections } from "../database/collection";
 import { syncFileCollections } from "../database/file";
+import { syncAgents, createAgents } from "./agents";
+import { createApi } from "./api";
 import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage";
 
 // ─── Heavy-script worker entrypoint ─────────────────────────────────────────
@@ -42,6 +44,7 @@ async function main() {
         await syncTenants();
         await syncCollections();
         await syncFileCollections();
+        await syncAgents(); // a heavy script gets the same `agents` registry as any other context
     } catch (err: any) {
         console.error('[script-worker] failed to bootstrap context:', err?.message);
         process.exit(1);
@@ -62,7 +65,7 @@ async function main() {
         await asyncContextStorage.run(new Map(), async () => {
             requestCtxStorage.set('trace', { id: crypto.randomUUID() });
             requestCtxStorage.set('internal', true);
-            await script.exec({ rest, progress, tenant });
+            await script.exec({ rest, progress, tenant, agents: createAgents(tenant.id, rest), api: createApi(rest) });
         });
         process.send?.({ type: 'done' });
         process.exit(0);

package/lib/scripts.ts

@@ -5,6 +5,8 @@ import fs from "fs/promises"
 import type { Script } from "../types/scripts"
 import type { Tenant } from "../types/tenant"
 import { useRest } from "../database/rest"
+import { createAgents } from "./agents"
+import { createApi } from "./api"
 import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage"
 
 
@@ -95,9 +97,12 @@ async function runScripts() {
         await asyncContextStorage.run(new Map(), async () => {
             requestCtxStorage.set('trace', { id: crypto.randomUUID() })
             requestCtxStorage.set('internal', true)
+            const rest = new useRest({ tenant_id: tenant.id })
             await script.exec({
-                rest: new useRest({ tenant_id: tenant.id }),
+                rest,
                 tenant,
+                agents: createAgents(tenant.id, rest),
+                api: createApi(rest),
             })
         })
     }

package/lib/sockets.ts

@@ -3,6 +3,8 @@ import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
 import { useRest } from "../database/rest"
+import { createAgents } from "../lib/agents"
+import { createApi } from "../lib/api"
 import { io } from "../server/io"
 import type { WebSocketHandler } from "../types/websocket"
 
@@ -26,7 +28,7 @@ async function loadSockets() {
                     const rest = new useRest({ tenant_id: tenant.id })
 
                     io.on('connection', (socket) => {
-                        handler.exec({ io, rest, socket })
+                        handler.exec({ io, rest, socket, agents: createAgents(tenant.id, rest), api: createApi(rest) })
                     })
 
                     console.log(`[socket] ${tenant.id}/${path.basename(file, '.ws.ts')} loaded`)

package/lib/workflow.ts

@@ -1,60 +1,232 @@
 import { Glob } from "bun"
-import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
-import type { WorkflowDefinition } from "../types/workflow"
+import { cfg } from "../server/config"
+import { logger } from "../utils/logger"
+import { AppError } from "./error"
+import { syncTtlRetention } from "../database/ttl"
+import type { WorkflowDefinition, WorkflowIndex } from "../types/workflow"
+import type { Tenant } from "../types/tenant"
 import { getTenant } from "../database/tenant"
 
+/** Every workflow of every tenant, keyed by `{tenant}:{id}` */
 const workflows: Map<string, WorkflowDefinition> = new Map();
 
+/**
+ * Indexes the engine itself filters on (see `database/workflow.ts`):
+ * - `listRuns()` → `find({ workflowId }).sort({ createdAt: -1 })`
+ * - `resumeAll()` → `find({ status: { $in: […] } })`
+ *
+ * Field names match MongoDB's default index naming, so an existing index with
+ * the same key is recognised (and never re-created or duplicated).
+ */
+const ENGINE_INDEXES: Record<string, 1 | -1>[] = [
+    { workflowId: 1, createdAt: -1 },
+    { status: 1 },
+]
+
+/** TTL index used for run retention — only prunes **finished** runs (`completedAt`) */
+const RUNS_TTL_INDEX = '_workflow_runs_ttl_'
+
+/**
+ * Run retention — **the tenant always wins**, `server.workflows.retention` is
+ * the fallback:
+ * - `tenant.workflows.retention` set (even `false`) → used as-is
+ * - otherwise                                     → `server.workflows.retention`
+ * - neither                                       → `undefined` (kept forever)
+ */
+function resolveWorkflowsRetention(tenant: Tenant): string | false | undefined {
+    if (tenant.workflows?.retention !== undefined) return tenant.workflows.retention
+    return cfg.server?.workflows?.retention
+}
+
+/** MongoDB's default index name for a key spec — `{ a: 1, b: -1 }` → `a_1_b_-1` */
+function indexName(key: Record<string, 1 | -1>): string {
+    return Object.entries(key).map(([field, direction]) => `${field}_${direction}`).join('_')
+}
+
 async function syncWorkflows() {
-    try {
-        workflows.clear();
-        for (let tenant of cfg.tenants ?? []) {
-            const TENANT_PATH = path.join(process.cwd(), tenant.dir)
-            const WORKFLOWS_PATH = path.join(TENANT_PATH, 'workflows')
-            let exist = await fs.exists(WORKFLOWS_PATH)
-            if (!exist) continue;
-            const isDirectory = await (await fs.stat(WORKFLOWS_PATH)).isDirectory()
-            if (!isDirectory) continue;
+    workflows.clear()
+
+    // ── Discovery — `{tenant.dir}/workflows/**/*.workflow.ts` ──────────────
+    // A broken file (or a broken tenant) must never hide the others.
+    for (const tenant of cfg.tenants ?? []) {
+        const WORKFLOWS_PATH = path.join(process.cwd(), tenant.dir, 'workflows')
+        try {
+            if (!(await fs.exists(WORKFLOWS_PATH))) continue
+            if (!(await fs.stat(WORKFLOWS_PATH)).isDirectory()) continue
 
             const glob = new Glob(path.join(WORKFLOWS_PATH, '**/*.workflow.ts'))
-            for await (let file of glob.scan('.')) {
-                let module = await import(file)
-                if (module?.default?._isWorkflow_) {
-                    const wf: WorkflowDefinition = { ...module.default, _tenant_: tenant.id }
-                    workflows.set(`${tenant.id}:${wf.id}`, wf)
+            for await (const file of glob.scan('.')) {
+                try {
+                    const module = await import(file)
+                    const definition = module?.default as WorkflowDefinition | undefined
+                    if (!definition?._isWorkflow_) continue
+                    if (definition.enabled === false) continue
+                    if (!definition.id) {
+                        console.warn(`⚠ Workflow ignored (no "id"): ${file}`)
+                        continue
+                    }
+
+                    const key = `${tenant.id}:${definition.id}`
+                    if (workflows.has(key)) {
+                        console.warn(
+                            `⚠ Duplicate workflow id '${definition.id}' for tenant '${tenant.id}' — ${file} overrides the previous definition`,
+                        )
+                    }
+                    workflows.set(key, { ...definition, _tenant_: tenant.id })
+                } catch (err: any) {
+                    console.error(`Failed to load workflow '${file}':`, err?.message)
                 }
             }
+        } catch (err: any) {
+            console.error(`Failed to load workflows for tenant '${tenant.id}':`, err?.message)
         }
+    }
 
-        // Créer les indexes sur _workflows_ pour les contextes définis
-        for (const [key, wf] of workflows) {
-          const tenantId = key.split(':')[0]
-          if (!wf.context || !tenantId) continue
-          const tenant = getTenant(tenantId)
-          const db = tenant?.database?.db
-          if (!db) continue
-
-          for (const [field, config] of Object.entries(wf.context)) {
-            const direction = config.index === true || config.index === 1 ? 1 : config.index === -1 ? -1 : 0
-            if (direction === 0) continue
-
-            try {
-              const indexKey = `context.${field}`
-              await db.collection('_workflows_').createIndex({ [indexKey]: direction })
-            } catch (err: any) {
-              console.error(`Failed to create index on _workflows_.${field}:`, err?.message)
+    logger.file('workflows: loaded', {
+        total: workflows.size,
+        tenants: [...new Set([...workflows.values()].map((wf) => wf._tenant_))],
+    })
+
+    // Indexes are a background concern: boot never waits for an index build.
+    ensureWorkflowIndexes().catch((err) => console.error('Failed to create workflow indexes:', err?.message))
+}
+
+/**
+ * Create the indexes `_workflows_` needs — the engine's query fields, the
+ * `context` fields declared by the workflows, and any explicit `indexes`.
+ * Only the missing ones are built (`background: true`), and a failure is
+ * logged, never fatal.
+ */
+async function ensureWorkflowIndexes(): Promise<void> {
+    for (const tenant of cfg.tenants ?? []) {
+        const db = getTenant(tenant.id)?.database?.db
+        if (!db) continue
+
+        // Desired indexes: engine queries first, then what the workflows declare
+        const desired = new Map<string, { key: Record<string, 1 | -1>; options: any }>()
+        for (const key of ENGINE_INDEXES) {
+            desired.set(indexName(key), { key, options: { background: true } })
+        }
+
+        for (const wf of workflows.values()) {
+            if (wf._tenant_ !== tenant.id) continue
+
+            // `context: { field: { index: true | 1 | -1 } }`
+            for (const [field, config] of Object.entries(wf.context ?? {})) {
+                const direction = config.index === true || config.index === 1 ? 1 : config.index === -1 ? -1 : 0
+                if (!direction) continue
+                const key = { [`context.${field}`]: direction } as Record<string, 1 | -1>
+                desired.set(indexName(key), { key, options: { background: true } })
+            }
+
+            // `indexes: [{ key, name?, unique?, sparse? }]` — compound and friends
+            for (const index of wf.indexes ?? []) {
+                if (!index?.key || !Object.keys(index.key).length) continue
+                // Never send `null`/`undefined` on the wire: Mongo rejects `unique: null`
+                desired.set(index.name ?? indexName(index.key), {
+                    key: index.key,
+                    options: {
+                        background: true,
+                        ...(index.name ? { name: index.name } : {}),
+                        ...(index.unique !== undefined ? { unique: index.unique } : {}),
+                        ...(index.sparse !== undefined ? { sparse: index.sparse } : {}),
+                    },
+                })
+            }
+        }
+
+        try {
+            // `listIndexes()` requires the collection to exist — create it first,
+            // like the file-collection loader does (`_workflows_` is only written
+            // when a workflow actually runs).
+            const exists = await db.listCollections({ name: '_workflows_' }).toArray()
+            if (!exists.length) await db.createCollection('_workflows_')
+
+            const collection = db.collection('_workflows_')
+            const existing = new Set(
+                (await collection.listIndexes().toArray()).map((index: any) => index.name),
+            )
+
+            for (const [name, { key, options }] of desired) {
+                if (existing.has(name)) continue
+                await collection.createIndex(key as any, options)
+                logger.file('workflows: index created', { tenant: tenant.id, index: name })
+            }
+
+            // Retention of finished runs — opt-in (`completedAt` is only set when a
+            // run finishes, so running/paused/failed runs are never pruned)
+            const retention = resolveWorkflowsRetention(tenant)
+            if (retention !== undefined) {
+                await syncTtlRetention(db, {
+                    collection: '_workflows_',
+                    index: RUNS_TTL_INDEX,
+                    field: 'completedAt',
+                    retention,
+                    label: 'Workflows',
+                })
+            }
+        } catch (err: any) {
+            console.error(`Failed to create workflow indexes for tenant '${tenant.id}':`, err?.message)
+        }
+    }
+}
+
+/**
+ * Validate — and coerce — the `context` of a run against the workflow's own
+ * declaration: this is what the `type` of a context field is for. Undeclared
+ * keys are kept as-is (the declaration is a contract on what you declare, not a
+ * closed schema). Dates sent as ISO strings are stored as real `Date`s, so the
+ * indexes on `context.*` stay typed.
+ */
+function validateWorkflowContext(wf: WorkflowDefinition, context: any): any {
+    if (!wf.context || context === undefined || context === null || typeof context !== 'object') {
+        return context
+    }
+
+    const out: Record<string, any> = { ...context }
+    const errors: string[] = []
+
+    for (const [field, spec] of Object.entries(wf.context)) {
+        const value = out[field]
+        if (value === undefined || value === null) continue
+
+        switch (spec.type) {
+            case 'string':
+                if (typeof value !== 'string') errors.push(`'${field}' must be a string (received ${typeof value})`)
+                break
+            case 'number':
+                if (typeof value !== 'number' || Number.isNaN(value)) errors.push(`'${field}' must be a number (received ${typeof value})`)
+                break
+            case 'date': {
+                const date = value instanceof Date ? value : new Date(String(value))
+                if (Number.isNaN(date.getTime())) errors.push(`'${field}' must be a date (Date or ISO string)`)
+                else out[field] = date
+                break
             }
-          }
         }
-    } catch (err: any) {
-        console.error('Failed to sync workflows:', err?.message)
     }
+
+    if (errors.length) {
+        throw new AppError(`Invalid workflow context: ${errors.join('; ')}`, {
+            code: 'WORKFLOW_CONTEXT_INVALID',
+            status: 400,
+        })
+    }
+    return out
 }
 
 function getWorkflow(id: string, tenantId: string): WorkflowDefinition | undefined {
     return workflows.get(`${tenantId}:${id}`)
 }
 
-export { syncWorkflows, getWorkflow }
+/** What was loaded — used by the boot banner and logs */
+function workflowStats(): { total: number; tenants: string[] } {
+    return {
+        total: workflows.size,
+        tenants: [...new Set([...workflows.values()].map((wf) => wf._tenant_!))],
+    }
+}
+
+export { syncWorkflows, ensureWorkflowIndexes, validateWorkflowContext, resolveWorkflowsRetention, getWorkflow, workflowStats, RUNS_TTL_INDEX as WORKFLOW_RUNS_TTL_INDEX }

package/lib/zip.ts

@@ -0,0 +1,109 @@
+import { inflateRawSync } from "node:zlib";
+import { AppError } from "./error";
+
+/**
+ * A minimal, **read-only** ZIP reader — enough to open a `.docx` or a `.xlsx`
+ * (both are ZIP containers) without adding a dependency.
+ *
+ * `Bun.Archive` only handles tar, and a document is not worth a package: the
+ * central directory of a ZIP is a simple, stable structure — find it, list the
+ * entries, inflate the one you need. Entries are decompressed **lazily**, so a
+ * workbook full of images never pays for them.
+ *
+ * Deliberately not supported (they never appear in an Office file): ZIP64
+ * archives, encrypted entries and multi-disk sets.
+ */
+
+const SIGNATURE = {
+    end: 0x06054b50,
+    central: 0x02014b50,
+    local: 0x04034b50,
+} as const;
+
+/** Zip entries are never larger than this in a document we read — sanity guard. */
+const MAX_EOCD_SCAN = 65_535 + 22; // the folder comment cap + the record itself
+
+type Entry = {
+    method: number;
+    compressedSize: number;
+    localOffset: number;
+};
+
+export type ZipArchive = {
+    /** Every entry name, in central-directory order. */
+    names(): string[];
+    /** The decompressed bytes of an entry, or `null` when it does not exist. */
+    read(name: string): Uint8Array | null;
+};
+
+function bad(reason: string): AppError {
+    return new AppError(`Unreadable archive: ${reason}`, { status: 400, code: "AGENT_FILE_INVALID" });
+}
+
+/** Open a ZIP buffer — throws `AGENT_FILE_INVALID` when it is not a readable ZIP. */
+function openZip(buffer: Uint8Array): ZipArchive {
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+
+    // ── End Of Central Directory — the only reliable place to start ───────
+    let end = -1;
+    const lowest = Math.max(0, buffer.length - MAX_EOCD_SCAN);
+    for (let offset = buffer.length - 22; offset >= lowest; offset--) {
+        if (view.getUint32(offset, true) === SIGNATURE.end) {
+            end = offset;
+            break;
+        }
+    }
+    if (end < 0) throw bad("no ZIP central directory (is it a real .docx/.xlsx?)");
+
+    const entries = new Map<string, Entry>();
+    const count = view.getUint16(end + 10, true);
+    let offset = view.getUint32(end + 16, true);
+
+    // ── Central directory ────────────────────────────────────────────────
+    for (let index = 0; index < count; index++) {
+        if (offset + 46 > buffer.length || view.getUint32(offset, true) !== SIGNATURE.central) {
+            throw bad("truncated central directory");
+        }
+
+        const method = view.getUint16(offset + 10, true);
+        const compressedSize = view.getUint32(offset + 20, true);
+        const nameLength = view.getUint16(offset + 28, true);
+        const extraLength = view.getUint16(offset + 30, true);
+        const commentLength = view.getUint16(offset + 32, true);
+        const localOffset = view.getUint32(offset + 42, true);
+
+        if (compressedSize === 0xffffffff || localOffset === 0xffffffff) {
+            throw bad("ZIP64 archives are not supported");
+        }
+
+        const name = new TextDecoder().decode(buffer.subarray(offset + 46, offset + 46 + nameLength));
+        entries.set(name, { method, compressedSize, localOffset });
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+
+    return {
+        names: () => [...entries.keys()],
+
+        read(name: string): Uint8Array | null {
+            const entry = entries.get(name);
+            if (!entry) return null;
+
+            // The local header repeats the name/extra — the payload starts after them.
+            const local = entry.localOffset;
+            if (local + 30 > buffer.length || view.getUint32(local, true) !== SIGNATURE.local) {
+                throw bad(`corrupted entry '${name}'`);
+            }
+
+            const start = local + 30 + view.getUint16(local + 26, true) + view.getUint16(local + 28, true);
+            const data = buffer.subarray(start, start + entry.compressedSize);
+            if (start + entry.compressedSize > buffer.length) throw bad(`truncated entry '${name}'`);
+
+            // 0 = stored, 8 = deflate — the only two methods Office writes
+            if (entry.method === 0) return data;
+            if (entry.method === 8) return new Uint8Array(inflateRawSync(data));
+            throw bad(`unsupported compression method ${entry.method} for '${name}'`);
+        },
+    };
+}
+
+export { openZip };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anteros/core",
   "module": "index.ts",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "type": "module",
   "description": "Anteros Core",
   "private": false,