@anteros/core 0.0.39 → 0.0.41

package/tests/upload.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { ObjectId } from "mongodb";
+import { createApp } from "../server/hono";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { getFileCollection } from "../database/file";
+import { useRest } from "../database/rest";
+
+const TENANT = "up-test";
+const DB = "mongodb://localhost:27017/_DB_UP_TEST";
+const SLUG = "photos";
+
+let rest: InstanceType<typeof useRest>;
+let server: any;
+let url = "";
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: "up-tenant", database: { uri: DB } }],
+    });
+    await syncTenants();
+
+    // File collection (disk storage) — no syncing from disk, declared directly
+    (cfg as any).fileCollections = [{
+        _tenant_: TENANT,
+        _isFileCollection_: true,
+        slug: SLUG,
+        fields: [{ name: "label", type: "string" }, { name: "takenAt", type: "date" }],
+        upload: { allowedMimeTypes: ["image/png", "text/plain"], maxSize: 5 * 1024 * 1024 },
+        storage: { driver: "disk" },
+        api: { access: { "*": true } },
+    }];
+
+    rest = new useRest({ internal: false, tenant_id: TENANT });
+    const app = createApp();
+    server = Bun.serve({ port: 0, fetch: app.fetch });
+    url = server.url.href.replace(/\/$/, "");
+});
+
+afterAll(async () => {
+    try { await rest.db.collection(SLUG).drop(); } catch {}
+    // clean the uploaded files
+    try {
+        const fs = await import("node:fs/promises");
+        await fs.rm(`${process.cwd()}/storage/${TENANT}/${SLUG}`, { recursive: true, force: true });
+    } catch {}
+    try { server.stop(true); } catch {}
+});
+
+function pngFile(name: string) {
+    // minimal valid PNG (1x1) so content detection sees a real image
+    const bytes = Buffer.from(
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+        "base64"
+    );
+    return new File([bytes], name, { type: "image/png" });
+}
+
+describe("upload — audit trail", () => {
+    /** Latest audit entry for an action, polling until it lands */
+    async function auditEntry(action: string, id?: string) {
+        const filter: any = { "operation.action": action };
+        if (id) filter["operation.result._id"] = id;
+        for (let i = 0; i < 40; i++) {
+            const found: any = await rest.db.collection("_audit_").findOne(filter, { sort: { ts: -1 } });
+            if (found) return found;
+            await Bun.sleep(25);
+        }
+        return null;
+    }
+
+    it("records an upload with the file metadata and the generated id — never the document", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("audited.png"));
+        form.append("label", "audited");
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+        const body: any = await res.json();
+
+        const logged: any = await auditEntry("upload", body._id);
+        expect(logged).not.toBeNull();
+        expect(logged.operation.collection).toBe(SLUG);
+        expect(logged.operation.collectionType).toBe("file");
+        expect(logged.operation.status).toBe("success");
+        expect(logged.internal).toBe(false); // HTTP upload
+
+        // parameters only: the file's metadata and which custom fields were sent
+        expect(logged.operation.input.file.name).toBe("audited.png");
+        expect(logged.operation.input.file.mimetype).toBe("image/png");
+        expect(typeof logged.operation.input.file.size).toBe("number");
+        expect(logged.operation.input.fields).toEqual(["label"]);
+        expect(logged.operation.input.label).toBeUndefined(); // the value is NOT stored
+
+        // and the generated id, never the stored document
+        expect(logged.operation.result).toEqual({ _id: body._id });
+    });
+
+    it("records a file deletion", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("deleted.png"));
+        const uploaded: any = await (
+            await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form })
+        ).json();
+
+        const res = await fetch(`${url}/files/${TENANT}/${SLUG}/${uploaded._id}`, { method: "DELETE" });
+        expect(res.status).toBe(200);
+
+        const logged: any = await auditEntry("deleteFile");
+        expect(logged).not.toBeNull();
+        expect(logged.operation.input.id).toBe(uploaded._id);
+        expect(logged.operation.input.filename).toBeString();
+        expect(logged.operation.result).toEqual({ deleted: true });
+        expect(logged.internal).toBe(false);
+    });
+});
+
+describe("upload — single file (unchanged contract)", () => {
+    it("returns a single object", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("one.png"));
+        form.append("label", "single");
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+
+        const body: any = await res.json();
+        expect(Array.isArray(body)).toBe(false);          // ← object, not an array
+        expect(body._id).toBeString();
+        expect(body._file.name).toBe("one.png");
+        expect(body._file.mimetype).toBe("image/png");
+        expect(body._file.url).toContain(`/files/${TENANT}/${SLUG}/`);
+        expect(body.createdAt).toBeString();
+        expect(body.updatedAt).toBeString();
+
+        // metadata persisted on the document
+        const doc: any = await rest.findOne(SLUG, body._id);
+        expect(doc.label).toBe("single");
+
+        // Stored as BSON Dates (same end result as collections via toBson)
+        const raw: any = await rest.db.collection(SLUG).findOne({ _id: new ObjectId(body._id) });
+        expect(raw.createdAt).toBeInstanceOf(Date);
+        expect(raw.updatedAt).toBeInstanceOf(Date);
+    });
+
+    it("accepts the 'upload' field name too", async () => {
+        const form = new FormData();
+        form.append("upload", pngFile("alt.png"));
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+        const body: any = await res.json();
+        expect(Array.isArray(body)).toBe(false);
+        expect(body._file.name).toBe("alt.png");
+    });
+});
+
+describe("upload — multiple files", () => {
+    it("returns an array and creates one document per file", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("a.png"));
+        form.append("file", pngFile("b.png"));
+        form.append("file", pngFile("c.png"));
+        form.append("label", "batch");
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+
+        const body: any = await res.json();
+        expect(Array.isArray(body)).toBe(true);
+        expect(body.length).toBe(3);
+        expect(body.map((f: any) => f._file.name).sort()).toEqual(["a.png", "b.png", "c.png"]);
+
+        // every file is its own document, all ids distinct, metadata shared
+        const ids = body.map((f: any) => f._id);
+        expect(new Set(ids).size).toBe(3);
+        for (const id of ids) {
+            const doc: any = await rest.findOne(SLUG, id);
+            expect(doc.label).toBe("batch");
+            expect(doc._file.url).toContain(`/files/${TENANT}/${SLUG}/`);
+            // Uploads carry timestamps (required by the replication cursor)
+            expect(doc.createdAt).toBeString();
+            expect(doc.updatedAt).toBeString();
+        }
+    });
+
+    it("still rejects a request without any file", async () => {
+        const form = new FormData();
+        form.append("label", "nofile");
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(400);
+        const body: any = await res.json();
+        expect(body.code).toBe("FILE_REQUIRED");
+    });
+
+    it("rejects the whole batch on an invalid file (per-file validation)", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("ok.png"));
+        form.append("file", new File([Buffer.from("nope")], "bad.exe", { type: "application/x-msdownload" }));
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(400);
+        const body: any = await res.json();
+        expect(body.code).toBe("MIMETYPE_NOT_ALLOWED");
+    });
+});
+
+describe("upload — custom field types (toBson, like collections)", () => {
+    it("converts a `date` field to a BSON Date", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("dated.png"));
+        form.append("label", "dated");
+        form.append("takenAt", "2024-05-01T10:00:00.000Z");
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+        const body: any = await res.json();
+
+        const raw: any = await rest.db.collection(SLUG).findOne({ _id: new ObjectId(body._id) });
+        expect(raw.takenAt).toBeInstanceOf(Date);
+        expect(raw.takenAt.toISOString()).toBe("2024-05-01T10:00:00.000Z");
+    });
+
+    it("leaves `_file` untouched, even when a name looks like a date", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("2024-01-01")); // ← a file literally named like a date
+
+        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        expect(res.status).toBe(200);
+        const body: any = await res.json();
+        expect(body._file.name).toBe("2024-01-01");
+
+        const raw: any = await rest.db.collection(SLUG).findOne({ _id: new ObjectId(body._id) });
+        expect(raw._file.name).toBe("2024-01-01"); // NOT converted to a Date
+        expect(typeof raw._file.name).toBe("string");
+    });
+});

