@frogfish/k2db 3.0.1 → 3.0.2

package/README.md

@@ -35,7 +35,7 @@ Deployment tips (Nomad, Lambda, etc.)
   export const handler = async (event) => {
     ready = ready || db.init();
     await ready; // reused across warm invocations
-    const res = await db.find("hello", { _owner: event.userId }, {}, 0, 10);
+    const res = await db.find("hello", {}, {}, 0, 10, event.userId);
     return { statusCode: 200, body: JSON.stringify(res) };
   };
   ```
@@ -100,7 +100,8 @@ Ownership (`_owner`)
 - Purpose: `_owner` is not a tenant ID nor a technical auth scope. It’s a required, opinionated piece of metadata that records who a document belongs to (the data subject or system principal that created/owns it).
 - Why it matters: Enables clear data lineage and supports privacy/jurisdiction workflows (GDPR/DSAR: “export all my data”, “delete my data”), audits, and stewardship.
 - Typical values: a user’s UUID when a signed-in human creates the record; for automated/system operations use a stable identifier like `"system"`, `"service:mailer"`, or `"migration:2024-09-01"`.
-- Not authorization: The library does not enforce access control based on `_owner`. Apply your authorization rules in the API/service layer using `_owner` as a helpful filter or join key.
+- Not authentication: k2db does not authenticate callers. Your API/service still decides *who* the caller is and whether they are allowed to act.
+- Optional enforcement: k2db can enforce owner scoping when you provide a per-call scope (see “Scope”), and can require scope on all calls when `ownershipMode: "strict"` is enabled.
 - Multi-tenant setups: If you have tenants, keep a distinct `tenantId` (or similar) alongside `_owner`. `_owner` continues to model “who owns this record” rather than “which tenant it belongs to”.
 
 Config
@@ -124,6 +125,343 @@ await db.init();
 await db.ensureIndexes("myCollection");
 ```
 
