refactor(api-keys): simplify authorization to a single-role gate
Redesign tenant API key authorization around one dimension (role) plus a central default-deny gate, replacing the previous role + KB-scoped flag model. - Add APIKeyGate as the single authority for API-key authorization: routes declare one policy (MinRole) via apiKeyGroup/apiKeyRoute helpers; undeclared routes are denied by default. JWT principals short-circuit the gate and the JWT-centric RBAC guards short-circuit for API-key principals. - Roles: viewer/contributor/admin are knowledge-base data-plane only (KB scope is a pure downstream data filter); owner is a full-access tenant tier that unlocks tenant-level infrastructure routes and is required for every method. - Drop the KBScoped policy flag and the KB-restricted-vs-tenant branching. - Security hardening: never disclose HMAC secret (return presence only), abort writes on API-key encryption failure, deny KB-restricted keys on /files, and backfill legacy key hashes at startup instead of O(N) plaintext scans. - Frontend: two-level create dialog (access type -> permission level), rename role labels to reflect actual scope, sync en/zh/ko/ru locales. - Fix startup self-check false-positive on trailing-slash routes and normalize gin paths before comparison; add regression tests.
This commit is contained in:
@@ -0,0 +1,160 @@
|
||||
package middleware
|
||||
|
||||
import (
|
||||
stderrors "errors"
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"github.com/Tencent/WeKnora/internal/types"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
var errTenantAPIKeyScopeForbidden = stderrors.New("tenant api key scope forbidden")
|
||||
|
||||
// APIKeyRoutePolicy declares how an X-API-Key caller may use a single route.
|
||||
//
|
||||
// Design: API-key authorization is a SEPARATE authority from the JWT
|
||||
// role/ownership guards. Ownership ("creator OR Admin+") is a human concept
|
||||
// and never applies to a machine principal; instead every API-key-accessible
|
||||
// route declares one policy here, and the APIKeyGate is the single place that
|
||||
// enforces it. Routes that declare no policy are denied for API keys by
|
||||
// default (fail-closed), which removes the old "remember to add APIKeyDeny"
|
||||
// footgun.
|
||||
type APIKeyRoutePolicy struct {
|
||||
// MinRole is the minimum tenant role an API key needs for this route.
|
||||
//
|
||||
// Data-plane routes (knowledge bases and their content) use Viewer /
|
||||
// Contributor / Admin; for those, safe reads (GET/HEAD/OPTIONS) only
|
||||
// require Viewer while writes require the declared role. Tenant-level
|
||||
// infrastructure routes (models, vector stores, MCP, data sources,
|
||||
// channels, tenant KV, ...) use Owner, which is required for EVERY
|
||||
// method — reading tenant configuration is itself a privileged action.
|
||||
//
|
||||
// KB scoping is NOT enforced here: a key's knowledge_base_ids allow-list
|
||||
// is a pure data filter applied by the KBAccess guards and the handler
|
||||
// scope checks on data-plane routes. Tenant-level routes are simply
|
||||
// gated behind the Owner role instead of being reachable by a narrow key.
|
||||
MinRole types.TenantRole
|
||||
}
|
||||
|
||||
// APIKeyRouteAuthorizer is the registry of per-route API-key policies. It is
|
||||
// populated at router-construction time (single-threaded) and only read at
|
||||
// request time, so it needs no locking.
|
||||
type APIKeyRouteAuthorizer struct {
|
||||
// policies is keyed by HTTP method, then by the gin full-path
|
||||
// template (e.g. "/api/v1/knowledge-bases/:id/knowledge/file").
|
||||
policies map[string]map[string]APIKeyRoutePolicy
|
||||
}
|
||||
|
||||
// NewAPIKeyRouteAuthorizer returns an empty authorizer.
|
||||
func NewAPIKeyRouteAuthorizer() *APIKeyRouteAuthorizer {
|
||||
return &APIKeyRouteAuthorizer{policies: map[string]map[string]APIKeyRoutePolicy{}}
|
||||
}
|
||||
|
||||
// Register records the API-key policy for (method, fullPath). fullPath MUST be
|
||||
// the same string gin reports via c.FullPath() for the route, otherwise the
|
||||
// gate lookup will miss and the route will be denied for API keys. Router-side
|
||||
// helpers build fullPath from the group's BasePath so the two stay in sync.
|
||||
func (a *APIKeyRouteAuthorizer) Register(method, fullPath string, policy APIKeyRoutePolicy) {
|
||||
method = strings.ToUpper(strings.TrimSpace(method))
|
||||
fullPath = normalizeRoutePath(fullPath)
|
||||
if a.policies[method] == nil {
|
||||
a.policies[method] = map[string]APIKeyRoutePolicy{}
|
||||
}
|
||||
a.policies[method][fullPath] = policy
|
||||
}
|
||||
|
||||
// Lookup returns the policy for (method, fullPath) if one was declared.
|
||||
func (a *APIKeyRouteAuthorizer) Lookup(method, fullPath string) (APIKeyRoutePolicy, bool) {
|
||||
byPath, ok := a.policies[strings.ToUpper(method)]
|
||||
if !ok {
|
||||
return APIKeyRoutePolicy{}, false
|
||||
}
|
||||
policy, ok := byPath[normalizeRoutePath(fullPath)]
|
||||
return policy, ok
|
||||
}
|
||||
|
||||
// RegisteredRoutes returns every (method, fullPath) pair the authorizer knows
|
||||
// about. Used by the router startup self-check to detect stale path templates.
|
||||
func (a *APIKeyRouteAuthorizer) RegisteredRoutes() map[string][]string {
|
||||
out := make(map[string][]string, len(a.policies))
|
||||
for method, byPath := range a.policies {
|
||||
paths := make([]string, 0, len(byPath))
|
||||
for path := range byPath {
|
||||
paths = append(paths, path)
|
||||
}
|
||||
out[method] = paths
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// Middleware returns the gate middleware. It runs as the first handler on the
|
||||
// authenticated API group, after routing (so c.FullPath() is populated). JWT
|
||||
// principals pass straight through; API-key principals are authorized purely
|
||||
// from the declared policy table.
|
||||
func (a *APIKeyRouteAuthorizer) Middleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
scope, ok := types.TenantAPIKeyScopeFromContext(c.Request.Context())
|
||||
if !ok {
|
||||
c.Next()
|
||||
return
|
||||
}
|
||||
if err := a.authorize(scope, c.Request.Method, c.FullPath()); err != nil {
|
||||
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
|
||||
"error": "Forbidden: API key scope does not allow this operation",
|
||||
})
|
||||
return
|
||||
}
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
|
||||
// authorize applies the declared policy to an API-key scope. Absent policy =>
|
||||
// default deny.
|
||||
func (a *APIKeyRouteAuthorizer) authorize(scope types.TenantAPIKeyScope, method, fullPath string) error {
|
||||
policy, ok := a.Lookup(method, fullPath)
|
||||
if !ok {
|
||||
return errTenantAPIKeyScopeForbidden
|
||||
}
|
||||
role := scope.Role
|
||||
if role == "" {
|
||||
role = types.TenantRoleViewer
|
||||
}
|
||||
required := policy.MinRole
|
||||
if required == "" {
|
||||
required = types.TenantRoleViewer
|
||||
}
|
||||
// Data-plane safe reads only need a Viewer floor. Tenant-level (Owner)
|
||||
// routes require the full role even for reads, so they are never lowered.
|
||||
if isSafeHTTPMethod(method) && required != types.TenantRoleOwner {
|
||||
required = types.TenantRoleViewer
|
||||
}
|
||||
if !role.HasPermission(required) {
|
||||
return errTenantAPIKeyScopeForbidden
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func isSafeHTTPMethod(method string) bool {
|
||||
switch method {
|
||||
case http.MethodGet, http.MethodHead, http.MethodOptions:
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {
|
||||
if p == "" {
|
||||
return ""
|
||||
}
|
||||
for strings.Contains(p, "//") {
|
||||
p = strings.ReplaceAll(p, "//", "/")
|
||||
}
|
||||
if len(p) > 1 {
|
||||
p = strings.TrimSuffix(p, "/")
|
||||
}
|
||||
return p
|
||||
}
|
||||
Reference in New Issue
Block a user