@anteros/core 0.0.20 → 0.0.22

package/tests/security.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "bun:test";
+import { Hono } from "hono";
+import { createMemoryStore, createRedisStore, rateLimit } from "../server/security";
+
+// ─── createMemoryStore ───────────────────────────────────────────────────
+
+describe("createMemoryStore", () => {
+    it("increments within a window", async () => {
+        const store = createMemoryStore();
+        expect((await store.increment("k", 60_000)).count).toBe(1);
+        expect((await store.increment("k", 60_000)).count).toBe(2);
+        store.dispose();
+    });
+
+    it("resets after the window expires", async () => {
+        const store = createMemoryStore();
+        await store.increment("k", 1);
+        expect((await store.increment("k", 1)).count).toBe(2);
+        // window (1ms) expired → resets to 1
+        await Bun.sleep(5);
+        const r = await store.increment("k", 1);
+        expect(r.count).toBe(1);
+        store.dispose();
+    });
+});
+
+// ─── createRedisStore (mocked RedisClient) ───────────────────────────────
+
+describe("createRedisStore", () => {
+    it("uses incr / pexpire / pttl", async () => {
+        const calls: string[] = [];
+        const mock: any = {
+            incr: async (k: string) => { calls.push(`incr:${k}`); return 1; },
+            pexpire: async (k: string, ms: number) => { calls.push(`pexpire:${k}:${ms}`); return 1; },
+            pttl: async (k: string) => { calls.push(`pttl:${k}`); return 4000; },
+        };
+        const store = createRedisStore(mock);
+        const r = await store.increment("key", 60_000);
+        expect(r.count).toBe(1);
+        expect(r.resetAt).toBeGreaterThan(Date.now());
+        expect(calls).toContain("incr:key");
+        expect(calls).toContain("pexpire:key:60000");
+        expect(calls).toContain("pttl:key");
+    });
+
+    it("only sets expiry on the first increment of a window", async () => {
+        let incrCount = 0;
+        let pexpireCalls = 0;
+        const mock: any = {
+            incr: async () => ++incrCount,
+            pexpire: async () => { pexpireCalls++; return 1; },
+            pttl: async () => 5000,
+        };
+        const store = createRedisStore(mock);
+        await store.increment("k", 1000); // count=1 → pexpire
+        await store.increment("k", 1000); // count=2 → no pexpire
+        expect(pexpireCalls).toBe(1);
+    });
+});
+
+// ─── rateLimit middleware ────────────────────────────────────────────────
+
+describe("rateLimit middleware", () => {
+    it("adds headers and blocks with 429 + Retry-After", async () => {
+        const app = new Hono();
+        app.use(rateLimit({ windowMs: 60_000, max: 2 }));
+        app.get("/", (c) => c.text("ok"));
+
+        const r1 = await app.request("/");
+        expect(r1.headers.get("X-RateLimit-Limit")).toBe("2");
+        expect(r1.headers.get("X-RateLimit-Remaining")).toBe("1");
+
+        await app.request("/");
+        const r3 = await app.request("/");
+        expect(r3.status).toBe(429);
+        expect(r3.headers.get("Retry-After")).toBeTruthy();
+        const body: any = await r3.json();
+        expect(body.code).toBe("RATE_LIMIT_EXCEEDED");
+    });
+
+    it("respects a custom keyGenerator", async () => {
+        const app = new Hono();
+        app.use(rateLimit({ windowMs: 60_000, max: 1, keyGenerator: () => "fixed-key" }));
+        app.get("/", (c) => c.text("ok"));
+        await app.request("/");
+        expect((await app.request("/")).status).toBe(429);
+    });
+
+    it("uses a shared Redis store when provided", async () => {
+        const calls: string[] = [];
+        const store = createRedisStore({
+            incr: async (k: string) => { calls.push(`incr:${k}`); return 5; },
+            pexpire: async () => 1,
+            pttl: async () => 3000,
+        } as any);
+        const app = new Hono();
+        app.use(rateLimit({ windowMs: 60_000, max: 2, store }));
+        app.get("/", (c) => c.text("ok"));
+        await app.request("/");
+        expect(calls.some((c) => c.startsWith("incr:"))).toBe(true);
+    });
+});

