Files
Enterprise-Knowledge-Base/internal/middleware/api_key_gate.go
T
wizardchen d2ffc1b973 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.
2026-07-07 12:00:13 +08:00

161 lines
5.6 KiB
Go

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
}