@opensaas/stack-rag 0.1.6 → 0.3.0

package/src/storage/access-filter.ts

@@ -0,0 +1,303 @@
+import type { AccessContext, PrismaFilter, AccessControl } from '@opensaas/stack-core'
+import type { OpenSaasConfig } from '@opensaas/stack-core'
+
+/**
+ * Execute an access control function (copied from @opensaas/stack-core/access)
+ */
+async function checkAccess<T = Record<string, unknown>>(
+  accessControl: AccessControl<T> | undefined,
+  args: {
+    session: AccessContext['session']
+    item?: T
+    context: AccessContext
+  },
+): Promise<boolean | PrismaFilter<T>> {
+  // No access control means deny by default
+  if (!accessControl) {
+    return false
+  }
+
+  // Execute the access control function
+  const result = await accessControl(args)
+
+  return result
+}
+
+/**
+ * Merge user filter with access control filter (copied from @opensaas/stack-core/access)
+ */
+function mergeFilters(
+  userFilter: PrismaFilter | undefined,
+  accessFilter: boolean | PrismaFilter,
+): PrismaFilter | null {
+  // If access is denied, return null
+  if (accessFilter === false) {
+    return null
+  }
+
+  // If access is fully granted, use user filter
+  if (accessFilter === true) {
+    return userFilter || {}
+  }
+
+  // Merge access filter with user filter
+  if (!userFilter) {
+    return accessFilter
+  }
+
+  // Combine filters with AND
+  return {
+    AND: [accessFilter, userFilter],
+  }
+}
+
+/**
+ * Build access control filter for a given list and context
+ * Extracts the filter that would be applied by the access control engine
+ *
+ * @param listKey - The list name (e.g., 'Post', 'Article')
+ * @param context - The access context with session
+ * @param config - The OpenSaas configuration
+ * @returns Prisma filter object or null if access is denied
+ */
+export async function buildAccessControlFilter(
+  listKey: string,
+  context: AccessContext,
+  config: OpenSaasConfig,
+): Promise<PrismaFilter | null> {
+  const listConfig = config.lists[listKey]
+
+  if (!listConfig) {
+    throw new Error(`List '${listKey}' not found in config`)
+  }
+
+  // Check query access control
+  const queryAccess = listConfig.access?.operation?.query
+
+  if (!queryAccess) {
+    // No access control means deny by default (following OpenSaaS Stack pattern)
+    return null
+  }
+
+  // Execute access control function
+  const accessResult = await checkAccess(queryAccess, {
+    session: context.session,
+    context,
+  })
+
+  // If access is denied (false), return null
+  if (accessResult === false) {
+    return null
+  }
+
+  // If access is fully granted (true), return empty filter
+  if (accessResult === true) {
+    return {}
+  }
+
+  // Otherwise, return the filter object
+  return accessResult
+}
+
+/**
+ * Merge access control filter with user-provided where clause
+ *
+ * @param accessFilter - Filter from access control
+ * @param userWhere - User-provided where clause
+ * @returns Combined filter or null if access is denied
+ */
+export function mergeAccessFilter(
+  accessFilter: PrismaFilter | null,
+  userWhere: Record<string, unknown> = {},
+): PrismaFilter | null {
+  if (accessFilter === null) {
+    return null
+  }
+
+  return mergeFilters(userWhere, accessFilter)
+}
+
+/**
+ * Convert a Prisma filter object to SQL WHERE clause
+ * Handles common Prisma filter operators
+ *
+ * @param filter - Prisma filter object
+ * @param tableName - Table name for column references
+ * @returns SQL WHERE clause string (without "WHERE" keyword)
+ */
+export function prismaFilterToSQL(filter: PrismaFilter, tableName?: string): string {
+  if (!filter || Object.keys(filter).length === 0) {
+    return 'TRUE' // No filter means all records
+  }
+
+  const conditions: string[] = []
+
+  for (const [key, value] of Object.entries(filter)) {
+    // Handle logical operators
+    if (key === 'AND') {
+      if (!Array.isArray(value)) continue
+      const andConditions = value
+        .map((subFilter) => prismaFilterToSQL(subFilter, tableName))
+        .filter((c) => c !== 'TRUE')
+      if (andConditions.length > 0) {
+        conditions.push(`(${andConditions.join(' AND ')})`)
+      }
+      continue
+    }
+
+    if (key === 'OR') {
+      if (!Array.isArray(value)) continue
+      const orConditions = value
+        .map((subFilter) => prismaFilterToSQL(subFilter, tableName))
+        .filter((c) => c !== 'TRUE')
+      if (orConditions.length > 0) {
+        conditions.push(`(${orConditions.join(' OR ')})`)
+      }
+      continue
+    }
+
+    if (key === 'NOT') {
+      const notCondition = prismaFilterToSQL(value as PrismaFilter, tableName)
+      if (notCondition !== 'TRUE') {
+        conditions.push(`NOT (${notCondition})`)
+      }
+      continue
+    }
+
+    // Handle field conditions
+    const columnName = tableName ? `"${tableName}"."${key}"` : `"${key}"`
+
+    if (value === null) {
+      conditions.push(`${columnName} IS NULL`)
+      continue
+    }
+
+    if (typeof value !== 'object' || value === null) {
+      // Direct equality
+      const escapedValue = escapeSQLValue(value)
+      conditions.push(`${columnName} = ${escapedValue}`)
+      continue
+    }
+
+    // Handle nested field conditions
+    const fieldConditions: string[] = []
+
+    for (const [operator, operatorValue] of Object.entries(value)) {
+      switch (operator) {
+        case 'equals':
+          if (operatorValue === null) {
+            fieldConditions.push(`${columnName} IS NULL`)
+          } else {
+            fieldConditions.push(`${columnName} = ${escapeSQLValue(operatorValue)}`)
+          }
+          break
+
+        case 'not':
+          if (operatorValue === null) {
+            fieldConditions.push(`${columnName} IS NOT NULL`)
+          } else {
+            fieldConditions.push(`${columnName} != ${escapeSQLValue(operatorValue)}`)
+          }
+          break
+
+        case 'in':
+          if (Array.isArray(operatorValue) && operatorValue.length > 0) {
+            const values = operatorValue.map((v) => escapeSQLValue(v)).join(', ')
+            fieldConditions.push(`${columnName} IN (${values})`)
+          }
+          break
+
+        case 'notIn':
+          if (Array.isArray(operatorValue) && operatorValue.length > 0) {
+            const values = operatorValue.map((v) => escapeSQLValue(v)).join(', ')
+            fieldConditions.push(`${columnName} NOT IN (${values})`)
+          }
+          break
+
+        case 'lt':
+          fieldConditions.push(`${columnName} < ${escapeSQLValue(operatorValue)}`)
+          break
+
+        case 'lte':
+          fieldConditions.push(`${columnName} <= ${escapeSQLValue(operatorValue)}`)
+          break
+
+        case 'gt':
+          fieldConditions.push(`${columnName} > ${escapeSQLValue(operatorValue)}`)
+          break
+
+        case 'gte':
+          fieldConditions.push(`${columnName} >= ${escapeSQLValue(operatorValue)}`)
+          break
+
+        case 'contains':
+          fieldConditions.push(`${columnName} LIKE ${escapeSQLValue(`%${operatorValue}%`)}`)
+          break
+
+        case 'startsWith':
+          fieldConditions.push(`${columnName} LIKE ${escapeSQLValue(`${operatorValue}%`)}`)
+          break
+
+        case 'endsWith':
+          fieldConditions.push(`${columnName} LIKE ${escapeSQLValue(`%${operatorValue}`)}`)
+          break
+
+        case 'isNull':
+          if (operatorValue === true) {
+            fieldConditions.push(`${columnName} IS NULL`)
+          } else {
+            fieldConditions.push(`${columnName} IS NOT NULL`)
+          }
+          break
+
+        // Add more operators as needed
+        default:
+          console.warn(`Unsupported Prisma filter operator: ${operator}`)
+      }
+    }
+
+    if (fieldConditions.length > 0) {
+      conditions.push(fieldConditions.join(' AND '))
+    }
+  }
+
+  if (conditions.length === 0) {
+    return 'TRUE'
+  }
+
+  if (conditions.length === 1) {
+    return conditions[0]
+  }
+
+  return conditions.join(' AND ')
+}
+
+/**
+ * Escape SQL values to prevent SQL injection
+ * Basic escaping - in production, use parameterized queries
+ */
+function escapeSQLValue(value: unknown): string {
+  if (value === null) {
+    return 'NULL'
+  }
+
+  if (typeof value === 'string') {
+    // Escape single quotes by doubling them
+    return `'${value.replace(/'/g, "''")}'`
+  }
+
+  if (typeof value === 'number') {
+    return value.toString()
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'TRUE' : 'FALSE'
+  }
+
+  if (value instanceof Date) {
+    return `'${value.toISOString()}'`
+  }
+
+  // Fallback for other types
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/src/storage/index.ts

@@ -82,5 +82,9 @@ export function createVectorStorage(config: VectorStorageConfig): VectorStorage
 // Export types and individual storage backends
 export * from './types.js'
 export { JsonVectorStorage, createJsonStorage } from './json.js'
+export { JsonFileStorage, createJsonFileStorage } from './json-file.js'
 export { PgVectorStorage, createPgVectorStorage } from './pgvector.js'
 export { SqliteVssStorage, createSqliteVssStorage } from './sqlite-vss.js'
+
+// Export access control utilities
+export { buildAccessControlFilter, mergeAccessFilter, prismaFilterToSQL } from './access-filter.js'

package/src/storage/json-file.ts

@@ -0,0 +1,157 @@
+import { readFileSync, existsSync } from 'node:fs'
+import type { VectorStorage, SearchOptions } from './types.js'
+import type { SearchResult, EmbeddingsIndex } from '../config/types.js'
+import { cosineSimilarity as calculateCosineSimilarity } from './types.js'
+
+/**
+ * JSON file-based vector storage
+ * Loads embeddings from a JSON file generated at build time
+ * Performs similarity search in JavaScript without database queries
+ * Ideal for static sites, documentation, and build-time generated embeddings
+ */
+export class JsonFileStorage implements VectorStorage {
+  readonly type = 'json-file'
+
+  private index: EmbeddingsIndex | null = null
+  private filePath: string
+
+  constructor(filePath: string) {
+    this.filePath = filePath
+  }
+
+  /**
+   * Load embeddings index from file
+   * Caches the result in memory
+   */
+  private loadIndex(): EmbeddingsIndex {
+    if (this.index) {
+      return this.index
+    }
+
+    if (!existsSync(this.filePath)) {
+      throw new Error(
+        `Embeddings file not found: ${this.filePath}. Run embeddings generation first.`,
+      )
+    }
+
+    try {
+      const content = readFileSync(this.filePath, 'utf-8')
+      this.index = JSON.parse(content) as EmbeddingsIndex
+      return this.index
+    } catch (error) {
+      throw new Error(`Failed to load embeddings from ${this.filePath}: ${error}`)
+    }
+  }
+
+  /**
+   * Search for similar documents using JavaScript-based cosine similarity
+   * Note: listKey parameter is included for interface compatibility but not used
+   * since this storage is typically used for standalone content (e.g., docs)
+   */
+  async search<T = unknown>(
+    _listKey: string,
+    _fieldName: string,
+    queryVector: number[],
+    options: SearchOptions,
+  ): Promise<SearchResult<T>[]> {
+    const { limit = 10, minScore = 0.0, where = {} } = options
+
+    const index = this.loadIndex()
+
+    // Validate query vector dimensions against index config
+    if (queryVector.length !== index.config.dimensions) {
+      throw new Error(
+        `Query vector dimensions (${queryVector.length}) don't match index dimensions (${index.config.dimensions})`,
+      )
+    }
+
+    const results: Array<{
+      item: T
+      score: number
+      distance: number
+      documentId: string
+      chunkIndex: number
+    }> = []
+
+    // Search through all documents and chunks
+    for (const [documentId, document] of Object.entries(index.documents)) {
+      // Apply where filters if provided (simple equality check)
+      if (where && Object.keys(where).length > 0) {
+        let matches = true
+        for (const [key, value] of Object.entries(where)) {
+          if ((document as Record<string, unknown>)[key] !== value) {
+            matches = false
+            break
+          }
+        }
+        if (!matches) continue
+      }
+
+      // Search through each chunk
+      for (const chunk of document.chunks) {
+        const score = this.cosineSimilarity(queryVector, chunk.embedding)
+
+        if (score >= minScore) {
+          results.push({
+            item: {
+              documentId,
+              title: document.title,
+              content: chunk.text,
+              chunkIndex: chunk.metadata.chunkIndex,
+              metadata: chunk.metadata,
+            } as T,
+            score,
+            distance: 1 - score,
+            documentId,
+            chunkIndex: chunk.metadata.chunkIndex,
+          })
+        }
+      }
+    }
+
+    // Sort by score (descending) and limit results
+    results.sort((a, b) => b.score - a.score)
+
+    return results.slice(0, limit)
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   */
+  cosineSimilarity(a: number[], b: number[]): number {
+    return calculateCosineSimilarity(a, b)
+  }
+
+  /**
+   * Get the loaded index for inspection
+   */
+  getIndex(): EmbeddingsIndex | null {
+    return this.index
+  }
+
+  /**
+   * Force reload the index from disk
+   */
+  reloadIndex(): void {
+    this.index = null
+    this.loadIndex()
+  }
+}
+
+/**
+ * Create a JSON file vector storage instance
+ *
+ * @example
+ * ```typescript
+ * import { createJsonFileStorage } from '@opensaas/stack-rag/storage'
+ *
+ * const storage = createJsonFileStorage('.embeddings/docs.json')
+ * const results = await storage.search('', '', queryVector, {
+ *   limit: 10,
+ *   minScore: 0.7
+ * })
+ * ```
+ */
+export function createJsonFileStorage(filePath: string): JsonFileStorage {
+  return new JsonFileStorage(filePath)
+}

package/src/storage/pgvector.ts

@@ -3,6 +3,7 @@ import type { SearchResult } from '../config/types.js'
 import type { PgVectorStorageConfig } from '../config/types.js'
 import { cosineSimilarity as calculateCosineSimilarity } from './types.js'
 import { getDbKey } from '@opensaas/stack-core'
+import { buildAccessControlFilter, mergeAccessFilter, prismaFilterToSQL } from './access-filter.js'
 
 /**
  * pgvector storage backend
@@ -62,7 +63,7 @@ export class PgVectorStorage implements VectorStorage {
     queryVector: number[],
     options: SearchOptions,
   ): Promise<SearchResult<T>[]> {
-    const { limit = 10, minScore = 0.0, context, where = {} } = options
+    const { limit = 10, minScore = 0.0, context, where = {}, config } = options
 
     const dbKey = getDbKey(listKey)
     const model = context.db[dbKey]
@@ -78,15 +79,11 @@ export class PgVectorStorage implements VectorStorage {
     const vectorString = `[${queryVector.join(',')}]`
 
     // We need to use Prisma.$queryRaw to access pgvector operators
-    // The access-controlled context.db doesn't expose $queryRaw directly,
-    // so we need to use a two-step approach:
-    // 1. Get all matching IDs using raw query
-    // 2. Fetch full items via access-controlled context
+    // However, we must enforce access control in the raw query itself
+    // to ensure users only see items they have access to
 
     try {
       // Get the underlying Prisma client
-      // Note: This bypasses access control for the similarity search,
-      // but we enforce it in the second query
       const prisma = context.prisma
 
       if (!prisma) {
@@ -94,20 +91,43 @@ export class PgVectorStorage implements VectorStorage {
         console.warn(
           'pgvector: Could not access Prisma client directly. ' +
             'Falling back to JSON-based search. ' +
-            'For full pgvector support, ensure the context exposes _prisma.',
+            'For full pgvector support, ensure the context exposes prisma.',
         )
         return this.fallbackSearch(listKey, fieldName, queryVector, options)
       }
 
-      // Raw query to get IDs and distances
+      // Build access control filter
+      let accessFilter = null
+      if (config) {
+        accessFilter = await buildAccessControlFilter(listKey, context, config)
+
+        // If access is denied, return empty results
+        if (accessFilter === null) {
+          return []
+        }
+      }
+
+      // Merge access filter with user where clause
+      const combinedFilter = accessFilter ? mergeAccessFilter(accessFilter, where) : where
+
+      // If merged filter is null (access denied), return empty results
+      if (combinedFilter === null) {
+        return []
+      }
+
+      // Convert Prisma filter to SQL WHERE clause
+      const tableName = listKey // Prisma table names match the model name (PascalCase by default)
+      const sqlWhereClause = prismaFilterToSQL(combinedFilter, tableName)
+
+      // Raw query to get IDs and distances with access control
       // We extract the vector from the JSON field and cast it to vector type
-      const tableName = listKey.toLowerCase() // Prisma table names are lowercase
       const results = (await prisma.$queryRawUnsafe(`
         SELECT id,
                (("${fieldName}"->>'vector')::vector ${distanceOp} '${vectorString}'::vector) as distance
         FROM "${tableName}"
         WHERE "${fieldName}" IS NOT NULL
           AND "${fieldName}"->>'vector' IS NOT NULL
+          AND (${sqlWhereClause})
         ORDER BY distance
         LIMIT ${limit * 2}
       `)) as Array<{ id: string; distance: string }>
@@ -128,9 +148,9 @@ export class PgVectorStorage implements VectorStorage {
       }
 
       // Fetch full items via access-controlled context
+      // This applies field-level access control and resolveOutput hooks
       const items = await model.findMany({
         where: {
-          ...where,
           id: {
             in: itemIds.map((r) => r.id),
           },

package/src/storage/storage.test.ts

@@ -13,6 +13,8 @@ function createMockContext(dbOverrides: Record<string, unknown> = {}): AccessCon
     sudo: vi.fn(),
     prisma: {} as unknown,
     storage: {} as unknown,
+    plugins: {},
+    _isSudo: false,
   } as AccessContext<unknown>
 }
 

package/src/storage/types.ts

@@ -65,6 +65,12 @@ export type SearchOptions = {
    * This is merged with access control filters
    */
   where?: Record<string, unknown>
+
+  /**
+   * OpenSaaS config for access control integration
+   * Required to properly enforce access control in raw SQL queries
+   */
+  config?: import('@opensaas/stack-core').OpenSaasConfig
 }
 
 /**