diff --git a/cmd/server/bootstrap.go b/cmd/server/bootstrap.go index 4ff4eb0e..b33d9950 100644 --- a/cmd/server/bootstrap.go +++ b/cmd/server/bootstrap.go @@ -38,6 +38,21 @@ const bootstrapEnvVar = "WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL" // here as additional dig.Invoke calls. func runStartupBootstrap(c *dig.Container) { ctx := context.Background() + + // One-shot: backfill SHA-256 key_hash for legacy tenant API keys that + // migration 000065 seeded with a placeholder. Without this, the first + // authentication of each migrated key falls back to an O(n) plaintext + // scan of the tenant's keys. Best-effort: warn, never abort startup. + if err := c.Invoke(func(apiKeySvc interfaces.TenantAPIKeyService) { + if n, err := apiKeySvc.BackfillMissingKeyHashes(ctx); err != nil { + logger.Warnf(ctx, "[bootstrap] tenant api key hash backfill failed: %v", err) + } else if n > 0 { + logger.Infof(ctx, "[bootstrap] backfilled %d legacy tenant api key hash(es)", n) + } + }); err != nil { + logger.Warnf(ctx, "[bootstrap] failed to resolve TenantAPIKeyService: %v", err) + } + email := strings.TrimSpace(os.Getenv(bootstrapEnvVar)) if email == "" { return diff --git a/frontend/src/api/tenant/index.ts b/frontend/src/api/tenant/index.ts index 6caadd80..1984ed5c 100644 --- a/frontend/src/api/tenant/index.ts +++ b/frontend/src/api/tenant/index.ts @@ -23,8 +23,8 @@ export interface APIPrincipalConfig { direct_header_name: string signed_token_header_name: string require_direct_header: boolean + // The server never returns the plaintext secret; only its presence. has_hmac_secret: boolean - hmac_secret?: string } export interface UpdateAPIPrincipalConfigPayload { @@ -48,7 +48,7 @@ export interface APIPrincipalTestToken { external_user_id: string } -export type TenantAPIKeyRole = 'viewer' | 'contributor' | 'admin' +export type TenantAPIKeyRole = 'viewer' | 'contributor' | 'admin' | 'owner' export interface TenantAPIKey { id: number diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index 276f1f09..59b49b15 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -5768,15 +5768,23 @@ export default { apiKeyNameRequired: 'Enter an API key name', toggleApiKeyVisible: 'Show or hide API key', apiKeyAccessRole: "Access role", - apiKeyAccessRoleHint: "Matches tenant member roles; requests are authorized by the selected role.", - accessRoleViewer: "Viewer", - accessRoleContributor: "Contributor", - accessRoleAdmin: "Admin", + apiKeyAccessType: "Access type", + apiKeyAccessTypeHint: "\"Knowledge base\" operates within the KB scope at the permission level below; \"Tenant full\" additionally unlocks every tenant-level API such as models and data sources.", + accessTypeKnowledgeBase: "Knowledge base", + accessTypeTenantFull: "Tenant full", + apiKeyPermissionLevel: "Permission level", + apiKeyAccessRoleHint: "The first three roles are limited to knowledge-base operations; \"Tenant Full\" also unlocks tenant-level APIs such as models and data sources.", + accessRoleViewer: "KB Read", + accessRoleContributor: "KB Write", + accessRoleAdmin: "KB Admin", + accessRoleOwner: "Tenant Full", accessRoleViewerDesc: "Query, search, and chat without modifying knowledge-base content.", accessRoleContributorDesc: "Create, update, or delete knowledge-base content within the selected scope.", - accessRoleAdminDesc: "Manage tenant-level settings and integrations; cannot create, rotate, or delete API keys.", + accessRoleAdminDesc: "Manage knowledge bases, including destructive operations like clearing a KB, within the selected scope; no tenant-level configuration.", + accessRoleOwnerDesc: "Full access, equivalent to a tenant owner: may call every tenant-level API (models, vector stores, data sources, channels, ...). Not limited by knowledge-base scope.", apiKeyKnowledgeScope: 'Knowledge bases', apiKeyKnowledgeScopePlaceholder: 'Leave empty to allow all knowledge bases', + apiKeyKnowledgeScopeOwnerHint: 'Owner is a full-access key; the knowledge-base scope does not apply to it.', allKnowledgeBases: 'All knowledge bases', createdAt: 'Created', actions: 'Actions', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index d4f82887..559fc2b3 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -5779,15 +5779,23 @@ export default { apiKeyNameRequired: "API Key 이름을 입력하세요", toggleApiKeyVisible: "API Key 표시 또는 숨기기", apiKeyAccessRole: "접근 역할", - apiKeyAccessRoleHint: "워크스페이스 멤버 역할과 동일하며, 요청 시 선택한 역할로 인증됩니다.", - accessRoleViewer: "뷰어", - accessRoleContributor: "편집", - accessRoleAdmin: "관리자", + apiKeyAccessType: "접근 유형", + apiKeyAccessTypeHint: "\"지식베이스\"는 아래 권한 수준에 따라 지식베이스 범위 내에서 작동합니다. \"테넌트 전체 접근\"은 모델, 데이터 소스 등 모든 테넌트 수준 API를 추가로 사용할 수 있습니다.", + accessTypeKnowledgeBase: "지식베이스", + accessTypeTenantFull: "테넌트 전체 접근", + apiKeyPermissionLevel: "권한 수준", + apiKeyAccessRoleHint: "앞의 세 역할은 지식베이스 범위 내 작업으로 제한되며, \"테넌트 전체 접근\"은 모델, 데이터 소스 등 테넌트 수준 API도 추가로 사용할 수 있습니다.", + accessRoleViewer: "지식베이스 읽기", + accessRoleContributor: "지식베이스 읽기·쓰기", + accessRoleAdmin: "지식베이스 관리자", + accessRoleOwner: "테넌트 전체 접근", accessRoleViewerDesc: "조회, 검색 및 대화만 가능하며 지식베이스 내용은 수정하지 않습니다.", accessRoleContributorDesc: "선택한 범위 내에서 지식베이스 콘텐츠를 생성, 수정 또는 삭제합니다.", - accessRoleAdminDesc: "테넌트 수준 설정 및 통합을 관리합니다. API Key 생성, 교체 또는 삭제는 불가합니다.", + accessRoleAdminDesc: "선택한 범위 내에서 지식베이스를 관리하며, 지식베이스 비우기 등 파괴적 작업을 포함합니다. 테넌트 수준 설정은 다루지 않습니다.", + accessRoleOwnerDesc: "전체 접근, 테넌트 소유자와 동일: 모델, 벡터 스토어, 데이터 소스, 채널 등 모든 테넌트 수준 API를 호출할 수 있으며 지식베이스 범위의 제한을 받지 않습니다.", apiKeyKnowledgeScope: "지식베이스 범위", apiKeyKnowledgeScopePlaceholder: "비워 두면 모든 지식베이스 접근 허용", + apiKeyKnowledgeScopeOwnerHint: "소유자는 전체 접근 키이므로 지식베이스 범위가 적용되지 않습니다.", allKnowledgeBases: "모든 지식베이스", createdAt: "생성일", actions: "작업", diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 9f92faea..e74c0d07 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -5600,15 +5600,23 @@ export default { apiKeyNameRequired: 'Введите название API key', toggleApiKeyVisible: 'Показать или скрыть API key', apiKeyAccessRole: 'Роль доступа', - apiKeyAccessRoleHint: 'Соответствует роли участника workspace; запросы авторизуются по выбранной роли.', - accessRoleViewer: 'Наблюдатель', - accessRoleContributor: 'Редактор', - accessRoleAdmin: 'Администратор', + apiKeyAccessType: 'Тип доступа', + apiKeyAccessTypeHint: '«База знаний» работает в пределах области БЗ на выбранном ниже уровне прав; «Полный доступ арендатора» дополнительно открывает все API уровня арендатора, такие как модели и источники данных.', + accessTypeKnowledgeBase: 'База знаний', + accessTypeTenantFull: 'Полный доступ арендатора', + apiKeyPermissionLevel: 'Уровень прав', + apiKeyAccessRoleHint: 'Первые три роли ограничены операциями с базами знаний; «Полный доступ арендатора» дополнительно открывает API уровня арендатора, такие как модели и источники данных.', + accessRoleViewer: 'Чтение БЗ', + accessRoleContributor: 'Чтение и запись БЗ', + accessRoleAdmin: 'Администратор БЗ', + accessRoleOwner: 'Полный доступ арендатора', accessRoleViewerDesc: 'Запросы, поиск и диалог без изменения содержимого баз знаний.', accessRoleContributorDesc: 'Создание, обновление или удаление записей в выбранном диапазоне баз знаний.', - accessRoleAdminDesc: 'Управление настройками арендатора и интеграциями; нельзя создавать, ротировать или удалять API keys.', + accessRoleAdminDesc: 'Управление базами знаний в выбранном диапазоне, включая деструктивные операции, такие как очистка базы знаний; настройки уровня арендатора недоступны.', + accessRoleOwnerDesc: 'Полный доступ, эквивалент владельца арендатора: доступны все API уровня арендатора (модели, векторные хранилища, источники данных, каналы, ...). Не ограничивается диапазоном баз знаний.', apiKeyKnowledgeScope: 'Базы знаний', apiKeyKnowledgeScopePlaceholder: 'Оставьте пустым, чтобы разрешить доступ ко всем базам знаний', + apiKeyKnowledgeScopeOwnerHint: 'Владелец — это ключ с полным доступом; диапазон баз знаний к нему не применяется.', allKnowledgeBases: 'Все базы знаний', createdAt: 'Создано', actions: 'Действия', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index 0e97726a..79ed126f 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -5781,15 +5781,23 @@ export default { apiKeyNameRequired: "请输入 API Key 名称", toggleApiKeyVisible: "显示或隐藏 API Key", apiKeyAccessRole: "访问角色", - apiKeyAccessRoleHint: "与空间成员角色一致,请求时按所选角色鉴权。", - accessRoleViewer: "访客", - accessRoleContributor: "编辑", - accessRoleAdmin: "管理员", + apiKeyAccessType: "访问类型", + apiKeyAccessTypeHint: "「知识库」按下方权限级别在知识库范围内操作;「租户完全访问」额外开放模型、数据源等全部租户级接口。", + accessTypeKnowledgeBase: "知识库", + accessTypeTenantFull: "租户完全访问", + apiKeyPermissionLevel: "权限级别", + apiKeyAccessRoleHint: "前三档仅限知识库范围内操作;「租户完全访问」额外开放模型、数据源等租户级接口。", + accessRoleViewer: "知识库只读", + accessRoleContributor: "知识库读写", + accessRoleAdmin: "知识库管理员", + accessRoleOwner: "租户完全访问", accessRoleViewerDesc: "查询、检索和对话,不修改知识库内容。", accessRoleContributorDesc: "创建、更新或删除知识库内容,受知识库范围限制。", - accessRoleAdminDesc: "管理租户级配置与集成设置;不能创建、轮换或删除 API 密钥。", + accessRoleAdminDesc: "知识库管理,包含清空知识库等破坏性操作,受知识库范围限制;不涉及租户级配置。", + accessRoleOwnerDesc: "完全访问,等同租户所有者:可调用模型、向量库、数据源、渠道等全部租户级接口,不受知识库范围限制。", apiKeyKnowledgeScope: "知识库范围", apiKeyKnowledgeScopePlaceholder: "留空表示允许访问全部知识库", + apiKeyKnowledgeScopeOwnerHint: "所有者为完全访问密钥,知识库范围对其不生效。", allKnowledgeBases: "全部知识库", createdAt: "创建时间", actions: "操作", diff --git a/frontend/src/views/integrations/ApiIntegrationSettings.vue b/frontend/src/views/integrations/ApiIntegrationSettings.vue index a53f3dd1..91a3a00e 100644 --- a/frontend/src/views/integrations/ApiIntegrationSettings.vue +++ b/frontend/src/views/integrations/ApiIntegrationSettings.vue @@ -460,21 +460,34 @@
- + +
+ + {{ $t('integrations.api.accessTypeKnowledgeBase') }} + {{ $t('integrations.api.accessTypeTenantFull') }} + +

{{ $t('integrations.api.apiKeyAccessTypeHint') }}

+
+ +
+
+
{{ $t('integrations.api.accessRoleViewer') }} {{ $t('integrations.api.accessRoleContributor') }} {{ $t('integrations.api.accessRoleAdmin') }} -

{{ $t('integrations.api.apiKeyAccessRoleHint') }}

+
+ +

{{ formatApiKeyAccessRoleLabel(apiKeyForm.role) }}

{{ apiKeyFormRoleDesc }}