package/tests/utils.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import * as func from "../utils/func";
+import utils from "../utils";
+import { cfg } from "../server/config";
+
+afterEach(() => {
+    cfg.server.jwt = undefined;
+});
+
+describe("omit", () => {
+    it("removes keys and regex patterns", () => {
+        const out = func.omit({ a: 1, b: 2, password: "x", secret_key: "y" }, ["a", /^secret_/]);
+        expect(out).toEqual({ b: 2, password: "x" });
+    });
+});
+
+describe("pick", () => {
+    it("picks simple keys", () => {
+        expect(func.pick({ a: 1, b: 2, c: 3 }, ["a", "c"])).toEqual({ a: 1, c: 3 });
+    });
+});
+
+describe("cleanDeep", () => {
+    it("removes null / undefined / empty recursively", () => {
+        expect(func.cleanDeep({ a: 1, b: null, c: undefined, d: [], e: {}, f: { g: null } })).toEqual({ a: 1 });
+    });
+});
+
+describe("clone / deepCopy", () => {
+    it("clone deep-copies plain objects", () => {
+        const src = { a: { b: [1, 2] } };
+        const copy = func.clone(src);
+        expect(copy).toEqual(src);
+        expect(copy).not.toBe(src);
+        copy.a!.b.push(3);
+        expect(src.a!.b).toEqual([1, 2]);
+    });
+
+    it("deepCopy preserves Date / Map / Set", () => {
+        const src = { d: new Date("2024-01-01"), m: new Map([["k", { v: 1 }]]), s: new Set([1, 2]) };
+        const copy = func.deepCopy(src);
+        expect(copy.d).toBeInstanceOf(Date);
+        expect(copy.m).toBeInstanceOf(Map);
+        expect(copy.s).toBeInstanceOf(Set);
+        expect((copy.m as Map<string, any>).get("k")).toEqual({ v: 1 });
+    });
+});
+
+describe("deepEquals", () => {
+    it("compares deeply", () => {
+        expect(utils.deepEquals({ a: 1, b: { c: [1, 2] } }, { a: 1, b: { c: [1, 2] } })).toBe(true);
+        expect(utils.deepEquals({ a: 1 }, { a: 2 })).toBe(false);
+    });
+});
+
+describe("isSlug / slugify", () => {
+    it("isSlug validates the slug pattern", () => {
+        expect(func.isSlug("my-product")).toBe(true);
+        expect(func.isSlug("My-Product")).toBe(false);
+        expect(func.isSlug("")).toBe(false);
+    });
+
+    it("slugify converts text", () => {
+        expect(func.slugify("Hello World!")).toBe("hello-world");
+    });
+});
+
+describe("jwt", () => {
+    it("signs and verifies", async () => {
+        cfg.server.jwt = { secret: "test-secret" };
+        const token = await func.jwt.sign({ sub: "u1", role: "admin" });
+        const { value, error } = await func.jwt.verify(token);
+        expect(error).toBeNull();
+        expect(value).not.toBeNull();
+        expect(value?.role).toBe("admin");
+        expect(value?.sub).toBe("u1");
+    });
+
+    it("detects expired tokens", async () => {
+        cfg.server.jwt = { secret: "s" };
+        const token = await func.jwt.sign({ sub: "u1" }, { expiresIn: "1s" });
+        await Bun.sleep(1100);
+        const { value, expired } = await func.jwt.verify(token);
+        expect(value).toBeNull();
+        expect(expired).toBe(true);
+    }, 5000);
+
+    it("rejects invalid tokens", async () => {
+        cfg.server.jwt = { secret: "s" };
+        const { value, error, expired } = await func.jwt.verify("not-a-jwt");
+        expect(value).toBeNull();
+        expect(error).not.toBeNull();
+        expect(expired).toBe(false);
+    });
+
+    it("rejects a token signed with a different secret", async () => {
+        cfg.server.jwt = { secret: "secret-a" };
+        const token = await func.jwt.sign({ sub: "u1" });
+        cfg.server.jwt = { secret: "secret-b" };
+        const { value, error } = await func.jwt.verify(token);
+        expect(value).toBeNull();
+        expect(error).not.toBeNull();
+    });
+});
+
+describe("password", () => {
+    it("hashes and verifies", () => {
+        const hash = utils.password.hashSync("hunter2");
+        expect(hash).not.toBe("hunter2");
+        expect(utils.password.verifySync("hunter2", hash)).toBe(true);
+        expect(utils.password.verifySync("wrong", hash)).toBe(false);
+    });
+});

