feat(knowledge): permission-aware knowledge bases behind a feature flag

apps/docs/content/docs/integrations/knowledge.mdx

@@ -33,7 +33,7 @@ Integrate Knowledge into the workflow. Perform full CRUD operations on documents
 
 ### Knowledge Search
 
-Search for similar content in a knowledge base using vector similarity
+Search for similar content in a knowledge base by relevance
 
 #### Input
 
@@ -43,7 +43,7 @@ Search for similar content in a knowledge base using vector similarity
 | `query` | string | No | Search query text \(optional when using tag filters\) |
 | `topK` | number | No | Number of most similar results to return \(1-100\) |
 | `tagFilters` | array | No | Array of tag filters with tagName and tagValue properties |
-| `searchMode` | string | No | Retrieval mode: 'vector' \(default\) uses semantic similarity only, 'hybrid' also runs a full-text leg and fuses both |
+| `searchMode` | string | No | Retrieval mode: 'hybrid' fuses a full-text leg with semantic similarity, 'vector' uses semantic similarity only; omit for the workspace's default |
 | `rerankerEnabled` | boolean | No | Whether to apply Cohere reranking to vector search results |
 | `rerankerModel` | string | No | Cohere rerank model to use \(one of: rerank-v4.0-pro, rerank-v4.0-fast, rerank-v3.5\) |
 | `rerankerInputCount` | number | No | Number of vector results sent to the Cohere reranker \(1–100\). Defaults to topK × 4 capped at 100. |

apps/docs/openapi-v2-knowledge.json