-
+
@@ -545,7 +558,6 @@ const apiKeyCreating = ref(false) const knowledgeBasesLoading = ref(false) const knowledgeBases = ref>([]) const secretInput = ref('') -const savedHMACSecret = ref('') const exampleTab = ref<'jwt' | 'curl'>('curl') const agents = ref([]) const agentsLoading = ref(false) @@ -568,7 +580,7 @@ const form = reactive({ require_direct_header: false, }) -type ApiKeyAccessRole = 'viewer' | 'contributor' | 'admin' +type ApiKeyAccessRole = 'viewer' | 'contributor' | 'admin' | 'owner' const apiKeyForm = reactive({ name: '', @@ -576,18 +588,50 @@ const apiKeyForm = reactive({ knowledge_base_ids: [] as string[], }) +// The role picker is presented as two levels: a top-level access type +// (knowledge-base vs. full tenant) and, for knowledge-base keys, a permission +// level (viewer/contributor/admin). Owner is a full-access key, for which the +// KB scope is meaningless and hidden. +const apiKeyRoleIsOwner = computed(() => apiKeyForm.role === 'owner') +type ApiKeyAccessType = 'kb' | 'tenant' +const apiKeyAccessType = ref('kb') +// Remember the last knowledge-base permission level so toggling back from +// "tenant full" restores the user's previous choice instead of resetting. +let lastKbRole: ApiKeyAccessRole = 'viewer' + +watch(apiKeyAccessType, (type) => { + if (type === 'tenant') { + apiKeyForm.role = 'owner' + apiKeyForm.knowledge_base_ids = [] + } else if (apiKeyForm.role === 'owner') { + apiKeyForm.role = lastKbRole === 'owner' ? 'viewer' : lastKbRole + } +}) + +watch( + () => apiKeyForm.role, + (role) => { + if (role !== 'owner') { + lastKbRole = role + } + }, +) + function formatApiKeyAccessRoleLabel(role: ApiKeyAccessRole | TenantAPIKeyRole | undefined): string { const normalized = (role ?? 'viewer') as ApiKeyAccessRole const labels: Record = { viewer: t('integrations.api.accessRoleViewer'), contributor: t('integrations.api.accessRoleContributor'), admin: t('integrations.api.accessRoleAdmin'), + owner: t('integrations.api.accessRoleOwner'), } return labels[normalized] ?? labels.viewer } const apiKeyFormRoleDesc = computed(() => { switch (apiKeyForm.role) { + case 'owner': + return t('integrations.api.accessRoleOwnerDesc') case 'admin': return t('integrations.api.accessRoleAdminDesc') case 'contributor': @@ -665,7 +709,10 @@ const directHeaderName = computed(() => DEFAULT_DIRECT_HEADER_NAME) const canAutoSave = computed(() => { if (!tenantId.value) return false if (form.mode === 'signed_token') { - return secretInput.value.trim() !== '' + // Either a secret is already stored server-side, or the user has just + // typed a new one. The plaintext secret is never returned by the API, + // so we rely on the has_hmac_secret presence flag. + return config.value?.has_hmac_secret === true || secretInput.value.trim() !== '' } return true }) @@ -686,7 +733,9 @@ const hasUnsavedPrincipalChanges = computed(() => { return ( form.mode !== cfg.mode || form.require_direct_header !== cfg.require_direct_header - || secretInput.value.trim() !== savedHMACSecret.value.trim() + // A non-empty input always means the user intends to set a new secret; + // the existing secret is never echoed back so any typed value is a change. + || secretInput.value.trim() !== '' ) }) @@ -831,8 +880,9 @@ async function load() { form.direct_header_name = DEFAULT_DIRECT_HEADER_NAME form.signed_token_header_name = DEFAULT_TOKEN_HEADER_NAME form.require_direct_header = cfgResp.data.require_direct_header === true - savedHMACSecret.value = cfgResp.data.hmac_secret || '' - secretInput.value = savedHMACSecret.value + // The plaintext secret is never returned; start with an empty input and + // rely on config.has_hmac_secret to reflect whether one is configured. + secretInput.value = '' ensurePlaygroundAgent() } catch (err: any) { error.value = err?.message || t('integrations.api.loadFailed') @@ -956,7 +1006,9 @@ async function saveIfNeeded(options: { showSuccess?: boolean } = {}) { signed_token_header_name: DEFAULT_TOKEN_HEADER_NAME, require_direct_header: form.require_direct_header, } - if (secretInput.value.trim() !== savedHMACSecret.value.trim()) { + // Only send the secret when the user typed a new one; otherwise the + // backend keeps the stored value untouched. + if (secretInput.value.trim() !== '') { payload.hmac_secret = secretInput.value.trim() } const resp = await updateAPIPrincipalConfig(tenantId.value, payload) @@ -964,8 +1016,7 @@ async function saveIfNeeded(options: { showSuccess?: boolean } = {}) { throw new Error(resp.message || t('integrations.api.saveFailed')) } config.value = resp.data - savedHMACSecret.value = resp.data.hmac_secret || payload.hmac_secret || '' - secretInput.value = savedHMACSecret.value + secretInput.value = '' if (options.showSuccess) { MessagePlugin.success(t('integrations.api.saveSuccess')) } @@ -1121,6 +1172,8 @@ function openCreateAPIKeyDialog() { apiKeyForm.name = '' apiKeyForm.role = 'viewer' apiKeyForm.knowledge_base_ids = [] + apiKeyAccessType.value = 'kb' + lastKbRole = 'viewer' apiKeyDialogVisible.value = true void loadKnowledgeBaseOptions() } @@ -1135,7 +1188,8 @@ async function createScopedAPIKey() { const resp = await createTenantAPIKey(tenantId.value, { name: apiKeyForm.name.trim(), role: apiKeyForm.role, - knowledge_base_ids: apiKeyForm.knowledge_base_ids, + // Owner keys are full-access; KB scoping does not apply to them. + knowledge_base_ids: apiKeyRoleIsOwner.value ? [] : apiKeyForm.knowledge_base_ids, }) if (!resp.success || !resp.data?.api_key) { throw new Error(resp.message || t('integrations.api.createApiKeyFailed')) diff --git a/internal/application/repository/tenant_api_key.go b/internal/application/repository/tenant_api_key.go index 760b05a3..64db04f3 100644 --- a/internal/application/repository/tenant_api_key.go +++ b/internal/application/repository/tenant_api_key.go @@ -77,6 +77,24 @@ func (r *tenantAPIKeyRepository) UpdateAPIKeyHash(ctx context.Context, id uint64 Update("key_hash", hash).Error } +// placeholderKeyHashPrefix mirrors the value written by migration +// 000065_tenant_api_keys.up.sql ('migrated-tenant-' || id). Rows still +// carrying it have never been authenticated since the upgrade, so their +// key_hash is not the real SHA-256 of the API key yet. +const placeholderKeyHashPrefix = "migrated-tenant-" + +func (r *tenantAPIKeyRepository) ListKeysWithPlaceholderHash( + ctx context.Context, +) ([]*types.TenantAPIKey, error) { + var keys []*types.TenantAPIKey + // AfterFind decrypts api_key, so callers get the plaintext token needed + // to compute the real hash. + err := r.db.WithContext(ctx). + Where("key_hash LIKE ? AND revoked_at IS NULL", placeholderKeyHashPrefix+"%"). + Find(&keys).Error + return keys, err +} + func (r *tenantAPIKeyRepository) UpdateAPIKeyLastUsed(ctx context.Context, id uint64, at time.Time) error { return r.db.WithContext(ctx). Model(&types.TenantAPIKey{}). diff --git a/internal/application/service/tenant_api_key.go b/internal/application/service/tenant_api_key.go index 2e8a8ff6..244b103b 100644 --- a/internal/application/service/tenant_api_key.go +++ b/internal/application/service/tenant_api_key.go @@ -134,6 +134,28 @@ func (s *tenantAPIKeyService) RevokeAllAPIKeys(ctx context.Context, tenantID uin return s.repo.RevokeAllAPIKeys(ctx, tenantID) } +func (s *tenantAPIKeyService) BackfillMissingKeyHashes(ctx context.Context) (int, error) { + keys, err := s.repo.ListKeysWithPlaceholderHash(ctx) + if err != nil { + return 0, err + } + backfilled := 0 + for _, key := range keys { + if key == nil || strings.TrimSpace(key.APIKey) == "" { + continue + } + hash := hashTenantAPIKey(key.APIKey) + if key.KeyHash == hash { + continue + } + if err := s.repo.UpdateAPIKeyHash(ctx, key.ID, hash); err != nil { + return backfilled, err + } + backfilled++ + } + return backfilled, nil +} + func generateTenantAPIKeyToken() (string, error) { var b [32]byte if _, err := rand.Read(b[:]); err != nil { diff --git a/internal/application/service/tenant_api_key_test.go b/internal/application/service/tenant_api_key_test.go index b09afd57..a9650830 100644 --- a/internal/application/service/tenant_api_key_test.go +++ b/internal/application/service/tenant_api_key_test.go @@ -107,6 +107,17 @@ func (r *fakeTenantAPIKeyRepo) UpdateAPIKeyHash(_ context.Context, id uint64, ha return apprepo.ErrTenantAPIKeyNotFound } +func (r *fakeTenantAPIKeyRepo) ListKeysWithPlaceholderHash(_ context.Context) ([]*types.TenantAPIKey, error) { + out := []*types.TenantAPIKey{} + for _, key := range r.byHash { + if key.RevokedAt == nil && strings.HasPrefix(key.KeyHash, "migrated-tenant-") { + cp := *key + out = append(out, &cp) + } + } + return out, nil +} + func (r *fakeTenantAPIKeyRepo) UpdateAPIKeyLastUsed(_ context.Context, id uint64, at time.Time) error { for _, key := range r.byHash { if key.ID == id && key.RevokedAt == nil { @@ -126,7 +137,7 @@ func TestTenantAPIKeyServiceAuthenticateTenantAPIKeyRepairsMigratedHash(t *testi Name: "Tenant API key", KeyHash: "migrated-tenant-42", APIKey: token, - Role: types.TenantRoleAdmin, + Role: types.TenantRoleAdmin, } if err := repo.CreateAPIKey(ctx, key); err != nil { t.Fatalf("CreateAPIKey returned error: %v", err) @@ -143,6 +154,40 @@ func TestTenantAPIKeyServiceAuthenticateTenantAPIKeyRepairsMigratedHash(t *testi } } +func TestTenantAPIKeyServiceBackfillMissingKeyHashes(t *testing.T) { + ctx := context.Background() + repo := newFakeTenantAPIKeyRepo() + svc := NewTenantAPIKeyService(repo) + + token := "sk-legacy-token-value" + legacy := &types.TenantAPIKey{ + TenantID: 7, + Name: "legacy", + KeyHash: "migrated-tenant-7", + APIKey: token, + Role: types.TenantRoleAdmin, + } + if err := repo.CreateAPIKey(ctx, legacy); err != nil { + t.Fatalf("CreateAPIKey returned error: %v", err) + } + + n, err := svc.BackfillMissingKeyHashes(ctx) + if err != nil { + t.Fatalf("BackfillMissingKeyHashes returned error: %v", err) + } + if n != 1 { + t.Fatalf("backfilled = %d, want 1", n) + } + // After backfill the key authenticates via the fast hash path. + if _, err := svc.AuthenticateAPIKey(ctx, token); err != nil { + t.Fatalf("AuthenticateAPIKey after backfill returned error: %v", err) + } + // Idempotent: a second run finds nothing to do. + if n, err := svc.BackfillMissingKeyHashes(ctx); err != nil || n != 0 { + t.Fatalf("second BackfillMissingKeyHashes = (%d, %v), want (0, nil)", n, err) + } +} + func TestTenantAPIKeyServiceRevokeAllAPIKeys(t *testing.T) { ctx := context.Background() repo := newFakeTenantAPIKeyRepo() @@ -151,7 +196,7 @@ func TestTenantAPIKeyServiceRevokeAllAPIKeys(t *testing.T) { first, err := svc.CreateAPIKey(ctx, interfaces.TenantAPIKeyCreateRequest{ TenantID: 42, Name: "first", - Role: types.TenantRoleViewer, + Role: types.TenantRoleViewer, }) if err != nil { t.Fatalf("CreateAPIKey first returned error: %v", err) @@ -159,7 +204,7 @@ func TestTenantAPIKeyServiceRevokeAllAPIKeys(t *testing.T) { second, err := svc.CreateAPIKey(ctx, interfaces.TenantAPIKeyCreateRequest{ TenantID: 42, Name: "second", - Role: types.TenantRoleViewer, + Role: types.TenantRoleViewer, }) if err != nil { t.Fatalf("CreateAPIKey second returned error: %v", err) diff --git a/internal/handler/tenant.go b/internal/handler/tenant.go index c7b964ce..4e3b8cca 100644 --- a/internal/handler/tenant.go +++ b/internal/handler/tenant.go @@ -116,8 +116,9 @@ type apiPrincipalConfigResponse struct { DirectHeaderName string `json:"direct_header_name"` SignedTokenHeaderName string `json:"signed_token_header_name"` RequireDirectHeader bool `json:"require_direct_header"` - HasHMACSecret bool `json:"has_hmac_secret"` - HMACSecret string `json:"hmac_secret,omitempty"` + // HasHMACSecret reports whether a signing secret is configured. The + // plaintext secret is NEVER returned — clients only learn presence. + HasHMACSecret bool `json:"has_hmac_secret"` } type apiPrincipalTestTokenRequest struct { @@ -162,6 +163,11 @@ const ( defaultAPIPrincipalTestTokenTTL = 15 * time.Minute maxAPIPrincipalTestTokenTTL = time.Hour maxAPIPrincipalExternalUserIDLen = 128 + // apiPrincipalSecretRedacted is the placeholder an update request may + // send in place of the HMAC secret to signal "leave the stored secret + // unchanged". The plaintext secret is never returned by GET, so the + // client cannot echo the real value back. + apiPrincipalSecretRedacted = "***" ) // defaultMaxOwnedTenantsPerUser is the cap applied when @@ -705,7 +711,7 @@ func validateTenantAPIKeyRequest( return errors.NewValidationError("name is required") } if role := types.NormalizeTenantAPIKeyRole(types.TenantRole(strings.TrimSpace(req.Role))); req.Role != "" && role == "" { - return errors.NewValidationError("role must be viewer, contributor, or admin") + return errors.NewValidationError("role must be one of viewer, contributor, admin, or owner") } for _, kbID := range req.KnowledgeBaseIDs { kbID = strings.TrimSpace(kbID) @@ -737,7 +743,6 @@ func apiPrincipalConfigForResponse(cfg *types.APIPrincipalConfig) apiPrincipalCo SignedTokenHeaderName: defaultAPIPrincipalTokenHeader, RequireDirectHeader: cfg.RequireDirectHeader, HasHMACSecret: strings.TrimSpace(cfg.HMACSecret) != "", - HMACSecret: strings.TrimSpace(cfg.HMACSecret), } } @@ -826,7 +831,14 @@ func (h *TenantHandler) UpdateAPIPrincipalConfig(c *gin.Context) { } hmacSecret := existingSecret if req.HMACSecret != nil { - hmacSecret = strings.TrimSpace(*req.HMACSecret) + provided := strings.TrimSpace(*req.HMACSecret) + // GET no longer discloses the plaintext secret, so a client that + // edits the config re-submits the redaction placeholder to mean + // "keep the existing secret". Treat it as a no-op instead of + // overwriting the real secret with "***". + if provided != apiPrincipalSecretRedacted { + hmacSecret = provided + } } cfg := &types.APIPrincipalConfig{ Mode: req.Mode, diff --git a/internal/middleware/api_key_access.go b/internal/middleware/api_key_access.go deleted file mode 100644 index 896924d9..00000000 --- a/internal/middleware/api_key_access.go +++ /dev/null @@ -1,108 +0,0 @@ -package middleware - -import ( - "context" - 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") - -// isTenantAPIKeyManagementPath reports tenant API-key lifecycle endpoints that -// no scoped key may call, regardless of role. -func isTenantAPIKeyManagementPath(path string) bool { - for _, marker := range []string{"/api-keys", "/api-principal"} { - if strings.Contains(path, marker) { - return true - } - } - // Legacy reset endpoint: POST /tenants/:id/api-key (singular). - return strings.HasSuffix(path, "/api-key") -} - -// rejectTenantAPIKeyManagementPath is a defense-in-depth guard in auth: API keys -// must never reach key-management routes even if a route forgets APIKeyDeny(). -// Role and KB checks are enforced by per-route APIKey* guards and types helpers. -func rejectTenantAPIKeyManagementPath(ctx context.Context, path string) error { - if _, ok := types.TenantAPIKeyScopeFromContext(ctx); !ok { - return nil - } - if isTenantAPIKeyManagementPath(path) { - return errTenantAPIKeyScopeForbidden - } - return nil -} - -// RequireAPIKeyDeny rejects all X-API-Key callers. JWT sessions pass through. -func RequireAPIKeyDeny() gin.HandlerFunc { - return func(c *gin.Context) { - if _, ok := types.TenantAPIKeyScopeFromContext(c.Request.Context()); ok { - c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ - "error": "Forbidden: API key scope does not allow this operation", - }) - return - } - c.Next() - } -} - -// RequireAPIKeyMinRole enforces minRole for X-API-Key callers on every HTTP -// method. JWT sessions pass through. -func RequireAPIKeyMinRole(minRole types.TenantRole) gin.HandlerFunc { - return func(c *gin.Context) { - if err := requireTenantAPIKeyMinRole(c.Request.Context(), minRole); err != nil { - c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ - "error": "Forbidden: API key scope does not allow this operation", - }) - return - } - c.Next() - } -} - -// RequireAPIKeyMinRoleForUnsafe enforces minRole for X-API-Key callers on -// POST/PUT/PATCH/DELETE only. Safe reads (GET/HEAD/OPTIONS) pass through so -// group-level guards can cover mixed read/write route trees. -func RequireAPIKeyMinRoleForUnsafe(minRole types.TenantRole) gin.HandlerFunc { - return func(c *gin.Context) { - if isSafeHTTPMethod(c.Request.Method) { - c.Next() - return - } - if err := requireTenantAPIKeyMinRole(c.Request.Context(), minRole); err != nil { - c.AbortWithStatusJSON(http.StatusForbidden, gin.H{ - "error": "Forbidden: API key scope does not allow this operation", - }) - return - } - c.Next() - } -} - -func requireTenantAPIKeyMinRole(ctx context.Context, minRole types.TenantRole) error { - scope, ok := types.TenantAPIKeyScopeFromContext(ctx) - if !ok { - return nil - } - role := scope.Role - if role == "" { - role = types.TenantRoleViewer - } - if !role.HasPermission(minRole) { - return errTenantAPIKeyScopeForbidden - } - return nil -} - -func isSafeHTTPMethod(method string) bool { - switch method { - case http.MethodGet, http.MethodHead, http.MethodOptions: - return true - default: - return false - } -} diff --git a/internal/middleware/api_key_access_test.go b/internal/middleware/api_key_access_test.go deleted file mode 100644 index bc10a9f1..00000000 --- a/internal/middleware/api_key_access_test.go +++ /dev/null @@ -1,114 +0,0 @@ -package middleware - -import ( - "context" - stderrors "errors" - "net/http" - "net/http/httptest" - "testing" - - "github.com/Tencent/WeKnora/internal/types" - "github.com/gin-gonic/gin" -) - -func TestRejectTenantAPIKeyManagementPath(t *testing.T) { - ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleAdmin, - }) - - for _, path := range []string{ - "/api/v1/tenants/1/api-keys", - "/api/v1/tenants/1/api-key", - "/api/v1/tenants/1/api-principal-config", - "/api/v1/tenants/1/api-principal-test-token", - } { - err := rejectTenantAPIKeyManagementPath(ctx, path) - if !stderrors.Is(err, errTenantAPIKeyScopeForbidden) { - t.Fatalf("management path %s error = %v, want errTenantAPIKeyScopeForbidden", path, err) - } - } - - if err := rejectTenantAPIKeyManagementPath(ctx, "/api/v1/knowledge-bases"); err != nil { - t.Fatalf("non-management path should pass: %v", err) - } - if err := rejectTenantAPIKeyManagementPath(context.Background(), "/api/v1/tenants/1/api-keys"); err != nil { - t.Fatalf("non-api-key principal should pass: %v", err) - } -} - -func TestRequireAPIKeyDenyBlocksAPIKey(t *testing.T) { - gin.SetMode(gin.TestMode) - ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleAdmin, - }) - w := httptest.NewRecorder() - c, _ := gin.CreateTestContext(w) - c.Request = httptest.NewRequest(http.MethodPost, "/api/v1/knowledge-bases", nil) - c.Request = c.Request.WithContext(ctx) - - RequireAPIKeyDeny()(c) - if !c.IsAborted() { - t.Fatal("expected API key request to be aborted") - } - if w.Code != http.StatusForbidden { - t.Fatalf("status = %d, want %d", w.Code, http.StatusForbidden) - } -} - -func TestRequireAPIKeyDenyAllowsJWT(t *testing.T) { - gin.SetMode(gin.TestMode) - w := httptest.NewRecorder() - c, _ := gin.CreateTestContext(w) - c.Request = httptest.NewRequest(http.MethodPost, "/api/v1/knowledge-bases", nil) - - RequireAPIKeyDeny()(c) - if c.IsAborted() { - t.Fatal("expected JWT request to pass RequireAPIKeyDeny") - } -} - -func TestRequireAPIKeyMinRoleForUnsafeSkipsSafeMethods(t *testing.T) { - ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleViewer, - }) - if err := requireTenantAPIKeyMinRole(ctx, types.TenantRoleAdmin); !stderrors.Is(err, errTenantAPIKeyScopeForbidden) { - t.Fatalf("viewer should not satisfy admin min role: %v", err) - } - - gin.SetMode(gin.TestMode) - w := httptest.NewRecorder() - c, _ := gin.CreateTestContext(w) - c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/models", nil) - c.Request = c.Request.WithContext(ctx) - - RequireAPIKeyMinRoleForUnsafe(types.TenantRoleAdmin)(c) - if c.IsAborted() { - t.Fatal("safe GET should skip unsafe min-role guard") - } -} - -func TestRequireAPIKeyMinRoleEnforcesOnPost(t *testing.T) { - ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleViewer, - }) - gin.SetMode(gin.TestMode) - w := httptest.NewRecorder() - c, _ := gin.CreateTestContext(w) - c.Request = httptest.NewRequest(http.MethodPost, "/api/v1/knowledge-search", nil) - c.Request = c.Request.WithContext(ctx) - - RequireAPIKeyMinRole(types.TenantRoleViewer)(c) - if c.IsAborted() { - t.Fatal("viewer key should pass viewer min role on POST") - } -} - -func TestRequireAPIKeyMinRoleForUnsafeAllowsContributorKnowledgeWrite(t *testing.T) { - ctx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleContributor, - KnowledgeBaseIDs: types.StringArray{"kb-1"}, - }) - if err := requireTenantAPIKeyMinRole(ctx, types.TenantRoleContributor); err != nil { - t.Fatalf("scoped knowledge write should pass route guard: %v", err) - } -} diff --git a/internal/middleware/api_key_gate.go b/internal/middleware/api_key_gate.go new file mode 100644 index 00000000..e143f180 --- /dev/null +++ b/internal/middleware/api_key_gate.go @@ -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 +} diff --git a/internal/middleware/api_key_gate_test.go b/internal/middleware/api_key_gate_test.go new file mode 100644 index 00000000..a628e5f7 --- /dev/null +++ b/internal/middleware/api_key_gate_test.go @@ -0,0 +1,166 @@ +package middleware + +import ( + "net/http" + "net/http/httptest" + "testing" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/gin-gonic/gin" +) + +func newTestAuthorizer() *APIKeyRouteAuthorizer { + a := NewAPIKeyRouteAuthorizer() + // Data-plane routes (Viewer read, Contributor write, Admin destructive) + // plus one tenant-level Owner route. + a.Register(http.MethodGet, "/api/v1/knowledge-bases/:id", policyMinRole(types.TenantRoleViewer)) + a.Register(http.MethodPost, "/api/v1/knowledge-bases/:id/knowledge/file", policyMinRole(types.TenantRoleContributor)) + a.Register(http.MethodDelete, "/api/v1/knowledge-bases/:id/knowledge", policyMinRole(types.TenantRoleAdmin)) + a.Register(http.MethodGet, "/api/v1/models", policyMinRole(types.TenantRoleOwner)) + a.Register(http.MethodPut, "/api/v1/tenants/kv/:key", policyMinRole(types.TenantRoleOwner)) + return a +} + +func policyMinRole(r types.TenantRole) APIKeyRoutePolicy { + return APIKeyRoutePolicy{MinRole: r} +} + +// runGate exercises the gate middleware with a given scope, method and route +// full-path, returning whether the request was allowed to proceed. +func runGate(t *testing.T, a *APIKeyRouteAuthorizer, scope *types.TenantAPIKeyScope, method, fullPath string) bool { + 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.Use(a.Middleware()) + allowed := false + engine.Handle(method, fullPath, func(c *gin.Context) { + allowed = true + c.Status(http.StatusOK) + }) + + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(method, concretePath(fullPath), nil)) + return allowed && w.Code == http.StatusOK +} + +// concretePath substitutes gin :params with literals so httptest can hit it. +func concretePath(tmpl string) string { + switch tmpl { + case "/api/v1/knowledge-bases/:id": + return "/api/v1/knowledge-bases/kb-1" + case "/api/v1/knowledge-bases/:id/knowledge/file": + return "/api/v1/knowledge-bases/kb-1/knowledge/file" + case "/api/v1/knowledge-bases/:id/knowledge": + return "/api/v1/knowledge-bases/kb-1/knowledge" + case "/api/v1/tenants/kv/:key": + return "/api/v1/tenants/kv/some-key" + default: + return tmpl + } +} + +func TestGateJWTPassesThrough(t *testing.T) { + a := newTestAuthorizer() + // No scope => JWT principal => always allowed, even on an Owner route. + if !runGate(t, a, nil, http.MethodGet, "/api/v1/models") { + t.Fatal("JWT principal must pass the gate") + } +} + +func TestGateDefaultDeny(t *testing.T) { + a := newTestAuthorizer() + owner := &types.TenantAPIKeyScope{Role: types.TenantRoleOwner} + gin.SetMode(gin.TestMode) + engine := gin.New() + engine.Use(func(c *gin.Context) { + c.Request = c.Request.WithContext(types.WithTenantAPIKeyScope(c.Request.Context(), *owner)) + c.Next() + }) + engine.Use(a.Middleware()) + engine.POST("/api/v1/agents", func(c *gin.Context) { c.Status(http.StatusOK) }) + w := httptest.NewRecorder() + engine.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/api/v1/agents", nil)) + if w.Code != http.StatusForbidden { + t.Fatalf("undeclared route should default-deny even an Owner key: status=%d", w.Code) + } +} + +func TestGateDataPlaneRoleLadder(t *testing.T) { + a := newTestAuthorizer() + viewer := &types.TenantAPIKeyScope{Role: types.TenantRoleViewer} + contributor := &types.TenantAPIKeyScope{Role: types.TenantRoleContributor} + admin := &types.TenantAPIKeyScope{Role: types.TenantRoleAdmin} + + // Safe read: any data-plane key (Viewer) passes. + if !runGate(t, a, viewer, http.MethodGet, "/api/v1/knowledge-bases/:id") { + t.Fatal("viewer key should read a declared KB route") + } + // Contributor write. + if runGate(t, a, viewer, http.MethodPost, "/api/v1/knowledge-bases/:id/knowledge/file") { + t.Fatal("viewer key must not perform a contributor write") + } + if !runGate(t, a, contributor, http.MethodPost, "/api/v1/knowledge-bases/:id/knowledge/file") { + t.Fatal("contributor key should perform a contributor write") + } + // Admin destructive. + if runGate(t, a, contributor, http.MethodDelete, "/api/v1/knowledge-bases/:id/knowledge") { + t.Fatal("contributor key must not perform an admin destructive op") + } + if !runGate(t, a, admin, http.MethodDelete, "/api/v1/knowledge-bases/:id/knowledge") { + t.Fatal("admin key should perform an admin destructive op") + } +} + +func TestGateTenantRoutesRequireOwner(t *testing.T) { + a := newTestAuthorizer() + admin := &types.TenantAPIKeyScope{Role: types.TenantRoleAdmin} + owner := &types.TenantAPIKeyScope{Role: types.TenantRoleOwner} + + // Even a safe GET on a tenant-level route requires Owner (no Viewer floor). + if runGate(t, a, admin, http.MethodGet, "/api/v1/models") { + t.Fatal("admin key must NOT read a tenant-level route") + } + if !runGate(t, a, owner, http.MethodGet, "/api/v1/models") { + t.Fatal("owner key should read a tenant-level route") + } + // Unsafe tenant write also requires Owner. + if runGate(t, a, admin, http.MethodPut, "/api/v1/tenants/kv/:key") { + t.Fatal("admin key must NOT write a tenant-level route") + } + if !runGate(t, a, owner, http.MethodPut, "/api/v1/tenants/kv/:key") { + t.Fatal("owner key should write a tenant-level route") + } +} + +func TestGateKBScopeDoesNotBlockDataPlane(t *testing.T) { + a := newTestAuthorizer() + // A KB-restricted key is NOT blocked by the gate on data-plane routes; + // its KB allow-list is enforced downstream by KBAccess/handler checks. + restricted := &types.TenantAPIKeyScope{ + Role: types.TenantRoleContributor, + KnowledgeBaseIDs: types.StringArray{"kb-1"}, + } + if !runGate(t, a, restricted, http.MethodPost, "/api/v1/knowledge-bases/:id/knowledge/file") { + t.Fatal("KB-restricted contributor key should pass the gate on a data-plane write") + } +} + +func TestNormalizeRoutePath(t *testing.T) { + cases := map[string]string{ + "/api/v1//models": "/api/v1/models", + "/api/v1/models/": "/api/v1/models", + "/": "/", + "/api/v1/agents": "/api/v1/agents", + } + for in, want := range cases { + if got := normalizeRoutePath(in); got != want { + t.Fatalf("normalizeRoutePath(%q)=%q want %q", in, got, want) + } + } +} diff --git a/internal/middleware/api_key_route_scope_manifest_test.go b/internal/middleware/api_key_route_scope_manifest_test.go deleted file mode 100644 index d4d264c6..00000000 --- a/internal/middleware/api_key_route_scope_manifest_test.go +++ /dev/null @@ -1,83 +0,0 @@ -package middleware - -import ( - "context" - "net/http" - "net/http/httptest" - "testing" - - "github.com/Tencent/WeKnora/internal/types" - "github.com/gin-gonic/gin" -) - -func TestTenantAPIKeyRouteScopeManifest(t *testing.T) { - readCtx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleViewer, - }) - writeCtx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleContributor, - }) - adminCtx := types.WithTenantAPIKeyScope(context.Background(), types.TenantAPIKeyScope{ - Role: types.TenantRoleAdmin, - }) - - baselineCases := []struct { - name string - ctx context.Context - path string - allowed bool - }{ - {name: "read get kb list", ctx: readCtx, path: "/api/v1/knowledge-bases", allowed: true}, - {name: "read get wiki page", ctx: readCtx, path: "/api/v1/knowledgebase/kb-1/wiki/pages", allowed: true}, - {name: "admin reset api key blocked", ctx: adminCtx, path: "/api/v1/tenants/1/api-key", allowed: false}, - {name: "admin api principal blocked", ctx: adminCtx, path: "/api/v1/tenants/1/api-principal-config", allowed: false}, - } - for _, tc := range baselineCases { - t.Run("baseline/"+tc.name, func(t *testing.T) { - err := rejectTenantAPIKeyManagementPath(tc.ctx, tc.path) - got := err == nil - if got != tc.allowed { - t.Fatalf("rejectTenantAPIKeyManagementPath(%s) allowed=%v, want %v (err=%v)", - tc.path, got, tc.allowed, err) - } - }) - } - - guardCases := []struct { - name string - ctx context.Context - method string - guard gin.HandlerFunc - allowed bool - }{ - {name: "read delete kb", ctx: readCtx, method: http.MethodDelete, guard: RequireAPIKeyMinRoleForUnsafe(types.TenantRoleContributor), allowed: false}, - {name: "write put kb", ctx: writeCtx, method: http.MethodPut, guard: RequireAPIKeyMinRoleForUnsafe(types.TenantRoleContributor), allowed: true}, - {name: "write create kb", ctx: writeCtx, method: http.MethodPost, guard: RequireAPIKeyDeny(), allowed: false}, - {name: "write batch delete", ctx: writeCtx, method: http.MethodPost, guard: RequireAPIKeyDeny(), allowed: false}, - {name: "write faq upsert", ctx: writeCtx, method: http.MethodPost, guard: RequireAPIKeyMinRoleForUnsafe(types.TenantRoleContributor), allowed: true}, - {name: "write semantic search post", ctx: writeCtx, method: http.MethodPost, guard: RequireAPIKeyMinRole(types.TenantRoleViewer), allowed: true}, - {name: "read semantic search post", ctx: readCtx, method: http.MethodPost, guard: RequireAPIKeyMinRole(types.TenantRoleViewer), allowed: true}, - {name: "read knowledge chat post", ctx: readCtx, method: http.MethodPost, guard: RequireAPIKeyMinRole(types.TenantRoleViewer), allowed: true}, - {name: "admin tenant kv", ctx: adminCtx, method: http.MethodPut, guard: RequireAPIKeyMinRoleForUnsafe(types.TenantRoleAdmin), allowed: true}, - {name: "contributor tenant kv", ctx: writeCtx, method: http.MethodPut, guard: RequireAPIKeyMinRoleForUnsafe(types.TenantRoleAdmin), allowed: false}, - } - for _, tc := range guardCases { - t.Run("guard/"+tc.name, func(t *testing.T) { - got := runAPIKeyGuard(t, tc.ctx, tc.method, tc.guard) - if got != tc.allowed { - t.Fatalf("guard allowed=%v, want %v", got, tc.allowed) - } - }) - } -} - -func runAPIKeyGuard(t *testing.T, ctx context.Context, method string, guard gin.HandlerFunc) bool { - t.Helper() - gin.SetMode(gin.TestMode) - w := httptest.NewRecorder() - c, _ := gin.CreateTestContext(w) - c.Request = httptest.NewRequest(method, "/api/v1/test", nil) - c.Request = c.Request.WithContext(ctx) - guard(c) - return !c.IsAborted() && w.Code != http.StatusForbidden -} diff --git a/internal/middleware/auth.go b/internal/middleware/auth.go index 68deeae8..a6612f98 100644 --- a/internal/middleware/auth.go +++ b/internal/middleware/auth.go @@ -260,11 +260,9 @@ func authenticateAPIKeyRequest( if c.IsAborted() { return false } - if err := rejectTenantAPIKeyManagementPath(c.Request.Context(), c.Request.URL.Path); err != nil { - c.JSON(http.StatusForbidden, gin.H{"error": "Forbidden: API key scope does not allow this operation"}) - c.Abort() - return false - } + // Per-route API-key authorization (role + KB scope + default-deny) is + // enforced by middleware.APIKeyRouteAuthorizer on the /api/v1 group. + // Key-management and any other undeclared route is denied there. return true } diff --git a/internal/middleware/auth_api_key_scope_test.go b/internal/middleware/auth_api_key_scope_test.go deleted file mode 100644 index c644a936..00000000 --- a/internal/middleware/auth_api_key_scope_test.go +++ /dev/null @@ -1,36 +0,0 @@ -package middleware - -import ( - "net/http" - "net/http/httptest" - "testing" - - "github.com/Tencent/WeKnora/internal/types" - "github.com/gin-gonic/gin" -) - -// TestAuthenticateAPIKeyScopeUsesRequestContextAfterAttach verifies the -// rejectTenantAPIKeyManagementPath call in authenticateAPIKeyRequest reads -// scope from c.Request.Context() after attachAPIKeyAuthContext. -func TestAuthenticateAPIKeyScopeUsesRequestContextAfterAttach(t *testing.T) { - gin.SetMode(gin.TestMode) - - c, _ := gin.CreateTestContext(httptest.NewRecorder()) - c.Request = httptest.NewRequest(http.MethodDelete, "/api/v1/knowledge-bases/kb-1", nil) - - preAttach := c.Request.Context() - c.Request = c.Request.WithContext(types.WithTenantAPIKeyScope(preAttach, types.TenantAPIKeyScope{ - KeyID: 1, - Role: types.TenantRoleViewer, - })) - - if err := rejectTenantAPIKeyManagementPath(preAttach, c.Request.URL.Path); err != nil { - t.Fatalf("pre-attach ctx should not carry scope and must not block: %v", err) - } - if err := rejectTenantAPIKeyManagementPath(c.Request.Context(), c.Request.URL.Path); err != nil { - t.Fatalf("non-management path should pass auth baseline: %v", err) - } - if err := requireTenantAPIKeyMinRole(c.Request.Context(), types.TenantRoleContributor); err == nil { - t.Fatal("viewer key must not satisfy contributor route guard on DELETE") - } -} diff --git a/internal/middleware/rbac.go b/internal/middleware/rbac.go index fa6d0242..2c104334 100644 --- a/internal/middleware/rbac.go +++ b/internal/middleware/rbac.go @@ -68,6 +68,13 @@ func RequireRole(min types.TenantRole, cfg *config.Config) gin.HandlerFunc { warnOnNilConfig(cfg) return func(c *gin.Context) { ctx := c.Request.Context() + // API-key principals are authorized solely by the APIKeyGate + // (role + KB scope + default-deny). The JWT role ladder does not + // apply to a machine principal, so short-circuit here. + if _, ok := types.TenantAPIKeyScopeFromContext(ctx); ok { + c.Next() + return + } role := types.TenantRoleFromContext(ctx) if role.HasPermission(min) { c.Next() @@ -121,6 +128,15 @@ func RequireSystemAdmin(cfg *config.Config) gin.HandlerFunc { warnOnNilConfig(cfg) return func(c *gin.Context) { ctx := c.Request.Context() + // API-key principals never gain system-admin authority, but the + // APIKeyGate is the single place that decides which routes they may + // reach. System routes are simply not declared there, so an API key + // is already rejected by default-deny before this guard runs. Short- + // circuit to avoid a misleading "system administrator required" 403. + if _, ok := types.TenantAPIKeyScopeFromContext(ctx); ok { + c.Next() + return + } if types.IsSystemAdminFromContext(ctx) { c.Next() return @@ -169,6 +185,15 @@ func RequireOwnershipOrRole(min types.TenantRole, lookup CreatorLookup, cfg *con warnOnNilConfig(cfg) return func(c *gin.Context) { ctx := c.Request.Context() + // API-key principals are authorized solely by the APIKeyGate. + // Ownership ("creator OR Admin+") is a human concept that cannot + // apply to a machine principal (its synthetic system-user never + // matches creator_id), so short-circuit here. KB-scope for API + // keys is still enforced by the KBAccess guards + handler checks. + if _, ok := types.TenantAPIKeyScopeFromContext(ctx); ok { + c.Next() + return + } role := types.TenantRoleFromContext(ctx) // 1. Fast path: role meets the bar. diff --git a/internal/middleware/rbac_api_key_shortcircuit_test.go b/internal/middleware/rbac_api_key_shortcircuit_test.go new file mode 100644 index 00000000..fc17b74f --- /dev/null +++ b/internal/middleware/rbac_api_key_shortcircuit_test.go @@ -0,0 +1,101 @@ +package middleware + +import ( + "context" + "net/http" + "net/http/httptest" + "testing" + + "github.com/Tencent/WeKnora/internal/config" + "github.com/Tencent/WeKnora/internal/types" + "github.com/gin-gonic/gin" +) + +// apiKeyRBACHarness seeds an API-key scope (as attachAPIKeyAuthContext would) +// plus a deliberately-insufficient TenantRole, then runs the guard. It +// asserts the JWT guard short-circuits for API-key principals so that +// per-route API-key authorization is left entirely to the APIKeyGate. +func apiKeyRBACHarness(scope types.TenantAPIKeyScope, role types.TenantRole, mw gin.HandlerFunc) *httptest.ResponseRecorder { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(func(c *gin.Context) { + ctx := context.WithValue(c.Request.Context(), types.TenantRoleContextKey, role) + ctx = types.WithTenantAPIKeyScope(ctx, scope) + c.Request = c.Request.WithContext(ctx) + c.Next() + }) + r.GET("/protected", mw, func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"ok": true}) }) + + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/protected", nil)) + return w +} + +func TestRequireRole_ShortCircuitsAPIKey(t *testing.T) { + // Viewer-role API key against an Admin gate would 403 under the JWT + // ladder; the short-circuit lets it through (the gate handles it). + w := apiKeyRBACHarness( + types.TenantAPIKeyScope{Role: types.TenantRoleViewer}, + types.TenantRoleViewer, + RequireRole(types.TenantRoleAdmin, cfgRBAC(true)), + ) + if w.Code != http.StatusOK { + t.Fatalf("API-key principal should short-circuit RequireRole, got %d", w.Code) + } +} + +func TestRequireSystemAdmin_ShortCircuitsAPIKey(t *testing.T) { + w := apiKeyRBACHarness( + types.TenantAPIKeyScope{Role: types.TenantRoleAdmin}, + types.TenantRoleAdmin, + RequireSystemAdmin(cfgRBAC(true)), + ) + if w.Code != http.StatusOK { + t.Fatalf("API-key principal should short-circuit RequireSystemAdmin, got %d", w.Code) + } +} + +// TestRequireOwnershipOrRole_ShortCircuitsAPIKeyContributor is the core +// regression for review #1: a Contributor API key writing to a KB it does not +// "own" (synthetic system user never matches creator_id) must not be 403'd by +// the OwnedKBOrAdmin guard when EnableRBAC=true. The lookup deliberately +// returns a foreign creator to prove the guard never runs it. +func TestRequireOwnershipOrRole_ShortCircuitsAPIKeyContributor(t *testing.T) { + lookupCalled := false + lookup := func(_ *gin.Context) (string, error) { + lookupCalled = true + return "some-other-human-user", nil + } + w := apiKeyRBACHarness( + types.TenantAPIKeyScope{Role: types.TenantRoleContributor, KnowledgeBaseIDs: types.StringArray{"kb-1"}}, + types.TenantRoleContributor, + RequireOwnershipOrRole(types.TenantRoleAdmin, lookup, cfgRBAC(true)), + ) + if w.Code != http.StatusOK { + t.Fatalf("Contributor API-key write should short-circuit OwnedKBOrAdmin, got %d", w.Code) + } + if lookupCalled { + t.Fatal("ownership lookup must not run for API-key principals") + } +} + +// 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) { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(func(c *gin.Context) { + ctx := context.WithValue(c.Request.Context(), types.TenantRoleContextKey, types.TenantRoleViewer) + c.Request = c.Request.WithContext(ctx) + c.Next() + }) + r.GET("/p", RequireRole(types.TenantRoleAdmin, &config.Config{Tenant: &config.TenantConfig{EnableRBAC: boolPtr(true)}}), + func(c *gin.Context) { c.Status(http.StatusOK) }) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/p", nil)) + if w.Code != http.StatusForbidden { + t.Fatalf("JWT Viewer must still be denied by Admin gate, got %d", w.Code) + } +} + +func boolPtr(b bool) *bool { return &b } diff --git a/internal/router/rbac.go b/internal/router/rbac.go index 8eb44a21..2379f8f3 100644 --- a/internal/router/rbac.go +++ b/internal/router/rbac.go @@ -1,6 +1,10 @@ package router import ( + "net/http" + "path" + "strings" + "github.com/Tencent/WeKnora/internal/config" "github.com/Tencent/WeKnora/internal/handler" "github.com/Tencent/WeKnora/internal/middleware" @@ -122,10 +126,10 @@ type rbacGuards struct { // Contributor who owns the KB can edit/delete its sub-resources // (documents, chunks, wiki pages); a Contributor who merely belongs // to the tenant gets 403 unless they're also Admin+. - knowledgeKBCreator middleware.CreatorLookup - chunkKBCreator middleware.CreatorLookup - chunkKBCreatorFromID middleware.CreatorLookup // chunk routes that address chunks by :id (no knowledge id in URL) - wikiKBCreator middleware.CreatorLookup + knowledgeKBCreator middleware.CreatorLookup + chunkKBCreator middleware.CreatorLookup + chunkKBCreatorFromID middleware.CreatorLookup // chunk routes that address chunks by :id (no knowledge id in URL) + wikiKBCreator middleware.CreatorLookup // Services for the KB-access guard (own / org-shared / via shared // agent). Captured here so route lines can reference g.KBAccess() @@ -136,6 +140,12 @@ type rbacGuards struct { chunkService middleware.ChunkLookup kbShareService interfaces.KBShareService agentShareService interfaces.AgentShareService + + // apiKeyAuthorizer is the single source of truth for which routes an + // X-API-Key principal may call. Routes opt in via the apiKeyGroup + // helpers below; anything not declared is denied by the gate. See + // middleware.APIKeyRouteAuthorizer. + apiKeyAuthorizer *middleware.APIKeyRouteAuthorizer } // newRBACGuards wires the guards from the live configuration and the @@ -153,7 +163,7 @@ func newRBACGuards( kbShareService interfaces.KBShareService, agentShareService interfaces.AgentShareService, ) *rbacGuards { - g := &rbacGuards{cfg: cfg} + g := &rbacGuards{cfg: cfg, apiKeyAuthorizer: middleware.NewAPIKeyRouteAuthorizer()} if kbHandler != nil { g.kbCreator = kbHandler.KBCreatorLookup g.kbCreatorFromKbIDParam = kbHandler.KBCreatorLookupFromKbIDParam @@ -198,23 +208,137 @@ func (g *rbacGuards) Owner() gin.HandlerFunc { return middleware.RequireRole(types.TenantRoleOwner, g.cfg) } -// API-key guards — orthogonal to JWT role guards. They only constrain -// X-API-Key principals; bearer sessions pass through unchanged. +// API-key authorization — a SEPARATE authority from the JWT role/ownership +// guards above. Instead of stacking a per-route guard that also had to know +// the caller's ownership, every API-key-accessible route declares one +// APIKeyRoutePolicy via the apiKeyGroup helpers; the gate on /api/v1 enforces +// it and denies any undeclared route by default. JWT sessions ignore all of +// this (they short-circuit the gate). +// +// Policy constructors. A single dimension — the minimum role — decides +// access; the key's knowledge_base_ids allow-list is a pure data filter +// applied downstream (KBAccess guards + handler scope checks), never here. +// +// - apiKeyViewer : data-plane reads/searches (Viewer floor). +// - apiKeyContributor : data-plane content writes (Contributor+). +// - apiKeyAdmin : destructive data-plane ops, e.g. clearing a KB (Admin+). +// - apiKeyOwner : tenant-level infrastructure (models, vector stores, +// MCP, data sources, channels, tenant KV, ...). Requires the Owner role +// for EVERY method, mirroring the original full-access tenant key. A key +// below Owner can only ever touch knowledge-base data. -func (g *rbacGuards) APIKeyDeny() gin.HandlerFunc { - return middleware.RequireAPIKeyDeny() +func apiKeyViewer() middleware.APIKeyRoutePolicy { + return middleware.APIKeyRoutePolicy{MinRole: types.TenantRoleViewer} } -func (g *rbacGuards) APIKeyViewer() gin.HandlerFunc { - return middleware.RequireAPIKeyMinRole(types.TenantRoleViewer) +func apiKeyContributor() middleware.APIKeyRoutePolicy { + return middleware.APIKeyRoutePolicy{MinRole: types.TenantRoleContributor} } -func (g *rbacGuards) APIKeyContributor() gin.HandlerFunc { - return middleware.RequireAPIKeyMinRoleForUnsafe(types.TenantRoleContributor) +func apiKeyAdmin() middleware.APIKeyRoutePolicy { + return middleware.APIKeyRoutePolicy{MinRole: types.TenantRoleAdmin} } -func (g *rbacGuards) APIKeyAdmin() gin.HandlerFunc { - return middleware.RequireAPIKeyMinRoleForUnsafe(types.TenantRoleAdmin) +func apiKeyOwner() middleware.APIKeyRoutePolicy { + return middleware.APIKeyRoutePolicy{MinRole: types.TenantRoleOwner} +} + +// apiKeyRouteGroup wraps a *gin.RouterGroup so route registration also records +// the route's API-key policy into the authorizer. Use g.apiKeyGroup(grp, +// policy) then register the API-key-accessible routes through it; register +// API-key-denied routes on the raw *gin.RouterGroup so they stay undeclared +// (default-deny). Per-route overrides use With(). +type apiKeyRouteGroup struct { + g *rbacGuards + grp *gin.RouterGroup + policy middleware.APIKeyRoutePolicy +} + +// ensureAPIKeyAuthorizer lazily allocates the authorizer so route +// registration is safe even when rbacGuards is built directly in tests +// (bypassing newRBACGuards). In production it is always pre-allocated. +func (g *rbacGuards) ensureAPIKeyAuthorizer() *middleware.APIKeyRouteAuthorizer { + if g.apiKeyAuthorizer == nil { + g.apiKeyAuthorizer = middleware.NewAPIKeyRouteAuthorizer() + } + return g.apiKeyAuthorizer +} + +// apiKeyGroup returns a wrapper that declares `policy` for every route +// registered through it (unless overridden via With). +func (g *rbacGuards) apiKeyGroup(grp *gin.RouterGroup, policy middleware.APIKeyRoutePolicy) *apiKeyRouteGroup { + g.ensureAPIKeyAuthorizer() + return &apiKeyRouteGroup{g: g, grp: grp, policy: policy} +} + +// With returns a sibling wrapper on the same gin group but with a different +// policy, for the odd route that differs from its group default (e.g. a read +// search inside an otherwise contributor-gated group). +func (a *apiKeyRouteGroup) With(policy middleware.APIKeyRoutePolicy) *apiKeyRouteGroup { + return &apiKeyRouteGroup{g: a.g, grp: a.grp, policy: policy} +} + +func (a *apiKeyRouteGroup) handle(method, rel string, handlers ...gin.HandlerFunc) gin.IRoutes { + full := path.Join(a.grp.BasePath(), rel) + a.g.ensureAPIKeyAuthorizer().Register(method, full, a.policy) + return a.grp.Handle(method, rel, handlers...) +} + +func (a *apiKeyRouteGroup) GET(rel string, h ...gin.HandlerFunc) gin.IRoutes { + return a.handle(http.MethodGet, rel, h...) +} + +func (a *apiKeyRouteGroup) POST(rel string, h ...gin.HandlerFunc) gin.IRoutes { + return a.handle(http.MethodPost, rel, h...) +} + +func (a *apiKeyRouteGroup) PUT(rel string, h ...gin.HandlerFunc) gin.IRoutes { + return a.handle(http.MethodPut, rel, h...) +} + +func (a *apiKeyRouteGroup) DELETE(rel string, h ...gin.HandlerFunc) gin.IRoutes { + return a.handle(http.MethodDelete, rel, h...) +} + +// apiKeyRoute declares a single API-key-accessible route directly on a gin +// group (for routes registered outside an apiKeyGroup, e.g. top-level r.POST). +func (g *rbacGuards) apiKeyRoute( + grp *gin.RouterGroup, method, rel string, policy middleware.APIKeyRoutePolicy, handlers ...gin.HandlerFunc, +) gin.IRoutes { + full := path.Join(grp.BasePath(), rel) + g.ensureAPIKeyAuthorizer().Register(method, full, policy) + return grp.Handle(method, rel, handlers...) +} + +// assertAPIKeyPoliciesMatchRoutes verifies every declared API-key policy +// resolves to a real registered route. gin's c.FullPath() must match the +// authorizer key verbatim or the gate silently 403s the route for API keys; +// panicking here turns that latent misconfiguration into a startup failure. +func (g *rbacGuards) assertAPIKeyPoliciesMatchRoutes(engine *gin.Engine) { + registered := map[string]struct{}{} + for _, ri := range engine.Routes() { + // Authorizer keys are stored normalized (trailing slash trimmed), so + // normalize gin's reported path the same way. Otherwise a route + // registered with a "/" rel (gin path ".../evaluation/") would look + // missing against the normalized key (".../evaluation") even though + // the gate — which also normalizes c.FullPath() — matches it fine. + p := ri.Path + if len(p) > 1 { + p = strings.TrimRight(p, "/") + } + registered[ri.Method+" "+p] = struct{}{} + } + var missing []string + for method, paths := range g.apiKeyAuthorizer.RegisteredRoutes() { + for _, p := range paths { + if _, ok := registered[method+" "+p]; !ok { + missing = append(missing, method+" "+p) + } + } + } + if len(missing) > 0 { + panic("api-key policy declared for non-existent route(s): " + strings.Join(missing, ", ")) + } } func (g *rbacGuards) SystemAdmin() gin.HandlerFunc { diff --git a/internal/router/rbac_selfcheck_test.go b/internal/router/rbac_selfcheck_test.go new file mode 100644 index 00000000..afa10b1e --- /dev/null +++ b/internal/router/rbac_selfcheck_test.go @@ -0,0 +1,53 @@ +package router + +import ( + "net/http" + "testing" + + "github.com/gin-gonic/gin" +) + +// TestAssertAPIKeyPoliciesMatchRoutes_TrailingSlash guards the class of bug +// where a route registered with a "/" rel (gin path ".../x/") was flagged as +// missing against the normalized policy key (".../x"), panicking at startup. +func TestAssertAPIKeyPoliciesMatchRoutes_TrailingSlash(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + v1 := engine.Group("/api/v1") + + g := &rbacGuards{} + noop := func(c *gin.Context) {} + + // Register through the apiKey helpers using both "" and "/" rel plus a + // nested path, mirroring real route declarations. + empty := g.apiKeyGroup(v1.Group("/knowledge-bases"), apiKeyViewer()) + empty.GET("", noop) + + slash := g.apiKeyGroup(v1.Group("/evaluation"), apiKeyOwner()) + slash.POST("/", noop) + slash.GET("/", noop) + + g.apiKeyRoute(v1, http.MethodGet, "/tenants", apiKeyOwner(), noop) + + // Must not panic: every declared policy resolves to a real route despite + // the trailing-slash difference on /evaluation. + g.assertAPIKeyPoliciesMatchRoutes(engine) +} + +// TestAssertAPIKeyPoliciesMatchRoutes_Missing verifies the self-check still +// panics when a policy points at a genuinely non-existent route. +func TestAssertAPIKeyPoliciesMatchRoutes_Missing(t *testing.T) { + gin.SetMode(gin.TestMode) + engine := gin.New() + + g := &rbacGuards{} + // Declare a policy for a path that is never registered on the engine. + g.ensureAPIKeyAuthorizer().Register(http.MethodPost, "/api/v1/does-not-exist", apiKeyOwner()) + + defer func() { + if recover() == nil { + t.Fatal("expected panic for policy on non-existent route") + } + }() + g.assertAPIKeyPoliciesMatchRoutes(engine) +} diff --git a/internal/router/router.go b/internal/router/router.go index c5938c87..1083071c 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -202,6 +202,13 @@ func NewRouter(params RouterParams) *gin.Engine { params.AgentShareService, ) + // API-key gate: single authority for X-API-Key principals. Runs + // first on every /api/v1 route (JWT sessions pass straight + // through) and denies any route not explicitly declared via the + // apiKeyGroup helpers. Must be attached BEFORE the Register* calls + // so that sub-groups inherit it. + v1.Use(rbacGuards.apiKeyAuthorizer.Middleware()) + RegisterAuthRoutes(v1, params.AuthHandler) RegisterTenantRoutes(v1, params.TenantHandler, params.TenantMemberHandler, params.TenantInvitationHandler, params.AuditLogHandler, rbacGuards) RegisterMyInvitationRoutes(v1, params.TenantInvitationHandler) @@ -232,6 +239,12 @@ func NewRouter(params RouterParams) *gin.Engine { RegisterWeKnoraCloudRoutes(v1, params.WeKnoraCloudHandler, rbacGuards) RegisterWikiPageRoutes(v1, params.WikiPageHandler, rbacGuards) RegisterChunkerDebugRoutes(v1, rbacGuards) + + // Fail fast if any declared API-key policy points at a route + // template that does not actually exist (typo / path drift). A + // stale template would silently 403 every API key on that route, + // so we panic at startup instead of shipping a dead policy. + rbacGuards.assertAPIKeyPoliciesMatchRoutes(r) } return r @@ -245,7 +258,7 @@ func NewRouter(params RouterParams) *gin.Engine { // has not yet expired are kept out by the role check, matching the // rest of the RBAC matrix in this file. func RegisterChunkerDebugRoutes(r *gin.RouterGroup, g *rbacGuards) { - r.POST("/chunker/preview", g.Viewer(), g.APIKeyViewer(), handler.PreviewChunking) + g.apiKeyRoute(r, http.MethodPost, "/chunker/preview", apiKeyViewer(), g.Viewer(), handler.PreviewChunking) } // RegisterChunkRoutes 注册分块相关的路由 @@ -255,8 +268,8 @@ func RegisterChunkerDebugRoutes(r *gin.RouterGroup, g *rbacGuards) { // shared with RegisterKnowledgeRoutes via OwnedChunkKBOrAdmin so the // same "creator-of-the-KB OR Admin+" rule applies to chunk edits. func RegisterChunkRoutes(r *gin.RouterGroup, handler *handler.ChunkHandler, g *rbacGuards) { - // 分块路由组 - chunks := r.Group("/chunks", g.APIKeyContributor()) + // 分块路由组。API key 策略:内容级写入 Contributor+ 且限定 KB 范围。 + chunks := g.apiKeyGroup(r.Group("/chunks"), apiKeyContributor()) { // 获取分块列表 — Viewer+ 且对父 KB 有 read 权限(own / shared / via shared agent) chunks.GET("/:knowledge_id", g.Viewer(), g.KBAccessReadFromKnowledgeIDParam("knowledge_id"), handler.ListKnowledgeChunks) @@ -288,8 +301,8 @@ func RegisterChunkRoutes(r *gin.RouterGroup, handler *handler.ChunkHandler, g *r // Cross-:id batch operations stay Contributor-gated — they don't have // a single owning KB to check against. func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandler, g *rbacGuards) { - // 知识库下的知识路由组(URL :id is the KB id) - kb := r.Group("/knowledge-bases/:id/knowledge", g.APIKeyContributor()) + // 知识库下的知识路由组(URL :id is the KB id)。API key 默认 Contributor+ 且限 KB 范围。 + kb := g.apiKeyGroup(r.Group("/knowledge-bases/:id/knowledge"), apiKeyContributor()) { kb.POST("/file", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.CreateKnowledgeFromFile) kb.POST("/url", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.CreateKnowledgeFromURL) @@ -297,11 +310,12 @@ func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandl kb.GET("", g.Viewer(), g.KBAccessRead("id"), handler.ListKnowledge) // Clearing all contents under a KB is a destructive op; gate // behind Admin instead of Contributor. - kb.DELETE("", g.Admin(), g.KBAccessWrite("id"), g.APIKeyAdmin(), handler.ClearKnowledgeBaseContents) + kb.With(apiKeyAdmin()).DELETE("", g.Admin(), g.KBAccessWrite("id"), handler.ClearKnowledgeBaseContents) } // 知识路由组(URL :id is a knowledge id; the guard walks it to the parent KB) - k := r.Group("/knowledge", g.APIKeyContributor()) + kgrp := r.Group("/knowledge") + k := g.apiKeyGroup(kgrp, apiKeyContributor()) { // Cross-knowledge endpoints (no :id) can't be gated on a single // KB — they accept arbitrary knowledge IDs and the handler must @@ -319,16 +333,15 @@ func RegisterKnowledgeRoutes(r *gin.RouterGroup, handler *handler.KnowledgeHandl k.GET("/:id/download", g.Viewer(), g.KBAccessReadFromKnowledgeIDParam("id"), handler.DownloadKnowledgeFile) k.GET("/:id/preview", g.Viewer(), g.KBAccessReadFromKnowledgeIDParam("id"), handler.PreviewKnowledgeFile) k.PUT("/image/:id/:chunk_id", g.OwnedKnowledgeKBOrAdmin(), g.KBAccessWriteFromKnowledgeIDParam("id"), handler.UpdateImageInfo) - // Batch / cross-KB ops stay Contributor-gated: there is no - // single owning KB to walk back to. A future PR could add a - // "must own every targeted KB" guard if the requirement - // surfaces. - k.PUT("/tags", g.Contributor(), g.APIKeyDeny(), handler.UpdateKnowledgeTagBatch) - k.POST("/batch-reparse", g.Contributor(), g.APIKeyDeny(), handler.BatchReparseKnowledge) k.GET("/search", g.Viewer(), handler.SearchKnowledge) - k.POST("/batch-delete", g.Contributor(), g.APIKeyDeny(), handler.BatchDeleteKnowledge) - k.POST("/move", g.Contributor(), g.APIKeyDeny(), handler.MoveKnowledge) k.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) } } @@ -345,7 +358,7 @@ func RegisterFAQRoutes(r *gin.RouterGroup, handler *handler.FAQHandler, g *rbacG // 等价于修改 KB 内容,必须遵循 KB 的"creator OR Admin+"矩阵 —— // 跟 chunks / wiki pages 保持一致。Viewer+ 可以读,Contributor 不能 // 改不属于自己的 KB 的 FAQ。 - faq := r.Group("/knowledge-bases/:id/faq", g.APIKeyContributor()) + faq := g.apiKeyGroup(r.Group("/knowledge-bases/:id/faq"), apiKeyContributor()) { // KBAccessRead/Write resolve own/shared/agent-visible access and // rewrite the request's tenant context — handler no longer @@ -361,7 +374,9 @@ func RegisterFAQRoutes(r *gin.RouterGroup, handler *handler.FAQHandler, g *rbacG faq.PUT("/entries/fields", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.UpdateEntryFieldsBatch) faq.PUT("/entries/tags", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.UpdateEntryTagBatch) faq.DELETE("/entries", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.DeleteEntries) - faq.POST("/search", g.Viewer(), g.KBAccessRead("id"), g.APIKeyViewer(), handler.SearchFAQ) + // Search is a read: Viewer keys may call it even though the group + // default is Contributor (POST is otherwise an unsafe method). + faq.With(apiKeyViewer()).POST("/search", g.Viewer(), g.KBAccessRead("id"), handler.SearchFAQ) // FAQ import result display status faq.PUT("/import/last-result/display", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.UpdateLastImportResultDisplayStatus) } @@ -374,19 +389,21 @@ func RegisterFAQRoutes(r *gin.RouterGroup, handler *handler.FAQHandler, g *rbacG // RegisterKnowledgeBaseRoutes 注册知识库相关的路由 func RegisterKnowledgeBaseRoutes(r *gin.RouterGroup, handler *handler.KnowledgeBaseHandler, g *rbacGuards) { - // 知识库路由组 - kb := r.Group("/knowledge-bases") + // 知识库路由组。API key 默认可读(Viewer,限 KB 范围);写入 Contributor+; + // 创建/拷贝 KB 不对 API key 开放(注册在原始 group 上,默认拒绝)。 + kbgrp := r.Group("/knowledge-bases") + kb := g.apiKeyGroup(kbgrp, apiKeyViewer()) { // 创建知识库 — Contributor+ (no :id, role-only floor); API keys may not create KBs. - kb.POST("", g.Contributor(), g.APIKeyDeny(), handler.CreateKnowledgeBase) + kbgrp.POST("", g.Contributor(), handler.CreateKnowledgeBase) // 获取知识库列表 — Viewer+ (no :id, role-only floor) kb.GET("", g.Viewer(), handler.ListKnowledgeBases) // 获取知识库详情 — Viewer+ 且对 KB 有 read 权限 kb.GET("/:id", g.Viewer(), g.KBAccessRead("id"), handler.GetKnowledgeBase) // 更新知识库 — 创建者本人 OR Admin+ 且对 KB 有 write 权限 - kb.PUT("/:id", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), g.APIKeyContributor(), handler.UpdateKnowledgeBase) + kb.With(apiKeyContributor()).PUT("/:id", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.UpdateKnowledgeBase) // 删除知识库 — 创建者本人 OR Admin+ 且对 KB 有 write 权限 - kb.DELETE("/:id", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), g.APIKeyContributor(), handler.DeleteKnowledgeBase) + kb.With(apiKeyContributor()).DELETE("/:id", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.DeleteKnowledgeBase) // 置顶/取消置顶知识库 — 创建者本人 OR Admin+ 且对 KB 有 write 权限 // Pin state is now per-(user, kb) (migration 000050). Anyone with // at least Viewer-level read access to the KB — including users @@ -394,13 +411,13 @@ func RegisterKnowledgeBaseRoutes(r *gin.RouterGroup, handler *handler.KnowledgeB // no edit permission is required. The OwnedKBOrAdmin guard was // removed accordingly. The route still requires KB read access // so callers can't poke at KBs they can't see. - kb.PUT("/:id/pin", g.Viewer(), g.KBAccessRead("id"), g.APIKeyContributor(), handler.TogglePinKnowledgeBase) + kb.With(apiKeyContributor()).PUT("/:id/pin", g.Viewer(), g.KBAccessRead("id"), handler.TogglePinKnowledgeBase) // 混合搜索 — Viewer+ 且对 KB 有 read 权限 (read-only) // POST is preferred; GET with JSON body is kept for backward compatibility (#1727). - kb.POST("/:id/hybrid-search", g.Viewer(), g.KBAccessRead("id"), g.APIKeyViewer(), handler.HybridSearch) + kb.POST("/:id/hybrid-search", g.Viewer(), g.KBAccessRead("id"), handler.HybridSearch) kb.GET("/:id/hybrid-search", g.Viewer(), g.KBAccessRead("id"), handler.HybridSearch) // 拷贝知识库 — Contributor+ (副本归调用者所有;不需要原 KB 的所有权) - kb.POST("/copy", g.Contributor(), g.APIKeyDeny(), handler.CopyKnowledgeBase) + kbgrp.POST("/copy", g.Contributor(), handler.CopyKnowledgeBase) // 获取知识库复制进度 — Viewer+ kb.GET("/copy/progress/:task_id", g.Viewer(), handler.GetKBCloneProgress) // 获取可移动目标知识库列表 — Viewer+ 且对 KB 有 read 权限 @@ -420,7 +437,7 @@ func RegisterKnowledgeTagRoutes(r *gin.RouterGroup, tagHandler *handler.TagHandl // Tags 是 KB 的子资源 — 创建/编辑/删除标签会改变 KB 内容的检索分类 // 行为,应该与 KB 主体的"creator OR Admin+"矩阵一致,避免一个无 // 关 Contributor 在他人 KB 里乱建/删标签影响 KB owner 的内容组织。 - kbTags := r.Group("/knowledge-bases/:id/tags", g.APIKeyContributor()) + kbTags := g.apiKeyGroup(r.Group("/knowledge-bases/:id/tags"), apiKeyContributor()) { // KBAccessRead/Write resolve own/shared/agent-visible access and // rewrite the request's tenant context to the effective tenant @@ -440,12 +457,15 @@ func RegisterKnowledgeTagRoutes(r *gin.RouterGroup, tagHandler *handler.TagHandl // (e.g. revoked accounts retained in the tenant for audit) cannot // reach the endpoints at all once RBAC is on. func RegisterMessageRoutes(r *gin.RouterGroup, handler *handler.MessageHandler, g *rbacGuards) { - messages := r.Group("/messages") + // Message history is tenant-wide and not attributable to a KB, so it is + // a tenant-level (Owner) surface for API keys — only a full-access key + // may read or delete it. + messages := g.apiKeyGroup(r.Group("/messages"), apiKeyOwner()) { - messages.POST("/search", g.Viewer(), g.APIKeyViewer(), handler.SearchMessages) + messages.POST("/search", g.Viewer(), handler.SearchMessages) messages.GET("/chat-history-stats", g.Viewer(), handler.GetChatHistoryKBStats) messages.GET("/:session_id/load", g.Viewer(), handler.LoadMessages) - messages.DELETE("/:session_id/:id", g.Viewer(), g.APIKeyAdmin(), handler.DeleteMessage) + messages.DELETE("/:session_id/:id", g.Viewer(), handler.DeleteMessage) } } @@ -457,7 +477,7 @@ func RegisterMessageRoutes(r *gin.RouterGroup, handler *handler.MessageHandler, // per-session ownership in the middleware layer the same way KB/agent // routes do today. func RegisterSessionRoutes(r *gin.RouterGroup, handler *session.Handler, g *rbacGuards) { - sessions := r.Group("/sessions", g.Viewer(), g.APIKeyContributor()) + sessions := g.apiKeyGroup(r.Group("/sessions", g.Viewer()), apiKeyContributor()) { sessions.POST("", handler.CreateSession) sessions.DELETE("/batch", handler.BatchDeleteSessions) @@ -483,19 +503,19 @@ func RegisterSessionRoutes(r *gin.RouterGroup, handler *session.Handler, g *rbac // surfaces; Viewer+ is sufficient because per-session/per-agent // authorisation is enforced inside the handlers. func RegisterChatRoutes(r *gin.RouterGroup, handler *session.Handler, g *rbacGuards) { - knowledgeChat := r.Group("/knowledge-chat", g.Viewer(), g.APIKeyViewer()) + knowledgeChat := g.apiKeyGroup(r.Group("/knowledge-chat", g.Viewer()), apiKeyViewer()) { knowledgeChat.POST("/:session_id", handler.KnowledgeQA) } // Agent-based chat - agentChat := r.Group("/agent-chat", g.Viewer(), g.APIKeyViewer()) + agentChat := g.apiKeyGroup(r.Group("/agent-chat", g.Viewer()), apiKeyViewer()) { agentChat.POST("/:session_id", handler.AgentQA) } // 新增知识检索接口,不需要session_id - knowledgeSearch := r.Group("/knowledge-search", g.Viewer(), g.APIKeyViewer()) + knowledgeSearch := g.apiKeyGroup(r.Group("/knowledge-search", g.Viewer()), apiKeyViewer()) { knowledgeSearch.POST("", handler.SearchKnowledge) } @@ -555,29 +575,34 @@ func RegisterTenantRoutes( // 安全说明:这里不挂 g.CrossTenant(),因为 self-service 创建 // 不需要跨租户特权;handler 也不读写 X-Tenant-ID 指向的现有 // 租户,所以越过 PathTenantMatch 守卫不会扩大攻击面。 - tenantRoutes.POST("", g.APIKeyDeny(), handler.CreateTenant) - tenantRoutes.GET("", handler.ListTenants) + // 创建租户不对 API key 开放(注册在原始 group,默认拒绝)。 + tenantRoutes.POST("", handler.CreateTenant) + g.apiKeyRoute(tenantRoutes, http.MethodGet, "", apiKeyOwner(), handler.ListTenants) // Generic KV configuration management (tenant-level). Tenant ID // is obtained from authentication context; the URL :key is a // config key, not a tenant ID, so these stay outside the - // PathTenantMatch group. - tenantRoutes.GET("/kv/:key", g.Viewer(), handler.GetTenantKV) - tenantRoutes.PUT("/kv/:key", g.Admin(), g.APIKeyAdmin(), handler.UpdateTenantKV) + // PathTenantMatch group. Tenant-level surface: only a full-access + // (Owner) API key may read or write it. + g.apiKeyRoute(tenantRoutes, http.MethodGet, "/kv/:key", apiKeyOwner(), g.Viewer(), handler.GetTenantKV) + g.apiKeyRoute(tenantRoutes, http.MethodPut, "/kv/:key", apiKeyOwner(), g.Admin(), handler.UpdateTenantKV) // Per-tenant endpoints share PathTenantMatch at the group level. + // None of the /tenants/:id/* endpoints are declared for API keys, + // so scoped keys are denied by default — tenant lifecycle, member + // management and key/principal management are JWT-only. tenantByID := tenantRoutes.Group("/:id", g.PathTenantMatch()) { tenantByID.GET("", g.Viewer(), handler.GetTenant) tenantByID.PUT("", g.Owner(), handler.UpdateTenant) tenantByID.DELETE("", g.Owner(), handler.DeleteTenant) - tenantByID.POST("/api-key", g.Owner(), g.APIKeyDeny(), handler.ResetAPIKey) - tenantByID.GET("/api-keys", g.Owner(), g.APIKeyDeny(), handler.ListAPIKeys) - tenantByID.POST("/api-keys", g.Owner(), g.APIKeyDeny(), handler.CreateAPIKey) - tenantByID.DELETE("/api-keys/:key_id", g.Owner(), g.APIKeyDeny(), handler.DeleteAPIKey) - tenantByID.GET("/api-principal-config", g.Owner(), g.APIKeyDeny(), handler.GetAPIPrincipalConfig) - tenantByID.PUT("/api-principal-config", g.Owner(), g.APIKeyDeny(), handler.UpdateAPIPrincipalConfig) - tenantByID.POST("/api-principal-test-token", g.Owner(), g.APIKeyDeny(), handler.CreateAPIPrincipalTestToken) + tenantByID.POST("/api-key", g.Owner(), handler.ResetAPIKey) + tenantByID.GET("/api-keys", g.Owner(), handler.ListAPIKeys) + tenantByID.POST("/api-keys", g.Owner(), handler.CreateAPIKey) + tenantByID.DELETE("/api-keys/:key_id", g.Owner(), handler.DeleteAPIKey) + tenantByID.GET("/api-principal-config", g.Owner(), handler.GetAPIPrincipalConfig) + tenantByID.PUT("/api-principal-config", g.Owner(), handler.UpdateAPIPrincipalConfig) + tenantByID.POST("/api-principal-test-token", g.Owner(), handler.CreateAPIPrincipalTestToken) // Tenant member management (PR 3 of #1303). Listing is // Viewer+ so any active member can see the roster; mutation @@ -634,8 +659,8 @@ func RegisterModelRoutes( credHandler *handler.ModelCredentialsHandler, g *rbacGuards, ) { - // 模型路由组 - models := r.Group("/models", g.APIKeyAdmin()) + // 模型路由组。租户级基础设施:仅完全访问(Owner)API key 可访问。 + models := g.apiKeyGroup(r.Group("/models"), apiKeyOwner()) { // 获取模型厂商列表 — Viewer+ models.GET("/providers", g.Viewer(), handler.ListModelProviders) @@ -662,10 +687,10 @@ func RegisterModelRoutes( // tenant; gate to Admin+ until product asks for a finer-grained // matrix. func RegisterEvaluationRoutes(r *gin.RouterGroup, handler *handler.EvaluationHandler, g *rbacGuards) { - evaluationRoutes := r.Group("/evaluation") + evaluationRoutes := g.apiKeyGroup(r.Group("/evaluation"), apiKeyOwner()) { - evaluationRoutes.POST("/", g.Admin(), g.APIKeyAdmin(), handler.Evaluation) - evaluationRoutes.GET("/", g.Viewer(), handler.GetEvaluationResult) + evaluationRoutes.POST("", g.Admin(), handler.Evaluation) + evaluationRoutes.GET("", g.Viewer(), handler.GetEvaluationResult) } } @@ -723,33 +748,36 @@ func RegisterAuthRoutes(r *gin.RouterGroup, handler *handler.AuthHandler) { func RegisterInitializationRoutes(r *gin.RouterGroup, handler *handler.InitializationHandler, g *rbacGuards) { // 初始化接口 - // GetCurrentConfigByKB 是只读,Viewer+ 即可。 - r.GET("/initialization/config/:kbId", g.Viewer(), g.KBAccessRead("kbId"), handler.GetCurrentConfigByKB) + // GetCurrentConfigByKB 是只读,Viewer+ 即可(KB 受限 key 可读其范围内的 KB)。 + g.apiKeyRoute(r, http.MethodGet, "/initialization/config/:kbId", + apiKeyViewer(), g.Viewer(), g.KBAccessRead("kbId"), handler.GetCurrentConfigByKB) // InitializeByKB / UpdateKBConfig 都是改 KB 的核心模型/storage 配置 — // 跟 PUT /knowledge-bases/:id 同等敏感,挂同款 OwnedKB 矩阵。 - r.POST("/initialization/initialize/:kbId", g.OwnedKBOrAdminFromKbIDParam(), g.APIKeyContributor(), handler.InitializeByKB) - r.PUT("/initialization/config/:kbId", g.OwnedKBOrAdminFromKbIDParam(), g.APIKeyContributor(), handler.UpdateKBConfig) + g.apiKeyRoute(r, http.MethodPost, "/initialization/initialize/:kbId", + apiKeyContributor(), g.OwnedKBOrAdminFromKbIDParam(), handler.InitializeByKB) + g.apiKeyRoute(r, http.MethodPut, "/initialization/config/:kbId", + apiKeyContributor(), g.OwnedKBOrAdminFromKbIDParam(), handler.UpdateKBConfig) // Ollama / 远程 API / 抽取等系统级检测/下载操作。这些不绑某个 KB, - // 但会改租户级模型配置或拉远端模型 — 一律 Admin+。Viewer+ 的检测 - // 入口已经在 settings 页面隐藏,但服务端仍要兜底。 - r.GET("/initialization/ollama/status", g.Viewer(), handler.CheckOllamaStatus) - r.GET("/initialization/ollama/models", g.Viewer(), handler.ListOllamaModels) - r.POST("/initialization/ollama/models/check", g.Admin(), g.APIKeyAdmin(), handler.CheckOllamaModels) - r.POST("/initialization/ollama/models/download", g.Admin(), g.APIKeyAdmin(), handler.DownloadOllamaModel) - r.GET("/initialization/ollama/download/progress/:taskId", g.Viewer(), handler.GetDownloadProgress) - r.GET("/initialization/ollama/download/tasks", g.Viewer(), handler.ListDownloadTasks) + // 会改租户级模型配置或拉远端模型;JWT 侧只读探测 Viewer+、变更 Admin+。 + // 对 API key 均为租户级:仅完全访问(Owner)key 可用。 + g.apiKeyRoute(r, http.MethodGet, "/initialization/ollama/status", apiKeyOwner(), g.Viewer(), handler.CheckOllamaStatus) + g.apiKeyRoute(r, http.MethodGet, "/initialization/ollama/models", apiKeyOwner(), g.Viewer(), handler.ListOllamaModels) + g.apiKeyRoute(r, http.MethodPost, "/initialization/ollama/models/check", apiKeyOwner(), g.Admin(), handler.CheckOllamaModels) + g.apiKeyRoute(r, http.MethodPost, "/initialization/ollama/models/download", apiKeyOwner(), g.Admin(), handler.DownloadOllamaModel) + g.apiKeyRoute(r, http.MethodGet, "/initialization/ollama/download/progress/:taskId", apiKeyOwner(), g.Viewer(), handler.GetDownloadProgress) + g.apiKeyRoute(r, http.MethodGet, "/initialization/ollama/download/tasks", apiKeyOwner(), g.Viewer(), handler.ListDownloadTasks) // 远程API相关接口 - r.POST("/initialization/remote/check", g.Admin(), g.APIKeyAdmin(), handler.CheckRemoteModel) - r.POST("/initialization/embedding/test", g.Admin(), g.APIKeyAdmin(), handler.TestEmbeddingModel) - r.POST("/initialization/rerank/check", g.Admin(), g.APIKeyAdmin(), handler.CheckRerankModel) - r.POST("/initialization/asr/check", g.Admin(), g.APIKeyAdmin(), handler.CheckASRModel) - r.POST("/initialization/multimodal/test", g.Admin(), g.APIKeyAdmin(), handler.TestMultimodalFunction) + g.apiKeyRoute(r, http.MethodPost, "/initialization/remote/check", apiKeyOwner(), g.Admin(), handler.CheckRemoteModel) + g.apiKeyRoute(r, http.MethodPost, "/initialization/embedding/test", apiKeyOwner(), g.Admin(), handler.TestEmbeddingModel) + g.apiKeyRoute(r, http.MethodPost, "/initialization/rerank/check", apiKeyOwner(), g.Admin(), handler.CheckRerankModel) + g.apiKeyRoute(r, http.MethodPost, "/initialization/asr/check", apiKeyOwner(), g.Admin(), handler.CheckASRModel) + g.apiKeyRoute(r, http.MethodPost, "/initialization/multimodal/test", apiKeyOwner(), g.Admin(), handler.TestMultimodalFunction) - r.POST("/initialization/extract/text-relation", g.Admin(), g.APIKeyAdmin(), handler.ExtractTextRelations) - r.POST("/initialization/extract/fabri-tag", g.Admin(), g.APIKeyAdmin(), handler.FabriTag) - r.POST("/initialization/extract/fabri-text", g.Admin(), g.APIKeyAdmin(), handler.FabriText) + g.apiKeyRoute(r, http.MethodPost, "/initialization/extract/text-relation", apiKeyOwner(), g.Admin(), handler.ExtractTextRelations) + g.apiKeyRoute(r, http.MethodPost, "/initialization/extract/fabri-tag", apiKeyOwner(), g.Admin(), handler.FabriTag) + g.apiKeyRoute(r, http.MethodPost, "/initialization/extract/fabri-text", apiKeyOwner(), g.Admin(), handler.FabriText) } // RegisterSystemRoutes registers system information routes @@ -760,7 +788,7 @@ func RegisterInitializationRoutes(r *gin.RouterGroup, handler *handler.Initializ // remote services with tenant credentials and could trigger network // fanout, so they're Admin+. func RegisterSystemRoutes(r *gin.RouterGroup, handler *handler.SystemHandler, g *rbacGuards) { - systemRoutes := r.Group("/system", g.APIKeyAdmin()) + systemRoutes := g.apiKeyGroup(r.Group("/system"), apiKeyOwner()) { systemRoutes.GET("/info", g.Viewer(), handler.GetSystemInfo) systemRoutes.GET("/parser-engines", g.Viewer(), handler.ListParserEngines) @@ -853,7 +881,7 @@ func RegisterMCPServiceRoutes( // redirect carries no WeKnora bearer — the single-use state authenticates. r.GET("/mcp-oauth/callback", oauthHandler.Callback) - mcpServices := r.Group("/mcp-services", g.APIKeyAdmin()) + mcpServices := g.apiKeyGroup(r.Group("/mcp-services"), apiKeyOwner()) { // Create MCP service — Admin+ mcpServices.POST("", g.Admin(), handler.CreateMCPService) @@ -886,7 +914,9 @@ func RegisterMCPServiceRoutes( mcpServices.DELETE("/:id/oauth/token", g.Viewer(), oauthHandler.Revoke) } - agentTool := r.Group("/agent", g.APIKeyDeny()) + // /agent tool-approval + OAuth resolution are interactive human flows; + // not declared for API keys (default-deny). + agentTool := r.Group("/agent") { // Resolving a pending tool-approval is gated to tenant members // (Viewer+). The approval card surfaces inside an agent chat the @@ -923,7 +953,7 @@ func RegisterWebSearchProviderRoutes( credHandler *handler.WebSearchProviderCredentialsHandler, g *rbacGuards, ) { - providers := r.Group("/web-search-providers", g.APIKeyAdmin()) + providers := g.apiKeyGroup(r.Group("/web-search-providers"), apiKeyOwner()) { // List available provider types (metadata for UI forms) — Viewer+ providers.GET("/types", g.Viewer(), h.ListProviderTypes) @@ -949,7 +979,7 @@ func RegisterWebSearchProviderRoutes( // writes (and connection tests, which probe external systems with stored // credentials) are Admin+. func RegisterVectorStoreRoutes(r *gin.RouterGroup, h *handler.VectorStoreHandler, g *rbacGuards) { - stores := r.Group("/vector-stores", g.APIKeyAdmin()) + stores := g.apiKeyGroup(r.Group("/vector-stores"), apiKeyOwner()) { // List available engine types (metadata for UI forms) — Viewer+ stores.GET("/types", g.Viewer(), h.ListStoreTypes) @@ -973,7 +1003,7 @@ func RegisterVectorStoreRoutes(r *gin.RouterGroup, h *handler.VectorStoreHandler // (IsBuiltin=true) have an empty creator and are always Admin+. Reads // are Viewer+, copy is Contributor+ (the copy is owned by the caller). func RegisterCustomAgentRoutes(r *gin.RouterGroup, agentHandler *handler.CustomAgentHandler, g *rbacGuards) { - agents := r.Group("/agents", g.APIKeyAdmin()) + agents := g.apiKeyGroup(r.Group("/agents"), apiKeyOwner()) { // Get placeholder definitions (must be before /:id to avoid conflict) — Viewer+ agents.GET("/placeholders", g.Viewer(), agentHandler.GetPlaceholders) @@ -993,7 +1023,7 @@ func RegisterCustomAgentRoutes(r *gin.RouterGroup, agentHandler *handler.CustomA agents.POST("/:id/copy", g.Contributor(), agentHandler.CopyAgent) } // Registered outside the group to avoid Gin route conflict with /agents/:id/shares in organization routes - r.GET("/agents/:id/suggested-questions", g.Viewer(), agentHandler.GetSuggestedQuestions) + g.apiKeyRoute(r, http.MethodGet, "/agents/:id/suggested-questions", apiKeyOwner(), g.Viewer(), agentHandler.GetSuggestedQuestions) } // RegisterUserFavoriteRoutes wires the per-user starred-resource endpoints. @@ -1004,7 +1034,8 @@ func RegisterCustomAgentRoutes(r *gin.RouterGroup, agentHandler *handler.CustomA // don't follow the OwnedXOrAdmin pattern: favorites aren't owned by the // resource's creator, they're owned by the user *doing* the starring. func RegisterUserFavoriteRoutes(r *gin.RouterGroup, h *handler.UserResourceFavoriteHandler, g *rbacGuards) { - favs := r.Group("/user/favorites", g.APIKeyDeny()) + // Favorites are per-user; not declared for API keys (default-deny). + favs := r.Group("/user/favorites") { favs.GET("", g.Viewer(), h.ListFavorites) favs.POST("", g.Viewer(), h.AddFavorite) @@ -1028,7 +1059,7 @@ func RegisterSkillRoutes(r *gin.RouterGroup, skillHandler *handler.SkillHandler, // RegisterOrganizationRoutes registers organization and sharing routes func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.OrganizationHandler, g *rbacGuards) { // Organization routes - orgs := r.Group("/organizations", g.APIKeyAdmin()) + orgs := g.apiKeyGroup(r.Group("/organizations"), apiKeyOwner()) { // Create organization (Admin+ in caller's tenant only) orgs.POST("", g.Admin(), orgHandler.CreateOrganization) @@ -1109,7 +1140,8 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza // 分享 KB 到组织 = 让组织里所有人能读这个 KB;这跟"修改 KB 元信息" // 同等敏感,所以挂同款 OwnedKBOrAdmin 矩阵。Viewer 在自己租户里 // 也不能私自把 KB 暴露出去。 - kbShares := r.Group("/knowledge-bases/:id/shares", g.APIKeyDeny()) + // KB share management is JWT-only; not declared for API keys. + kbShares := r.Group("/knowledge-bases/:id/shares") { // Share knowledge base kbShares.POST("", g.OwnedKBOrAdmin(), orgHandler.ShareKnowledgeBase) @@ -1128,7 +1160,8 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza // 校验(与 ListSharesByKnowledgeBase 不对称),如果路由层只挂 Viewer // 任何同租户成员都能枚举他人 agent 的分享去向——这里把 owner 校验 // 兜底到路由层,匹配 POST/DELETE 的矩阵。 - agentShares := r.Group("/agents/:id/shares", g.APIKeyDeny()) + // Agent share management is JWT-only; not declared for API keys. + agentShares := r.Group("/agents/:id/shares") { agentShares.POST("", g.OwnedAgentOrAdmin(), orgHandler.ShareAgent) agentShares.GET("", g.OwnedAgentOrAdmin(), orgHandler.ListAgentShares) @@ -1136,13 +1169,13 @@ func RegisterOrganizationRoutes(r *gin.RouterGroup, orgHandler *handler.Organiza } // Shared knowledge bases route — Viewer+ - r.GET("/shared-knowledge-bases", g.Viewer(), orgHandler.ListSharedKnowledgeBases) + g.apiKeyRoute(r, http.MethodGet, "/shared-knowledge-bases", apiKeyOwner(), g.Viewer(), orgHandler.ListSharedKnowledgeBases) // Shared agents route — Viewer+ - r.GET("/shared-agents", g.Viewer(), orgHandler.ListSharedAgents) + g.apiKeyRoute(r, http.MethodGet, "/shared-agents", apiKeyOwner(), g.Viewer(), orgHandler.ListSharedAgents) // "Disable by me" 是租户级偏好(写到 tenant_disabled_shared_agents), // 影响整个租户在会话下拉里看到的 agent 列表。任何 Viewer 改这个表就 // 等于替整个租户做决定 — 必须 Admin+ 才允许调整。 - r.POST("/shared-agents/disabled", g.Admin(), g.APIKeyAdmin(), orgHandler.SetSharedAgentDisabledByMe) + g.apiKeyRoute(r, http.MethodPost, "/shared-agents/disabled", apiKeyOwner(), g.Admin(), orgHandler.SetSharedAgentDisabledByMe) } // RegisterEmbedPublicRoutes registers anonymous embed endpoints secured by publish tokens. @@ -1186,12 +1219,12 @@ func RegisterEmbedChannelRoutes(r *gin.RouterGroup, embedHandler *handler.EmbedC if embedHandler == nil { return } - agentEmbed := r.Group("/agents/:id/embed-channels", g.APIKeyAdmin()) + agentEmbed := g.apiKeyGroup(r.Group("/agents/:id/embed-channels"), apiKeyOwner()) { agentEmbed.POST("", g.Admin(), embedHandler.CreateEmbedChannel) agentEmbed.GET("", g.Viewer(), embedHandler.ListEmbedChannels) } - channels := r.Group("/embed-channels", g.APIKeyAdmin()) + channels := g.apiKeyGroup(r.Group("/embed-channels"), apiKeyOwner()) { channels.GET("", g.Viewer(), embedHandler.ListAllEmbedChannels) channels.GET("/:channel_id", g.Viewer(), embedHandler.GetEmbedChannel) @@ -1220,14 +1253,14 @@ func RegisterIMRoutes(r *gin.Engine, imHandler *handler.IMHandler) { // (which can hijack a personal WeChat session) is Admin+. func RegisterIMChannelRoutes(r *gin.RouterGroup, imHandler *handler.IMHandler, g *rbacGuards) { // Channel CRUD under agents - agentChannels := r.Group("/agents/:id/im-channels", g.APIKeyAdmin()) + agentChannels := g.apiKeyGroup(r.Group("/agents/:id/im-channels"), apiKeyOwner()) { agentChannels.POST("", g.Admin(), imHandler.CreateIMChannel) agentChannels.GET("", g.Viewer(), imHandler.ListIMChannels) } // Channel operations by channel ID - channels := r.Group("/im-channels", g.APIKeyAdmin()) + channels := g.apiKeyGroup(r.Group("/im-channels"), apiKeyOwner()) { channels.GET("", g.Viewer(), imHandler.ListAllIMChannels) channels.PUT("/:id", g.Admin(), imHandler.UpdateIMChannel) @@ -1237,7 +1270,7 @@ func RegisterIMChannelRoutes(r *gin.RouterGroup, imHandler *handler.IMHandler, g // WeChat QR code login (requires authentication) — Admin+: a successful // scan binds a personal WeChat account to the tenant. - wechatGroup := r.Group("/wechat", g.APIKeyAdmin()) + wechatGroup := g.apiKeyGroup(r.Group("/wechat"), apiKeyOwner()) { wechatGroup.POST("/qrcode", g.Admin(), imHandler.WeChatGetQRCode) wechatGroup.POST("/qrcode/status", g.Admin(), imHandler.WeChatPollQRCodeStatus) @@ -1428,6 +1461,17 @@ func newFileServeHandler(globalFileService interfaces.FileService) gin.HandlerFu return } + // /files is registered on the engine root, outside the /api/v1 + // API-key gate. A KB-restricted API key must not fetch arbitrary + // tenant files: a raw storage path cannot be attributed to the + // key's KB allow-list, so serving it would bypass the KB scope. + if scope, ok := types.TenantAPIKeyScopeFromContext(c.Request.Context()); ok && scope.IsKnowledgeBaseRestricted() { + logger.Warnf(context.Background(), + "[Router] /files denied KB-restricted API key: tenant_id=%d file_path=%q", tenant.ID, filePath) + c.JSON(http.StatusForbidden, gin.H{"error": "forbidden: API key scope does not allow file access"}) + return + } + if err := secutils.ValidateStoragePathTenant(filePath, tenant.ID); err != nil { logger.Warnf(context.Background(), "[Router] /files denied cross-tenant or invalid path: tenant_id=%d file_path=%q err=%v", tenant.ID, filePath, err) c.JSON(http.StatusForbidden, gin.H{"error": "forbidden: file path not accessible"}) @@ -1697,7 +1741,7 @@ func RegisterDataSourceRoutes( g *rbacGuards, ) { // Data source routes - ds := r.Group("/datasource", g.APIKeyAdmin()) + ds := g.apiKeyGroup(r.Group("/datasource"), apiKeyOwner()) { // Get available connector types — Viewer+ ds.GET("/types", g.Viewer(), handler.GetAvailableConnectors) @@ -1739,8 +1783,8 @@ func RegisterDataSourceRoutes( // management endpoints. SaveCredentials persists external SaaS keys // for the tenant (Admin+), Status is a low-risk readiness probe (Viewer+). func RegisterWeKnoraCloudRoutes(r *gin.RouterGroup, handler *handler.WeKnoraCloudHandler, g *rbacGuards) { - r.POST("/weknoracloud/credentials", g.Admin(), g.APIKeyAdmin(), handler.SaveCredentials) - r.GET("/models/weknoracloud/status", g.Viewer(), handler.Status) + g.apiKeyRoute(r, http.MethodPost, "/weknoracloud/credentials", apiKeyOwner(), g.Admin(), handler.SaveCredentials) + g.apiKeyRoute(r, http.MethodGet, "/models/weknoracloud/status", apiKeyOwner(), g.Viewer(), handler.Status) } // RegisterWikiPageRoutes registers wiki page related routes. @@ -1753,7 +1797,7 @@ func RegisterWeKnoraCloudRoutes(r *gin.RouterGroup, handler *handler.WeKnoraClou // :kb_id resolves directly to the owning KB so a Contributor who owns // the KB can manage its wiki, while a non-owner Contributor gets 403. func RegisterWikiPageRoutes(r *gin.RouterGroup, wikiHandler *handler.WikiPageHandler, g *rbacGuards) { - wiki := r.Group("/knowledgebase/:kb_id/wiki", g.APIKeyContributor()) + wiki := g.apiKeyGroup(r.Group("/knowledgebase/:kb_id/wiki"), apiKeyContributor()) { // Page CRUD wiki.GET("/pages", g.Viewer(), g.KBAccessRead("kb_id"), wikiHandler.ListPages) diff --git a/internal/types/interfaces/tenant.go b/internal/types/interfaces/tenant.go index bea5ca9c..63d6222c 100644 --- a/internal/types/interfaces/tenant.go +++ b/internal/types/interfaces/tenant.go @@ -85,6 +85,10 @@ type TenantAPIKeyRepository interface { RevokeAllAPIKeys(ctx context.Context, tenantID uint64) error UpdateAPIKeyHash(ctx context.Context, id uint64, hash string) error UpdateAPIKeyLastUsed(ctx context.Context, id uint64, at time.Time) error + // ListKeysWithPlaceholderHash returns keys whose key_hash is still the + // migration placeholder (never authenticated since the 000065 upgrade), + // so the real SHA-256 hash can be computed and backfilled. + ListKeysWithPlaceholderHash(ctx context.Context) ([]*types.TenantAPIKey, error) } type TenantAPIKeyService interface { @@ -94,4 +98,9 @@ type TenantAPIKeyService interface { ListAPIKeys(ctx context.Context, tenantID uint64) ([]*types.TenantAPIKey, error) RevokeAPIKey(ctx context.Context, tenantID uint64, id uint64) error RevokeAllAPIKeys(ctx context.Context, tenantID uint64) error + // BackfillMissingKeyHashes computes and persists the SHA-256 key_hash + // for legacy keys still carrying the migration placeholder, so their + // first authentication does not fall back to an O(n) plaintext scan. + // Returns the number of keys backfilled. + BackfillMissingKeyHashes(ctx context.Context) (int, error) } diff --git a/internal/types/tenant_api_key.go b/internal/types/tenant_api_key.go index 022bcd66..dee6cc95 100644 --- a/internal/types/tenant_api_key.go +++ b/internal/types/tenant_api_key.go @@ -35,9 +35,14 @@ func (TenantAPIKey) TableName() string { func (k *TenantAPIKey) BeforeSave(tx *gorm.DB) error { if key := utils.GetAESKey(); key != nil && k.APIKey != "" { - if encrypted, err := utils.EncryptAESGCM(k.APIKey, key); err == nil { - tx.Statement.SetColumn("api_key", encrypted) + encrypted, err := utils.EncryptAESGCM(k.APIKey, key) + if err != nil { + // Never fall through to storing the plaintext key: abort the + // write so the caller sees the failure instead of silently + // persisting an unencrypted secret. + return fmt.Errorf("encrypt tenant_api_keys.api_key (id=%d): %w", k.ID, err) } + tx.Statement.SetColumn("api_key", encrypted) } return nil } @@ -84,6 +89,8 @@ func (s TenantAPIKeyScope) Normalize() TenantAPIKeyScope { // NormalizeTenantAPIKeyRole maps stored/API role strings to tenant RBAC roles. func NormalizeTenantAPIKeyRole(role TenantRole) TenantRole { switch strings.ToLower(strings.TrimSpace(string(role))) { + case string(TenantRoleOwner): + return TenantRoleOwner case string(TenantRoleAdmin): return TenantRoleAdmin case string(TenantRoleContributor): diff --git a/internal/types/tenant_api_key_test.go b/internal/types/tenant_api_key_test.go index d15542aa..48cb5e19 100644 --- a/internal/types/tenant_api_key_test.go +++ b/internal/types/tenant_api_key_test.go @@ -18,8 +18,9 @@ func TestNormalizeTenantAPIKeyRole(t *testing.T) { {name: "viewer", in: TenantRoleViewer, want: TenantRoleViewer}, {name: "contributor", in: TenantRoleContributor, want: TenantRoleContributor}, {name: "admin", in: TenantRoleAdmin, want: TenantRoleAdmin}, + {name: "owner", in: TenantRoleOwner, want: TenantRoleOwner}, {name: "empty defaults viewer", in: "", want: TenantRoleViewer}, - {name: "invalid", in: "owner", want: ""}, + {name: "invalid", in: "superuser", want: ""}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) {