mongo.do 0.1.0

package/dist/vectorize/document-serializer.d.ts

@@ -0,0 +1,119 @@
+/**
+ * DocumentSerializer - Extracts text content from MongoDB documents for embedding
+ *
+ * This serializer prepares documents for vector embedding by:
+ * - Extracting text content from specified fields
+ * - Handling nested objects and arrays
+ * - Supporting configurable field selection (include/exclude)
+ * - Extracting metadata for vector storage
+ *
+ * Part of the Vector & Hybrid Search epic (mondodb-txn.3.1)
+ */
+import type { VectorizeMetadata } from '../types/vectorize';
+/**
+ * Options for document serialization
+ */
+export interface SerializerOptions {
+    /**
+     * Fields to include in the serialized text.
+     * Supports dot notation for nested fields (e.g., 'metadata.author')
+     * Supports wildcards (e.g., 'details.*' for all fields under details)
+     * If provided, only these fields will be serialized.
+     */
+    includedFields?: string[];
+    /**
+     * Fields to exclude from the serialized text.
+     * Supports dot notation for nested fields.
+     * Applied after includedFields if both are specified.
+     */
+    excludedFields?: string[];
+    /**
+     * Separator to use between field values.
+     * Default: ' ' (space)
+     */
+    separator?: string;
+    /**
+     * Fields to extract as metadata for vector storage.
+     * Supports dot notation for nested fields.
+     */
+    metadataFields?: string[];
+    /**
+     * Maximum depth to traverse nested objects.
+     * Default: 10
+     */
+    maxDepth?: number;
+    /**
+     * Order of fields in the serialized output.
+     * Fields not in this list appear after ordered fields.
+     */
+    fieldOrder?: string[];
+}
+/**
+ * Result of document serialization
+ */
+export interface SerializedDocument {
+    /** The document ID */
+    documentId: string;
+    /** The serialized text content for embedding */
+    text: string;
+    /** Optional metadata extracted from the document */
+    metadata?: VectorizeMetadata;
+}
+/**
+ * DocumentSerializer - Converts MongoDB documents to text for embedding
+ */
+export declare class DocumentSerializer {
+    /**
+     * Serialize a single document to text for embedding
+     *
+     * @param doc - The MongoDB document to serialize
+     * @param options - Serialization options
+     * @returns Serialized document with text and metadata
+     */
+    serialize(doc: Record<string, unknown>, options?: SerializerOptions): SerializedDocument;
+    /**
+     * Serialize multiple documents in batch
+     *
+     * @param docs - Array of MongoDB documents
+     * @param options - Serialization options applied to all documents
+     * @returns Array of serialized documents
+     */
+    serializeBatch(docs: Record<string, unknown>[], options?: SerializerOptions): SerializedDocument[];
+    /**
+     * Extract the document ID from various formats
+     */
+    private extractDocumentId;
+    /**
+     * Get the list of fields to serialize based on include/exclude options
+     */
+    private getFieldsToSerialize;
+    /**
+     * Expand field patterns including wildcards
+     */
+    private expandFieldPatterns;
+    /**
+     * Check if a field path matches a dot notation pattern
+     */
+    private matchesDotNotation;
+    /**
+     * Get a nested value from an object using dot notation
+     */
+    private getNestedValue;
+    /**
+     * Serialize a value to text
+     */
+    private serializeValue;
+    /**
+     * Check if a field path should be excluded
+     */
+    private isFieldExcluded;
+    /**
+     * Extract metadata fields from the document
+     */
+    private extractMetadata;
+    /**
+     * Convert a value to a valid VectorizeMetadataValue
+     */
+    private toMetadataValue;
+}
+//# sourceMappingURL=document-serializer.d.ts.map

