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:
@@ -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 {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
@@ -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{}
|
||||
|
||||
@@ -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())
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user