From d1cab68e3d49ae6c1758d117060f151e05b7ffaa Mon Sep 17 00:00:00 2001 From: wizardchen Date: Mon, 20 Jul 2026 19:47:42 +0800 Subject: [PATCH] fix(api-keys): allow scoped file serve and ingest batch routes Let tenant-wide retrieve keys serve tenant-bounded /files paths while denying KB-restricted keys, declare knowledge batch write routes for ingest-capable keys, and short-circuit ownership checks for API-key principals already authorized by the gate and KB allow-list. --- internal/middleware/api_key_gate.go | 31 ++++++++ internal/middleware/api_key_gate_test.go | 68 +++++++++++++++++ internal/middleware/rbac.go | 11 +++ .../rbac_api_key_shortcircuit_test.go | 31 ++++++++ internal/router/router.go | 59 ++++++++++----- .../router_api_key_capabilities_test.go | 33 +++++++++ internal/router/router_files_test.go | 74 +++++++++++++++---- 7 files changed, 271 insertions(+), 36 deletions(-) diff --git a/internal/middleware/api_key_gate.go b/internal/middleware/api_key_gate.go index c5a0acac..a25e2b9d 100644 --- a/internal/middleware/api_key_gate.go +++ b/internal/middleware/api_key_gate.go @@ -161,6 +161,37 @@ func DenyAPIKeyPrincipal() gin.HandlerFunc { } } +// AllowFileServeAPIKey guards the tenant-scoped file-proxy routes (/files and +// the KB-scoped image proxy) for X-API-Key callers. Those routes serve an +// arbitrary storage path that only carries a tenant segment — there is no KB +// id in the path a KB-restricted key's allow-list could be checked against — +// so a KB-restricted key is denied outright (it must download KB content via +// the KB-scoped routes such as /knowledge/:id/download, which DO enforce the +// allow-list). A key passes when it is full-access, or when it is NOT +// KB-restricted and carries the retrieve capability: that is exactly the class +// of key that can already read any of the tenant's KB content, so exposing the +// tenant-bounded raw file path (the handler still enforces +// ValidateStoragePathTenant / the KB owner tenant) grants it nothing new. JWT +// sessions carry no API-key scope and pass straight through. +func AllowFileServeAPIKey() gin.HandlerFunc { + return func(c *gin.Context) { + scope, ok := types.TenantAPIKeyScopeFromContext(c.Request.Context()) + if !ok { + c.Next() + return + } + if scope.FullAccess || + (!scope.IsKnowledgeBaseRestricted() && + scope.HasCapability(types.APIKeyCapabilityRetrieve)) { + c.Next() + return + } + c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ + "error": "Forbidden: API key scope does not allow this operation", + }) + } +} + // normalizeRoutePath collapses duplicate slashes and trims a trailing slash so // helper-built paths (BasePath()+rel) match gin's c.FullPath() exactly. func normalizeRoutePath(p string) string { diff --git a/internal/middleware/api_key_gate_test.go b/internal/middleware/api_key_gate_test.go index 6ddd4aad..fceb4773 100644 --- a/internal/middleware/api_key_gate_test.go +++ b/internal/middleware/api_key_gate_test.go @@ -215,6 +215,74 @@ func TestDenyAPIKeyPrincipalAllowsJWT(t *testing.T) { } } +// runAllowFileServe mounts AllowFileServeAPIKey ahead of a handler and reports +// whether the request reached the handler. +func runAllowFileServe(t *testing.T, scope *types.TenantAPIKeyScope) (reached bool, status int) { + t.Helper() + gin.SetMode(gin.TestMode) + engine := gin.New() + engine.Use(func(c *gin.Context) { + if scope != nil { + c.Request = c.Request.WithContext(types.WithTenantAPIKeyScope(c.Request.Context(), *scope)) + } + c.Next() + }) + engine.GET("/files", AllowFileServeAPIKey(), func(c *gin.Context) { + reached = true + c.Status(http.StatusOK) + }) + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/files", nil)) + return reached, w.Code +} + +func TestAllowFileServeAPIKey(t *testing.T) { + cases := []struct { + name string + scope *types.TenantAPIKeyScope + wantReached bool + }{ + {name: "jwt passes", scope: nil, wantReached: true}, + {name: "full access passes", scope: &types.TenantAPIKeyScope{FullAccess: true}, wantReached: true}, + { + name: "tenant-wide retrieve passes", + scope: &types.TenantAPIKeyScope{ + Capabilities: types.StringArray{string(types.APIKeyCapabilityRetrieve)}, + }, + wantReached: true, + }, + { + name: "kb-restricted retrieve denied", + scope: &types.TenantAPIKeyScope{ + KnowledgeBaseIDs: types.StringArray{"kb-1"}, + Capabilities: types.StringArray{string(types.APIKeyCapabilityRetrieve)}, + }, + wantReached: false, + }, + { + name: "non-retrieve capability denied", + scope: &types.TenantAPIKeyScope{ + Capabilities: types.StringArray{string(types.APIKeyCapabilityChat)}, + }, + wantReached: false, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + reached, status := runAllowFileServe(t, tc.scope) + if reached != tc.wantReached { + t.Fatalf("reached=%v want %v (status=%d)", reached, tc.wantReached, status) + } + if tc.wantReached && status != http.StatusOK { + t.Fatalf("expected 200, got %d", status) + } + if !tc.wantReached && status != http.StatusForbidden { + t.Fatalf("expected 403, got %d", status) + } + }) + } +} + func TestNormalizeRoutePath(t *testing.T) { cases := map[string]string{ "/api/v1//models": "/api/v1/models", diff --git a/internal/middleware/rbac.go b/internal/middleware/rbac.go index 2067ac9e..3f948dbf 100644 --- a/internal/middleware/rbac.go +++ b/internal/middleware/rbac.go @@ -314,6 +314,17 @@ func EvaluateOwnershipOrRole( creatorID string, lookupErr error, ) error { + // API-key principals are authorized solely by the APIKeyGate (route + // policy) plus the KB allow-list handlers enforce separately + // (requireTenantAPIKeyKnowledgeBase(s)). Ownership ("creator OR Admin+") + // is a human concept that never applies to a machine principal, so + // short-circuit here — exactly as RequireOwnershipOrRole does for the + // middleware form. Without this, a scoped key (synthesized as Viewer for + // legacy-guard compatibility) would be 403'd by the body-carried-KB + // ownership checks even though the gate + allow-list already admitted it. + if _, ok := types.TenantAPIKeyScopeFromContext(ctx); ok { + return nil + } role := types.TenantRoleFromContext(ctx) if role.HasPermission(min) { return nil diff --git a/internal/middleware/rbac_api_key_shortcircuit_test.go b/internal/middleware/rbac_api_key_shortcircuit_test.go index b4a3876f..caa562d6 100644 --- a/internal/middleware/rbac_api_key_shortcircuit_test.go +++ b/internal/middleware/rbac_api_key_shortcircuit_test.go @@ -82,6 +82,37 @@ func TestRequireOwnershipOrRole_ShortCircuitsAPIKey(t *testing.T) { } } +// TestEvaluateOwnershipOrRole_ShortCircuitsAPIKey mirrors +// TestRequireOwnershipOrRole_ShortCircuitsAPIKey for the handler-side twin used +// when the KB id is carried in the request body (MoveKnowledge / +// BatchDeleteKnowledge via requireKBOwnershipOrAdmin). A scoped ingest key that +// the APIKeyGate + KB allow-list already admitted must not be re-rejected here +// just because it is synthesized as a Viewer for legacy-guard compatibility. +func TestEvaluateOwnershipOrRole_ShortCircuitsAPIKey(t *testing.T) { + ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ + KnowledgeBaseIDs: types.StringArray{"kb-1"}, + Capabilities: types.StringArray{string(types.APIKeyCapabilityIngest)}, + }) + // Synthesized Viewer role + a foreign creator would 403 a human caller. + ctx = context.WithValue(ctx, types.TenantRoleContextKey, types.TenantRoleViewer) + + if err := EvaluateOwnershipOrRole(ctx, cfgRBAC(true), + types.TenantRoleAdmin, "some-other-human-user", nil); err != nil { + t.Fatalf("API-key principal should short-circuit EvaluateOwnershipOrRole, got %v", err) + } +} + +// Sanity: a JWT Viewer with a foreign creator is still forbidden — the +// short-circuit must be scoped to API-key principals only. +func TestEvaluateOwnershipOrRole_JWTViewerStillDenied(t *testing.T) { + ctx := context.WithValue(context.Background(), types.TenantRoleContextKey, types.TenantRoleViewer) + err := EvaluateOwnershipOrRole(ctx, cfgRBAC(true), + types.TenantRoleAdmin, "some-other-human-user", nil) + if err == nil { + t.Fatal("JWT Viewer with foreign creator must be denied by EvaluateOwnershipOrRole") + } +} + // Sanity: a real JWT Viewer is still rejected by the Admin gate — the // short-circuit must be scoped to API-key principals only. func TestRequireRole_JWTViewerStillDenied(t *testing.T) { diff --git a/internal/router/router.go b/internal/router/router.go index e0ed1d7c..cb272fee 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -352,10 +352,18 @@ func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandl kRead := k.With(apiKeyRetrieve(apiKeyFullAccess())) { // Cross-knowledge endpoints (no :id) can't be gated on a single - // KB — they accept arbitrary knowledge IDs and the handler must - // fan out the access check itself. /batch and /search are read - // routes; /move and /batch-delete stay JWT Contributor-gated and are - // not declared for API keys. + // KB via the URL — they accept a kb_id (or source/target KB) in the + // body and the handler fans out the access check itself. /batch and + // /search are read routes (retrieve). /move, /batch-delete, + // /batch-reparse and /tags are content writes that each bound + // themselves to a single (or source+target) KB and enforce the API + // key's KB allow-list downstream — MoveKnowledge via + // requireTenantAPIKeyKnowledgeBases(source,target); the batch ops via + // validateKnowledgeBaseAccessWithKBID (requireTenantAPIKeyKnowledgeBase) + // plus a per-item "belongs to the authorized KB" check in the handler + // and service. They are therefore declared for API keys under the + // ingest capability, matching their single-document siblings + // (k.DELETE("/:id"), k.POST("/:id/reparse"), k.PUT("/:id")). kRead.GET("/batch", g.Viewer(), handler.GetKnowledgeBatch) kRead.GET("/:id", g.Viewer(), g.KBAccessReadFromKnowledgeIDParam("id"), handler.GetKnowledge) kRead.GET("/:id/stages", g.Viewer(), g.KBAccessReadFromKnowledgeIDParam("id"), handler.GetKnowledgeSpans) @@ -370,13 +378,15 @@ func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandl k.PUT("/image/:id/:chunk_id", g.OwnedKnowledgeKBOrAdmin(), g.KBAccessWriteFromKnowledgeIDParam("id"), handler.UpdateImageInfo) kRead.GET("/search", g.Viewer(), handler.SearchKnowledge) kRead.GET("/move/progress/:task_id", g.Viewer(), handler.GetKnowledgeMoveProgress) - // Batch / cross-KB write ops stay Contributor-gated for JWT and are - // NOT declared for API keys (default-deny): they fan out to arbitrary - // KBs with no single owning KB to bound a key's scope against. - kgrp.PUT("/tags", g.Contributor(), handler.UpdateKnowledgeTagBatch) - kgrp.POST("/batch-reparse", g.Contributor(), handler.BatchReparseKnowledge) - kgrp.POST("/batch-delete", g.Contributor(), handler.BatchDeleteKnowledge) - kgrp.POST("/move", g.Contributor(), handler.MoveKnowledge) + // Batch / cross-KB content writes: JWT Contributor+, or an API key + // with the ingest capability (or full access). Each handler binds the + // operation to a single (move: source+target) KB and rejects any KB + // or knowledge id outside the key's allow-list, so a scoped ingest key + // can only touch KBs it is already permitted to write. + k.PUT("/tags", g.Contributor(), handler.UpdateKnowledgeTagBatch) + k.POST("/batch-reparse", g.Contributor(), handler.BatchReparseKnowledge) + k.POST("/batch-delete", g.Contributor(), handler.BatchDeleteKnowledge) + k.POST("/move", g.Contributor(), handler.MoveKnowledge) } } @@ -1712,12 +1722,15 @@ func serveFilesWithResources( resourceCatalog interfaces.ResourceCatalog, ) { logger.Infof(context.Background(), "[Router] Serving files from /files") - // /files sits outside the /api/v1 APIKeyGate; storage paths cannot be - // attributed to a key's KB allow-list, so API keys are denied outright - // (embed routes use their own /embed/.../files handler). + // /files sits outside the /api/v1 APIKeyGate, so it carries its own + // API-key guard. A KB-restricted key is denied (a raw storage path cannot + // be bounded to its allow-list); full-access keys and tenant-wide retrieve + // keys pass, since the handler still enforces same-tenant paths + // (ValidateStoragePathTenant). Embed routes use their own + // /embed/.../files handler. r.GET( "/files", - middleware.DenyAPIKeyPrincipal(), + middleware.AllowFileServeAPIKey(), newFileServeHandler(globalFileService, storageResolver, resourceCatalog), ) } @@ -1830,11 +1843,17 @@ func serveKBScopedFiles( resourceCatalogs ...interfaces.ResourceCatalog, ) { logger.Infof(context.Background(), "[Router] Serving KB-scoped files from /knowledge-bases/:id/files") - // API keys are denied outright (as on /files): a signed URL's tenant/KB - // scope cannot authorize serving an arbitrary file_path under the owner - // tenant, and this route deliberately crosses the caller's own tenant. - r.GET("/knowledge-bases/:id/files", - middleware.DenyAPIKeyPrincipal(), + // API-key access mirrors /files: KB-restricted keys are denied (an + // arbitrary file_path under the KB owner tenant cannot be bounded to a + // key's allow-list), while full-access and tenant-wide retrieve keys pass + // — KBAccessRead still confines them to KBs they may read (own / + // org-shared / agent-visible), exactly as it does for a JWT Viewer. The + // route is declared to the gate with the retrieve policy so it is reachable + // at all; AllowFileServeAPIKey then applies the stricter not-KB-restricted + // constraint. + g.apiKeyRoute(r, http.MethodGet, "/knowledge-bases/:id/files", + apiKeyRetrieve(apiKeyFullAccess()), + middleware.AllowFileServeAPIKey(), g.Viewer(), g.KBAccessRead("id"), newKBScopedFileServeHandlerWithResources( diff --git a/internal/router/router_api_key_capabilities_test.go b/internal/router/router_api_key_capabilities_test.go index 22d079f9..0d3e0ae2 100644 --- a/internal/router/router_api_key_capabilities_test.go +++ b/internal/router/router_api_key_capabilities_test.go @@ -431,6 +431,39 @@ func TestChunkerPreviewRouteRequiresRetrieveOrIngestCapability(t *testing.T) { } } +// The batch / cross-KB content-write routes bind themselves to a single (or +// source+target) KB and enforce the API key's KB allow-list downstream, so +// they are reachable by an ingest-capable (or full-access) key — matching +// their single-document siblings. +func TestKnowledgeBatchWriteRoutesDeclareIngestCapability(t *testing.T) { + gin.SetMode(gin.TestMode) + g := &rbacGuards{} + v1 := gin.New().Group("/api/v1") + + RegisterKnowledgeRoutes(v1, &handler.KnowledgeHandler{}, g) + + cases := []struct { + method string + path string + }{ + {http.MethodPost, "/api/v1/knowledge/move"}, + {http.MethodPost, "/api/v1/knowledge/batch-delete"}, + {http.MethodPost, "/api/v1/knowledge/batch-reparse"}, + {http.MethodPut, "/api/v1/knowledge/tags"}, + } + for _, tc := range cases { + t.Run(tc.method+" "+tc.path, func(t *testing.T) { + policy := mustLookupAPIKeyPolicy(t, g, tc.method, tc.path) + if !policy.RequireFullAccess { + t.Fatal("policy should require full access without a matching capability") + } + if !policyHasCapability(policy, types.APIKeyCapabilityIngest) { + t.Fatalf("policy capabilities = %#v, want ingest", policy.Capabilities) + } + }) + } +} + func TestKBCloneProgressRouteRequiresRetrieveOrManageKbsCapability(t *testing.T) { gin.SetMode(gin.TestMode) g := &rbacGuards{} diff --git a/internal/router/router_files_test.go b/internal/router/router_files_test.go index 6e586904..d818d734 100644 --- a/internal/router/router_files_test.go +++ b/internal/router/router_files_test.go @@ -275,29 +275,71 @@ func TestServeFilesRejectsPathWithoutTenantSegment(t *testing.T) { } } -func TestServeFilesRejectsAPIKeyPrincipal(t *testing.T) { +// /files carries its own API-key guard (middleware.AllowFileServeAPIKey): +// full-access and tenant-wide retrieve keys may serve tenant-bounded paths, +// but KB-restricted keys (and keys lacking retrieve) are denied because a raw +// storage path cannot be bounded to a KB allow-list. +func TestServeFilesAPIKeyScopeMatrix(t *testing.T) { gin.SetMode(gin.TestMode) t.Setenv("STORAGE_TYPE", "local") - engine := gin.New() - serveFiles(engine, &stubFileService{ - getFile: func(ctx context.Context, filePath string) (io.ReadCloser, error) { - t.Fatalf("GetFile should not be called for API-key principal, got %q", filePath) - return nil, nil + const filePath = "local://42/docs/example.txt" + + cases := []struct { + name string + scope types.TenantAPIKeyScope + wantCode int + }{ + { + name: "full access allowed", + scope: types.TenantAPIKeyScope{FullAccess: true}, + wantCode: http.StatusOK, }, - }) + { + name: "tenant-wide retrieve allowed", + scope: types.TenantAPIKeyScope{ + Capabilities: types.StringArray{string(types.APIKeyCapabilityRetrieve)}, + }, + wantCode: http.StatusOK, + }, + { + name: "kb-restricted retrieve denied", + scope: types.TenantAPIKeyScope{ + KnowledgeBaseIDs: types.StringArray{"kb-1"}, + Capabilities: types.StringArray{string(types.APIKeyCapabilityRetrieve)}, + }, + wantCode: http.StatusForbidden, + }, + { + name: "non-retrieve capability denied", + scope: types.TenantAPIKeyScope{ + Capabilities: types.StringArray{string(types.APIKeyCapabilityChat)}, + }, + wantCode: http.StatusForbidden, + }, + } - filePath := "local://42/docs/example.txt" - req := httptest.NewRequest(http.MethodGet, "/files?file_path="+url.QueryEscape(filePath), nil) - ctx := context.WithValue(req.Context(), types.TenantInfoContextKey, &types.Tenant{ID: 42}) - ctx = types.WithTenantAPIKeyScope(ctx, types.TenantAPIKeyScope{FullAccess: true}) - req = req.WithContext(ctx) + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + engine := gin.New() + serveFiles(engine, &stubFileService{ + getFile: func(_ context.Context, _ string) (io.ReadCloser, error) { + return io.NopCloser(strings.NewReader("body")), nil + }, + }) - recorder := httptest.NewRecorder() - engine.ServeHTTP(recorder, req) + req := httptest.NewRequest(http.MethodGet, "/files?file_path="+url.QueryEscape(filePath), nil) + ctx := context.WithValue(req.Context(), types.TenantInfoContextKey, &types.Tenant{ID: 42}) + ctx = types.WithTenantAPIKeyScope(ctx, tc.scope) + req = req.WithContext(ctx) - if got, want := recorder.Code, http.StatusForbidden; got != want { - t.Fatalf("status = %d, want %d body=%s", got, want, recorder.Body.String()) + recorder := httptest.NewRecorder() + engine.ServeHTTP(recorder, req) + + if got := recorder.Code; got != tc.wantCode { + t.Fatalf("status = %d, want %d body=%s", got, tc.wantCode, recorder.Body.String()) + } + }) } }