fix: harden API principal config after review

Add require_direct_header toggle, external user ID validation, JWT TTL
limits, SaveToken error handling, ru-RU i18n, API docs, and Go SDK methods.
This commit is contained in:
wizardchen
2026-06-30 10:54:00 +08:00
committed by lyingbug
parent cb99736d72
commit 97bca74a31
17 changed files with 1212 additions and 14 deletions
+2
View File
@@ -23,6 +23,7 @@ export interface APIPrincipalConfig {
mode: APIPrincipalMode
direct_header_name: string
signed_token_header_name: string
require_direct_header: boolean
has_hmac_secret: boolean
}
@@ -30,6 +31,7 @@ export interface UpdateAPIPrincipalConfigPayload {
mode: APIPrincipalMode
direct_header_name?: string
signed_token_header_name?: string
require_direct_header?: boolean
hmac_secret?: string
}
+2
View File
@@ -5763,6 +5763,8 @@ export default {
directWarning: 'Direct user ID trusts the caller-supplied header. Use only for trusted server-to-server calls.',
signedRecommended: 'Recommended for user-facing apps: your backend signs a short-lived HS256 JWT for the external user.',
directHeader: 'User ID header',
requireDirectHeader: 'Require user ID header',
requireDirectHeaderDesc: 'When enabled, API Key requests without the user ID header are rejected; when disabled they fall back to the tenant principal.',
tokenHeader: 'Token header',
hmacSecret: 'HMAC secret',
secretConfigured: 'Secret configured; enter a new value to rotate',
+2
View File
@@ -5774,6 +5774,8 @@ export default {
directWarning: "직접 사용자 ID 모드는 요청 헤더를 신뢰합니다. 신뢰된 서버 간 호출에만 사용하세요.",
signedRecommended: "사용자 대상 앱에는 권장됩니다. 비즈니스 백엔드가 외부 사용자용 단기 HS256 JWT를 서명합니다.",
directHeader: "사용자 ID 헤더",
requireDirectHeader: "사용자 ID 헤더 필수",
requireDirectHeaderDesc: "켜면 사용자 ID 헤더가 없는 API Key 요청을 거부하고, 끄면 테넌트 Principal로 처리합니다.",
tokenHeader: "토큰 헤더",
hmacSecret: "HMAC secret",
secretConfigured: "Secret configured; enter a new value to rotate",
+34
View File
@@ -2358,6 +2358,8 @@ export default {
listFailed: 'Не удалось получить список тенантов',
searchFailed: 'Не удалось выполнить поиск тенантов',
resetApiKeyFailed: 'Не удалось сбросить API Key',
getApiPrincipalConfigFailed: 'Не удалось получить конфигурацию API principal',
updateApiPrincipalConfigFailed: 'Не удалось обновить конфигурацию API principal',
updateFailed: 'Не удалось обновить информацию об арендаторе'
},
initialization: {
@@ -5570,9 +5572,41 @@ export default {
tabs: {
im: 'IM-интеграция',
embed: 'Веб-встраивание',
api: 'API Key',
chrome: 'Расширение Chrome',
claw: 'Claw Skill',
},
api: {
title: 'Интеграция API Key',
subtitle: 'Используйте API Key арендатора для серверной интеграции и выберите, как передавать идентификатор конечного пользователя.',
loading: 'Загрузка настроек API-интеграции...',
retry: 'Повторить',
copy: 'Копировать',
copySuccess: 'Скопировано',
save: 'Сохранить',
baseUrl: 'Базовый URL API',
baseUrlDesc: 'Используйте с путями REST API.',
apiKey: 'API Key арендатора',
apiKeyDesc: 'API Key остаётся на уровне арендатора; идентификатор пользователя задаётся режимом ниже.',
principalMode: 'Режим идентификации пользователя',
principalModeDesc: 'Определяет, как запросы с X-API-Key сопоставляются с Principal для OAuth MCP и других per-user функций.',
modeTenant: 'Только арендатор',
modeDirect: 'Прямой ID пользователя',
modeSigned: 'Подписанный token',
directWarning: 'Прямой ID доверяет заголовку вызывающей стороны. Используйте только для доверенных server-to-server вызовов.',
signedRecommended: 'Рекомендуется для пользовательских приложений: ваш backend подписывает краткоживущий HS256 JWT для внешнего пользователя.',
directHeader: 'Заголовок ID пользователя',
requireDirectHeader: 'Требовать заголовок ID пользователя',
requireDirectHeaderDesc: 'Если включено, запросы без заголовка ID пользователя отклоняются; иначе используется Principal уровня арендатора.',
tokenHeader: 'Заголовок token',
hmacSecret: 'HMAC secret',
secretConfigured: 'Secret настроен; введите новое значение для ротации',
generateSecret: 'Сгенерировать secret',
requestExample: 'Пример запроса',
loadFailed: 'Не удалось загрузить настройки API-интеграции',
saveFailed: 'Не удалось сохранить настройки API-интеграции',
saveSuccess: 'Настройки API-интеграции сохранены',
},
manageSectionTitle: 'Настройка каналов',
manageSectionDesc: 'Выберите агента, чтобы создать или изменить каналы интеграции для него',
selectAgent: 'Выберите агента',
+2
View File
@@ -5776,6 +5776,8 @@ export default {
directWarning: "直接传用户 ID 会信任调用方请求头,仅建议用于可信服务端到服务端调用。",
signedRecommended: "推荐给面向用户的应用:业务方后端为外部用户签发短期 HS256 JWT。",
directHeader: "用户 ID 请求头",
requireDirectHeader: "必须携带用户 ID",
requireDirectHeaderDesc: "开启后,缺少用户 ID 请求头的 API Key 请求将被拒绝;关闭则回退为租户级 Principal。",
tokenHeader: "Token 请求头",
hmacSecret: "HMAC 密钥",
secretConfigured: "已配置密钥;输入新值可轮换",
@@ -75,6 +75,9 @@
<div v-if="form.mode === 'direct_header'" class="field-grid">
<label>{{ $t('integrations.api.directHeader') }}</label>
<t-input v-model="form.direct_header_name" class="mono-input" />
<label>{{ $t('integrations.api.requireDirectHeader') }}</label>
<t-switch v-model="form.require_direct_header" />
<p class="field-hint span-all">{{ $t('integrations.api.requireDirectHeaderDesc') }}</p>
</div>
<div v-if="form.mode === 'signed_token'" class="field-grid">
@@ -139,6 +142,7 @@ const form = reactive({
mode: 'tenant' as APIPrincipalMode,
direct_header_name: 'X-External-User-ID',
signed_token_header_name: 'X-External-User-Token',
require_direct_header: false,
})
const apiBaseUrl = computed(() => {
@@ -197,6 +201,7 @@ async function load() {
form.mode = cfgResp.data.mode || 'tenant'
form.direct_header_name = cfgResp.data.direct_header_name || 'X-External-User-ID'
form.signed_token_header_name = cfgResp.data.signed_token_header_name || 'X-External-User-Token'
form.require_direct_header = cfgResp.data.require_direct_header === true
secretInput.value = ''
} catch (err: any) {
error.value = err?.message || t('integrations.api.loadFailed')
@@ -219,6 +224,7 @@ async function save() {
mode: form.mode,
direct_header_name: form.direct_header_name.trim(),
signed_token_header_name: form.signed_token_header_name.trim(),
require_direct_header: form.require_direct_header,
}
if (secretInput.value.trim()) {
payload.hmac_secret = secretInput.value.trim()
@@ -324,6 +330,14 @@ onMounted(load)
color: var(--td-text-color-secondary);
font-size: 13px;
}
.field-hint.span-all {
grid-column: 1 / -1;
margin: 0;
color: var(--td-text-color-placeholder);
font-size: 12px;
line-height: 1.5;
}
}
.example-box {