@anteros/core 0.0.40 → 0.0.42

package/tests/replication.test.ts

@@ -0,0 +1,188 @@
+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 {
+    startReplication,
+    stopReplication,
+    replicateTenant,
+    getReplicationState,
+} from "../database/replication";
+
+const TEST_TENANT = "repl";
+const SRC_DB = "mongodb://localhost:27017/_REPL_TEST_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_TEST_DEST";
+const DEST_ID = "backup";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "src",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: DEST_ID, uri: DEST_DB }],
+            },
+        }],
+    });
+
+    // Connect the source DB manually with a short timeout so a missing MongoDB
+    // fails fast and clearly (instead of hanging or process.exit(1)).
+    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();
+
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "orders",
+            fields: [
+                { name: "title", type: "string" },
+                { name: "status", type: "string" },
+                { name: "customer", type: "relationship", relation: { to: "customers" } },
+                { name: "paidAt", type: "date" },
+            ],
+            replication: { enabled: true },
+        },
+    ];
+
+    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 (_) {}
+});
+
+describe("replication", () => {
+    it("replicates inserted documents", async () => {
+        const marker = `ins-${crypto.randomUUID()}`;
+        const source: any = await rest.insertOne("orders", { title: marker, status: "new" });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect((dest as any)?.status).toBe("new");
+        // The destination keeps the **same `_id`** (the upsert is keyed on it), same BSON type
+        expect((dest as any)?._id.toString()).toBe(source._id);
+        expect((dest as any)?._id).toBeInstanceOf(ObjectId);
+    });
+
+    it("keeps a custom `_id` type (string) as-is", async () => {
+        const marker = `custom-${crypto.randomUUID()}`;
+        const customId = `order-${crypto.randomUUID()}`; // not a 24-hex string
+        await sourceClient.db().collection("orders").insertOne({
+            _id: customId as any,
+            title: marker,
+            status: "new",
+            updatedAt: new Date(),
+        });
+        await replicateTenant(TEST_TENANT);
+
+        const dest: any = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect(dest._id).toBe(customId);
+        expect(typeof dest._id).toBe("string");
+    });
+
+    it("writes BSON types on the destination — ObjectId relations and Dates stay typed", async () => {
+        const marker = `bson-${crypto.randomUUID()}`;
+        const customerId = new ObjectId();
+        const paidAt = new Date("2026-03-04T05:06:07.000Z");
+
+        // Through the framework: the relation string and the ISO date are converted
+        // to BSON by `toBson` before hitting MongoDB.
+        const source: any = await rest.insertOne("orders", {
+            title: marker,
+            status: "paid",
+            customer: customerId.toHexString(),
+            paidAt: paidAt.toISOString(),
+        });
+        await replicateTenant(TEST_TENANT);
+
+        // …and the destination must hold the same BSON types, not strings
+        const dest: any = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect(dest._id).toBeInstanceOf(ObjectId);
+        expect(dest._id.toString()).toBe(source._id);
+        expect(dest.customer).toBeInstanceOf(ObjectId);
+        expect(dest.customer.toString()).toBe(customerId.toHexString());
+        expect(dest.paidAt).toBeInstanceOf(Date);
+        expect(dest.paidAt.getTime()).toBe(paidAt.getTime());
+        expect(dest.createdAt).toBeInstanceOf(Date);
+        expect(dest.updatedAt).toBeInstanceOf(Date);
+
+        // The source itself stores the very same types (the copy is faithful)
+        const raw: any = await sourceClient.db().collection("orders").findOne({ title: marker });
+        expect(raw.customer).toBeInstanceOf(ObjectId);
+        expect(raw.paidAt).toBeInstanceOf(Date);
+        expect(typeof raw.customer).toBe(typeof dest.customer);
+    });
+
+    it("replicates updates", async () => {
+        const marker = `upd-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker, status: "draft" });
+        await replicateTenant(TEST_TENANT);
+
+        await rest.updateOne("orders", doc._id, { $set: { status: "paid" } });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect((dest as any)?.status).toBe("paid");
+    });
+
+    it("replicates deletes via tombstone", async () => {
+        const marker = `del-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker, status: "x" });
+        await replicateTenant(TEST_TENANT);
+
+        const before = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(before).toBeDefined();
+
+        await rest.deleteOne("orders", doc._id);
+        await replicateTenant(TEST_TENANT);
+
+        const after = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(after).toBeNull();
+    });
+
+    it("does not re-copy unchanged documents (cursor is persisted)", async () => {
+        const marker = `resume-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker, status: "new" });
+
+        const first = await replicateTenant(TEST_TENANT);
+        const second = await replicateTenant(TEST_TENANT);
+
+        const r1 = first.find((r) => r.collection === "orders" && r.destination === DEST_ID);
+        const r2 = second.find((r) => r.collection === "orders" && r.destination === DEST_ID);
+        expect(r1?.inserted).toBeGreaterThanOrEqual(1);
+        expect(r2?.inserted).toBe(0);
+        expect(r2?.updated).toBe(0);
+    });
+
+    it("stores state in _replication_", async () => {
+        await rest.insertOne("orders", { title: `state-${crypto.randomUUID()}`, status: "new" });
+        await replicateTenant(TEST_TENANT);
+
+        const state = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(state.length).toBe(1);
+        expect(state[0]!.status).toBe("success");
+        expect(state[0]!.cursor).toBeDefined();
+    });
+});

package/tests/upload.test.ts

@@ -1,9 +1,11 @@
 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";
+import { createApi } from "../lib/api";
 
 const TENANT = "up-test";
 const DB = "mongodb://localhost:27017/_DB_UP_TEST";
@@ -25,7 +27,7 @@ beforeAll(async () => {
         _tenant_: TENANT,
         _isFileCollection_: true,
         slug: SLUG,
-        fields: [{ name: "label", type: "string" }],
+        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 } },
@@ -56,13 +58,72 @@ function pngFile(name: string) {
     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}/api/${TENANT}/upload/${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}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form })
+        ).json();
+
+        const res = await fetch(`${url}/api/${TENANT}/files/${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 });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
 
         const body: any = await res.json();
@@ -70,18 +131,25 @@ describe("upload — single file (unchanged contract)", () => {
         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._file.url).toContain(`/api/${TENANT}/files/${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 });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
         const body: any = await res.json();
         expect(Array.isArray(body)).toBe(false);
@@ -97,7 +165,7 @@ describe("upload — multiple files", () => {
         form.append("file", pngFile("c.png"));
         form.append("label", "batch");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(200);
 
         const body: any = await res.json();
@@ -111,7 +179,10 @@ describe("upload — multiple files", () => {
         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}/`);
+            expect(doc._file.url).toContain(`/api/${TENANT}/files/${SLUG}/`);
+            // Uploads carry timestamps (required by the replication cursor)
+            expect(doc.createdAt).toBeString();
+            expect(doc.updatedAt).toBeString();
         }
     });
 
