@frogfish/k2db 3.0.1 → 3.0.2

package/db.js

@@ -1,8 +1,7 @@
 // src/db.ts
 import { K2Error, ServiceError, wrap } from "@frogfish/k2error"; // Keep the existing error structure
 import { MongoClient, } from "mongodb";
-import { randomBytes, createHash } from "crypto";
-// import debugLib from "debug";
+import { randomBytes, createHash, createCipheriv, createDecipheriv } from "crypto";
 import { Topic } from '@frogfish/ratatouille';
 import { z } from "zod";
 // const debug = debugLib("k2:db");
@@ -157,8 +156,74 @@ export class K2DB {
     initialized = false;
     initPromise;
     schemas = new Map();
+    ownershipMode;
+    aggregationMode;
+    secureFieldPrefixes;
+    secureFieldEncryptionKey;
+    secureFieldEncryptionKeyId;
     constructor(conf) {
         this.conf = conf;
+        this.ownershipMode = conf.ownershipMode ?? "lax";
+        this.aggregationMode = conf.aggregationMode ?? "loose";
+        this.secureFieldPrefixes = (conf.secureFieldPrefixes ?? [])
+            .map((p) => (typeof p === "string" ? p.trim() : ""))
+            .filter((p) => !!p);
+        const keyB64 = (conf.secureFieldEncryptionKey ?? "").trim();
+        const kid = (conf.secureFieldEncryptionKeyId ?? "").trim();
+        this.secureFieldEncryptionKeyId = kid || undefined;
+        if (keyB64) {
+            let keyBuf;
+            try {
+                keyBuf = Buffer.from(keyB64, "base64");
+            }
+            catch (e) {
+                throw new K2Error(ServiceError.CONFIGURATION_ERROR, "secureFieldEncryptionKey must be base64-encoded", "sys_mdb_secure_key_invalid");
+            }
+            if (keyBuf.length !== 32) {
+                throw new K2Error(ServiceError.CONFIGURATION_ERROR, "secureFieldEncryptionKey must decode to 32 bytes (AES-256)", "sys_mdb_secure_key_invalid");
+            }
+            this.secureFieldEncryptionKey = keyBuf;
+        }
+    }
+    /**
+     * Normalize a scope value for ownership enforcement.
+     */
+    normalizeScope(scope) {
+        if (scope === undefined || scope === null)
+            return undefined;
+        if (typeof scope !== "string")
+            return undefined;
+        const s = scope.trim();
+        if (!s)
+            return undefined;
+        if (s === "*")
+            return "*";
+        return s.toLowerCase();
+    }
+    /**
+     * Apply a scope constraint to criteria for ownership enforcement.
+     */
+    applyScopeToCriteria(criteria, scope) {
+        const normalizedScope = this.normalizeScope(scope);
+        // Strict mode requires an explicit scope per call.
+        if (this.ownershipMode === "strict" && !normalizedScope) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Scope is required in strict ownership mode", "sys_mdb_scope_required");
+        }
+        // Lax mode with no scope: legacy behavior (no owner constraint injected).
+        if (!normalizedScope)
+            return criteria;
+        // Explicit all-scope request: do not constrain by _owner.
+        if (normalizedScope === "*")
+            return criteria;
+        // If caller already provided _owner in criteria, ensure it matches the scope to avoid ambiguity/bypass.
+        if (criteria && typeof criteria === "object" && Object.prototype.hasOwnProperty.call(criteria, "_owner")) {
+            const existing = criteria._owner;
+            if (typeof existing === "string" && existing.trim().toLowerCase() !== normalizedScope) {
+                throw new K2Error(ServiceError.BAD_REQUEST, "Conflicting _owner in criteria and provided scope", "sys_mdb_scope_conflict");
+            }
+            // If it matches (or is non-string), prefer the explicit scope value.
+        }
+        return { ...(criteria || {}), _owner: normalizedScope };
     }
     /**
      * Initializes the MongoDB connection.
@@ -277,45 +342,81 @@ export class K2DB {
             throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_gc", `Error getting collection: ${collectionName}`);
         }
     }
-    async get(collectionName, uuid) {
+    /**
+     * Retrieves a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param uuid - UUID of the document.
+     * @param scope - (optional) Owner selector; "*" means all owners.
+     */
+    async get(collectionName, uuid, scope) {
         const id = K2DB.normalizeId(uuid);
+        // Note: findOne() decrypts secure-prefixed fields for single-record reads when encryption is enabled.
         const res = await this.findOne(collectionName, {
             _uuid: id,
             _deleted: { $ne: true },
-        });
+        }, undefined, scope);
         if (!res) {
             throw new K2Error(ServiceError.NOT_FOUND, "Document not found", "sys_mdb_get_not_found");
         }
         return res;
     }
     /**
-     * Retrieves a single document by UUID.
+     * Retrieves a single document by criteria.
      * @param collectionName - Name of the collection.
-     * @param uuid - UUID of the document.
-     * @param objectTypeName - Optional object type name.
+     * @param criteria - Criteria to find the document.
      * @param fields - Optional array of fields to include.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async findOne(collectionName, criteria, fields) {
+    async findOne(collectionName, criteria, fields, scope) {
         const collection = await this.getCollection(collectionName);
         const projection = {};
         // Exclude soft-deleted documents by default unless caller specifies otherwise
         const normalizedCriteria = K2DB.normalizeCriteriaIds(criteria || {});
-        const query = {
+        let query = {
             ...normalizedCriteria,
             ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                 ? {}
                 : { _deleted: { $ne: true } }),
         };
-        if (fields && fields.length > 0) {
-            fields.forEach((field) => {
-                projection[field] = 1;
+        query = this.applyScopeToCriteria(query, scope);
+        // If a projection is requested, forbid explicitly projecting secure-prefixed fields.
+        // Also ensure _uuid is fetched when secure encryption is enabled so decryption AAD is correct.
+        const requestedFields = Array.isArray(fields) ? fields.slice() : undefined;
+        if (requestedFields && requestedFields.length > 0) {
+            requestedFields.forEach((field) => {
+                if (typeof field !== "string")
+                    return;
+                const f = field.trim();
+                if (!f)
+                    return;
+                // Deny any projection that includes secure-prefixed fields (including nested dotted paths)
+                if (this.pathHasSecureSegment(f)) {
+                    throw new K2Error(ServiceError.BAD_REQUEST, "Projection cannot include secure-prefixed field(s)", "sys_mdb_projection_secure_field");
+                }
+                projection[f] = 1;
             });
+            // Ensure we can decrypt secure fields that are present in the returned doc
+            if (this.hasSecureEncryption()) {
+                projection["_uuid"] = 1;
+            }
         }
         try {
             const item = await this.runTimed("findOne", { collectionName, query, projection }, async () => await collection.findOne(query, { projection }));
             if (item) {
                 const { _id, ...rest } = item;
-                return rest;
+                const out = rest;
+                const aadBase = out._uuid
+                    ? `k2db|${collectionName}|${out._uuid}`
+                    : `k2db|${collectionName}`;
+                const decrypted = this.decryptSecureFieldsDeep(out, aadBase);
+                // If caller requested a projection and did NOT request _uuid, hide it again (it may have been added for decrypt AAD).
+                if (requestedFields && requestedFields.length > 0) {
+                    const wantsUuid = requestedFields.some((f) => typeof f === "string" && f.trim() === "_uuid");
+                    if (!wantsUuid) {
+                        delete decrypted._uuid;
+                    }
+                }
+                return decrypted;
             }
             return null;
         }
@@ -330,12 +431,14 @@ export class K2DB {
      * @param params - Optional search parameters (for sorting, including/excluding fields).
      * @param skip - Number of documents to skip (for pagination).
      * @param limit - Maximum number of documents to return.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async find(collectionName, filter, params = {}, skip = 0, limit = 100) {
+    async find(collectionName, filter, params = {}, skip = 0, limit = 100, scope) {
         const collection = await this.getCollection(collectionName);
         // Ensure filter is valid, defaulting to an empty object
         let criteria = { ...(filter || {}) };
         criteria = K2DB.normalizeCriteriaIds(criteria);
+        criteria = this.applyScopeToCriteria(criteria, scope);
         // Handle the _deleted field if params specify not to include deleted documents
         if (!params?.includeDeleted && !Object.prototype.hasOwnProperty.call(criteria, "_deleted")) {
             if (params?.deleted === true) {
@@ -353,7 +456,14 @@ export class K2DB {
         else if (Array.isArray(params.filter)) {
             projection = {};
             params.filter.forEach((field) => {
-                projection[field] = 1; // Only include the specified fields
+                const f = typeof field === "string" ? field.trim() : "";
+                if (!f)
+                    return;
+                // Deny any projection that includes secure-prefixed fields (including nested dotted paths)
+                if (this.pathHasSecureSegment(f)) {
+                    throw new K2Error(ServiceError.BAD_REQUEST, "Projection cannot include secure-prefixed field(s)", "sys_mdb_projection_secure_field");
+                }
+                projection[f] = 1; // Only include the specified fields
             });
             projection._id = 0; // Hide _id when using include list
         }
@@ -385,7 +495,8 @@ export class K2DB {
             // Remove _id safely from each document
             const result = data.map((doc) => {
                 const { _id, ...rest } = doc;
-                return rest;
+                // For multi-record reads, never return secure-prefixed fields (even if encrypted-at-rest is enabled)
+                return this.stripSecureFieldsDeep(rest);
             });
             return result;
         }
@@ -394,18 +505,25 @@ export class K2DB {
         }
     }
     /**
-     * Aggregates documents based on criteria with pagination support.
+     * Aggregates documents based on criteria with pagination support (may validate/limit stages in guarded/strict aggregationMode). Secure-prefixed fields may be stripped from results when configured.
      * @param collectionName - Name of the collection.
      * @param criteria - Aggregation pipeline criteria.
      * @param skip - Number of documents to skip (for pagination).
      * @param limit - Maximum number of documents to return.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async aggregate(collectionName, criteria, skip = 0, limit = 100) {
+    async aggregate(collectionName, criteria, skip = 0, limit = 100, scope) {
         if (criteria.length === 0) {
             throw new K2Error(ServiceError.SYSTEM_ERROR, "Aggregation criteria cannot be empty", "sys_mdb_ag_empty");
         }
+        // Prevent aggregation from reading/deriving values from secure-prefixed fields (when configured)
+        this.assertNoSecureFieldRefsInPipeline(criteria);
+        // Validate the aggregation pipeline for allowed/disallowed stages and safety caps
+        this.validateAggregationPipeline(criteria, skip, limit);
         // Enforce soft-delete behavior: never return documents marked as deleted
         criteria = K2DB.enforceNoDeletedInPipeline(criteria);
+        // Enforce ownership scope within the pipeline (and nested pipelines)
+        criteria = this.enforceScopeInPipeline(criteria, scope);
         // Add pagination stages to the aggregation pipeline
         if (skip > 0) {
             criteria.push({ $skip: skip });
@@ -423,14 +541,400 @@ export class K2DB {
             return stage;
         });
         try {
-            const data = await this.runTimed("aggregate", { collectionName, pipeline: sanitizedCriteria }, async () => await collection.aggregate(sanitizedCriteria).toArray());
-            // Enforce BaseDocument type on each document
-            return data.map((doc) => doc);
+            const data = await this.runTimed("aggregate", { collectionName, pipeline: sanitizedCriteria }, async () => {
+                const mode = this.aggregationMode ?? "loose";
+                const opts = {};
+                if (mode !== "loose") {
+                    opts.maxTimeMS = 2000;
+                }
+                return await collection.aggregate(sanitizedCriteria, opts).toArray();
+            });
+            // Enforce BaseDocument type on each document and strip secure-prefixed fields (if configured)
+            return data.map((doc) => this.stripSecureFieldsDeep(doc));
         }
         catch (err) {
             throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_ag", "Aggregation failed");
         }
     }
+    /**
+     * Validate an aggregation pipeline for safety based on aggregationMode.
+     * - loose: no validation
+     * - guarded: deny obvious footguns (writes, server-side code) and enforce basic caps
+     * - strict: allow only a small safe subset of stages and enforce basic caps
+     */
+    validateAggregationPipeline(pipeline, skip, limit) {
+        const mode = this.aggregationMode ?? "loose";
+        if (mode === "loose")
+            return;
+        // Hard caps to reduce accidental/abusive heavy queries
+        const maxStages = 50;
+        if (pipeline.length > maxStages) {
+            throw new K2Error(ServiceError.BAD_REQUEST, `Aggregation pipeline too long (max ${maxStages} stages)`, "sys_mdb_ag_pipeline_too_long");
+        }
+        // Require a positive limit in guarded/strict to avoid accidental full scans.
+        // Note: aggregate() appends $limit later; enforce here based on the provided arg.
+        if (!(typeof limit === "number") || !isFinite(limit) || limit <= 0) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Aggregation requires a positive limit in guarded/strict mode", "sys_mdb_ag_limit_required");
+        }
+        const maxLimit = 1000;
+        if (limit > maxLimit) {
+            throw new K2Error(ServiceError.BAD_REQUEST, `Aggregation limit too large (max ${maxLimit})`, "sys_mdb_ag_limit_too_large");
+        }
+        const ops = this.collectStageOps(pipeline);
+        const denyGuarded = new Set(["$out", "$merge", "$function", "$accumulator"]);
+        const allowStrict = new Set(["$match", "$project", "$sort", "$skip", "$limit"]);
+        if (mode === "guarded") {
+            for (const op of ops) {
+                if (denyGuarded.has(op)) {
+                    throw new K2Error(ServiceError.BAD_REQUEST, `Aggregation stage ${op} is not allowed in guarded mode`, "sys_mdb_ag_stage_denied");
+                }
+            }
+            return;
+        }
+        // strict
+        for (const op of ops) {
+            if (!allowStrict.has(op)) {
+                throw new K2Error(ServiceError.BAD_REQUEST, `Aggregation stage ${op} is not allowed in strict mode`, "sys_mdb_ag_stage_denied");
+            }
+        }
+    }
+    /** Collect top-level stage operators for a pipeline (e.g. "$match", "$lookup"). */
+    collectStageOps(pipeline) {
+        const ops = [];
+        for (const stage of pipeline || []) {
+            if (!stage || typeof stage !== "object")
+                continue;
+            const keys = Object.keys(stage);
+            if (keys.length === 1 && keys[0].startsWith("$")) {
+                ops.push(keys[0]);
+            }
+            else {
+                // Unknown/non-canonical stage shape; treat as invalid in strict/guarded
+                ops.push("__invalid__");
+            }
+        }
+        return ops;
+    }
+    /** True if a field key is considered secure and must not be returned. */
+    isSecureFieldKey(key) {
+        if (!this.secureFieldPrefixes.length)
+            return false;
+        for (const p of this.secureFieldPrefixes) {
+            if (key.startsWith(p))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Recursively strips secure-prefixed fields from objects/arrays (e.g. "#passport_number").
+     * This is applied on read results (e.g. aggregate) so pipelines cannot exfiltrate secure fields.
+     */
+    stripSecureFieldsDeep(val) {
+        if (!this.secureFieldPrefixes.length)
+            return val;
+        if (val === null || val === undefined)
+            return val;
+        if (Array.isArray(val)) {
+            return val.map((x) => this.stripSecureFieldsDeep(x));
+        }
+        if (typeof val !== "object") {
+            return val;
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(val)) {
+            if (this.isSecureFieldKey(k))
+                continue;
+            out[k] = this.stripSecureFieldsDeep(v);
+        }
+        return out;
+    }
+    /** True if secure-field encryption is enabled (requires both key and keyId). */
+    hasSecureEncryption() {
+        return !!this.secureFieldEncryptionKey && !!this.secureFieldEncryptionKeyId;
+    }
+    /** Encrypt a JS value using AES-256-GCM and return "<kid>:<ivB64>.<tagB64>.<ctB64>". */
+    encryptSecureValueToString(value, aad) {
+        const kid = this.secureFieldEncryptionKeyId;
+        const iv = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", this.secureFieldEncryptionKey, iv);
+        cipher.setAAD(Buffer.from(aad, "utf8"));
+        const pt = Buffer.from(JSON.stringify(value), "utf8");
+        const ct = Buffer.concat([cipher.update(pt), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const payload = `${iv.toString("base64")}.${tag.toString("base64")}.${ct.toString("base64")}`;
+        return `${kid}:${payload}`;
+    }
+    /** Decrypt a "<kid>:<ivB64>.<tagB64>.<ctB64>" string back into a JS value. */
+    decryptSecureStringToValue(s, aad) {
+        if (!this.hasSecureEncryption())
+            return s;
+        if (typeof s !== "string")
+            return s;
+        const idx = s.indexOf(":");
+        if (idx <= 0)
+            return s;
+        const kid = s.slice(0, idx);
+        const payload = s.slice(idx + 1);
+        // Only decrypt if kid matches the configured key id
+        if (!this.secureFieldEncryptionKeyId || kid !== this.secureFieldEncryptionKeyId) {
+            return s;
+        }
+        const parts = payload.split(".");
+        if (parts.length !== 3)
+            return s;
+        try {
+            const iv = Buffer.from(parts[0], "base64");
+            const tag = Buffer.from(parts[1], "base64");
+            const ct = Buffer.from(parts[2], "base64");
+            const decipher = createDecipheriv("aes-256-gcm", this.secureFieldEncryptionKey, iv);
+            decipher.setAAD(Buffer.from(aad, "utf8"));
+            decipher.setAuthTag(tag);
+            const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+            return JSON.parse(pt.toString("utf8"));
+        }
+        catch (err) {
+            throw wrap(err, ServiceError.SYSTEM_ERROR, "sys_mdb_secure_decrypt_failed", "Failed to decrypt secure field");
+        }
+    }
+    /**
+     * Encrypt secure-prefixed fields in an object/array tree.
+     * Only keys with secure prefixes are encrypted; other keys are recursed to allow nested secure keys.
+     */
+    encryptSecureFieldsDeep(val, aadPrefix) {
+        if (!this.secureFieldPrefixes.length)
+            return val;
+        if (!this.hasSecureEncryption())
+            return val;
+        if (val === null || val === undefined)
+            return val;
+        if (Array.isArray(val)) {
+            return val.map((x) => this.encryptSecureFieldsDeep(x, aadPrefix));
+        }
+        if (typeof val !== "object")
+            return val;
+        const out = {};
+        for (const [k, v] of Object.entries(val)) {
+            if (this.isSecureFieldKey(k)) {
+                const aad = `${aadPrefix}|${k}`;
+                out[k] = this.encryptSecureValueToString(v, aad);
+            }
+            else {
+                out[k] = this.encryptSecureFieldsDeep(v, aadPrefix);
+            }
+        }
+        return out;
+    }
+    /**
+     * Decrypt secure-prefixed fields in an object/array tree.
+     * If a secure field value is not an encrypted string, it is returned as-is.
+     */
+    decryptSecureFieldsDeep(val, aadPrefix) {
+        if (!this.secureFieldPrefixes.length)
+            return val;
+        if (!this.hasSecureEncryption())
+            return val;
+        if (val === null || val === undefined)
+            return val;
+        if (Array.isArray(val)) {
+            return val.map((x) => this.decryptSecureFieldsDeep(x, aadPrefix));
+        }
+        if (typeof val !== "object")
+            return val;
+        const out = {};
+        for (const [k, v] of Object.entries(val)) {
+            if (this.isSecureFieldKey(k)) {
+                const aad = `${aadPrefix}|${k}`;
+                out[k] = typeof v === "string" ? this.decryptSecureStringToValue(v, aad) : v;
+            }
+            else {
+                out[k] = this.decryptSecureFieldsDeep(v, aadPrefix);
+            }
+        }
+        return out;
+    }
+    /**
+     * Throws if an aggregation pipeline references any secure-prefixed field paths.
+     * This prevents deriving output from secure fields (e.g. {$group: {x: {$sum: "$#passport_number"}}}).
+     */
+    assertNoSecureFieldRefsInPipeline(pipeline) {
+        if (!this.secureFieldPrefixes.length)
+            return;
+        if (!Array.isArray(pipeline))
+            return;
+        if (this.containsSecureFieldRefDeep(pipeline)) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Aggregation pipeline references secure-prefixed field(s)", "sys_mdb_ag_secure_field_ref");
+        }
+    }
+    /** Recursively detects secure field references in an aggregation pipeline AST. */
+    containsSecureFieldRefDeep(val) {
+        if (!this.secureFieldPrefixes.length)
+            return false;
+        if (val === null || val === undefined)
+            return false;
+        if (Array.isArray(val)) {
+            return val.some((x) => this.containsSecureFieldRefDeep(x));
+        }
+        if (typeof val === "string") {
+            return this.stringHasSecureFieldPath(val);
+        }
+        if (typeof val !== "object")
+            return false;
+        for (const [k, v] of Object.entries(val)) {
+            // Object keys can be field names in some expressions; treat them as potential paths too.
+            if (this.stringHasSecureFieldPath(k))
+                return true;
+            if (this.containsSecureFieldRefDeep(v))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Returns true if a string appears to reference a secure field path.
+     * We consider:
+     * - "$path.to.field"
+     * - "$$var.path.to.field"
+     * - plain "path.to.field" (e.g. $getField: { field: "#passport_number" })
+     */
+    stringHasSecureFieldPath(s) {
+        if (!this.secureFieldPrefixes.length)
+            return false;
+        if (typeof s !== "string")
+            return false;
+        const raw = s.trim();
+        if (!raw)
+            return false;
+        // Handle "$$var.path" form (aggregation variables)
+        if (raw.startsWith("$$")) {
+            const after = raw.slice(2);
+            const dot = after.indexOf(".");
+            if (dot === -1)
+                return false; // just a variable name
+            const path = after.slice(dot + 1);
+            return this.pathHasSecureSegment(path);
+        }
+        // Handle "$path" form (field paths)
+        if (raw.startsWith("$")) {
+            const path = raw.slice(1);
+            return this.pathHasSecureSegment(path);
+        }
+        // Handle plain "path" strings (e.g. $getField field names)
+        return this.pathHasSecureSegment(raw);
+    }
+    /** True if any segment in a dotted path starts with a secure prefix. */
+    pathHasSecureSegment(path) {
+        const p = path.trim();
+        if (!p)
+            return false;
+        const segments = p.split(".");
+        for (const seg of segments) {
+            if (!seg)
+                continue;
+            if (this.isSecureFieldKey(seg))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Ensures an aggregation pipeline respects ownership scope for the root
+     * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
+     */
+    enforceScopeInPipeline(pipeline, scope) {
+        const normalizedScope = this.normalizeScope(scope);
+        // Strict mode requires an explicit scope per call.
+        if (this.ownershipMode === "strict" && !normalizedScope) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Scope is required in strict ownership mode", "sys_mdb_scope_required");
+        }
+        // Lax mode with no scope, or explicit all-scope: no owner constraint injected.
+        if (!normalizedScope || normalizedScope === "*") {
+            return Array.isArray(pipeline) ? pipeline.map((s) => ({ ...s })) : [];
+        }
+        const cloned = Array.isArray(pipeline) ? pipeline.map((s) => ({ ...s })) : [];
+        // Insert a $match to constrain owner near the start, but after any
+        // first-stage-only operators like $search, $geoNear, $vectorSearch.
+        const reservedFirst = ["$search", "$geoNear", "$vectorSearch"];
+        let insertIdx = 0;
+        while (insertIdx < cloned.length &&
+            typeof cloned[insertIdx] === "object" &&
+            cloned[insertIdx] !== null &&
+            Object.keys(cloned[insertIdx]).length === 1 &&
+            reservedFirst.includes(Object.keys(cloned[insertIdx])[0])) {
+            insertIdx++;
+        }
+        const ownerMatch = { $match: { _owner: normalizedScope } };
+        cloned.splice(insertIdx, 0, ownerMatch);
+        const mapStage = (stage) => {
+            if (!stage || typeof stage !== "object")
+                return stage;
+            if (stage.$lookup) {
+                const lu = { ...stage.$lookup };
+                if (Array.isArray(lu.pipeline)) {
+                    lu.pipeline = this.enforceScopeInPipeline(lu.pipeline, normalizedScope);
+                }
+                else if (lu.localField && lu.foreignField) {
+                    // Convert simple lookup to pipeline lookup so we can enforce owner scope (and deleted) in foreign coll.
+                    const localVar = "__lk";
+                    const ownerVar = "__own";
+                    lu.let = { [localVar]: `$${lu.localField}`, [ownerVar]: normalizedScope };
+                    lu.pipeline = [
+                        {
+                            $match: {
+                                $expr: {
+                                    $and: [
+                                        {
+                                            $cond: [
+                                                { $isArray: "$$" + localVar },
+                                                { $in: ["$" + lu.foreignField, "$$" + localVar] },
+                                                { $eq: ["$" + lu.foreignField, "$$" + localVar] },
+                                            ],
+                                        },
+                                        { $eq: ["$_owner", "$$" + ownerVar] },
+                                        { $ne: ["$_deleted", true] },
+                                    ],
+                                },
+                            },
+                        },
+                    ];
+                    delete lu.localField;
+                    delete lu.foreignField;
+                }
+                return { $lookup: lu };
+            }
+            if (stage.$unionWith) {
+                const uw = stage.$unionWith;
+                if (typeof uw === "string") {
+                    return {
+                        $unionWith: {
+                            coll: uw,
+                            pipeline: [
+                                { $match: { _owner: normalizedScope } },
+                                { $match: { _deleted: { $ne: true } } },
+                            ],
+                        },
+                    };
+                }
+                else if (uw && typeof uw === "object") {
+                    const uwc = { ...uw };
+                    uwc.pipeline = this.enforceScopeInPipeline(uwc.pipeline || [], normalizedScope);
+                    return { $unionWith: uwc };
+                }
+            }
+            if (stage.$graphLookup) {
+                const gl = { ...stage.$graphLookup };
+                const existing = gl.restrictSearchWithMatch || {};
+                gl.restrictSearchWithMatch = { ...existing, _owner: normalizedScope };
+                return { $graphLookup: gl };
+            }
+            if (stage.$facet) {
+                const facets = { ...stage.$facet };
+                for (const key of Object.keys(facets)) {
+                    facets[key] = this.enforceScopeInPipeline(facets[key] || [], normalizedScope);
+                }
+                return { $facet: facets };
+            }
+            return stage;
+        };
+        return cloned.map(mapStage);
+    }
     /**
      * Ensures an aggregation pipeline excludes soft-deleted documents for the root
      * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
@@ -469,7 +973,13 @@ export class K2DB {
                             $match: {
                                 $expr: {
                                     $and: [
-                                        { $eq: ["$" + lu.foreignField, "$$" + localVar] },
+                                        {
+                                            $cond: [
+                                                { $isArray: "$$" + localVar },
+                                                { $in: ["$" + lu.foreignField, "$$" + localVar] },
+                                                { $eq: ["$" + lu.foreignField, "$$" + localVar] },
+                                            ],
+                                        },
                                         { $ne: ["$_deleted", true] },
                                     ],
                                 },
@@ -527,6 +1037,13 @@ export class K2DB {
         if (typeof owner !== "string") {
             throw new K2Error(ServiceError.BAD_REQUEST, "Owner must be of a string type", "sys_mdb_crv2");
         }
+        const normalizedOwner = owner.trim().toLowerCase();
+        if (!normalizedOwner) {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Owner must be a non-empty string", "sys_mdb_owner_empty");
+        }
+        if (normalizedOwner === "*") {
+            throw new K2Error(ServiceError.BAD_REQUEST, "Owner cannot be '*'", "sys_mdb_owner_star");
+        }
         const collection = await this.getCollection(collectionName);
         const timestamp = Date.now();
         // Generate a new UUIDv7 encoded as Crockford Base32 with hyphens
@@ -534,12 +1051,13 @@ export class K2DB {
         // Remove reserved fields from user data, then validate/transform via schema if present
         const safeData = K2DB.stripReservedFields(data);
         const validated = this.applySchema(collectionName, safeData, /*partial*/ false);
+        const storedData = this.encryptSecureFieldsDeep(validated, `k2db|${collectionName}|${newUuid}`);
         // Spread validated data first, then set internal fields to prevent overwriting
         const document = {
-            ...validated,
+            ...storedData,
             _created: timestamp,
             _updated: timestamp,
-            _owner: owner,
+            _owner: normalizedOwner,
             _uuid: newUuid,
         };
         try {
@@ -564,8 +1082,9 @@ export class K2DB {
      * @param collectionName - Name of the collection.
      * @param criteria - Update criteria.
      * @param values - Values to update or replace with.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async updateAll(collectionName, criteria, values) {
+    async updateAll(collectionName, criteria, values, scope) {
         this.validateCollectionName(collectionName);
         const collection = await this.getCollection(collectionName);
         debug(`Updating ${collectionName} with criteria: ${JSON.stringify(criteria)}`);
@@ -582,7 +1101,10 @@ export class K2DB {
         if (deletedFlag !== undefined) {
             values._deleted = deletedFlag;
         }
+        // Encrypt secure-prefixed fields at rest (no-op unless encryption is configured)
+        values = this.encryptSecureFieldsDeep(values, `k2db|${collectionName}`);
         criteria = K2DB.normalizeCriteriaIds(criteria || {});
+        criteria = this.applyScopeToCriteria(criteria, scope);
         criteria = {
             ...criteria,
             _deleted: { $ne: true },
@@ -604,20 +1126,26 @@ export class K2DB {
      * @param id - UUID string to identify the document.
      * @param data - Data to update or replace with.
      * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async update(collectionName, id, data, replace = false) {
+    async update(collectionName, id, data, replace = false, scope) {
         id = K2DB.normalizeId(id);
         this.validateCollectionName(collectionName);
         const collection = await this.getCollection(collectionName);
         data = K2DB.stripReservedFields(data);
         data = this.applySchema(collectionName, data, /*partial*/ !replace);
         data._updated = Date.now(); // Set the _updated timestamp
+        // PATCH path: encrypt secure-prefixed fields at rest (no-op unless encryption is configured).
+        // REPLACE path: encrypt after underscore-field merge to avoid double-encrypt.
+        if (!replace) {
+            data = this.encryptSecureFieldsDeep(data, `k2db|${collectionName}|${id}`);
+        }
         try {
             let res;
             // If replacing the document, first get the original document
             if (replace) {
                 // Get the original document to preserve fields starting with underscore
-                const originalDoc = await this.get(collectionName, id);
+                const originalDoc = await this.get(collectionName, id, scope);
                 // Override all fields starting with underscore from the original document
                 const fieldsToPreserve = Object.keys(originalDoc).reduce((acc, key) => {
                     if (key.startsWith("_")) {
@@ -628,12 +1156,14 @@ export class K2DB {
                 // Merge the preserved fields into the data
                 data = { ...data, ...fieldsToPreserve };
                 data._updated = Date.now();
+                // Encrypt secure-prefixed fields at rest (no-op unless encryption is configured)
+                data = this.encryptSecureFieldsDeep(data, `k2db|${collectionName}|${id}`);
                 // Now replace the document with the merged data
-                res = await this.runTimed("replaceOne", { collectionName, _uuid: id }, async () => await collection.replaceOne({ _uuid: id, _deleted: { $ne: true } }, data));
+                res = await this.runTimed("replaceOne", { collectionName, _uuid: id }, async () => await collection.replaceOne(this.applyScopeToCriteria({ _uuid: id, _deleted: { $ne: true } }, scope), data));
             }
             else {
                 // If patching, just update specific fields using $set
-                res = await this.runTimed("updateOne", { collectionName, _uuid: id }, async () => await collection.updateOne({ _uuid: id, _deleted: { $ne: true } }, { $set: data }));
+                res = await this.runTimed("updateOne", { collectionName, _uuid: id }, async () => await collection.updateOne(this.applyScopeToCriteria({ _uuid: id, _deleted: { $ne: true } }, scope), { $set: data }));
             }
             // Use matchedCount to determine existence; modifiedCount indicates actual change
             if (res.matchedCount === 0) {
@@ -649,13 +1179,14 @@ export class K2DB {
      * Removes (soft deletes) multiple documents based on criteria.
      * @param collectionName - Name of the collection.
      * @param criteria - Removal criteria.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async deleteAll(collectionName, criteria) {
+    async deleteAll(collectionName, criteria, scope) {
         this.validateCollectionName(collectionName);
         try {
             const result = await this.updateAll(collectionName, criteria, {
                 _deleted: true,
-            });
+            }, scope);
             return { deleted: result.updated };
         }
         catch (err) {
@@ -666,12 +1197,13 @@ export class K2DB {
      * Removes (soft deletes) a single document by UUID.
      * @param collectionName - Name of the collection.
      * @param id - UUID of the document.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async delete(collectionName, id) {
+    async delete(collectionName, id, scope) {
         id = K2DB.normalizeId(id);
         try {
             // Call deleteAll to soft delete the document by UUID
-            const result = await this.deleteAll(collectionName, { _uuid: id });
+            const result = await this.deleteAll(collectionName, { _uuid: id }, scope);
             // Check the result of the deleteAll operation
             if (result.deleted === 1) {
                 // Successfully deleted one document
@@ -694,19 +1226,19 @@ export class K2DB {
      * Permanently deletes a document that has been soft-deleted.
      * @param collectionName - Name of the collection.
      * @param id - UUID of the document.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async purge(collectionName, id) {
+    async purge(collectionName, id, scope) {
         id = K2DB.normalizeId(id);
         const collection = await this.getCollection(collectionName);
         try {
-            const item = await this.runTimed("findOne", { collectionName, _uuid: id, _deleted: true }, async () => await collection.findOne({
-                _uuid: id,
-                _deleted: true,
-            }));
+            const findFilter = this.applyScopeToCriteria({ _uuid: id, _deleted: true }, scope);
+            const item = await this.runTimed("findOne", { collectionName, ...findFilter }, async () => await collection.findOne(findFilter));
             if (!item) {
                 throw new K2Error(ServiceError.SYSTEM_ERROR, "Cannot purge item that is not deleted", "sys_mdb_gcol_pg2");
             }
-            await this.runTimed("deleteOne", { collectionName, _uuid: id }, async () => await collection.deleteOne({ _uuid: id }));
+            const delFilter = this.applyScopeToCriteria({ _uuid: id }, scope);
+            await this.runTimed("deleteOne", { collectionName, ...delFilter }, async () => await collection.deleteOne(delFilter));
             return { id };
         }
         catch (err) {
@@ -719,8 +1251,9 @@ export class K2DB {
      * @param collectionName - Name of the collection.
      * @param olderThanMs - Age threshold in milliseconds; documents with
      *                      `_updated <= (Date.now() - olderThanMs)` will be purged.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async purgeDeletedOlderThan(collectionName, olderThanMs) {
+    async purgeDeletedOlderThan(collectionName, olderThanMs, scope) {
         this.validateCollectionName(collectionName);
         if (typeof olderThanMs !== 'number' || !isFinite(olderThanMs) || olderThanMs < 0) {
             throw new K2Error(ServiceError.BAD_REQUEST, 'olderThanMs must be a non-negative number', 'sys_mdb_purge_older_invalid');
@@ -728,10 +1261,11 @@ export class K2DB {
         const collection = await this.getCollection(collectionName);
         const cutoff = Date.now() - olderThanMs;
         try {
-            const res = await this.runTimed('deleteMany', { collectionName, olderThanMs, cutoff }, async () => await collection.deleteMany({
+            const delFilter = this.applyScopeToCriteria({
                 _deleted: true,
                 _updated: { $lte: cutoff },
-            }));
+            }, scope);
+            const res = await this.runTimed('deleteMany', { collectionName, olderThanMs, cutoff, ...delFilter }, async () => await collection.deleteMany(delFilter));
             return { purged: res.deletedCount ?? 0 };
         }
         catch (err) {
@@ -742,10 +1276,12 @@ export class K2DB {
      * Restores a soft-deleted document.
      * @param collectionName - Name of the collection.
      * @param criteria - Criteria to identify the document.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async restore(collectionName, criteria) {
+    async restore(collectionName, criteria, scope) {
         const collection = await this.getCollection(collectionName);
-        const crit = K2DB.normalizeCriteriaIds(criteria || {});
+        let crit = K2DB.normalizeCriteriaIds(criteria || {});
+        crit = this.applyScopeToCriteria(crit, scope);
         const query = { ...crit, _deleted: true };
         try {
             const res = await this.runTimed("updateMany", { collectionName, query }, async () => await collection.updateMany(query, {
@@ -762,17 +1298,19 @@ export class K2DB {
      * Counts documents based on criteria.
      * @param collectionName - Name of the collection.
      * @param criteria - Counting criteria.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async count(collectionName, criteria) {
+    async count(collectionName, criteria, scope) {
         const collection = await this.getCollection(collectionName);
         try {
             const norm = K2DB.normalizeCriteriaIds(criteria || {});
-            const query = {
+            let query = {
                 ...norm,
                 ...(criteria && Object.prototype.hasOwnProperty.call(criteria, "_deleted")
                     ? {}
                     : { _deleted: { $ne: true } }),
             };
+            query = this.applyScopeToCriteria(query, scope);
             const cnt = await this.runTimed("countDocuments", { collectionName, query }, async () => await collection.countDocuments(query));
             return { count: cnt };
         }
@@ -781,11 +1319,21 @@ export class K2DB {
         }
     }
     /**
-     * Drops an entire collection.
+     * Drops an entire collection (global destructive operation).
      * @param collectionName - Name of the collection.
+     * @param scope - (optional) Must be "*" in strict ownership mode.
      */
-    async drop(collectionName) {
+    async drop(collectionName, scope) {
         const collection = await this.getCollection(collectionName);
+        const normalizedScope = this.normalizeScope(scope);
+        // Global destructive operation: require explicit all-scope gate in strict mode.
+        if (this.ownershipMode === "strict" && normalizedScope !== "*") {
+            throw new K2Error(ServiceError.BAD_REQUEST, 'Dropping a collection requires scope="*" in strict ownership mode', "sys_mdb_drop_scope_required");
+        }
+        // In lax mode, allow legacy behavior when scope is omitted; if provided, it must be "*".
+        if (this.ownershipMode === "lax" && normalizedScope !== undefined && normalizedScope !== "*") {
+            throw new K2Error(ServiceError.BAD_REQUEST, 'Dropping a collection only supports scope="*"', "sys_mdb_drop_scope_invalid");
+        }
         try {
             await collection.drop();
             return { status: "ok" };
@@ -817,7 +1365,7 @@ export class K2DB {
         }
         return criteria;
     }
-    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
+    /** Recursively normalizes query fields: `_uuid` uppercased, `_owner` lowercased. */
     static normalizeCriteriaIds(obj) {
         if (!obj || typeof obj !== "object")
             return obj;
@@ -828,6 +1376,9 @@ export class K2DB {
             if (k === "_uuid") {
                 out[k] = K2DB.normalizeUuidField(v);
             }
+            else if (k === "_owner") {
+                out[k] = K2DB.normalizeOwnerField(v);
+            }
             else if (v && typeof v === "object") {
                 out[k] = K2DB.normalizeCriteriaIds(v);
             }
@@ -856,6 +1407,23 @@ export class K2DB {
         }
         return val;
     }
+    /** Lowercase helper for `_owner` field supporting operators like $in/$nin/$eq/$ne and arrays. */
+    static normalizeOwnerField(val) {
+        if (typeof val === "string")
+            return val.trim().toLowerCase();
+        if (Array.isArray(val)) {
+            return val.map((x) => (typeof x === "string" ? x.trim().toLowerCase() : x));
+        }
+        if (val && typeof val === "object") {
+            const out = { ...val };
+            for (const op of ["$in", "$nin", "$eq", "$ne", "$all"]) {
+                if (op in out)
+                    out[op] = K2DB.normalizeOwnerField(out[op]);
+            }
+            return out;
+        }
+        return val;
+    }
     /** Strip any user-provided fields that start with '_' (reserved). */
     static stripReservedFields(obj) {
         const out = {};
@@ -1095,26 +1663,33 @@ export class K2DB {
     async snapshotCurrent(collectionName, current) {
         const hc = await this.getHistoryCollection(collectionName);
         const version = await this.nextVersion(collectionName, current._uuid);
+        const storedSnapshot = this.encryptSecureFieldsDeep(current, `k2db|${collectionName}|${current._uuid}`);
         await hc.insertOne({
             _uuid: current._uuid,
             _v: version,
             _at: Date.now(),
-            snapshot: current,
+            snapshot: storedSnapshot,
         });
         return { version };
     }
     /**
      * Update a document and keep the previous version in a history collection.
      * If maxVersions is provided, prunes oldest snapshots beyond that number.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID string to identify the document.
+     * @param data - Data to update or replace with.
+     * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     * @param maxVersions - Maximum number of versions to keep (optional).
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    async updateVersioned(collectionName, id, data, replace = false, maxVersions) {
+    async updateVersioned(collectionName, id, data, replace = false, maxVersions, scope) {
         id = K2DB.normalizeId(id);
         // Get current doc (excludes deleted) and snapshot it
-        const current = await this.get(collectionName, id);
+        const current = await this.get(collectionName, id, scope);
         await this.ensureHistoryIndexes(collectionName);
         const { version } = await this.snapshotCurrent(collectionName, current);
         // Perform update
-        const res = await this.update(collectionName, id, data, replace);
+        const res = await this.update(collectionName, id, data, replace, scope);
         // Optionally prune old versions
         if (typeof maxVersions === "number" && maxVersions >= 0) {
             const hc = await this.getHistoryCollection(collectionName);
@@ -1135,9 +1710,18 @@ export class K2DB {
         }
         return [{ updated: res.updated, versionSaved: version }];
     }
-    /** List versions (latest first). */
-    async listVersions(collectionName, id, skip = 0, limit = 20) {
+    /**
+     * List versions (latest first).
+     * @param collectionName - Name of the collection.
+     * @param id - UUID string to identify the document.
+     * @param skip - Number of versions to skip (for pagination).
+     * @param limit - Maximum number of versions to return.
+     * @param scope - (optional) Owner selector; "*" means all owners.
+     */
+    async listVersions(collectionName, id, skip = 0, limit = 20, scope) {
         id = K2DB.normalizeId(id);
+        // Gate history access by ownership of the current document
+        await this.get(collectionName, id, scope);
         const hc = await this.getHistoryCollection(collectionName);
         const rows = await hc
             .find({ _uuid: id })
@@ -1148,21 +1732,30 @@ export class K2DB {
             .toArray();
         return rows;
     }
-    /** Revert the current document to a specific historical version (preserves metadata). */
-    async revertToVersion(collectionName, id, version) {
+    /**
+     * Revert the current document to a specific historical version (preserves metadata).
+     * @param collectionName - Name of the collection.
+     * @param id - UUID string to identify the document.
+     * @param version - Version number to revert to.
+     * @param scope - (optional) Owner selector; "*" means all owners.
+     */
+    async revertToVersion(collectionName, id, version, scope) {
         id = K2DB.normalizeId(id);
+        // Gate history access by ownership of the current document
+        await this.get(collectionName, id, scope);
         const hc = await this.getHistoryCollection(collectionName);
         const row = await hc.findOne({ _uuid: id, _v: version });
         if (!row) {
             throw new K2Error(ServiceError.NOT_FOUND, `Version ${version} for ${id} not found`, "sys_mdb_version_not_found");
         }
         const snapshot = row.snapshot;
+        const snapshotPlain = this.decryptSecureFieldsDeep(snapshot, `k2db|${collectionName}|${id}`);
         // Only apply non-underscore fields; metadata is preserved by replace=true path
         const apply = {};
-        for (const [k, v] of Object.entries(snapshot)) {
+        for (const [k, v] of Object.entries(snapshotPlain)) {
             if (!k.startsWith("_"))
                 apply[k] = v;
         }
-        return this.update(collectionName, id, apply, true);
+        return this.update(collectionName, id, apply, true, scope);
     }
 }