package/tests/vars-api.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { ObjectId } from "mongodb";
+import { createApp } from "../server/hono";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncVars } from "../database/vars";
+import { useRest } from "../database/rest";
+
+const TENANT = "vars-api";
+const DB = "mongodb://localhost:27017/_VARS_API_TEST";
+const DIR = "packages/core/tests/fixtures/vars-tenant";
+
+let rest: InstanceType<typeof useRest>;
+let server: any;
+let url = "";
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: DIR, database: { uri: DB } }],
+    });
+    await syncTenants();
+    await syncVars();
+
+    rest = new useRest({ internal: false, tenant_id: TENANT });
+    const app = createApp();
+    server = Bun.serve({ port: 0, fetch: app.fetch });
+    url = server.url.href.replace(/\/$/, "");
+});
+
+afterAll(async () => {
+    try { await rest.db.dropDatabase(); } catch (_) {}
+    try { server.stop(true); } catch (_) {}
+});
+
+const post = (action: string, body: any) =>
+    fetch(`${url}/vars/${TENANT}/${action}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+
+const json = async (action: string, body: any) => {
+    const res = await post(action, body);
+    return { status: res.status, body: await res.json() as any };
+};
+
+describe("vars HTTP API — access control", () => {
+    it("denies a namespace without api.access", async () => {
+        const res = await json("get", { ns: "private", key: "secret" });
+        expect(res.status).toBe(401);
+        expect(res.body.code).toBe("ACCESS_DENIED");
+    });
+
+    it("rejects an unknown namespace", async () => {
+        const res = await json("get", { ns: "nope", key: "x" });
+        expect(res.status).toBe(400);
+        expect(res.body.code).toBe("NAMESPACE_NOT_FOUND");
+    });
+
+    it("requires the namespace", async () => {
+        const res = await json("get", { key: "x" });
+        expect(res.status).toBe(400);
+        expect(res.body.code).toBe("NAMESPACE_REQUIRED");
+    });
+});
+
+describe("vars HTTP API — CRUD", () => {
+    it("set / get / has / del", async () => {
+        expect((await json("set", { ns: "config", key: "plan", value: "pro" })).status).toBe(200);
+
+        const got = await json("get", { ns: "config", key: "plan" });
+        expect(got.body.value).toBe("pro");
+
+        expect((await json("has", { ns: "config", key: "plan" })).body.exists).toBe(true);
+        expect((await json("del", { ns: "config", key: "plan" })).body.ok).toBe(true);
+        expect((await json("get", { ns: "config", key: "plan" })).body.value).toBeUndefined();
+    });
+
+    it("setMany / all", async () => {
+        await json("setMany", { ns: "config", entries: { a: 1, b: 2 } });
+        const all = await json("all", { ns: "config" });
+        expect(all.body.vars).toMatchObject({ a: 1, b: 2 });
+    });
+
+    it("entry carries the meta", async () => {
+        const id = new ObjectId().toHexString();
+        await json("set", { ns: "config", key: "lic", value: "L-1", meta: { note: "hi" }, scope: id });
+
+        const entry = await json("entry", { ns: "config", key: "lic", scope: id });
+        expect(entry.body.entry.value).toBe("L-1");
+        expect(entry.body.entry.meta).toEqual({ note: "hi" });
+    });
+
+    it("incr", async () => {
+        await json("set", { ns: "config", key: "hits", value: 5 });
+        expect((await json("incr", { ns: "config", key: "hits" })).body.value).toBe(6);
+    });
+
+    it("scope keeps values isolated", async () => {
+        const id = new ObjectId().toHexString();
+        await json("set", { ns: "config", key: "lic", value: "SCOPED", scope: id });
+        expect((await json("get", { ns: "config", key: "lic", scope: id })).body.value).toBe("SCOPED");
+    });
+
+    it("TTL round-trips as an expiry", async () => {
+        await json("set", { ns: "config", key: "tmp", value: "x", ttl: "1h" });
+        const entry = await json("entry", { ns: "config", key: "tmp" });
+        expect(typeof entry.body.entry.expiresAt).toBe("string");
+        expect((await json("expire", { ns: "config", key: "tmp", ttl: "30m" })).body.ok).toBe(true);
+    });
+
+    it("validates the value against its spec", async () => {
+        const res = await json("set", { ns: "config", key: "maxUsers", value: "not-a-number" });
+        expect(res.status).toBe(400);
+        expect(res.body.code).toBe("VALIDATION_ERROR");
+    });
+
+    it("rejects an unknown action", async () => {
+        const res = await json("nope", { ns: "config", key: "x" });
+        expect(res.status).toBe(400);
+    });
+});

package/tests/vars-replication.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncVars } from "../database/vars";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+
+const TEST_TENANT = "vars-repl";
+const SRC_DB = "mongodb://localhost:27017/_VARS_REPL_SRC";
+const DEST_DB = "mongodb://localhost:27017/_VARS_REPL_DEST";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "packages/core/tests/fixtures/vars-tenant",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: "backup", uri: DEST_DB }],
+            },
+        }],
+    });
+
+    sourceClient = new MongoClient(SRC_DB, { serverSelectionTimeoutMS: 3000 });
+    await sourceClient.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = sourceClient;
+    tenant.database.db = sourceClient.db();
+
+    await syncVars();
+    await startReplication();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+    destClient = new MongoClient(DEST_DB, { serverSelectionTimeoutMS: 3000 });
+    await destClient.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    try { await sourceClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.close(); } catch (_) {}
+    try { await sourceClient.close(); } catch (_) {}
+});
+
+const destVar = (key: string, ns = "config") =>
+    destClient.db().collection("_vars_").findOne({ ns, key });
+
+describe("vars replication", () => {
+    it("replicates the `_vars_` collection (all namespaces)", async () => {
+        await rest.vars.set("config", "licence", "REPL-1");
+        await replicateTenant(TEST_TENANT);
+
+        expect((await destVar("licence"))?.value).toBe("REPL-1");
+
+        // Seeded defaults are replicated too
+        expect((await destVar("maxUsers"))?.value).toBe(100);
+    });
+
+    it("propagates variable deletion", async () => {
+        await rest.vars.set("config", "tmp", "x", { ttl: "1h" });
+        await replicateTenant(TEST_TENANT);
+        expect(await destVar("tmp")).toBeDefined();
+
+        await rest.vars.del("config", "tmp");
+        await replicateTenant(TEST_TENANT);
+        expect(await destVar("tmp")).toBeNull();
+    });
+
+    it("propagates scoped variables", async () => {
+        const mine = "aabbccddeeff001122334455";
+        await rest.vars.scope(mine).set("config", "licence", "SCOPED-1");
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("_vars_").findOne({
+            ns: "config", key: "licence", scope: { $ne: null },
+        });
+        expect(dest?.value).toBe("SCOPED-1");
+    });
+
+    it("does NOT replicate namespaces that did not opt in", async () => {
+        // `private.var.ts` has no `replication` — it must never reach the destination.
+        await rest.vars.set("private", "secret", "top-secret");
+        await replicateTenant(TEST_TENANT);
+
+        expect(await destClient.db().collection("_vars_").findOne({ ns: "private" })).toBeNull();
+    });
+});

package/tests/vars.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient, ObjectId } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncVars } from "../database/vars";
+import { define } from "../lib/define";
+
+const TEST_TENANT = "vars";
+const DB = "mongodb://localhost:27017/_VARS_TEST";
+
+let rest: InstanceType<typeof useRest>;
+let client: MongoClient;
+const raw = () => client.db().collection("_vars_");
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "packages/core/tests/fixtures/vars-tenant",
+            database: { uri: DB },
+        }],
+    });
+
+    client = new MongoClient(DB, { serverSelectionTimeoutMS: 3000 });
+    await client.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = client;
+    tenant.database.db = client.db();
+
+    await syncVars();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await client.db().dropDatabase(); } catch (_) {}
+    try { await client.close(); } catch (_) {}
+});
+
+describe("define.Vars", () => {
+    it("marks the definition", () => {
+        const v = define.Vars({ namespace: "x", vars: { a: 1 } });
+        expect(v._isVars_).toBe(true);
+    });
+});
+
+describe("vars loading & seeding", () => {
+    it("loads the definitions from vars/*.var.ts", () => {
+        const namespaces = (cfg.vars ?? []).map((v) => v.namespace).sort();
+        expect(namespaces).toEqual(["config", "private"]);
+        expect((cfg.vars ?? []).every((v) => v._tenant_ === TEST_TENANT)).toBe(true);
+    });
+
+    it("seeds default values at the global scope", async () => {
+        expect(await rest.vars.get<string>("config", "licence")).toBe("RDX00");
+        expect(await rest.vars.get<number>("config", "maxUsers")).toBe(100);
+    });
+
+    it("never overwrites an existing value when re-seeding", async () => {
+        await rest.vars.set("config", "licence", "CHANGED");
+        await syncVars();
+        expect(await rest.vars.get<string>("config", "licence")).toBe("CHANGED");
+    });
+
+    it("always creates the scope + TTL indexes", async () => {
+        const names = (await raw().listIndexes().toArray()).map((i) => i.name);
+        expect(names).toContain("scope_1_ns_1");
+        expect(names).toContain("expiresAt_1");
+    });
+});
+
+describe("rest.vars — CRUD", () => {
+    it("set / get / has / del", async () => {
+        await rest.vars.set("app", "theme", "dark");
+        expect(await rest.vars.get<string>("app", "theme")).toBe("dark");
+        expect(await rest.vars.has("app", "theme")).toBe(true);
+
+        expect(await rest.vars.del("app", "theme")).toBe(true);
+        expect(await rest.vars.get<string>("app", "theme")).toBeUndefined();
+        expect(await rest.vars.has("app", "theme")).toBe(false);
+        expect(await rest.vars.del("app", "theme")).toBe(false);
+    });
+
+    it("stores rich values (objects, arrays, booleans)", async () => {
+        const value = { max: 10, tags: ["a", "b"], on: true };
+        await rest.vars.set("app", "limits", value);
+        expect(await rest.vars.get<any>("app", "limits")).toEqual(value);
+    });
+
+    it("setMany / all / clear", async () => {
+        await rest.vars.setMany("bulk", { a: 1, b: 2, c: 3 });
+        expect(await rest.vars.all("bulk")).toEqual({ a: 1, b: 2, c: 3 });
+        expect(await rest.vars.clear("bulk")).toBe(3);
+        expect(await rest.vars.all("bulk")).toEqual({});
+    });
+
+    it("incr is atomic (and creates a missing key)", async () => {
+        await rest.vars.set("counters", "hits", 5);
+        expect(await rest.vars.incr("counters", "hits")).toBe(6);
+        expect(await rest.vars.incr("counters", "hits", 10)).toBe(16);
+        expect(await rest.vars.incr("counters", "fresh", 3)).toBe(3);
+    });
+
+    it("isolates namespaces", async () => {
+        await rest.vars.set("ns1", "k", "a");
+        await rest.vars.set("ns2", "k", "b");
+        expect(await rest.vars.get<string>("ns1", "k")).toBe("a");
+        expect(await rest.vars.get<string>("ns2", "k")).toBe("b");
+    });
+});
+
+describe("rest.vars — scope (per company)", () => {
+    it("keeps a distinct value per scope", async () => {
+        const acme = new ObjectId().toHexString();
+        const globex = new ObjectId().toHexString();
+
+        await rest.vars.scope(acme).set("config", "licence", "ACME-001");
+        await rest.vars.scope(globex).set("config", "licence", "GLBX-002");
+
+        expect(await rest.vars.scope(acme).get<string>("config", "licence")).toBe("ACME-001");
+        expect(await rest.vars.scope(globex).get<string>("config", "licence")).toBe("GLBX-002");
+        // global value untouched
+        expect(await rest.vars.get<string>("config", "licence")).not.toBe("ACME-001");
+    });
+
+    it("accepts an explicit scope option", async () => {
+        const id = new ObjectId().toHexString();
+        await rest.vars.set("config", "licence", "SCOPED", { scope: id });
+        expect(await rest.vars.get<string>("config", "licence", { scope: id })).toBe("SCOPED");
+    });
+});
+
+describe("rest.vars — meta", () => {
+    it("stores and returns validated meta", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.set("config", "licence", "ACME-003", { meta: { note: "Contrat 2026" } });
+        const entry = await acme.entry("config", "licence");
+
+        expect(entry?.value).toBe("ACME-003");
+        expect(entry?.meta).toEqual({ note: "Contrat 2026" });
+        expect(String(entry?.scope)).toBe(id);
+    });
+
+    it("rejects unknown meta keys", async () => {
+        await expect(
+            rest.vars.set("config", "licence", "X", { meta: { nope: 1 } }),
+        ).rejects.toThrow(/nope/);
+    });
+
+    it("filters entries on meta with `where`", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.setMany("flags", { a: true, b: false }, { meta: { note: "grp" } });
+        const found = await acme.entries("flags", { where: { note: "grp" } });
+
+        expect(found.length).toBe(2);
+        expect(await acme.entries("flags", { where: { note: "other" } })).toEqual([]);
+    });
+});
+
+describe("rest.vars — validation", () => {
+    it("rejects a value that does not match its spec", async () => {
+        await expect(rest.vars.set("config", "maxUsers", "not-a-number")).rejects.toThrow(/maxUsers/);
+    });
+});
+
+describe("rest.vars — TTL", () => {
+    it("stores an expiry set per call", async () => {
+        await rest.vars.set("ttl", "k", "v", { ttl: "1h" });
+        const entry = await rest.vars.entry("ttl", "k");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+        expect(entry!.expiresAt!.getTime()).toBeGreaterThan(Date.now());
+    });
+
+    it("applies the variable's default TTL", async () => {
+        await rest.vars.set("config", "session", "s1"); // `session` declares ttl: '1h'
+        const entry = await rest.vars.entry("config", "session");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("`set` without ttl clears an existing one", async () => {
+        await rest.vars.set("ttl", "clear", "v", { ttl: "1h" });
+        await rest.vars.set("ttl", "clear", "v2"); // no ttl → authoritative reset
+        const entry = await rest.vars.entry("ttl", "clear");
+        expect(entry?.expiresAt).toBeNull();
+    });
+
+    it("`expire` sets / renews the TTL", async () => {
+        await rest.vars.set("ttl", "renew", "v");
+        expect(await rest.vars.expire("ttl", "renew", "30m")).toBe(true);
+        const entry = await rest.vars.entry("ttl", "renew");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("hides an expired entry from reads", async () => {
+        await raw().insertOne({
+            _id: "config:gone",
+            ns: "config", key: "gone", scope: null,
+            value: "x", meta: {},
+            expiresAt: new Date(Date.now() - 1000),
+            createdAt: new Date(), updatedAt: new Date(),
+        } as any);
+
+        expect(await rest.vars.get<string>("config", "gone")).toBeUndefined();
+        expect(await rest.vars.has("config", "gone")).toBe(false);
+        expect(await rest.vars.entry("config", "gone")).toBeUndefined();
+    });
+
+    it("rejects an invalid ttl", async () => {
+        await expect(rest.vars.set("ttl", "bad", "v", { ttl: "abc" })).rejects.toThrow(/ttl/);
+    });
+});