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.
This commit is contained in:
wizardchen
2026-07-20 19:47:42 +08:00
committed by lyingbug
parent 23e606f570
commit d1cab68e3d
7 changed files with 271 additions and 36 deletions
+31
View File
@@ -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 {
+68
View File
@@ -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",
+11
View File
@@ -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
@@ -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) {
+39 -20
View File
@@ -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(
@@ -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{}
+58 -16
View File
@@ -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())
}
})
}
}