+### Scope config
+
+- `ownershipMode?: "lax" | "strict"` (default: `"lax"`)
+  - `"lax"` (default): Passing a scope is optional. If you provide a scope, k2db enforces it as an owner filter; if omitted, behavior is unchanged from historical (no owner enforcement, but still enforces soft-delete).
+  - `"strict"`: Scope is *required* on all scopified methods (see “Scope” below). If you omit scope, k2db throws an error. This helps prevent accidental missing owner filters.
+
+Example config with strict mode:
+```ts
+const db = new K2DB({
+  name: "mydb",
+  hosts: [{ host: "cluster0.example.mongodb.net" }],
+  user: process.env.DB_USER,
+  password: process.env.DB_PASS,
+  ownershipMode: "strict",
+});
+```
+
+### Aggregation config
+
+- `aggregationMode?: "loose" | "guarded" | "strict"` (default: `"loose"`)
+  - `"loose"`: No aggregation pipeline validation (all MongoDB stages permitted).
+  - `"guarded"`: Denies `$out`, `$merge`, `$function`, `$accumulator`; requires a positive limit, caps max limit, and adds `maxTimeMS`.
+  - `"strict"`: Allows only `$match`, `$project`, `$sort`, `$skip`, `$limit` stages; also requires and caps limit.
+
+Example:
+```ts
+const db = new K2DB({
+  name: "mydb",
+  hosts: [{ host: "cluster0.example.mongodb.net" }],
+  aggregationMode: "guarded", // disables dangerous stages, enforces limit
+});
+```
+
+## Scope
+
+Scope is an optional per-call “owner filter” that k2db can apply to most data access and mutation methods. It provides a safety guardrail to help prevent missing `_owner` filters, especially in multi-tenant or user-data contexts.
+
+**Scope is not authentication or authorization:** It does not decide *who* may act. Your API/service is still responsible for authenticating callers and deciding what scopes/owners they are allowed to access.
+
+### Type
+
+```ts
+type Scope = string | "*";
+```
+- If a `string` is provided, only documents with `_owner === scope` are included or affected.
+- If `"*"` is provided, *all* owners are included (no owner filter). This is intended for admin/service-to-service operations—never pass untrusted `"*"` from user input.
+
+### Modes
+
+- In `ownershipMode: "lax"` (default):
+  - If `scope` is omitted: No owner filtering is applied (historical behavior; still enforces soft-delete).
+  - If `scope` is provided: Only docs with `_owner === scope` (or all docs if `"*"`).
+- In `ownershipMode: "strict"`:
+  - `scope` is *required* for all scopified methods (see below). If not provided, k2db throws an error.
+  - Use `"*"` for admin/system/service calls (do not invent a magic owner like `_system`).
+
+### Methods that support scope
+
+The following methods accept an optional `scope?: Scope | string` as their final argument:
+- `get`
+- `findOne`
+- `find`
+- `count`
+- `update`
+- `updateAll`
+- `delete`
+- `deleteAll`
+- `restore`
+- `purge`
+- `purgeDeletedOlderThan`
+- `drop` and `dropDatabase`: For destructive/admin operations, use `"*"` as scope to indicate you intend to operate without owner restriction.
+
+### Examples
+
+#### a) User reads own docs
+```ts
+// Only docs owned by this user
+await db.find("posts", {}, {}, 0, 20, userId);
+```
+
+#### b) Admin/service reads or mutates all docs
+```ts
+// Read all posts (no owner restriction)
+await db.find("posts", {}, {}, 0, 20, "*");
+
+// Delete a user (admin only)
+await db.delete("users", id, "*");
+```
+
+#### c) Strict mode with HTTP header mapping
+Suppose your API receives:
+```
+X-Scope: <userId> | *
+```
+You should map this header to the `scope` argument:
+```ts
+const scope = req.headers["x-scope"];
+// Only allow "*" for trusted admin/service credentials!
+await db.find("posts", {}, {}, 0, 20, scope);
+```
+
+### Rules of thumb
+- Never pass untrusted `"*"` as a scope—restrict this to trusted admin/service credentials only.
+- Prefer passing a scope everywhere; enabling strict mode helps you catch missing owner filters.
+- Normalize `_owner` values consistently—prefer lowercase and a single convention (e.g., always userId as lowercase UUID).
+
+
+## Aggregation
+
+Aggregation in k2db lets you run MongoDB pipelines with guardrails for soft-delete, secure fields, and pipeline safety.
+
+### `aggregate(collection, pipeline, skip?, limit?)`
+
+Runs an aggregation pipeline on the given collection, returning an array of documents. k2db automatically injects filters and enforces restrictions for safety and consistency.
+
+#### What k2db enforces automatically
+
+- **Soft-delete enforcement:** Automatically inserts a `$match: { _deleted: { $ne: true } }` stage near the start of your pipeline so only non-deleted documents are returned. For pipelines beginning with `$search`, `$geoNear`, or `$vectorSearch`, the filter is injected after the first stage to avoid breaking those operators.
+- **Nested enforcement:** For `$lookup`, `$unionWith`, `$graphLookup`, and `$facet`, any sub-pipeline is rewritten to ensure the non-deleted filter applies to foreign collections as well. Simple `$lookup` with `localField`/`foreignField` is rewritten to pipeline form so the non-deleted filter can be injected.
+- **Pagination:** If you pass `skip`/`limit`, those are appended to the pipeline. In `"guarded"`/`"strict"` aggregationMode, a positive limit is required and capped to a safe maximum, and `maxTimeMS` is set to prevent long-running queries.
+- **Secure fields:** If `secureFieldPrefixes` is configured (e.g. `["#"]`), any pipeline referencing a secure-prefixed field (such as `"#passport_number"`) is rejected, even in expressions. Returned documents are also stripped of any keys beginning with a secure prefix.
+
+#### What you cannot do (by default)
+
+- **Return soft-deleted documents:** The injected `$match: { _deleted: { $ne: true } }` filter means aggregate will never return soft-deleted docs, regardless of your pipeline.
+- **Use secure fields in aggregate:** Any pipeline referencing a field like `"#passport_number"` (including in `$project`, `$addFields`, or expressions) is rejected with an error. Even if a document contains a secure-prefixed field, it is stripped from the output.
+- **Use dangerous or non-allowlisted stages:** In `"guarded"` mode, you cannot use `$out`, `$merge`, `$function`, or `$accumulator`. In `"strict"` mode, only `$match`, `$project`, `$sort`, `$skip`, and `$limit` are allowed.
+
+#### Filtering level: root vs nested pipelines
+
+- The root pipeline always gets the non-deleted filter injected (unless the first stage is `$search`, `$geoNear`, or `$vectorSearch`, in which case it's injected after).
+- For nested pipelines in `$lookup`, `$unionWith`, `$graphLookup`, and `$facet`, k2db rewrites or injects the non-deleted filter into each sub-pipeline, so deleted foreign documents are excluded.
+- If a `$lookup` uses the simple `localField`/`foreignField` form, k2db rewrites it to a pipeline `$lookup` so filtering can be enforced.
+
+#### Examples
+
+**1) Basic aggregation: injected soft-delete filter**
+
+Suppose you call:
+```js
+const pipeline = [
+  { $match: { status: "active" } },
+  { $project: { name: 1, status: 1 } }
+];
+await db.aggregate("users", pipeline);
+```
+**Effective pipeline after k2db injection:**
+```js
+[
+  { $match: { _deleted: { $ne: true } } },      // injected
+  { $match: { status: "active" } },
+  { $project: { name: 1, status: 1 } }
+]
+```
+
+**2) `$lookup` rewritten for non-deleted foreign docs**
+
+Original pipeline:
+```js
+[
+  {
+    $lookup: {
+      from: "orders",
+      localField: "_uuid",
+      foreignField: "user_id",
+      as: "orders"
+    }
+  }
+]
+```
+k2db rewrites this to:
+```js
+[
+  {
+    $lookup: {
+      from: "orders",
+      let: { local_id: "$_uuid" },
+      pipeline: [
+        { $match: { _deleted: { $ne: true } } }, // injected for foreign docs
+        { $match: { $expr: { $eq: ["$user_id", "$$local_id"] } } }
+      ],
+      as: "orders"
+    }
+  }
+]
+```
+
+**3) Secure field reference is rejected**
+
+Pipeline:
+```js
+[
+  { $project: { name: 1, passport: "$#passport_number" } }
+]
+```
+Result: **Throws an error** — referencing a secure-prefixed field (`"#passport_number"`) is not allowed in aggregate pipelines.
+
+**4) Attempting to aggregate deleted docs returns nothing**
+
+Pipeline:
+```js
+[
+  { $match: { _deleted: true } }
+]
+```
+Result: Returns **no documents** — k2db injects `{ _deleted: { $ne: true } }` before your match, so the result set is always empty.
+
+---
+
+> **Note:** k2db's aggregation guardrails ensure you cannot accidentally leak deleted or secure data, or run dangerous stages in stricter modes.
+
+## Secure fields and encryption at rest
+
+k2db supports **secure fields**: fields whose keys start with a configurable prefix (recommended: `#`). Secure fields are designed to be hard to accidentally leak in bulk queries and hard to casually access in code.
+
+This feature has two layers:
+
+1) **Guardrails (always):** Secure fields are stripped from multi-record reads (`find`, `aggregate`) and cannot be explicitly projected. Aggregation pipelines are also rejected if they reference secure fields.
+2) **Encryption at rest (optional):** When enabled, secure-field values are encrypted before being written to MongoDB and decrypted on single-record reads.
+
+### Why `#` (friction) instead of `__somethingNice`
+
+The goal is to make secure fields “visually wrong” and **ergonomically annoying** to access on purpose:
+
+- `doc["#passport_number"]` is explicit and reviewable.
+- `doc.#passport_number` is impossible (forces bracket access).
+- It discourages lazy DTO copying and casual destructuring that can accidentally leak secrets.
+
+Using `__private` looks “normal”, which increases the chance developers will treat it like any other field and accidentally return it in list endpoints.
+
+Also, `_...` is reserved for k2db’s metadata (`_uuid`, `_owner`, `_created`, …), so `#...` cleanly avoids that namespace.
+
+### Configuration
+
+Enable secure fields by setting `secureFieldPrefixes`. To also encrypt them at rest, provide a base64 AES-256 key and a key id.
+
+```ts
+const db = new K2DB({
+  name: "mydb",
+  hosts: [{ host: "cluster0.example.mongodb.net" }],
+
+  // Treat "#..." fields as secure
+  secureFieldPrefixes: ["#"],
+
+  // Optional encryption-at-rest for secure fields:
+  // - must decode to 32 bytes (AES-256)
+  // - values are stored as "<keyid>:<payload>"
+  secureFieldEncryptionKeyId: "k1",
+  secureFieldEncryptionKey: process.env.K2DB_SECURE_KEY_B64,
+});
+```
+
+Key requirements:
+- `secureFieldEncryptionKey` must be **base64** and decode to **32 bytes**.
+- Encryption is enabled only when **both** `secureFieldEncryptionKey` and `secureFieldEncryptionKeyId` are provided.
+
+> Note: Today k2db decrypts only ciphertexts whose `keyid` matches the configured `secureFieldEncryptionKeyId`. If the stored `keyid` differs, the encrypted string is returned as-is (useful during key rotation rollout, but plan your rotation strategy accordingly).
+
+### Storage format
+
+When encryption is enabled, each secure field value is stored as a single string:
+
+```
+<keyid>:<ivB64>.<tagB64>.<ctB64>
+```
+
+- Algorithm: AES-256-GCM
+- Plaintext: `JSON.stringify(value)` (so secure fields may be strings, numbers, objects, arrays, etc.)
+
+### Behavior by method
+
+With `secureFieldPrefixes: ["#"]`:
+
+- **create / update / updateAll**:
+  - If encryption is enabled, `#...` values are encrypted before write.
+  - If encryption is disabled, values are stored as provided.
+- **get / findOne** (single-record reads):
+  - If encryption is enabled, `#...` values are decrypted and returned in the object.
+  - If encryption is disabled, values are returned as stored.
+- **find** (multi-record reads):
+  - Secure fields are **stripped** from every returned document (even if encryption is disabled).
+- **aggregate**:
+  - Secure fields are **not allowed to be referenced** in the pipeline (k2db throws).
+  - Secure fields are also **stripped** from returned documents as a second safety net.
+- **projections**:
+  - `findOne(fields=[...])` and `find(params.filter=[...])` cannot include secure fields (throws).
+
+### Examples
+
+#### 1) Store a secure field
+
+```ts
+const owner = userId.toLowerCase();
+
+const { id } = await db.create("profiles", owner, {
+  name: "Ada",
+  "#passport_number": "123456789",
+  "#home_address": { line1: "1 Example St", city: "Perth" },
+});
+```
+
+- If encryption is enabled, MongoDB stores `"#passport_number"` and `"#home_address"` as encrypted strings.
+- If encryption is disabled, they are stored as plaintext (still guarded on reads).
+
+#### 2) Single-record read returns secure fields
+
+```ts
+const profile = await db.get("profiles", id, owner);
+
+// Explicit access (friction by design)
+console.log(profile["#passport_number"]);
+```
+
+#### 3) Multi-record read strips secure fields
+
+```ts
+const list = await db.find("profiles", {}, {}, 0, 50, owner);
+
+// "#..." fields are removed from each document in list
+console.log(list[0]["#passport_number"]); // undefined
+```
+
+#### 4) Aggregation cannot reference secure fields
+
+```ts
+await db.aggregate("profiles", [
+  { $project: { name: 1, passport: "$#passport_number" } },
+]);
+// throws: secure-prefixed field referenced in pipeline
+```
+
+### What this is (and isn’t)
+
+- This is a **data safety guardrail** and optional encryption-at-rest mechanism.
+- It is **not authentication/authorization**: you still must decide who the caller is and what they’re allowed to do.
+- For admin/service operations, combine this with **Scope** rules: do not accept `"*"` from untrusted callers.
+
 Environment loader
 ```ts
 const conf = K2DB.fromEnv(); // K2DB_NAME (logical db), K2DB_HOSTS, K2DB_USER, K2DB_PASSWORD, K2DB_AUTH_SOURCE, K2DB_REPLICASET, K2DB_SLOW_MS
@@ -305,19 +643,19 @@ db.clearSchema("hello");
 - `VersionInfo`: `{ _uuid: string; _v: number; _at: number }`
 
 Returns by method
-- `get(collection, id)`: `Promise<BaseDocument>`
-- `find(collection, filter, params?, skip?, limit?)`: `Promise<BaseDocument[]>`
-- `findOne(collection, criteria, fields?)`: `Promise<BaseDocument|null>`
+- `get(collection, id, scope?)`: `Promise<BaseDocument>`
+- `find(collection, filter, params?, skip?, limit?, scope?)`: `Promise<BaseDocument[]>`
+- `findOne(collection, criteria, fields?, scope?)`: `Promise<BaseDocument|null>`
 - `aggregate(collection, pipeline, skip?, limit?)`: `Promise<BaseDocument[]>`
 - `create(collection, owner, data)`: `Promise<CreateResult>`
-- `update(collection, id, data, replace?)`: `Promise<UpdateResult>`
-- `updateAll(collection, criteria, values)`: `Promise<UpdateResult>`
-- `delete(collection, id)`: `Promise<DeleteResult>`
-- `deleteAll(collection, criteria)`: `Promise<DeleteResult>`
-- `purge(collection, id)`: `Promise<PurgeResult>`
-- `restore(collection, criteria)`: `Promise<RestoreResult>`
-- `count(collection, criteria)`: `Promise<CountResult>`
-- `drop(collection)`: `Promise<DropResult>`
+- `update(collection, id, data, replace?, scope?)`: `Promise<UpdateResult>`
+- `updateAll(collection, criteria, values, scope?)`: `Promise<UpdateResult>`
+- `delete(collection, id, scope?)`: `Promise<DeleteResult>`
+- `deleteAll(collection, criteria, scope?)`: `Promise<DeleteResult>`
+- `purge(collection, id, scope?)`: `Promise<PurgeResult>`
+- `restore(collection, criteria, scope?)`: `Promise<RestoreResult>`
+- `count(collection, criteria, scope?)`: `Promise<CountResult>`
+- `drop(collection, scope?)`: `Promise<DropResult>`
 - `ensureIndexes(collection, opts?)`: `Promise<void>`
 - `ensureHistoryIndexes(collection)`: `Promise<void>`
 - `updateVersioned(collection, id, data, replace?, maxVersions?)`: `Promise<VersionedUpdateResult[]>`

package/db.d.ts

@@ -23,6 +23,11 @@ export interface DatabaseConfig {
         beforeQuery?: (op: string, details: any) => void;
         afterQuery?: (op: string, details: any, durationMs: number) => void;
     };
+    ownershipMode?: "lax" | "strict";
+    aggregationMode?: "loose" | "guarded" | "strict";
+    secureFieldPrefixes?: string[];
+    secureFieldEncryptionKey?: string;
+    secureFieldEncryptionKeyId?: string;
 }
 export interface BaseDocument {
     _id?: ObjectId;
@@ -67,6 +72,7 @@ export interface VersionInfo {
     _v: number;
     _at: number;
 }
+export type Scope = string | "*";
 export declare class K2DB {
     private conf;
     private db;
@@ -75,7 +81,20 @@ export declare class K2DB {
     private initialized;
     private initPromise?;
     private schemas;
+    private readonly ownershipMode;
+    private readonly aggregationMode;
+    private readonly secureFieldPrefixes;
+    private readonly secureFieldEncryptionKey?;
+    private readonly secureFieldEncryptionKeyId?;
     constructor(conf: DatabaseConfig);
+    /**
+     * Normalize a scope value for ownership enforcement.
+     */
+    private normalizeScope;
+    /**
+     * Apply a scope constraint to criteria for ownership enforcement.
+     */
+    private applyScopeToCriteria;
     /**
      * Initializes the MongoDB connection.
      */
@@ -91,15 +110,21 @@ export declare class K2DB {
      * @param collectionName - Name of the collection.
      */
     private getCollection;
-    get(collectionName: string, uuid: string): Promise<BaseDocument>;
     /**
      * Retrieves a single document by UUID.
      * @param collectionName - Name of the collection.
      * @param uuid - UUID of the document.
-     * @param objectTypeName - Optional object type name.
+     * @param scope - (optional) Owner selector; "*" means all owners.
+     */
+    get(collectionName: string, uuid: string, scope?: Scope | string): Promise<BaseDocument>;
+    /**
+     * Retrieves a single document by criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Criteria to find the document.
      * @param fields - Optional array of fields to include.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    findOne(collectionName: string, criteria: any, fields?: Array<string>): Promise<BaseDocument | null>;
+    findOne(collectionName: string, criteria: any, fields?: Array<string>, scope?: Scope | string): Promise<BaseDocument | null>;
     /**
      * Finds documents based on parameters with pagination support.
      * @param collectionName - Name of the collection.
@@ -107,16 +132,72 @@ export declare 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.
      */
-    find(collectionName: string, filter: any, params?: any, skip?: number, limit?: number): Promise<BaseDocument[]>;
+    find(collectionName: string, filter: any, params?: any, skip?: number, limit?: number, scope?: Scope | string): Promise<BaseDocument[]>;
     /**
-     * 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.
+     */
+    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number, scope?: Scope | string): Promise<BaseDocument[]>;
+    /**
+     * 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
+     */
+    private validateAggregationPipeline;
+    /** Collect top-level stage operators for a pipeline (e.g. "$match", "$lookup"). */
+    private collectStageOps;
+    /** True if a field key is considered secure and must not be returned. */
+    private isSecureFieldKey;
+    /**
+     * 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.
+     */
+    private stripSecureFieldsDeep;
+    /** True if secure-field encryption is enabled (requires both key and keyId). */
+    private hasSecureEncryption;
+    /** Encrypt a JS value using AES-256-GCM and return "<kid>:<ivB64>.<tagB64>.<ctB64>". */
+    private encryptSecureValueToString;
+    /** Decrypt a "<kid>:<ivB64>.<tagB64>.<ctB64>" string back into a JS value. */
+    private decryptSecureStringToValue;
+    /**
+     * 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.
+     */
+    private encryptSecureFieldsDeep;
+    /**
+     * Decrypt secure-prefixed fields in an object/array tree.
+     * If a secure field value is not an encrypted string, it is returned as-is.
+     */
+    private decryptSecureFieldsDeep;
+    /**
+     * 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"}}}).
      */
-    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    private assertNoSecureFieldRefsInPipeline;
+    /** Recursively detects secure field references in an aggregation pipeline AST. */
+    private containsSecureFieldRefDeep;
+    /**
+     * 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" })
+     */
+    private stringHasSecureFieldPath;
+    /** True if any segment in a dotted path starts with a secure prefix. */
+    private pathHasSecureSegment;
+    /**
+     * Ensures an aggregation pipeline respects ownership scope for the root
+     * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
+     */
+    private enforceScopeInPipeline;
     /**
      * Ensures an aggregation pipeline excludes soft-deleted documents for the root
      * collection and any joined collections ($lookup, $unionWith, $graphLookup, $facet).
@@ -135,8 +216,9 @@ export declare 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.
      */
-    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>): Promise<UpdateResult>;
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>, scope?: Scope | string): Promise<UpdateResult>;
     /**
      * Updates a single document by UUID.
      * Can either replace the document or patch it.
@@ -144,60 +226,70 @@ export declare 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.
      */
-    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean): Promise<UpdateResult>;
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, scope?: Scope | string): Promise<UpdateResult>;
     /**
      * 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.
      */
-    deleteAll(collectionName: string, criteria: any): Promise<DeleteResult>;
+    deleteAll(collectionName: string, criteria: any, scope?: Scope | string): Promise<DeleteResult>;
     /**
      * 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.
      */
-    delete(collectionName: string, id: string): Promise<DeleteResult>;
+    delete(collectionName: string, id: string, scope?: Scope | string): Promise<DeleteResult>;
     /**
      * 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.
      */
-    purge(collectionName: string, id: string): Promise<PurgeResult>;
+    purge(collectionName: string, id: string, scope?: Scope | string): Promise<PurgeResult>;
     /**
      * Permanently deletes all documents that are soft-deleted and whose _updated
      * timestamp is older than the provided threshold (in milliseconds ago).
      * @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.
      */
-    purgeDeletedOlderThan(collectionName: string, olderThanMs: number): Promise<PurgeManyResult>;
+    purgeDeletedOlderThan(collectionName: string, olderThanMs: number, scope?: Scope | string): Promise<PurgeManyResult>;
     /**
      * 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.
      */
-    restore(collectionName: string, criteria: any): Promise<RestoreResult>;
+    restore(collectionName: string, criteria: any, scope?: Scope | string): Promise<RestoreResult>;
     /**
      * Counts documents based on criteria.
      * @param collectionName - Name of the collection.
      * @param criteria - Counting criteria.
+     * @param scope - (optional) Owner selector; "*" means all owners.
      */
-    count(collectionName: string, criteria: any): Promise<CountResult>;
+    count(collectionName: string, criteria: any, scope?: Scope | string): Promise<CountResult>;
     /**
-     * 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.
      */
-    drop(collectionName: string): Promise<DropResult>;
+    drop(collectionName: string, scope?: Scope | string): Promise<DropResult>;
     /**
      * Sanitizes aggregation criteria.
      * @param criteria - Aggregation stage criteria.
      */
     private static sanitiseCriteria;
-    /** Recursively uppercases any values for fields named `_uuid` within a query object. */
+    /** Recursively normalizes query fields: `_uuid` uppercased, `_owner` lowercased. */
     private static normalizeCriteriaIds;
     /** Uppercase helper for `_uuid` field supporting operators like $in/$nin/$eq/$ne and arrays. */
     private static normalizeUuidField;
+    /** Lowercase helper for `_owner` field supporting operators like $in/$nin/$eq/$ne and arrays. */
+    private static normalizeOwnerField;
     /** Strip any user-provided fields that start with '_' (reserved). */
     private static stripReservedFields;
     /** True if string matches K2 ID format (Crockford Base32, 8-4-4-4-6, uppercase). */
@@ -274,12 +366,31 @@ export declare class K2DB {
     /**
      * 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.
+     */
+    updateVersioned(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, maxVersions?: number, scope?: Scope | string): Promise<VersionedUpdateResult[]>;
+    /**
+     * 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.
+     */
+    listVersions(collectionName: string, id: string, skip?: number, limit?: number, scope?: Scope | string): Promise<VersionInfo[]>;
+    /**
+     * 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.
      */
-    updateVersioned(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, maxVersions?: number): Promise<VersionedUpdateResult[]>;
-    /** List versions (latest first). */
-    listVersions(collectionName: string, id: string, skip?: number, limit?: number): Promise<VersionInfo[]>;
-    /** Revert the current document to a specific historical version (preserves metadata). */
-    revertToVersion(collectionName: string, id: string, version: number): Promise<{
+    revertToVersion(collectionName: string, id: string, version: number, scope?: Scope | string): Promise<{
         updated: number;
     }>;
 }