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.apiKeyAccessRole') }}
+ {{ $t('integrations.api.apiKeyAccessType') }}
+
+
+ {{ $t('integrations.api.accessTypeKnowledgeBase') }}
+ {{ $t('integrations.api.accessTypeTenantFull') }}
+
+
{{ $t('integrations.api.apiKeyAccessTypeHint') }}
+
+
+
+
+ {{ $t('integrations.api.apiKeyPermissionLevel') }}
{{ $t('integrations.api.accessRoleViewer') }}
{{ $t('integrations.api.accessRoleContributor') }}
{{ $t('integrations.api.accessRoleAdmin') }}
-
{{ $t('integrations.api.apiKeyAccessRoleHint') }}
+
+
+
{{ formatApiKeyAccessRoleLabel(apiKeyForm.role) }}
{{ apiKeyFormRoleDesc }}
-
+
{{ $t('integrations.api.apiKeyKnowledgeScope') }}
@@ -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) {