@anteros/core 0.0.39 → 0.0.41

package/tests/audit.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants, getTenant } from "../database/tenant";
+import {
+    AUDIT_COLLECTION,
+    LEGACY_AUDIT_COLLECTION,
+    AUDIT_TTL_INDEX,
+    migrateAuditCollection,
+    syncAuditRetention,
+} from "../database/audit";
+
+const TEST_TENANT = "audit";
+const TEST_DB = "mongodb://localhost:27017/_AUDIT_TEST";
+
+// Second tenant: proves `tenant.audit.retention` is wired end-to-end
+const TTL_TENANT = "audit-ttl";
+const TTL_DB = "mongodb://localhost:27017/_AUDIT_TTL_TEST";
+
+let rest: InstanceType<typeof useRest>;
+
+/**
+ * Latest audit entry for a (collection, action) pair.
+ *
+ * `#logActivity` is fire-and-forget, so we poll — and when the same pair was
+ * already logged by an earlier test, `since` (captured *before* the operation)
+ * makes sure we wait for the new entry instead of reading the stale one.
+ */
+async function lastActivity(collection: string, action: string, since?: Date) {
+    for (let i = 0; i < 40; i++) {
+        const found: any = await rest.db.collection(AUDIT_COLLECTION).findOne(
+            {
+                "operation.collection": collection,
+                "operation.action": action,
+                ...(since ? { ts: { $gte: since } } : {}),
+            },
+            { sort: { ts: -1 } },
+        );
+        if (found) return found;
+        await Bun.sleep(25);
+    }
+    return null;
+}
+
+/** Minimal activity document (same shape as `ActivityInput`). */
+function activity(action: string) {
+    return {
+        internal: true,
+        trace: { id: crypto.randomUUID() },
+        meta: {},
+        operation: {
+            tenant: TEST_TENANT,
+            action,
+            collection: "items",
+            status: "success",
+            input: null,
+            result: null,
+            error: null,
+            duration: 0,
+            transaction: false,
+        },
+        ts: new Date(),
+    } as any;
+}
+
+/** Index document, or undefined when absent. */
+async function index(name: string): Promise<any> {
+    return (await rest.db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+        .find((i: any) => i.name === name);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [
+            { id: TEST_TENANT, dir: "src", database: { uri: TEST_DB } },
+            { id: TTL_TENANT, dir: "src", database: { uri: TTL_DB }, audit: { retention: "7d" } },
+        ],
+    });
+    await syncTenants();
+
+    // Declared collections — needed to exercise the `$lookup` allow-list and `collectionType`
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "items",
+            fields: [{ name: "title", type: "string" }],
+            api: { access: { "*": true } },
+        },
+    ];
+    (cfg as any).fileCollections = [
+        {
+            _tenant_: TEST_TENANT,
+            _isFileCollection_: true,
+            slug: "photos",
+            fields: [{ name: "label", type: "string" }],
+            api: { access: { "*": true } },
+        },
+    ];
+
+    rest = new useRest({ internal: true, tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("items").drop(); } catch (_) {}
+    try { await rest.db.collection("photos").drop(); } catch (_) {}
+    try { await rest.db.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+    try { await rest.db.collection(LEGACY_AUDIT_COLLECTION).drop(); } catch (_) {}
+    try { await getTenant(TTL_TENANT)?.database?.db?.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+});
+
+describe("audit collection", () => {
+    it("writes to `_audit_`", async () => {
+        await rest.audit.addActivities([activity("unit")]);
+
+        const stored: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.action": "unit" });
+        expect(stored).toBeDefined();
+        expect(stored.operation.collection).toBe("items");
+    });
+
+    it("reads back through getActivities", async () => {
+        const logs = await rest.audit.getActivities({
+            $match: { "operation.action": "unit" },
+            $limit: 10,
+        } as any);
+        expect(logs.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it("does not use the legacy `_activities_` name anymore", async () => {
+        const legacy = await rest.db.listCollections({ name: LEGACY_AUDIT_COLLECTION }).toArray();
+        expect(legacy.length).toBe(0);
+    });
+
+    it("is on disk as soon as a mutation resolves (no polling needed)", async () => {
+        const doc: any = await rest.insertOne("items", { title: "awaited" });
+
+        // Deliberately **no** polling: mutations await their audit entry, so it is
+        // already there — a successful write can never lose its trace.
+        const logged: any = await rest.db.collection(AUDIT_COLLECTION).findOne({
+            "operation.action": "insertOne",
+            "operation.result._id": doc._id,
+        });
+        expect(logged).not.toBeNull();
+        expect(logged.operation.status).toBe("success");
+    });
+
+    it("accepts `_audit_` as a $lookup target from a declared collection", async () => {
+        const rows = await rest.aggregate("items", [
+            { $lookup: { from: AUDIT_COLLECTION, localField: "_id", foreignField: "_id", as: "audit" } },
+            { $limit: 1 },
+        ]);
+        expect(Array.isArray(rows)).toBe(true);
+    });
+});
+
+describe("audit collectionType", () => {
+    it("labels a document collection as `document`", async () => {
+        await rest.insertOne("items", { title: "collectionType" });
+
+        const logged = await lastActivity("items", "insertOne");
+        expect(logged).not.toBeNull();
+        expect(logged.operation.collectionType).toBe("document");
+    });
+
+    it("labels a file collection as `file`", async () => {
+        await rest.insertOne("photos", { label: "ct", _file: { filename: "ct.png" } });
+
+        const logged = await lastActivity("photos", "insertOne");
+        expect(logged).not.toBeNull();
+        expect(logged.operation.collectionType).toBe("file");
+    });
+
+    it("leaves `collectionType` undefined for an internal collection", async () => {
+        // `_audit_` is not declared anywhere — no type to report
+        const logged: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.collection": "_locks_" });
+        expect(logged?.operation?.collectionType).toBeUndefined();
+    });
+});
+
+describe("audit read operations", () => {
+    it("logs `find` with its parameters, never the result", async () => {
+        const since = new Date();
+        const docs = await rest.find("items", { $match: { title: "collectionType" }, $limit: 5 });
+        expect(docs.length).toBeGreaterThanOrEqual(1); // the read really returned data
+
+        const logged = await lastActivity("items", "find", since);
+        expect(logged).not.toBeNull();
+        expect(logged.operation.input.params).toEqual({ $match: { title: "collectionType" }, $limit: 5 });
+        expect(logged.operation.result).toBeNull();          // ← nothing returned is stored
+        expect(logged.operation.status).toBe("success");
+    });
+
+    it("logs `findOne` with the id", async () => {
+        const since = new Date();
+        const [first] = await rest.find("items", { $limit: 1 });
+        const doc: any = await rest.findOne("items", first!._id);
+        expect(doc).not.toBeNull();
+
+        const logged = await lastActivity("items", "findOne", since);
+        expect(logged.operation.input.id).toBeString();
+        expect(logged.operation.result).toBeNull();
+    });
+
+    it("logs `aggregate` with its pipeline", async () => {
+        const since = new Date();
+        const pipeline = [{ $match: { title: "collectionType" } }, { $limit: 1 }];
+        const rows = await rest.aggregate("items", pipeline);
+        expect(rows.length).toBeGreaterThanOrEqual(1);
+
+        const logged = await lastActivity("items", "aggregate", since);
+        expect(logged.operation.input.pipeline).toEqual(pipeline);
+        expect(logged.operation.result).toBeNull();
+    });
+
+    it("logs a failed read with its error and still no result", async () => {
+        const since = new Date();
+        await expect(rest.aggregate("items", [
+            { $lookup: { from: "not_declared", localField: "_id", foreignField: "_id", as: "x" } },
+        ])).rejects.toThrow();
+
+        const logged = await lastActivity("items", "aggregate", since);
+        expect(logged.operation.status).toBe("error");
+        expect(logged.operation.error.message).toBeString();
+        expect(logged.operation.result).toBeNull();
+    });
+});
+
+describe("audit query indexes", () => {
+    it("are ensured at boot", async () => {
+        const names = (await rest.db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+            .map((i: any) => i.name);
+        expect(names).toContain("_audit_ts_");
+        expect(names).toContain("_audit_collection_ts_");
+        expect(names).toContain("_audit_status_ts_");
+        expect(names).toContain("_audit_trace_");
+    });
+
+    it("serve the documented sorts and filters", async () => {
+        expect((await index("_audit_ts_")).key).toEqual({ ts: -1 });
+        expect((await index("_audit_collection_ts_")).key).toEqual({ "operation.collection": 1, ts: -1 });
+        expect((await index("_audit_status_ts_")).key).toEqual({ "operation.status": 1, ts: -1 });
+        expect((await index("_audit_trace_")).key).toEqual({ "trace.id": 1 });
+    });
+});
+
+describe("audit retention (TTL)", () => {
+    it("stays untouched — no TTL index — when retention is not configured", async () => {
+        expect(await syncAuditRetention(rest.db, undefined)).toBe("skipped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("creates a TTL index when a duration is configured", async () => {
+        expect(await syncAuditRetention(rest.db, "90d")).toBe("applied");
+
+        const ttl = await index(AUDIT_TTL_INDEX);
+        expect(ttl.key).toEqual({ ts: 1 });
+        expect(ttl.expireAfterSeconds).toBe(90 * 86400);
+    });
+
+    it("is idempotent — the same duration is a no-op", async () => {
+        expect(await syncAuditRetention(rest.db, "90d")).toBe("unchanged");
+    });
+
+    it("updates expireAfterSeconds when the duration changes", async () => {
+        expect(await syncAuditRetention(rest.db, "24h")).toBe("applied");
+        expect((await index(AUDIT_TTL_INDEX)).expireAfterSeconds).toBe(24 * 3600);
+    });
+
+    it("drops the TTL index when retention is explicitly disabled", async () => {
+        expect(await syncAuditRetention(rest.db, false)).toBe("dropped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("ignores an invalid duration", async () => {
+        expect(await syncAuditRetention(rest.db, "banana")).toBe("skipped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("is wired through `tenant.audit.retention`", async () => {
+        const db = getTenant(TTL_TENANT)!.database!.db!;
+        const ttl: any = (await db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+            .find((i: any) => i.name === AUDIT_TTL_INDEX);
+
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(7 * 86400);
+    });
+});
+
+describe("audit collection migration (`_activities_` → `_audit_`)", () => {
+    it("renames an existing legacy collection, without losing documents", async () => {
+        await rest.db.collection(AUDIT_COLLECTION).drop().catch(() => {});
+        await rest.db.collection(LEGACY_AUDIT_COLLECTION).insertOne(activity("legacy") as any);
+
+        expect(await migrateAuditCollection(rest.db)).toBe(true);
+
+        const legacy = await rest.db.listCollections({ name: LEGACY_AUDIT_COLLECTION }).toArray();
+        expect(legacy.length).toBe(0);
+
+        const moved: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.action": "legacy" });
+        expect(moved).toBeDefined();
+    });
+
+    it("is idempotent — a second run is a no-op", async () => {
+        expect(await migrateAuditCollection(rest.db)).toBe(false);
+    });
+
+    it("never touches the legacy collection when `_audit_` already exists", async () => {
+        await rest.db.collection(AUDIT_COLLECTION).insertOne(activity("keep") as any);
+        await rest.db.collection(LEGACY_AUDIT_COLLECTION).insertOne(activity("orphan") as any);
+
+        expect(await migrateAuditCollection(rest.db)).toBe(false);
+
+        // neither merged nor dropped — both collections survive untouched
+        expect(await rest.db.collection(AUDIT_COLLECTION).countDocuments({ "operation.action": "orphan" })).toBe(0);
+        expect(await rest.db.collection(LEGACY_AUDIT_COLLECTION).countDocuments({})).toBe(1);
+    });
+});

package/tests/crypto.test.ts

@@ -62,7 +62,7 @@ describe("crypto — symmetric AES-256-GCM", () => {
 
     it("decrypt(cipher, true, fields) decrypts the listed sub-fields inside the JSON", async () => {
         const c = useSymCrypt({ secret: "s" });
-        // json contenant des sous-champs chiffrés (convention field-level : JSON.stringify)
+        // json containing encrypted sub-fields (field-level convention: JSON.stringify)
         const encZip = await c.encrypt(JSON.stringify("75000"));
         const encPhone = await c.encrypt(JSON.stringify("0600000000"));
         const container = await c.encrypt({ city: "Paris", zip: encZip, contact: { phone: encPhone } });
@@ -72,7 +72,7 @@ describe("crypto — symmetric AES-256-GCM", () => {
         expect(dec.zip).toBe("75000");
         expect(dec.contact.phone).toBe("0600000000");
 
-        // sans les champs → sous-champs toujours chiffrés
+        // without the fields → sub-fields stay encrypted
         const raw = await c.decrypt<any>(container, true);
         expect(raw.zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(raw.city).toBe("Paris");
@@ -94,7 +94,7 @@ describe("crypto — symmetric AES-256-GCM", () => {
         const json = { city: "Paris", note: "plain text", zip: await c.encrypt(JSON.stringify("75000")) };
         const dec = await c.decrypt<any>(json, true, ["zip", "note", "missing"]);
         expect(dec.city).toBe("Paris");
-        expect(dec.note).toBe("plain text"); // pas un ciphertext → inchangé
+        expect(dec.note).toBe("plain text"); // not a ciphertext → kept as-is
         expect(dec.zip).toBe("75000");
     });
 
@@ -103,7 +103,7 @@ describe("crypto — symmetric AES-256-GCM", () => {
         const encZip = await c.encrypt(JSON.stringify("69001"));
         const encOther = await c.encrypt(JSON.stringify("69002"));
 
-        // array conteneur direct (ex: doc.addresses renvoyé par une requête)
+        // direct array container (e.g. doc.addresses returned by a query)
         const arr = [
             { city: "Lyon", zip: encZip },
             { city: "Villeurbanne", zip: encOther },
@@ -111,11 +111,11 @@ describe("crypto — symmetric AES-256-GCM", () => {
         const dec = await c.decrypt<any>(arr, true, ["zip"]);
         expect(dec[0].zip).toBe("69001");
         expect(dec[1].zip).toBe("69002");
-        expect(dec[0].city).toBe("Lyon"); // non-chiffré conservé
-        expect(dec).not.toBe(arr); // copie, pas de mutation
+        expect(dec[0].city).toBe("Lyon"); // non-encrypted value kept
+        expect(dec).not.toBe(arr); // copy, no mutation
         expect(arr[0]!.zip).toMatch(/^[A-Za-z0-9+/=]+$/); // input intact
 
-        // ciphertext dont le plaintext est un array de json
+        // ciphertext whose plaintext is an array of json
         const encContainer = await c.encrypt([{ zip: encZip }, { zip: encOther }]);
         const dec2 = await c.decrypt<any>(encContainer, true, ["zip"]);
         expect(dec2[0].zip).toBe("69001");
@@ -125,10 +125,10 @@ describe("crypto — symmetric AES-256-GCM", () => {
 
 describe("crypto — key rotation (versioned secrets)", () => {
     it("decrypts old ciphertexts after rotating the secret", async () => {
-        const old = useSymCrypt({ secret: "v1-secret" }); // version 1 par défaut
+        const old = useSymCrypt({ secret: "v1-secret" }); // version 1 by default
         const enc = await old.encrypt({ apiKey: "sk-rot" });
 
-        // Rotation : nouvelle clé active v2, l'ancienne conservée en decrypt-only
+        // Rotation: new active key v2, the old one kept for decrypt-only
         const rotated = useSymCrypt({ secret: "v2-secret", version: 2, previousSecrets: { 1: "v1-secret" } });
         const dec = await rotated.decrypt<{ apiKey: string }>(enc, true);
         expect(dec.apiKey).toBe("sk-rot");
@@ -139,7 +139,7 @@ describe("crypto — key rotation (versioned secrets)", () => {
         const enc = await c.encrypt("data");
         const buf = Buffer.from(enc, "base64");
         expect(buf[0]).toBe(2);
-        // round-trip avec la même instance
+        // round-trip with the same instance
         const dec = await c.decrypt(enc);
         expect(dec).toBe("data");
     });
@@ -147,7 +147,7 @@ describe("crypto — key rotation (versioned secrets)", () => {
     it("still decrypts legacy ciphertexts (no version byte)", async () => {
         const c = useSymCrypt({ secret: "s" });
         const enc = await c.encrypt("legacy");
-        // Simule un ciphertext produit AVANT la rotation (format sans octet de version)
+        // Simulates a ciphertext produced BEFORE the rotation (format without a version byte)
         const legacy = Buffer.from(Buffer.from(enc, "base64").subarray(1)).toString("base64");
         const dec = await c.decrypt(legacy);
         expect(dec).toBe("legacy");
@@ -164,11 +164,11 @@ describe("crypto — key rotation (versioned secrets)", () => {
         const c = useSymCrypt({ secret: "s", aad: "myapp:prod" });
         const enc = await c.encrypt({ apiKey: "sk-aad" });
 
-        // même instance → OK (défaut appliqué au decrypt aussi)
+        // same instance → OK (default applied on decrypt too)
         const dec = await c.decrypt<{ apiKey: string }>(enc, true);
         expect(dec.apiKey).toBe("sk-aad");
 
-        // sans l'AAD config → échec (tag invalide)
+        // without the config AAD → fails (invalid tag)
         const other = useSymCrypt({ secret: "s" });
         await expect(other.decrypt(enc, true)).rejects.toThrow();
     });
@@ -178,15 +178,15 @@ describe("crypto — key rotation (versioned secrets)", () => {
         const enc = await c.encrypt("x", "explicit:ctx");
         const dec = await c.decrypt(enc, false, "explicit:ctx");
         expect(dec).toBe("x");
-        // le défaut ne déchiffre pas le chiffré lié à l'explicite
+        // the default cannot decrypt the ciphertext bound to the explicit AAD
         await expect(c.decrypt(enc, false, "default:ctx")).rejects.toThrow();
     });
 
     it("legacy ciphertexts (no AAD) still decrypt after a default AAD is configured", async () => {
-        const legacy = useSymCrypt({ secret: "s" }); // chiffré SANS AAD (ancien comportement)
+        const legacy = useSymCrypt({ secret: "s" }); // encrypted WITHOUT AAD (legacy behavior)
         const enc = await legacy.encrypt("old-data");
 
-        const c = useSymCrypt({ secret: "s", aad: "myapp:prod" }); // config avec AAD par défaut
+        const c = useSymCrypt({ secret: "s", aad: "myapp:prod" }); // config with a default AAD
         const dec = await c.decrypt(enc);
         expect(dec).toBe("old-data");
     });
@@ -223,7 +223,7 @@ describe("crypto — encryption mode (server.encryption.mode)", () => {
     it("resolve() returns the instance matching the configured mode", async () => {
         delete (cfg.server as any).encryption;
         formatConfig({ server: { port: 4000 }, tenants: [] });
-        const priv = await useAsymCrypt().exportPrivateKey(); // pair fraîche, pas de mode config
+        const priv = await useAsymCrypt().exportPrivateKey(); // fresh pair, no configured mode
 
         delete (cfg.server as any).encryption;
         formatConfig({ server: { port: 4000, encryption: { mode: "symmetric", secret: "cfg" } }, tenants: [] });

package/tests/db-cache.test.ts

@@ -152,10 +152,10 @@ describe("DB query cache (useCache)", () => {
         const r1: any = await rest.find("items", params, { useCache: true });
         expect(r1[0]!.count).toBe(1);
 
-        // update avec un ObjectId NATIF (pas un string) — la normalisation String(id) doit matcher l'index
+        // update with a NATIVE ObjectId (not a string) — String(id) normalization must match the index
         await rest.updateOne("items", new ObjectId(a._id), { $set: { count: 77 } });
         const r2: any = await rest.find("items", params, { useCache: true });
-        expect(r2[0]!.count).toBe(77); // invalidé + refetch
+        expect(r2[0]!.count).toBe(77); // invalidated + refetch
 
         await rest.db.collection("items").deleteMany({ title: marker });
     });
@@ -168,15 +168,15 @@ describe("DB query cache (useCache)", () => {
         const b = await rest.insertOne("items", { title: marker, count: 2 });
         const c = await rest.insertOne("items", { title: marker, count: 3 });
 
-        const params = { $match: { title: marker }, $sort: { count: 1 } }; // ordre garanti: a(1), b(2), c(3)
-        await rest.find("items", params, { useCache: true }); // cache peuplé (3 docs)
+        const params = { $match: { title: marker }, $sort: { count: 1 } }; // guaranteed order: a(1), b(2), c(3)
+        await rest.find("items", params, { useCache: true }); // cache populated (3 docs)
 
-        // le 3e id (c) n'est PAS taggé (maxTags: 2) → pas d'invalidation ciblée
+        // the 3rd id (c) is NOT tagged (maxTags: 2) → no targeted invalidation
         await rest.updateOne("items", c._id, { $set: { count: 33 } });
         const r1: any = await rest.find("items", params, { useCache: true });
-        expect(r1.find((d: any) => d._id === c._id)!.count).toBe(3); // cache conservé
+        expect(r1.find((d: any) => d._id === c._id)!.count).toBe(3); // cache kept
 
-        // le 1er id (a) est taggé → invalidation ciblée
+        // the 1st id (a) is tagged → targeted invalidation
         await rest.updateOne("items", a._id, { $set: { count: 11 } });
         const r2: any = await rest.find("items", params, { useCache: true });
         expect(r2.find((d: any) => d._id === a._id)!.count).toBe(11); // refetch

package/tests/field-encryption.test.ts

@@ -24,12 +24,12 @@ beforeAll(async () => {
     await syncCollections();
     (cfg as any).collections = [encCollection([
         { name: "name", type: "string" },
-        { name: "ssn", type: "string", encryption: true },           // champ chiffré
-        { name: "profile", type: "json", encryption: true },          // objet chiffré
+        { name: "ssn", type: "string", encryption: true },           // whole value encrypted
+        { name: "profile", type: "json", encryption: true },          // whole json encrypted
         { name: "age", type: "number" },
-        { name: "address", type: "json", encryptionOptions: { path: "zip" } },          // json : seul address.zip est chiffré
-        { name: "contacts", type: "json", encryptionOptions: { path: ["phone", "email"] } }, // plusieurs chemins
-        { name: "addresses", type: "json", encryptionOptions: { path: "zip" } },        // array de json
+        { name: "address", type: "json", encryptionOptions: { path: "zip" } },          // json: only address.zip encrypted
+        { name: "contacts", type: "json", encryptionOptions: { path: ["phone", "email"] } }, // several paths
+        { name: "addresses", type: "json", encryptionOptions: { path: "zip" } },        // array of json
     ])];
     rest = new useRest({ internal: false, tenant_id: TENANT });
 });
@@ -44,35 +44,35 @@ describe("field-level encryption", () => {
     it("insert stores ciphertext in Mongo but returns plaintext", async () => {
         const doc: any = await rest.insertOne("patients", { name: "John", ssn: "123-45-6789", profile: { city: "Paris", zip: 75000 }, age: 42 });
 
-        // réponse API = plaintext
+        // API response = plaintext
         expect(doc.ssn).toBe("123-45-6789");
         expect(doc.profile).toEqual({ city: "Paris", zip: 75000 });
 
-        // en base = ciphertext (version byte + IV + data)
+        // in Mongo = ciphertext (version byte + IV + data)
         const raw = await rest.db.collection("patients").findOne({ _id: new ObjectId(doc._id) });
         expect(raw).not.toBeNull();
         expect(raw!.ssn).not.toBe("123-45-6789");
         expect(typeof raw!.ssn).toBe("string");
         expect(raw!.ssn).toMatch(/^[A-Za-z0-9+/=]+$/); // base64
         expect(raw!.profile).not.toEqual({ city: "Paris" });
-        // champ non chiffré intact
+        // non-encrypted field untouched
         expect(raw!.name).toBe("John");
         expect(raw!.age).toBe(42);
     });
 
     it("find / findOne return ciphertext (no decrypt on output)", async () => {
         const list: any = await rest.find("patients", { $match: { name: "John" } });
-        // lecture = ciphertext (jamais décrypté automatiquement)
+        // read = ciphertext (never decrypted automatically)
         expect(list[0].ssn).not.toBe("123-45-6789");
         expect(list[0].ssn).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(list[0].profile).not.toEqual({ city: "Paris", zip: 75000 });
-        // champs non chiffrés intacts
+        // non-encrypted fields untouched
         expect(list[0].name).toBe("John");
 
         const one: any = await rest.findOne("patients", list[0]._id);
         expect(one.ssn).toMatch(/^[A-Za-z0-9+/=]+$/);
 
-        // décryptage MANUEL explicite (utils.crypt.resolve())
+        // explicit MANUAL decryption (utils.crypt.resolve())
         const cipher = resolve();
         const dec = await cipher.decrypt<string>(one.ssn, true);
         expect(dec).toBe("123-45-6789");
@@ -82,10 +82,10 @@ describe("field-level encryption", () => {
         const doc: any = await rest.findOne("patients", (await rest.find("patients", { $match: { name: "John" } }))[0]!._id);
         const updated: any = await rest.updateOne("patients", doc._id, { $set: { ssn: "987-65-4321" } });
 
-        // retour = ciphertext (plus de décryptage automatique)
+        // response = ciphertext (no automatic decryption anymore)
         expect(updated.ssn).not.toBe("987-65-4321");
         expect(updated.ssn).toMatch(/^[A-Za-z0-9+/=]+$/);
-        // base = nouveau ciphertext
+        // stored = new ciphertext
         const raw = await rest.db.collection("patients").findOne({ _id: new ObjectId(doc._id) });
         expect(raw).not.toBeNull();
         expect(raw!.ssn).not.toBe("987-65-4321");
@@ -99,17 +99,17 @@ describe("field-level encryption", () => {
         const raw = await rest.db.collection("patients").find({ name: { $in: ["A", "B"] } }).toArray();
         for (const r of raw) expect(r.ssn).toMatch(/^[A-Za-z0-9+/=]+$/);
         const list: any = await rest.find("patients", { $match: { name: { $in: ["A", "B"] } } });
-        // lecture = ciphertext, décrypté manuellement
+        // read = ciphertext, decrypted manually
         for (const d of list) expect(d.ssn).toMatch(/^[A-Za-z0-9+/=]+$/);
     });
 
     it("rejects operators that cannot work on ciphertext ($inc on an encrypted field)", async () => {
         const doc: any = await rest.findOne("patients", (await rest.find("patients", { $match: { name: "John" } }))[0]!._id);
         await expect(
-            rest.updateOne("patients", doc._id, { $set: { ssn: "x" }, $inc: { age: 1 } }) // $inc sur age (non chiffré) OK
+            rest.updateOne("patients", doc._id, { $set: { ssn: "x" }, $inc: { age: 1 } }) // $inc on age (not encrypted) OK
         ).resolves.toBeTruthy();
         await expect(
-            rest.updateOne("patients", doc._id, { $set: { ssn: "y" }, $inc: { ssn: 1 } as any }) // $inc sur champ chiffré → rejeté
+            rest.updateOne("patients", doc._id, { $set: { ssn: "y" }, $inc: { ssn: 1 } as any }) // $inc on an encrypted field → rejected
         ).rejects.toThrow(/ENCRYPTED_FIELD_OPERATOR|not supported/);
     });
 
@@ -119,7 +119,7 @@ describe("field-level encryption", () => {
         await expect(rest.insertOne("patients", { name: "NoCfg", ssn: "000-00-0000" }))
             .rejects.toThrow(/ENCRYPTION_NOT_CONFIGURED|server\.encryption/);
 
-        // restore config pour les tests suivants
+        // restore the config for the following tests
         formatConfig({ server: { port: 4000, encryption: { mode: "symmetric", secret: "field-enc-secret" } }, tenants: [] });
     });
 });
@@ -130,22 +130,22 @@ describe("field-level encryption — encryptionOptions.path (json sub-paths)", (
             name: "Alice",
             address: { street: "Rue X", city: "Paris", zip: "75000" },
         });
-        // réponse = plaintext partout
+        // response = plaintext everywhere
         expect(doc.address.zip).toBe("75000");
         expect(doc.address.city).toBe("Paris");
 
-        // en base : seul zip est ciphertext, le reste est en clair
+        // in Mongo: only zip is ciphertext, the rest stays in clear
         const raw = await rest.db.collection("patients").findOne({ _id: new ObjectId(doc._id) });
         expect(raw!.address.zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(raw!.address.city).toBe("Paris");
         expect(raw!.address.street).toBe("Rue X");
 
-        // lecture rest = ciphertext au path, plaintext ailleurs
+        // rest read = ciphertext at the path, plaintext elsewhere
         const list: any = await rest.find("patients", { $match: { name: "Alice" } });
         expect(list[0].address.zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(list[0].address.city).toBe("Paris");
 
-        // décryptage manuel
+        // manual decryption
         const cipher = resolve();
         const zip = await cipher.decrypt<string>(list[0].address.zip, true);
         expect(zip).toBe("75000");
@@ -158,10 +158,10 @@ describe("field-level encryption — encryptionOptions.path (json sub-paths)", (
             addresses: [{ zip: "69001" }, { zip: "69002", city: "Lyon" }],
         });
         const raw = await rest.db.collection("patients").findOne({ _id: new ObjectId(doc._id) });
-        // array de json : chaque élément chiffré sur son zip
+        // array of json: every element encrypted on its zip
         expect(raw!.addresses[0].zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(raw!.addresses[1].zip).toMatch(/^[A-Za-z0-9+/=]+$/);
-        expect(raw!.addresses[1].city).toBe("Lyon"); // non-chiffré intact
+        expect(raw!.addresses[1].city).toBe("Lyon"); // non-encrypted value untouched
         // multiple paths
         expect(raw!.contacts.phone).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(raw!.contacts.email).toMatch(/^[A-Za-z0-9+/=]+$/);
@@ -171,12 +171,12 @@ describe("field-level encryption — encryptionOptions.path (json sub-paths)", (
     it("encrypts the path on $set replacement and dot-notation $set", async () => {
         const doc: any = await rest.findOne("patients", (await rest.find("patients", { $match: { name: "Alice" } }))[0]!._id);
 
-        // $set du json complet → zip re-chiffré dans le remplacement
+        // $set of the whole json → zip re-encrypted inside the replacement
         const up1: any = await rest.updateOne("patients", doc._id, { $set: { address: { city: "Nice", zip: "06000" } } });
         expect(up1.address.zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         expect(up1.address.city).toBe("Nice");
 
-        // dot-notation $set sur le path exact → valeur chiffrée
+        // dot-notation $set on the exact path → value encrypted
         const up2: any = await rest.updateOne("patients", doc._id, { $set: { "address.zip": "06100" } });
         expect(up2.address.zip).toMatch(/^[A-Za-z0-9+/=]+$/);
         const raw = await rest.db.collection("patients").findOne({ _id: new ObjectId(doc._id) });