package/types/collection.d.ts

@@ -7,6 +7,25 @@ import type { Context } from "hono";
 import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
 import type { ActionsApiList, ApiAccess, ApiActions } from "./api";
+import type { Server as SocketIO } from "socket.io";
+
+/** Context passed to a collection custom action (`define.Action`). */
+export type CollectionActionContext = {
+    rest: InstanceType<typeof useRest>;
+    data: any;
+    error: typeof fn.error;
+    io: SocketIO;
+    jwt: typeof jwt;
+    token: {
+        value: string | null;
+        decoded: Record<string, unknown> | null;
+        provided: boolean;
+        expired: boolean;
+    };
+};
+
+/** A custom action on a collection — `define.Action(fn)`. */
+export type CollectionAction = (ctx: CollectionActionContext) => Promise<any>;
 export type Collection = {
     type?: "document" | "file";
     slug: string;
@@ -58,11 +77,7 @@ export type Collection = {
         readOnlyFields?: (string | RegExp)[];
     };
     actions?: {
-        [key: string]: (ctx: {
-            rest: InstanceType<typeof useRest>;
-            data: any;
-            error: typeof fn.error;
-        }) => Promise<any>;
+        [key: string]: CollectionAction;
     };
     /**
      * The tenant id of the collection

package/types/config.d.ts

@@ -6,14 +6,21 @@ import type { Route } from "./route";
 import type { Service } from "./service";
 import type { Script } from "./scripts";
 import type { FileCollection } from "./file";
+import type { McpTool, McpResource } from "./mcp";
 export type ServerConfig = {
     debug?: boolean;
     version?: string;
-    clusterMode?: boolean;
     server: {
         name?: string;
         port: number;
-        reusePort?: boolean;  // override Bun's reusePort (default: clusterMode && not dev)
+        /** Bun's SO_REUSEPORT — allows multiple processes to bind the same port. Spawn them yourself. */
+        reusePort?: boolean;
+        /** Number of worker processes when reusePort is on (default: CPU count) */
+        workers?: number;
+        /** Master supervision port exposing aggregated /health (default: port + 1) */
+        metricsPort?: number;
+        /** When true, trusts proxy headers (CF-Connecting-IP / X-Forwarded-For) as the client IP. Default: false. */
+        trustProxy?: boolean;
         body?: {
             maxSize?: number;
         };
@@ -35,8 +42,16 @@ export type ServerConfig = {
             enabled?: boolean;
             windowMs?: number;
             max?: number;
-            /** If true, uses Redis store (requires ioredis client available) */
+            /** Redis store override: unset = auto (Redis when `redis` block or REDIS_* env vars are present), false = force in-memory, true = force Redis */
             useRedis?: boolean;
+            /** Redis connection used when useRedis is true (env fallbacks: REDIS_URL / REDIS_HOST / REDIS_PORT / REDIS_PASSWORD) */
+            redis?: {
+                /** redis:// connection string (takes precedence over host/port/password) */
+                url?: string;
+                host?: string;
+                port?: number;
+                password?: string;
+            };
             /** Stricter limits for login endpoints */
             login?: {
                 windowMs?: number;
@@ -54,4 +69,6 @@ export type Config = ServerConfig & {
     services?: Service[]
     scripts?: Script[]
     fileCollections?: FileCollection[]
+    mcpTools?: McpTool[]
+    mcpResources?: McpResource[]
 }

package/types/hook.d.ts

@@ -1,7 +1,8 @@
 import type { MongoRest } from "../database/mongodbadapter";
 import type { Server as SocketIO } from "socket.io";
 import type { ActionsApiList } from "./api";
-type metaHook = {
+
+export type HookMeta = {
     action: ActionsApiList;
     collection: string;
     data?: any;
@@ -14,17 +15,19 @@ type metaHook = {
     pipeline?: any[];
     options?: any;
 }
+
+/** Context passed to a collection hook (`define.Hook`). */
+export type HookContext = {
+    rest: MongoRest;
+    action: ActionsApiList;
+    meta: HookMeta;
+    io: SocketIO;
+};
+
+/** A collection hook — `define.Hook(fn)`, used as beforeOperation/afterOperation. */
+export type CollectionHook = (ctx: HookContext) => Promise<void>;
+
 export type HooksCollection = {
-    beforeOperation?: (ctx: {
-        rest: MongoRest;
-        action: ActionsApiList;
-        meta: metaHook;
-        io: SocketIO;
-    }) => Promise<void>;
-    afterOperation?: (ctx: {
-        rest: MongoRest;
-        action: ActionsApiList;
-        meta: metaHook;
-        io: SocketIO;
-    }) => Promise<void>;
+    beforeOperation?: CollectionHook;
+    afterOperation?: CollectionHook;
 }

package/types/mcp.d.ts

@@ -0,0 +1,81 @@
+import type Joi from "joi";
+import type { ContentBlock } from "@modelcontextprotocol/sdk/types.js";
+import type { Context } from "hono";
+import type { useRest } from "../database/rest";
+
+/**
+ * MCP tool result — the Model Context Protocol `CallToolResult` shape.
+ * `exec` must return this (or a Promise of it).
+ */
+export type McpToolResult = {
+    content: ContentBlock[];
+    isError?: boolean;
+    structuredContent?: unknown;
+};
+
+/**
+ * MCP tool definition — auto-loaded from `{tenant.dir}/mcp/tools/**\/*.tool.ts`.
+ * Served over the MCP protocol at `GET/POST /mcp/:tenant_id` (Streamable HTTP).
+ */
+export type McpTool = {
+    _isMcpTool_?: boolean;
+    _tenant_?: string;
+    /** Tool name — unique per tenant (how the LLM calls it) */
+    name: string;
+    /** Short description shown to the LLM */
+    description?: string;
+    enabled?: boolean;
+    /** Joi schema describing the tool arguments (same language as collections — `v`) */
+    inputSchema: Joi.Schema;
+    /** Handler executed when the LLM calls the tool (args are Joi-validated).
+     * Must return the MCP protocol result shape: `{ content: [{ type, text | data… }] }`. */
+    exec: (ctx: {
+        c: Context;
+        rest: InstanceType<typeof useRest>;
+        /** Parsed & validated arguments */
+        args: Record<string, any>;
+    }) => McpToolResult | Promise<McpToolResult>;
+};
+
+/**
+ * MCP resource read result — the protocol `ReadResourceResult` shape.
+ * `contents` is an array of text or blob (base64) content blocks.
+ */
+export type McpResourceResult = {
+    contents: Array<{
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    }>;
+};
+
+/**
+ * MCP resource — read-only data exposed by URI (like a file the LLM can open).
+ * Auto-loaded from `{tenant.dir}/mcp/resources/**\/*.resource.ts`.
+ *
+ * The `uri` can be static (`orders://summary`) or a template
+ * (`users://{id}`) — template params are extracted and passed to `read`.
+ */
+export type McpResource = {
+    _isMcpResource_?: boolean;
+    _tenant_?: string;
+    /** Resource name — unique per tenant */
+    name: string;
+    /** Short description shown to the LLM */
+    description?: string;
+    enabled?: boolean;
+    /** Static URI (e.g. `orders://summary`) or template (e.g. `users://{id}`) */
+    uri: string;
+    /** Content type of the resource (default: application/json) */
+    mimeType?: string;
+    /** Handler called when the LLM reads the resource */
+    read: (ctx: {
+        c: Context;
+        rest: InstanceType<typeof useRest>;
+        /** Params extracted from the URI template (e.g. `{ id: '123' }`) */
+        params: Record<string, string>;
+        /** The exact URI the client requested */
+        uri: string;
+    }) => McpResourceResult | Promise<McpResourceResult>;
+};

package/types/scripts.d.ts

@@ -1,10 +1,23 @@
 import { useRest } from "../database/rest"
+import type { Tenant } from "./tenant"
 
 
 export type Script = {
     _isScript_?: boolean;
     enabled: boolean;
+    /**
+     * Run in a separate Bun process so heavy work (large JSON, long imports…)
+     * never blocks the HTTP server. The subprocess reconnects the tenant DB and
+     * rebuilds collection schemas automatically.
+     */
+    heavy?: boolean;
+    /** Max runtime in ms for heavy scripts (default: no timeout) */
+    timeout?: number;
     exec: (ctx: {
         rest: InstanceType<typeof useRest>
+        /** Report progress — only wired for heavy scripts (sent via IPC to the parent) */
+        progress?: (percent: number, info?: any) => void;
+        /** Tenant this script runs for */
+        tenant?: Tenant;
     }) => void
-}
+}

package/utils/cache.ts

@@ -50,6 +50,25 @@ class Cache {
             }
         })
     }
+
+    // ─── BentoCache provider API (delegated to the underlying instance) ───
+
+    set(options: any): Promise<boolean> { return this.#cache.set(options); }
+    setForever(options: any): Promise<boolean> { return this.#cache.setForever(options); }
+    get(options: any): Promise<unknown> { return this.#cache.get(options); }
+    getOrSet(options: any): Promise<unknown> { return this.#cache.getOrSet(options); }
+    getOrSetForever(options: any): Promise<unknown> { return this.#cache.getOrSetForever(options); }
+    has(options: any): Promise<boolean> { return this.#cache.has(options); }
+    missing(options: any): Promise<boolean> { return this.#cache.missing(options); }
+    pull(key: string): Promise<unknown> { return this.#cache.pull(key); }
+    delete(options: any): Promise<boolean> { return this.#cache.delete(options); }
+    deleteMany(options: any): Promise<boolean> { return this.#cache.deleteMany(options); }
+    deleteByTag(options: any): Promise<boolean> { return this.#cache.deleteByTag(options); }
+    expire(options: any): Promise<boolean> { return this.#cache.expire(options); }
+    clear(options?: any): Promise<void> { return this.#cache.clear(options); }
+    prune(): Promise<void> { return this.#cache.prune(); }
+    namespace(namespace: string): any { return this.#cache.namespace(namespace); }
+    disconnect(): Promise<void> { return this.#cache.disconnect(); }
 }
 
 
@@ -93,4 +112,4 @@ export {
     useFilesystemCache,
     useMemoryCache,
     useRedisCache
-}
+}

package/utils/crypto.ts

@@ -2,6 +2,20 @@ const IV_LENGTH = 12;
 const TAG_LENGTH = 16;
 const RSA_KEY_SIZE = 256;
 
+/**
+ * Build AES-GCM parameters with optional Additional Authenticated Data.
+ * AAD binds the ciphertext to its context (field/record/tenant) so a valid
+ * ciphertext cannot be swapped into another context (substitution attack).
+ */
+function gcmParams(iv: Uint8Array, aad?: string) {
+    return {
+        name: "AES-GCM" as const,
+        iv,
+        tagLength: TAG_LENGTH * 8,
+        ...(aad ? { additionalData: new TextEncoder().encode(aad) } : {}),
+    };
+}
+
 interface JsonWebKey {
     kty?: string;
     alg?: string;
@@ -43,12 +57,12 @@ class CryptSym {
         return this.#key;
     }
 
-    async encrypt(data: string | object): Promise<string> {
+    async encrypt(data: string | object, aad?: string): Promise<string> {
         const text = typeof data === "object" ? JSON.stringify(data) : data;
         const key = await this.#getKey();
         const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
         const encrypted = await crypto.subtle.encrypt(
-            { name: "AES-GCM", iv, tagLength: TAG_LENGTH * 8 },
+            gcmParams(iv, aad),
             key,
             new TextEncoder().encode(text)
         );
@@ -58,14 +72,17 @@ class CryptSym {
         return Buffer.from(buffer).toString("base64");
     }
 
-    async decrypt<T = string>(cipher: string, parseJson?: boolean): Promise<T> {
+    async decrypt<T = string>(cipher: string, parseJson?: boolean, aad?: string): Promise<T> {
         try {
             const buffer = new Uint8Array(Buffer.from(cipher, "base64"));
+            if (buffer.length < IV_LENGTH + TAG_LENGTH) {
+                throw new Error("ciphertext too short");
+            }
             const iv = buffer.slice(0, IV_LENGTH);
             const data = buffer.slice(IV_LENGTH);
             const key = await this.#getKey();
             const decrypted = await crypto.subtle.decrypt(
-                { name: "AES-GCM", iv, tagLength: TAG_LENGTH * 8 },
+                gcmParams(iv, aad),
                 key,
                 data
             );
@@ -131,7 +148,7 @@ class CryptAsym {
         return this.#keyPair;
     }
 
-    async encrypt(data: string | object, publicKey?: CryptoKey): Promise<string> {
+    async encrypt(data: string | object, publicKey?: CryptoKey, aad?: string): Promise<string> {
         const text = typeof data === "object" ? JSON.stringify(data) : data;
         const rsaKey = publicKey ?? (await this.#getKeyPair()).publicKey;
 
@@ -143,7 +160,7 @@ class CryptAsym {
 
         const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
         const encrypted = await crypto.subtle.encrypt(
-            { name: "AES-GCM", iv, tagLength: TAG_LENGTH * 8 },
+            gcmParams(iv, aad),
             aesKey,
             new TextEncoder().encode(text)
         );
@@ -162,7 +179,7 @@ class CryptAsym {
         return Buffer.from(result).toString("base64");
     }
 
-    async decrypt<T = string>(cipher: string, parseJson?: boolean): Promise<T> {
+    async decrypt<T = string>(cipher: string, parseJson?: boolean, aad?: string): Promise<T> {
         try {
             const buffer = new Uint8Array(Buffer.from(cipher, "base64"));
             if (buffer.length < RSA_KEY_SIZE + IV_LENGTH + TAG_LENGTH) {
@@ -189,7 +206,7 @@ class CryptAsym {
             );
 
             const decrypted = await crypto.subtle.decrypt(
-                { name: "AES-GCM", iv, tagLength: TAG_LENGTH * 8 },
+                gcmParams(iv, aad),
                 aesKey,
                 ciphertext
             );

package/utils/func.ts

@@ -19,15 +19,16 @@ const jwt = {
         audience?: string | string[];
         subject?: string;
     }) => {
-        let SECRET_ = cfg.server.jwt?.secret || Bun.env.JWT_SECRET
+        const SECRET_ = cfg.server.jwt?.secret || Bun.env.JWT_SECRET
         if (!SECRET_) throw new Error('JWT_SECRET is not set');
-        let EXPIRES_IN = cfg.server.jwt?.expiresIn || '1h'
+        // Per-call expiresIn wins over the global config (default: 7d)
+        const EXPIRES_IN = options?.expiresIn || cfg.server.jwt?.expiresIn || '7d'
 
         const secret = new TextEncoder().encode(SECRET_);
         const signer = new Jose.SignJWT(payload)
             .setProtectedHeader({ alg: 'HS256' })
             .setIssuedAt()
-            .setExpirationTime(EXPIRES_IN || '1h')
+            .setExpirationTime(EXPIRES_IN)
 
         if (options?.issuer) signer.setIssuer(options.issuer)
         if (options?.audience) signer.setAudience(options.audience)
@@ -301,7 +302,14 @@ function isEpochNumber(value: number): boolean {
 }
 
 function deepCopy<T>(value: T): T {
-    return clone(value);
+    // structuredClone preserves Date / RegExp / Map / Set / typed arrays
+    // (clone() uses toJson, which JSON-serializes and loses those types).
+    // Falls back to clone() for values structuredClone cannot handle.
+    try {
+        return structuredClone(value);
+    } catch {
+        return clone(value);
+    }
 }
 
 type FormatToDateResult<T> = T extends string