Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(auth): let retrieve-scoped API keys discover shared knowledge bases (#4523)

u7-u7df0b2d2ad64c
diff --git a/internal/router/router_api_key_capabilities_test.go b/internal/router/router_api_key_capabilities_test.go
index b0223ae12..1c2515c36 100644
--- a/internal/router/router_api_key_capabilities_test.go
+++ b/internal/router/router_api_key_capabilities_test.go
@@ -664,6 +664,48 @@ func TestFAQImportProgressRouteRequiresRetrieveOrIngestCapability(t *testing.T)
}
}
+// Listing shared knowledge bases is read-only discovery: a scoped key that
+// may already retrieve KB data must be able to discover the shared KBs its
+// allow-list covers, without being promoted to manage_spaces.
+func TestSharedKnowledgeBaseDiscoveryAdmitsRetrieveCapability(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ g := &rbacGuards{}
+ v1 := gin.New().Group("/api/v1")
+
+ RegisterOrganizationRoutes(v1, &handler.OrganizationHandler{}, g)
+
+ for _, path := range []string{
+ "/api/v1/shared-knowledge-bases",
+ "/api/v1/organizations/:id/shared-knowledge-bases",
+ } {
+ t.Run(path, func(t *testing.T) {
+ policy := mustLookupAPIKeyPolicy(t, g, http.MethodGet, path)
+ if !policy.RequireFullAccess {
+ t.Fatal("policy should require full access without a matching capability")
+ }
+ if !policyHasCapability(policy, types.APIKeyCapabilityRetrieve) {
+ t.Fatalf("policy capabilities = %#v, want retrieve", policy.Capabilities)
+ }
+ if !policyHasCapability(policy, types.APIKeyCapabilityManageSpaces) {
+ t.Fatalf("policy capabilities = %#v, want manage_spaces preserved", policy.Capabilities)
+ }
+ })
+ }
+
+ // Opening the two discovery routes must not leak the capability into the
+ // rest of the organization group, nor into the shared-agents listing.
+ for _, tc := range []struct{ method, path string }{
+ {http.MethodPost, "/api/v1/organizations"},
+ {http.MethodGet, "/api/v1/organizations/:id/members"},
+ {http.MethodGet, "/api/v1/shared-agents"},
+ } {
+ policy := mustLookupAPIKeyPolicy(t, g, tc.method, tc.path)
+ if policyHasCapability(policy, types.APIKeyCapabilityRetrieve) {
+ t.Fatalf("%s %s must not admit retrieve", tc.method, tc.path)
+ }
+ }
+}
+
func mustLookupAPIKeyPolicy(
t *testing.T,
g *rbacGuards,
diff --git a/internal/router/routes_agent.go b/internal/router/routes_agent.go
index b08c7f4bc..85de8f845 100644
--- a/internal/router/routes_agent.go
+++ b/internal/router/routes_agent.go
@@ -172,8 +172,12 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza
orgs.GET("/:id/shares", g.Viewer(), orgHandler.ListOrgShares)
// List agents shared to this organization — Viewer+
orgs.GET("/:id/agent-shares", g.Viewer(), orgHandler.ListOrgAgentShares)
- // List all knowledge bases in this organization (including mine) for list-page space view — Viewer+
- orgs.GET("/:id/shared-knowledge-bases", g.Viewer(), orgHandler.ListOrganizationSharedKnowledgeBases)
+ // List all knowledge bases in this organization (including mine) for list-page space view — Viewer+.
+ // Discovery is read-only, so a scoped key with `retrieve` may use it;
+ // the handler narrows rows to the key's KB allow-list.
+ orgs.With(apiKeyRetrieve(apiKeyManageSpaces(apiKeyFullAccess()))).GET(
+ "/:id/shared-knowledge-bases", g.Viewer(), orgHandler.ListOrganizationSharedKnowledgeBases,
+ )
// List all agents in this organization (including mine) for list-page space view — Viewer+
orgs.GET("/:id/shared-agents", g.Viewer(), orgHandler.ListOrganizationSharedAgents)
}
@@ -212,8 +216,12 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza
agentShares.DELETE("/:share_id", g.OwnedAgentOrAdmin(), orgHandler.RemoveAgentShare)
}
- // Shared knowledge bases route — Viewer+
- g.apiKeyRoute(r, http.MethodGet, "/shared-knowledge-bases", apiKeyManageSpaces(apiKeyFullAccess()), g.Viewer(), orgHandler.ListSharedKnowledgeBases)
+ // Shared knowledge bases route — Viewer+.
+ // Listing is read-only discovery: a scoped key with `retrieve` may use it
+ // so it can discover the shared KBs it is already allowed to search. The
+ // handler filters every row through the key's KB allow-list.
+ g.apiKeyRoute(r, http.MethodGet, "/shared-knowledge-bases",
+ apiKeyRetrieve(apiKeyManageSpaces(apiKeyFullAccess())), g.Viewer(), orgHandler.ListSharedKnowledgeBases)
// Shared agents route — Viewer+
g.apiKeyRoute(r, http.MethodGet, "/shared-agents", apiKeyManageSpaces(apiKeyFullAccess()), g.Viewer(), orgHandler.ListSharedAgents)
// "Disable by me" 是空间级偏好(写到 tenant_disabled_shared_agents),
diff --git a/website-docs/03-features/01-tenant-auth.md b/website-docs/03-features/01-tenant-auth.md
index eda134141..334428cf8 100644
--- a/website-docs/03-features/01-tenant-auth.md
+++ b/website-docs/03-features/01-tenant-auth.md
@@ -347,7 +347,7 @@ flowchart LR
| 能力 | 说明 |
| --- | --- |
-| `retrieve` | 读取 / 搜索知识库数据(KB 列表、知识详情、hybrid-search 等) |
+| `retrieve` | 读取 / 搜索知识库数据(KB 列表、知识详情、hybrid-search、共享 KB 清单发现等) |
| `chat` | 会话流:创建 session、knowledge-chat / agent-chat、加载与删除消息 |
| `read_agents` | 列出与查看 Agent(不含创建修改) |
| `ingest` | 写内容:上传文档、编辑 chunk / FAQ / 标签 / Wiki、批量删除与移动知识 |
diff --git a/website-docs/04-api/02-api-org.md b/website-docs/04-api/02-api-org.md
index 9df382f33..e2a73c004 100644
--- a/website-docs/04-api/02-api-org.md
+++ b/website-docs/04-api/02-api-org.md
@@ -2,7 +2,7 @@
管理组织成员以及知识库和智能体的共享关系。组织以工作空间为成员单位。
-组织(Organization)以“空间(tenant)”为成员单位。组织组路由的 API key 策略为 `manage_spaces` 或 full-access;KB/Agent 分享管理仅 full-access key 可用。
+组织(Organization)以“空间(tenant)”为成员单位。组织组路由的 API key 策略为 `manage_spaces` 或 full-access;两个只读的「共享知识库清单」端点额外允许 `retrieve`,方便只读 key 发现自己本就有权检索的共享库;KB/Agent 分享管理仅 full-access key 可用。
## 组织管理(/api/v1/organizations)
@@ -294,7 +294,7 @@ curl $BASE/api/v1/organizations/org-1/agent-shares -H "Authorization: Bearer $TO
### GET /api/v1/organizations/:id/shared-knowledge-bases
-用途:组织空间视图:组织内全部共享 KB(含我自己的)。权限:Viewer+。
+用途:组织空间视图:组织内全部共享 KB(含我自己的)。权限:Viewer+;API key 需 `manage_spaces`、`retrieve` 或 full-access,且只返回该 key 白名单内的 KB。
响应:200 `{"success":true,"data":[...含 is_mine、source_from_agent 标记...],"total":N}`
@@ -410,7 +410,7 @@ curl -X DELETE $BASE/api/v1/agents/agent-1/shares/s-1 -H "Authorization: Bearer
### GET /api/v1/shared-knowledge-bases
-用途:列出通过组织共享给我的 KB(去除属主侧向量库元数据)。权限:Viewer+;API key 需 `manage_spaces` 或 full-access。
+用途:列出通过组织共享给我的 KB(去除属主侧向量库元数据)。权限:Viewer+;API key 需 `manage_spaces`、`retrieve` 或 full-access,且只返回该 key 白名单内的 KB。
响应:200 `{"success":true,"data":[...],"total":N}`