@@ -119,7 +190,7 @@ describe("upload — multiple files", () => {
         const form = new FormData();
         form.append("label", "nofile");
 
-        const res = await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST", body: form });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form });
         expect(res.status).toBe(400);
         const body: any = await res.json();
         expect(body.code).toBe("FILE_REQUIRED");
@@ -130,9 +201,71 @@ describe("upload — multiple files", () => {
         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 });
+        const res = await fetch(`${url}/api/${TENANT}/upload/${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}/api/${TENANT}/upload/${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}/api/${TENANT}/upload/${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");
+    });
+});
+
+describe("api.files — the in-process facade", () => {
+    it("builds a file URL, with the transformations the route understands", () => {
+        const api = createApi(rest);
+
+        expect(api.files.url(SLUG, "f1.png")).toBe(`/api/${TENANT}/files/${SLUG}/f1.png`);
+        expect(api.files.url(SLUG, "f1.png", { width: 200, format: "webp" }))
+            .toBe(`/api/${TENANT}/files/${SLUG}/f1.png?w=200&format=webp`);
+        expect(api.files.url(SLUG, "f1.png", { width: 200, height: 100, format: "avif", quality: 70 }))
+            .toBe(`/api/${TENANT}/files/${SLUG}/f1.png?w=200&h=100&format=avif&q=70`);
+    });
+
+    it("deletes the binary and the document — the same path as the route", async () => {
+        const form = new FormData();
+        form.append("file", pngFile("to-delete.png"));
+        const uploaded: any = await (
+            await fetch(`${url}/api/${TENANT}/upload/${SLUG}`, { method: "POST", body: form })
+        ).json();
+
+        const fs = await import("node:fs/promises");
+        const storage = getFileCollection(SLUG, TENANT)?.storage as any;
+        const dir = `${process.cwd()}/${storage?.path ?? "storage"}/${TENANT}/${SLUG}`;
+        expect((await fs.readdir(dir)).some((name) => name.startsWith(uploaded._id))).toBe(true);
+
+        const result = await createApi(rest).files.delete(SLUG, uploaded._id);
+
+        expect(result).toEqual({ message: "File deleted", ok: true });
+        expect(await rest.findOne(SLUG, uploaded._id)).toBeNull();
+        expect((await fs.readdir(dir)).some((name) => name.startsWith(uploaded._id))).toBe(false);
+    });
+});

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}/api/${TENANT}/vars/${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,96 @@
+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 opt out (`enabled: false`)", async () => {
+        // `private.var.ts` declares `replication: { enabled: false }` — 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();
+    });
+});