@@ -6144,7 +6144,6 @@
           },
           "searchMode": {
             "description": "Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search.",
-            "default": "vector",
             "anyOf": [
               {
                 "type": "string",

apps/sim/.env.example

@@ -203,6 +203,7 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # FORKING_ENABLED=                                                # Workspace forks
 # CREDENTIAL_GROUPS=                                              # Enterprise managed OAuth collections
 # TABLE_ROW_TTL=                                                  # Table TTL columns and expired-row cleanup
+# KNOWLEDGE_MEMBER_ACCESS=                                        # Per-member knowledge connectors and hybrid-by-default retrieval
 # ORGANIZATIONS_ENABLED= / NEXT_PUBLIC_ORGANIZATIONS_ENABLED=     # Organizations only
 
 # Instance organization (Optional). Most enterprise features read their settings from the

apps/sim/app/api/files/authorization.ts

@@ -4,6 +4,12 @@ import { createLogger } from '@sim/logger'
 import { permissionSatisfies } from '@sim/platform-authz/workspace'
 import { and, eq, isNull } from 'drizzle-orm'
 import { NextResponse } from 'next/server'
+import { knowledgeAccessCondition } from '@/lib/knowledge/access/predicate'
+import {
+  resolveUserKnowledgeAccessScope,
+  WORKSPACE_ACCESS_SCOPE,
+} from '@/lib/knowledge/access/scope'
+import type { KnowledgeAccessScope, SystemAccessScope } from '@/lib/knowledge/access/types'
 import { getFileMetadata } from '@/lib/uploads'
 import type { StorageContext } from '@/lib/uploads/config'
 import type { StorageConfig } from '@/lib/uploads/core/storage-client'
@@ -141,7 +147,7 @@ export async function verifyFileAccess(
   customConfig?: StorageConfig,
   context?: StorageContext | 'general',
   isLocal?: boolean,
-  options?: { requireWrite?: boolean }
+  options?: { requireWrite?: boolean; knowledgeAccess?: KnowledgeFileAccess }
 ): Promise<boolean> {
   const requireWrite = options?.requireWrite ?? false
   try {
@@ -182,7 +188,7 @@ export async function verifyFileAccess(
 
     // 4. KB files: kb/filename
     if (inferredContext === 'knowledge-base') {
-      return await verifyKBFileAccess(cloudKey, userId, customConfig)
+      return await verifyKBFileAccess(cloudKey, userId, customConfig, options?.knowledgeAccess)
     }
 
     // 5. Chat files: chat/filename
@@ -485,7 +491,14 @@ async function verifyCopilotFileAccess(
  * signal only: it reflects whether the file is still part of a live KB, not who
  * owns it (ownership comes from the binding).
  */
-async function hasActiveKbDocumentForKey(cloudKey: string, workspaceId: string): Promise<boolean> {
+/** A reader once resolved: a person's or the workspace's tokens, or the system reading its own rows. */
+type ResolvedKnowledgeFileAccess = KnowledgeAccessScope | SystemAccessScope
+
+async function hasActiveKbDocumentForKey(
+  cloudKey: string,
+  workspaceId: string,
+  access: ResolvedKnowledgeFileAccess
+): Promise<boolean> {
   const rows = await db
     .select({ id: document.id })
     .from(document)
@@ -497,14 +510,35 @@ async function hasActiveKbDocumentForKey(cloudKey: string, workspaceId: string):
         eq(document.userExcluded, false),
         isNull(document.archivedAt),
         isNull(document.deletedAt),
-        isNull(knowledgeBase.deletedAt)
+        isNull(knowledgeBase.deletedAt),
+        knowledgeAccessCondition(access)
       )
     )
     .limit(1)
 
   return rows.length > 0
 }
 
+/**
+ * How a KB file read identifies the reader for document access. `'user'` is
+ * for a session-authenticated person; a resolved scope is for a caller that
+ * already holds one (an execution with a principal). The system scope is for
+ * a background job reading a connector-owned row it is processing, which in
+ * members mode is hidden until the sync materializes its readers. Anything
+ * else — an internal token, a tool running with the workflow owner's id —
+ * reads as the workspace, never as the person whose id it happens to carry.
+ */
+export type KnowledgeFileAccess = 'user' | ResolvedKnowledgeFileAccess
+
+async function resolveKnowledgeFileAccess(
+  knowledgeAccess: KnowledgeFileAccess | undefined,
+  userId: string,
+  workspaceId: string
+): Promise<ResolvedKnowledgeFileAccess> {
+  if (knowledgeAccess === 'user') return resolveUserKnowledgeAccessScope(userId, workspaceId)
+  return knowledgeAccess ?? WORKSPACE_ACCESS_SCOPE
+}
+
 /**
  * Verify access to KB files (`kb/<key>`).
  *
@@ -522,7 +556,8 @@ async function hasActiveKbDocumentForKey(cloudKey: string, workspaceId: string):
 async function verifyKBFileAccess(
   cloudKey: string,
   userId: string,
-  customConfig?: StorageConfig
+  customConfig?: StorageConfig,
+  knowledgeAccess?: KnowledgeFileAccess
 ): Promise<boolean> {
   try {
     const binding = await getFileMetadataByKey(cloudKey, 'knowledge-base', {
@@ -552,10 +587,12 @@ async function verifyKBFileAccess(
       return false
     }
 
-    if (!(await hasActiveKbDocumentForKey(cloudKey, binding.workspaceId))) {
-      logger.warn('KB file access denied: no active document references the file', {
+    const access = await resolveKnowledgeFileAccess(knowledgeAccess, userId, binding.workspaceId)
+    if (!(await hasActiveKbDocumentForKey(cloudKey, binding.workspaceId, access))) {
+      logger.warn('KB file access denied: no readable document references the file', {
         userId,
         cloudKey,
+        accessScopeKind: access.kind,
       })
       return false
     }

apps/sim/app/api/files/export/[id]/route.test.ts

@@ -25,7 +25,10 @@ function embeds(...ids: string[]) {
   mockExtractEmbeddedFileRefs.mockReturnValue({ keys: [], ids })
 }
 
-vi.mock('@/lib/auth/hybrid', () => ({ checkSessionOrInternalAuth: mockCheckAuth }))
+vi.mock('@/lib/auth/hybrid', () => ({
+  AuthType: { SESSION: 'session', API_KEY: 'api_key', INTERNAL_JWT: 'internal_jwt' },
+  checkSessionOrInternalAuth: mockCheckAuth,
+}))
 vi.mock('@/lib/uploads/server/metadata', () => ({
   getFileMetadataById: mockGetFileMetadataById,
 }))

apps/sim/app/api/files/export/[id]/route.ts

@@ -7,7 +7,7 @@ import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { fileExportContract } from '@/lib/api/contracts/storage-transfer'
 import { parseRequest } from '@/lib/api/server'
-import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { MATERIALIZE_CONCURRENCY, mapWithConcurrency } from '@/lib/core/utils/concurrency'
 import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -81,7 +81,10 @@ export const GET = withRouteHandler(
       return NextResponse.json({ error: 'Not found' }, { status: 404 })
     }
 
-    const hasAccess = await verifyFileAccess(record.key, userId)
+    const knowledgeAccess = authResult.authType === AuthType.SESSION ? 'user' : undefined
+    const hasAccess = await verifyFileAccess(record.key, userId, undefined, undefined, undefined, {
+      knowledgeAccess,
+    })
     if (!hasAccess) {
       logger.warn('Unauthorized file export attempt', { id, userId })
       return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
@@ -164,7 +167,13 @@ export const GET = withRouteHandler(
         try {
           const imgRecord = await getFileMetadataById(storedFileId(imageId))
           if (!imgRecord) return null
-          if (!(await verifyFileAccess(imgRecord.key, userId))) return null
+          if (
+            !(await verifyFileAccess(imgRecord.key, userId, undefined, undefined, undefined, {
+              knowledgeAccess,
+            }))
+          ) {
+            return null
+          }
           return { imageId, record: imgRecord, size: getWorkspaceFileSize(imgRecord) }
         } catch (error) {
           logger.warn('Failed to resolve asset for export', {

apps/sim/app/api/files/serve/[...path]/route.test.ts

@@ -397,7 +397,8 @@ describe('File Serve API Route', () => {
       'test-user-id',
       undefined,
       'mothership',
-      false
+      false,
+      { knowledgeAccess: undefined }
     )
     expect(storageServiceMockFns.mockDownloadFile).toHaveBeenCalledWith({
       key: 'workspace/test-workspace-id/1234567890-photo.png',

apps/sim/app/api/files/serve/[...path]/route.ts

@@ -8,7 +8,7 @@ import {
   concealCrossTenantResourceError,
   InternalUnauthenticatedError,
 } from '@/lib/api/server/routes'
-import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { resolveServableDocBytes } from '@/lib/copilot/tools/server/files/doc-compile'
 import { DocCompileUserError } from '@/lib/copilot/tools/server/files/doc-compile-error'
 import { asOrchestrationError } from '@/lib/core/orchestration/types'
@@ -26,7 +26,7 @@ import { internalWorkspaceFileServeAuth } from '@/lib/workspace-files/api'
 import { readWorkspaceFileContentByKey } from '@/lib/workspace-files/application/read-workspace-file-content-by-key'
 import { isSimPageSource, SIM_PAGE_CONTENT_TYPE } from '@/lib/workspace-files/page-compile'
 import { renderSimPageDocumentWithAssets } from '@/lib/workspace-files/page-document.server'
-import { verifyFileAccess } from '@/app/api/files/authorization'
+import { type KnowledgeFileAccess, verifyFileAccess } from '@/app/api/files/authorization'
 import {
   createErrorResponse,
   createFileResponse,
@@ -271,12 +271,29 @@ export const GET = withRouteHandler(
 
       const userId = legacyAuthResult?.userId
       if (!userId) throw new Error('Authenticated file serve request is missing a user ID')
+      /** Only a session identifies a person; an internal token's user id reads as the workspace. */
+      const knowledgeAccess =
+        legacyAuthResult?.authType === AuthType.SESSION ? ('user' as const) : undefined
 
       if (isUsingCloudStorage()) {
-        return await handleCloudProxy(cloudKey, userId, options, request.signal, storageContext)
+        return await handleCloudProxy(
+          cloudKey,
+          userId,
+          options,
+          request.signal,
+          storageContext,
+          knowledgeAccess
+        )
       }
 
-      return await handleLocalFile(cloudKey, userId, options, request.signal, storageContext)
+      return await handleLocalFile(
+        cloudKey,
+        userId,
+        options,
+        request.signal,
+        storageContext,
+        knowledgeAccess
+      )
     } catch (error) {
       if (error instanceof InternalUnauthenticatedError) {
         logger.warn('Unauthorized file access attempt', { error: error.message })
@@ -359,7 +376,8 @@ async function handleLocalFile(
   userId: string,
   options: ServeOptions,
   signal: AbortSignal | undefined,
-  context: StorageContext
+  context: StorageContext,
+  knowledgeAccess: KnowledgeFileAccess | undefined
 ): Promise<NextResponse> {
   const ownerKey = `user:${userId}`
   try {
@@ -368,7 +386,8 @@ async function handleLocalFile(
       userId,
       undefined, // customConfig
       context,
-      true // isLocal
+      true, // isLocal
+      { knowledgeAccess }
     )
 
     if (!hasAccess) {
@@ -419,7 +438,8 @@ async function handleCloudProxy(
   userId: string,
   options: ServeOptions,
   signal: AbortSignal | undefined,
-  context: StorageContext
+  context: StorageContext,
+  knowledgeAccess: KnowledgeFileAccess | undefined
 ): Promise<NextResponse> {
   const ownerKey = `user:${userId}`
   try {
@@ -430,7 +450,8 @@ async function handleCloudProxy(
       userId,
       undefined, // customConfig
       context, // context
-      false // isLocal
+      false, // isLocal
+      { knowledgeAccess }
     )
 
     if (!hasAccess) {

apps/sim/app/api/files/view/[id]/route.ts

@@ -3,7 +3,7 @@ import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { fileViewContract } from '@/lib/api/contracts/storage-transfer'
 import { parseRequest } from '@/lib/api/server'
-import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { AuthType, checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getServeStoragePrefix, type StorageContext } from '@/lib/uploads/config'
 import { getFileMetadataById } from '@/lib/uploads/server/metadata'
@@ -37,7 +37,9 @@ export const GET = withRouteHandler(
       record.key,
       authResult.userId,
       undefined,
-      record.context as StorageContext | 'general'
+      record.context as StorageContext | 'general',
+      undefined,
+      { knowledgeAccess: authResult.authType === AuthType.SESSION ? 'user' : undefined }
     )
     if (!hasAccess) {
       logger.warn('Unauthorized file view attempt', { id, userId: authResult.userId })

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/access/route.ts

@@ -0,0 +1,39 @@
+import { updateKnowledgeConnectorAccessContract } from '@/lib/api/contracts/knowledge'
+import {
+  defineInternalJsonRoute,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import {
+  resolveInternalKnowledgeBillingAttribution,
+  toInternalKnowledgeConnector,
+} from '@/lib/knowledge/api/internal-route'
+import { internalKnowledgeErrorPolicies } from '@/lib/knowledge/api/route-policies'
+import { updateKnowledgeConnectorAccess } from '@/lib/knowledge/application/connector-access'
+import { knowledgeOperations } from '@/lib/knowledge/application/operations'
+
+export const PATCH = defineInternalJsonRoute({
+  contract: updateKnowledgeConnectorAccessContract,
+  auth: internalSessionAuth,
+  operation: knowledgeOperations.updateConnectorAccess,
+  rateLimit: internalRateLimits.none({
+    reason: 'A settings action an admin performs by hand; the switch itself is bounded',
+  }),
+  errorPolicy: internalKnowledgeErrorPolicies.connectors,
+  mapInput: ({ params, body }, { principal, request }) => ({
+    connectorId: params.connectorId,
+    knowledgeBaseId: params.id,
+    accessMode: body.accessMode,
+    credentialGroupId: body.credentialGroupId,
+    credentialGroupOptionId: body.credentialGroupOptionId,
+    credentialId: body.credentialId,
+    resolveBillingAttribution: (workspaceId: string) =>
+      resolveInternalKnowledgeBillingAttribution(request, principal, workspaceId),
+    source: 'ui' as const,
+  }),
+  useCase: updateKnowledgeConnectorAccess,
+  present: ({ connector }) => ({
+    success: true as const,
+    data: toInternalKnowledgeConnector(connector),
+  }),
+})

apps/sim/app/api/knowledge/[id]/connectors/[connectorId]/enroll/route.ts

@@ -0,0 +1,26 @@
+import { startKnowledgeConnectorMemberEnrollmentContract } from '@/lib/api/contracts/knowledge'
+import {
+  defineInternalJsonRoute,
+  internalRateLimits,
+  internalSessionAuth,
+} from '@/lib/api/server/routes'
+import { internalKnowledgeErrorPolicies } from '@/lib/knowledge/api/route-policies'
+import { startKnowledgeConnectorMemberEnrollment } from '@/lib/knowledge/application/connector-access'
+import { knowledgeOperations } from '@/lib/knowledge/application/operations'
+
+export const POST = defineInternalJsonRoute({
+  contract: startKnowledgeConnectorMemberEnrollmentContract,
+  auth: internalSessionAuth,
+  operation: knowledgeOperations.enrollConnectorMember,
+  rateLimit: internalRateLimits.none({
+    reason:
+      'A member connecting their own account by hand; each call only re-issues their own invitation',
+  }),
+  errorPolicy: internalKnowledgeErrorPolicies.connectors,
+  mapInput: ({ params }) => ({
+    connectorId: params.connectorId,
+    knowledgeBaseId: params.id,
+  }),
+  useCase: startKnowledgeConnectorMemberEnrollment,
+  present: ({ url }) => ({ success: true as const, data: { url } }),
+})

apps/sim/app/api/knowledge/[id]/connectors/route.ts

@@ -49,6 +49,9 @@ export const POST = defineInternalJsonRoute({
     apiKey: body.apiKey,
     sourceConfig: body.sourceConfig,
     syncIntervalMinutes: body.syncIntervalMinutes,
+    accessMode: body.accessMode,
+    credentialGroupId: body.credentialGroupId,
+    credentialGroupOptionId: body.credentialGroupOptionId,
     resolveBillingAttribution: (workspaceId: string) =>
       resolveInternalKnowledgeBillingAttribution(request, principal, workspaceId),
     source: 'ui' as const,