@frogfish/k2db 2.0.7 → 3.0.2

package/{dist/db.d.ts → db.d.ts}

@@ -1,5 +1,12 @@
 import { ObjectId } from "mongodb";
 import { ZodTypeAny } from "zod";
+/**
+ * Test helper: fully reset the shared MongoClient pool.
+ *
+ * Not for production usage; intended for test runners to clean up
+ * between suites without restarting the process.
+ */
+export declare function resetSharedMongoClientsForTests(): Promise<void>;
 export interface HostConfig {
     host: string;
     port?: number;
@@ -8,6 +15,7 @@ export interface DatabaseConfig {
     name: string;
     user?: string;
     password?: string;
+    authSource?: string;
     hosts?: HostConfig[];
     replicaset?: string;
     slowQueryMs?: number;
@@ -15,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;
@@ -59,12 +72,29 @@ export interface VersionInfo {
     _v: number;
     _at: number;
 }
+export type Scope = string | "*";
 export declare class K2DB {
     private conf;
     private db;
     private connection;
+    private clientKey?;
+    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.
      */
@@ -80,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.
@@ -96,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"}}}).
+     */
+    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" })
      */
-    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    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).
@@ -124,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.
@@ -133,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). */
@@ -240,12 +343,6 @@ export declare class K2DB {
      * Optional: Checks the health of the database connection.
      */
     isHealthy(): Promise<boolean>;
-    /**
-     * Utility to normalize the error type.
-     * @param err - The caught error of type `unknown`.
-     * @returns A normalized error of type `Error`.
-     */
-    private normalizeError;
     /** Name of the history collection for a given collection. */
     private historyName;
     /** Register a Zod schema for a collection. */
@@ -269,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;
     }>;
 }