package/dist/vectorize/document-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-serializer.d.ts","sourceRoot":"","sources":["../../src/vectorize/document-serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAA0B,MAAM,oBAAoB,CAAA;AAEnF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IAEzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAC7B;AA0BD;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;OAMG;IACH,SAAS,CACP,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB;IA6CrB;;;;;;OAMG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB,EAAE;IAIvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiD5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAwB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAiFtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,OAAO,CAAC,eAAe;CA2BxB"}

package/dist/vectorize/document-serializer.js

@@ -0,0 +1,320 @@
+/**
+ * DocumentSerializer - Extracts text content from MongoDB documents for embedding
+ *
+ * This serializer prepares documents for vector embedding by:
+ * - Extracting text content from specified fields
+ * - Handling nested objects and arrays
+ * - Supporting configurable field selection (include/exclude)
+ * - Extracting metadata for vector storage
+ *
+ * Part of the Vector & Hybrid Search epic (mondodb-txn.3.1)
+ */
+/**
+ * Fields that are automatically excluded as they likely contain embedding vectors
+ */
+const DEFAULT_EXCLUDED_PATTERNS = [
+    'embedding',
+    'vector',
+    '_embedding',
+    '_vector',
+    'embeddings',
+    'vectors'
+];
+/**
+ * Check if a field name matches vector/embedding patterns
+ */
+function isEmbeddingField(fieldName) {
+    const lowerName = fieldName.toLowerCase();
+    return DEFAULT_EXCLUDED_PATTERNS.some(pattern => lowerName === pattern ||
+        lowerName.endsWith('_' + pattern) ||
+        lowerName.endsWith(pattern));
+}
+/**
+ * DocumentSerializer - Converts MongoDB documents to text for embedding
+ */
+export class DocumentSerializer {
+    /**
+     * Serialize a single document to text for embedding
+     *
+     * @param doc - The MongoDB document to serialize
+     * @param options - Serialization options
+     * @returns Serialized document with text and metadata
+     */
+    serialize(doc, options = {}) {
+        const { includedFields, excludedFields, separator = ' ', metadataFields, maxDepth = 10, fieldOrder } = options;
+        // Extract document ID
+        const documentId = this.extractDocumentId(doc);
+        // Extract metadata if requested
+        const metadata = metadataFields
+            ? this.extractMetadata(doc, metadataFields)
+            : undefined;
+        // Get fields to serialize (excluding _id)
+        const fieldsToSerialize = this.getFieldsToSerialize(doc, includedFields, excludedFields, fieldOrder);
+        // Serialize field values to text
+        const textParts = [];
+        for (const field of fieldsToSerialize) {
+            const value = this.getNestedValue(doc, field);
+            if (value !== undefined && value !== null) {
+                const serialized = this.serializeValue(value, 0, maxDepth, field, excludedFields);
+                if (serialized) {
+                    textParts.push(serialized);
+                }
+            }
+        }
+        return {
+            documentId,
+            text: textParts.join(separator),
+            metadata
+        };
+    }
+    /**
+     * Serialize multiple documents in batch
+     *
+     * @param docs - Array of MongoDB documents
+     * @param options - Serialization options applied to all documents
+     * @returns Array of serialized documents
+     */
+    serializeBatch(docs, options = {}) {
+        return docs.map(doc => this.serialize(doc, options));
+    }
+    /**
+     * Extract the document ID from various formats
+     */
+    extractDocumentId(doc) {
+        const id = doc._id;
+        if (id === undefined || id === null) {
+            return '';
+        }
+        if (typeof id === 'string') {
+            return id;
+        }
+        if (typeof id === 'object' && id !== null && 'toString' in id) {
+            return id.toString();
+        }
+        return String(id);
+    }
+    /**
+     * Get the list of fields to serialize based on include/exclude options
+     */
+    getFieldsToSerialize(doc, includedFields, excludedFields, fieldOrder) {
+        let fields;
+        if (includedFields && includedFields.length > 0) {
+            // Expand wildcards and use only included fields
+            fields = this.expandFieldPatterns(doc, includedFields);
+        }
+        else {
+            // Use all fields except _id
+            fields = Object.keys(doc).filter(f => f !== '_id');
+        }
+        // Apply exclusions
+        if (excludedFields && excludedFields.length > 0) {
+            const excludeSet = new Set(excludedFields);
+            fields = fields.filter(f => {
+                // Check exact match
+                if (excludeSet.has(f))
+                    return false;
+                // Check if any exclusion pattern matches as prefix
+                for (const exclude of excludedFields) {
+                    if (f.startsWith(exclude + '.'))
+                        return false;
+                    // Check dot notation matches
+                    if (this.matchesDotNotation(f, exclude))
+                        return false;
+                }
+                return true;
+            });
+        }
+        // Filter out embedding fields by default
+        fields = fields.filter(f => !isEmbeddingField(f));
+        // Apply field ordering if specified
+        if (fieldOrder && fieldOrder.length > 0) {
+            const orderMap = new Map(fieldOrder.map((f, i) => [f, i]));
+            fields.sort((a, b) => {
+                const aOrder = orderMap.get(a) ?? Infinity;
+                const bOrder = orderMap.get(b) ?? Infinity;
+                if (aOrder === bOrder)
+                    return 0;
+                return aOrder - bOrder;
+            });
+        }
+        return fields;
+    }
+    /**
+     * Expand field patterns including wildcards
+     */
+    expandFieldPatterns(doc, patterns) {
+        const result = [];
+        for (const pattern of patterns) {
+            if (pattern.endsWith('.*')) {
+                // Wildcard pattern - expand to all fields under the prefix
+                const prefix = pattern.slice(0, -2);
+                const nested = this.getNestedValue(doc, prefix);
+                if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+                    for (const key of Object.keys(nested)) {
+                        result.push(`${prefix}.${key}`);
+                    }
+                }
+            }
+            else {
+                result.push(pattern);
+            }
+        }
+        return result;
+    }
+    /**
+     * Check if a field path matches a dot notation pattern
+     */
+    matchesDotNotation(fieldPath, pattern) {
+        const fieldParts = fieldPath.split('.');
+        const patternParts = pattern.split('.');
+        if (patternParts.length > fieldParts.length)
+            return false;
+        for (let i = 0; i < patternParts.length; i++) {
+            if (patternParts[i] !== fieldParts[i])
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Get a nested value from an object using dot notation
+     */
+    getNestedValue(obj, path) {
+        const parts = path.split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            if (typeof current !== 'object') {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+    /**
+     * Serialize a value to text
+     */
+    serializeValue(value, depth, maxDepth, fieldPath = '', excludedFields) {
+        // Check depth limit
+        if (depth >= maxDepth) {
+            return '';
+        }
+        // Handle null/undefined
+        if (value === null || value === undefined) {
+            return '';
+        }
+        // Handle primitives
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'boolean') {
+            return String(value);
+        }
+        // Handle Date
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        // Handle arrays
+        if (Array.isArray(value)) {
+            // Skip if it looks like an embedding vector (array of numbers)
+            if (value.length > 0 && typeof value[0] === 'number' && isEmbeddingField(fieldPath)) {
+                return '';
+            }
+            const parts = [];
+            for (const item of value) {
+                const serialized = this.serializeValue(item, depth + 1, maxDepth, fieldPath, excludedFields);
+                if (serialized) {
+                    parts.push(serialized);
+                }
+            }
+            return parts.join(' ');
+        }
+        // Handle objects
+        if (typeof value === 'object') {
+            const obj = value;
+            const parts = [];
+            for (const [key, val] of Object.entries(obj)) {
+                // Skip embedding fields
+                if (isEmbeddingField(key)) {
+                    continue;
+                }
+                // Build the full path for this nested field
+                const nestedPath = fieldPath ? `${fieldPath}.${key}` : key;
+                // Check if this nested path should be excluded
+                if (excludedFields && this.isFieldExcluded(nestedPath, excludedFields)) {
+                    continue;
+                }
+                const serialized = this.serializeValue(val, depth + 1, maxDepth, nestedPath, excludedFields);
+                if (serialized) {
+                    parts.push(serialized);
+                }
+            }
+            return parts.join(' ');
+        }
+        // Fallback for other types
+        return String(value);
+    }
+    /**
+     * Check if a field path should be excluded
+     */
+    isFieldExcluded(fieldPath, excludedFields) {
+        for (const exclude of excludedFields) {
+            // Exact match
+            if (fieldPath === exclude)
+                return true;
+            // The field is a parent of an excluded field (include it, but children will be checked)
+            // The field starts with the exclusion pattern (it's a child of excluded path)
+            if (fieldPath.startsWith(exclude + '.'))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Extract metadata fields from the document
+     */
+    extractMetadata(doc, metadataFields) {
+        const metadata = {};
+        for (const field of metadataFields) {
+            const value = this.getNestedValue(doc, field);
+            if (value !== undefined) {
+                const metaValue = this.toMetadataValue(value);
+                if (metaValue !== undefined) {
+                    metadata[field] = metaValue;
+                }
+            }
+        }
+        return metadata;
+    }
+    /**
+     * Convert a value to a valid VectorizeMetadataValue
+     */
+    toMetadataValue(value) {
+        if (value === null || value === undefined) {
+            return undefined;
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (typeof value === 'number') {
+            return value;
+        }
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        // Handle string arrays
+        if (Array.isArray(value)) {
+            if (value.every(item => typeof item === 'string')) {
+                return value;
+            }
+            // Convert non-string arrays to string arrays
+            return value.map(item => String(item));
+        }
+        // For other types, convert to string
+        return String(value);
+    }
+}
+//# sourceMappingURL=document-serializer.js.map

package/dist/vectorize/document-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-serializer.js","sourceRoot":"","sources":["../../src/vectorize/document-serializer.ts"],"names":[],"mappings":"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"}

package/dist/wire/auth/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Authentication module exports
+ */
+export { ScramAuthenticator, InMemoryCredentialsProvider, createScramCredentials, type StoredCredentials, type ScramConversation, type ScramResult, type CredentialsProvider, } from './scram.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/wire/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wire/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAA"}

package/dist/wire/auth/index.js

@@ -0,0 +1,5 @@
+/**
+ * Authentication module exports
+ */
+export { ScramAuthenticator, InMemoryCredentialsProvider, createScramCredentials, } from './scram.js';
+//# sourceMappingURL=index.js.map

package/dist/wire/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/wire/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,GAKvB,MAAM,YAAY,CAAA"}

package/dist/wire/auth/scram.d.ts

@@ -0,0 +1,160 @@
+/**
+ * SCRAM-SHA-256 Authentication Implementation
+ *
+ * Implements the Salted Challenge Response Authentication Mechanism (SCRAM)
+ * per RFC 5802 and RFC 7677 (SHA-256 variant).
+ *
+ * MongoDB uses SCRAM-SHA-256 as its primary authentication mechanism.
+ */
+import { Binary } from 'bson';
+/** User credentials stored in the system */
+export interface StoredCredentials {
+    username: string;
+    /** Salt for SCRAM (base64 encoded) */
+    salt: string;
+    /** Stored key (base64 encoded) */
+    storedKey: string;
+    /** Server key (base64 encoded) */
+    serverKey: string;
+    /** Iteration count for PBKDF2 */
+    iterationCount: number;
+    /** Database the user belongs to */
+    db: string;
+    /** Roles assigned to the user */
+    roles?: Array<{
+        role: string;
+        db: string;
+    }>;
+}
+/** SCRAM conversation state */
+export interface ScramConversation {
+    username: string;
+    db: string;
+    clientNonce: string;
+    serverNonce: string;
+    salt: string;
+    iterationCount: number;
+    clientFirstMessageBare: string;
+    serverFirstMessage: string;
+    step: 'init' | 'challenge' | 'complete';
+}
+/** SCRAM authentication result */
+export interface ScramResult {
+    success: boolean;
+    conversationId?: number;
+    payload?: Buffer;
+    done: boolean;
+    error?: string;
+}
+/** Credentials provider interface */
+export interface CredentialsProvider {
+    getCredentials(username: string, db: string): Promise<StoredCredentials | null>;
+}
+/**
+ * SCRAM-SHA-256 Authenticator
+ *
+ * Handles server-side SCRAM authentication flow.
+ */
+export declare class ScramAuthenticator {
+    private credentialsProvider;
+    private conversations;
+    private nextConversationId;
+    constructor(credentialsProvider: CredentialsProvider);
+    /**
+     * Handle saslStart command - begin authentication
+     *
+     * @param mechanism - Should be "SCRAM-SHA-256"
+     * @param payload - Client's first message (Binary or Buffer)
+     * @param db - Authentication database
+     */
+    saslStart(mechanism: string, payload: Binary | Buffer | Uint8Array, db: string): Promise<ScramResult>;
+    /**
+     * Handle saslContinue command - continue authentication
+     *
+     * @param conversationId - Conversation ID from saslStart
+     * @param payload - Client's response message
+     */
+    saslContinue(conversationId: number, payload: Binary | Buffer | Uint8Array): Promise<ScramResult>;
+    /**
+     * Parse client-first-message
+     * Format: gs2-header n=username,r=client-nonce
+     * gs2-header is typically "n,," (no channel binding, no authzid)
+     */
+    private parseClientFirstMessage;
+    /**
+     * Parse client-final-message
+     * Format: c=channel-binding,r=nonce,p=client-proof
+     */
+    private parseClientFinalMessage;
+    /**
+     * Verify client proof and generate server signature
+     */
+    private verifyClientProof;
+    /**
+     * Generate a random nonce
+     */
+    private generateNonce;
+    /**
+     * Generate a random salt
+     */
+    private generateSalt;
+    /**
+     * Compute SHA-256 hash
+     */
+    private sha256;
+    /**
+     * Compute HMAC-SHA-256
+     */
+    private hmacSha256;
+    /**
+     * Timing-safe comparison
+     */
+    private timingSafeEqual;
+    /**
+     * Clean up a conversation
+     */
+    cleanupConversation(conversationId: number): void;
+    /**
+     * Get conversation username for successful auth
+     */
+    getConversationUser(conversationId: number): {
+        username: string;
+        db: string;
+    } | null;
+}
+/**
+ * Create SCRAM credentials from a password
+ *
+ * This is used when adding users to generate the stored credentials.
+ */
+export declare function createScramCredentials(username: string, password: string, db: string, iterationCount?: number): Promise<StoredCredentials>;
+/**
+ * In-memory credentials provider for testing and simple deployments
+ */
+export declare class InMemoryCredentialsProvider implements CredentialsProvider {
+    private credentials;
+    /**
+     * Add a user with a password
+     */
+    addUser(username: string, password: string, db: string, roles?: Array<{
+        role: string;
+        db: string;
+    }>): Promise<void>;
+    /**
+     * Add pre-computed credentials
+     */
+    addCredentials(credentials: StoredCredentials): void;
+    /**
+     * Get credentials for a user
+     */
+    getCredentials(username: string, db: string): Promise<StoredCredentials | null>;
+    /**
+     * Remove a user
+     */
+    removeUser(username: string, db: string): boolean;
+    /**
+     * Check if a user exists
+     */
+    hasUser(username: string, db: string): boolean;
+}
+//# sourceMappingURL=scram.d.ts.map

package/dist/wire/auth/scram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scram.d.ts","sourceRoot":"","sources":["../../../src/wire/auth/scram.ts"],"names":[],"mappings":"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"}