@itphx/synth-backend 0.10.1 → 0.12.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/dist/app/bootstrap.d.ts +2 -2
  2. package/dist/app/deps.d.ts +77 -33
  3. package/dist/app/deps.js +969 -102
  4. package/dist/app/listen.d.ts +13 -2
  5. package/dist/app/listen.js +138 -10
  6. package/dist/app/mount-routes.d.ts +16 -3
  7. package/dist/app/mount-routes.js +625 -32
  8. package/dist/app.d.ts +42 -7
  9. package/dist/app.js +149 -12
  10. package/dist/auth/guards.d.ts +17 -1
  11. package/dist/auth/guards.js +46 -2
  12. package/dist/auth/middleware.d.ts +2 -12
  13. package/dist/auth/middleware.js +20 -2
  14. package/dist/auth/oidc.d.ts +7 -0
  15. package/dist/auth/oidc.js +27 -6
  16. package/dist/auth/plugin-scope.d.ts +10 -0
  17. package/dist/auth/plugin-scope.js +69 -0
  18. package/dist/auth/service-scope.d.ts +7 -3
  19. package/dist/auth/service-scope.js +8 -4
  20. package/dist/events/hub.js +3 -38
  21. package/dist/lib/app-config.d.ts +2 -0
  22. package/dist/lib/app-config.js +3 -2
  23. package/dist/lib/defaults-store.d.ts +2 -25
  24. package/dist/lib/defaults-store.js +5 -87
  25. package/dist/lib/i18n.js +153 -0
  26. package/dist/main.js +67 -4
  27. package/dist/routes/agents.d.ts +12 -3
  28. package/dist/routes/agents.js +14 -2
  29. package/dist/routes/auth.d.ts +12 -2
  30. package/dist/routes/auth.js +16 -2
  31. package/dist/routes/context.d.ts +2 -2
  32. package/dist/routes/gateway-patterns.d.ts +2 -2
  33. package/dist/routes/llm.d.ts +8 -2
  34. package/dist/routes/llm.js +6 -3
  35. package/dist/routes/mcp-registry.d.ts +15 -3
  36. package/dist/routes/mcp-registry.js +122 -21
  37. package/dist/routes/messages.d.ts +7 -4
  38. package/dist/routes/messages.js +34 -3
  39. package/dist/routes/models.d.ts +7 -2
  40. package/dist/routes/models.js +3 -1
  41. package/dist/routes/processes.d.ts +34 -0
  42. package/dist/routes/processes.js +26 -0
  43. package/dist/routes/projects.d.ts +9 -3
  44. package/dist/routes/projects.js +8 -1
  45. package/dist/routes/providers.d.ts +15 -3
  46. package/dist/routes/providers.js +33 -21
  47. package/dist/routes/queue.d.ts +5 -4
  48. package/dist/routes/queue.js +30 -3
  49. package/dist/routes/sessions.d.ts +50 -3
  50. package/dist/routes/sessions.js +221 -74
  51. package/dist/test-helpers/close-server.d.ts +33 -0
  52. package/dist/test-helpers/close-server.js +50 -0
  53. package/package.json +4 -4
package/dist/app.d.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { createServer } from 'node:http';
2
2
  import { WebSocketServer } from 'ws';
3
3
  import { Hono } from 'hono';
4
- import type { EventBus, SessionManager, QueueProcessorManager, ChatOrchestrator, ProjectStore, RuntimeSettingsStore, EventRouter, RequestSessionService, EventBindingStore, EventJournalStore, EventIngress, ScheduleStore, SchedulerService, WebhookStore, WebhookService } from '@itphx/synth-core';
4
+ import { MetricsRegistry } from '@itphx/synth-core';
5
+ import type { EventBus, SessionManager, QueueProcessorManager, ChatOrchestrator, ProjectRepository, SettingsRepository, EventRouter, RequestSessionService, EventBindingRepository, EventJournalRepository, EventIngress, ScheduleRepository, SchedulerService, WebhookRepository, WebhookService, PluginRuntime, McpManager } from '@itphx/synth-core';
5
6
  import type { BackendConfig } from './lib/app-config.js';
6
7
  import type { AuthKit } from './auth/middleware.js';
7
8
  import type { EventHub } from './events/hub.js';
@@ -28,17 +29,31 @@ export interface BackendAppHandle {
28
29
  eventBus: EventBus;
29
30
  eventHub: EventHub;
30
31
  sessionManager: SessionManager;
31
- projectStore: ProjectStore;
32
+ projectStore: ProjectRepository;
32
33
  orchestrator: ChatOrchestrator;
33
34
  queueManager: QueueProcessorManager;
34
- settingsStore: RuntimeSettingsStore;
35
+ settingsStore: SettingsRepository;
36
+ /** ADR-094: реестр метрик (HTTP/процесс и доменные коллекторы). */
37
+ metrics: MetricsRegistry;
38
+ /** ADR-094: остановка процессных метрик и фоновых доменных коллекторов на shutdown. */
39
+ stopMetrics: () => void;
35
40
  eventRouter: EventRouter;
36
41
  requestSessionService: RequestSessionService;
37
- eventBindingStore: EventBindingStore;
38
- eventJournal: EventJournalStore;
42
+ eventBindingStore: EventBindingRepository;
43
+ eventJournal: EventJournalRepository;
39
44
  /** ADR-089: ingress-точка приёма внешних событий. */
40
45
  ingress: EventIngress;
41
- scheduleStore: ScheduleStore;
46
+ /**
47
+ * ADR-090 (Ф5б-1): рантайм плагинов — старт-активация установленного
48
+ * (`main.ts`) и точки для HTTP API/CLI (Ф5б-2/3).
49
+ */
50
+ pluginRuntime: PluginRuntime;
51
+ /**
52
+ * ADR-071 §2.5: менеджер MCP. Конфиг серверов приходит из единого реестра
53
+ * (в т.ч. после привязки внешнего доступа к коннектору, ADR-105 Ф4).
54
+ */
55
+ mcpManager: McpManager;
56
+ scheduleStore: ScheduleRepository;
42
57
  scheduler: SchedulerService;
43
58
  /** ADR-051 (срез): остановка планировщика (на graceful shutdown). */
44
59
  stopScheduler: () => void;
@@ -46,14 +61,34 @@ export interface BackendAppHandle {
46
61
  stopEphemeralSweeper: () => void;
47
62
  /** ADR-089: остановка периодической retention-очистки журнала событий. */
48
63
  stopEventJournalPruner: () => void;
64
+ /** ADR-102: остановка retention-очистки суточных роллапов аналитики. */
65
+ stopAnalyticsRollupPruner: () => void;
66
+ /**
67
+ * Этап 1 roadmap 0.13 (блок 3): остановка retention-очистки вопросов и
68
+ * освобождение ожиданий ответа.
69
+ */
70
+ stopQuestionPruner: () => void;
71
+ /**
72
+ * Этап 1 roadmap 0.13 (блок 4): остановка retention-очистки реестра фоновых
73
+ * прогонов (PROP-096).
74
+ */
75
+ stopBackgroundRunPruner: () => void;
76
+ /**
77
+ * PROP-097 (блок 5b): остановка retention-очистки логов фоновых процессов.
78
+ */
79
+ stopProcessLogPruner: () => void;
80
+ /** ADR-115: остановка GC осиротевших вложений сообщений. */
81
+ stopAttachmentPruner: () => void;
49
82
  /** ADR-052 (этап II): реестр подписок webhooks (для тестов/диагностики). */
50
- webhookStore: WebhookStore;
83
+ webhookStore: WebhookRepository;
51
84
  /** ADR-052 (этап II): движок исходящих webhooks. */
52
85
  webhookService: WebhookService;
53
86
  /** ADR-052 (этап II): остановка движка webhooks (на graceful shutdown). */
54
87
  stopWebhookService: () => void;
55
88
  /** ADR-052 (этап II): остановка retention-очистки журнала доставок. */
56
89
  stopWebhookDeliveryPruner: () => void;
90
+ /** Egress: остановка retention-очистки журнала внешних запросов. */
91
+ stopEgressLogPruner: () => void;
57
92
  /**
58
93
  * Поднять HTTP-сервер (+ WebSocket /ws/events) на указанном порту.
59
94
  * Порт 0 → эфемерный; возвращает фактический порт.
package/dist/app.js CHANGED
@@ -17,14 +17,16 @@ import { Hono } from 'hono';
17
17
  import { cors } from 'hono/cors';
18
18
  import { logger } from 'hono/logger';
19
19
  import { createMiddleware } from 'hono/factory';
20
- import { nowISO, SYNTH_VERSION } from '@itphx/synth-shared';
21
- import { ServiceApiKeyStore, applyBootstrapServiceKeys, KeyRateLimiter, getServiceCredential, } from '@itphx/synth-core';
20
+ import { applyBootstrapServiceKeys, checkExecutionMode, createHealthRoutes, createHttpMetricsMiddleware, createMetricsRoutes, KeyRateLimiter, getServiceCredential, MetricsRegistry, registerProcessMetrics, resolveMetricsEnabled, resolveMetricsToken, resolvePluginServerPolicy, setSynthReady, } from '@itphx/synth-core';
21
+ import { resolveExecutionConfig } from '@itphx/synth-shared';
22
+ import { createStorageDegradedGuard, createStorageStatusRoutes } from '@itphx/synth-core/server/storage-degraded.js';
22
23
  import { loadBackendConfig } from './lib/app-config.js';
23
24
  import { resolveCorsOrigin } from './lib/cors.js';
24
25
  import { createAuthMiddleware } from './auth/middleware.js';
26
+ import { requirePluginTokenBinding } from './auth/plugin-scope.js';
25
27
  import { createAuthRoutes } from './routes/auth.js';
26
28
  import { t } from './lib/i18n.js';
27
- import { createBackendDeps } from './app/deps.js';
29
+ import { createBackendDeps, createBackendStorage } from './app/deps.js';
28
30
  import { mountBackendRoutes } from './app/mount-routes.js';
29
31
  import { createBackendListen } from './app/listen.js';
30
32
  /**
@@ -54,12 +56,58 @@ export async function createBackendApp(opts = {}) {
54
56
  try {
55
57
  // Конфигурация
56
58
  const backendConfig = await loadBackendConfig({ configPath: opts.configPath });
59
+ // ADR-077: топология исполнения — параметр запуска (инвариант 24). Fail-closed:
60
+ // неверный `mode`/`failMode` — ошибка; `remote` без адресов/пакета исполнителя/
61
+ // читаемого токена — старт прерывается, а не «молча уходит в inline».
62
+ const execution = resolveExecutionConfig(backendConfig.synth, process.env);
63
+ const executionCheck = await checkExecutionMode(execution);
64
+ if (!executionCheck.ok) {
65
+ throw new Error(executionCheck.message);
66
+ }
57
67
  const app = new Hono();
58
68
  app.use(logger());
69
+ // ADR-096 (W2.4): единый контекст хранения — собирается до `auth`, реестр
70
+ // service-key (`storage.serviceKeys`) нужен резолверу `synth_svc_…`; тот же
71
+ // инстанс переиспользует `createBackendDeps` (в т.ч. `mcpRegistry`, который
72
+ // деп сидирует instance-серверами).
73
+ // ADR-094: контекст хранения нужен до включения метрик — runtime-настройка
74
+ // `metrics.enabled` (`settings.json`/PG) применяется при старте.
75
+ const storage = await createBackendStorage(backendConfig);
76
+ // ADR-094: метрики — реестр до middleware; при `metrics.enabled=false`
77
+ // ничего не собираем, `/metrics` отдаёт 404 (middleware не ставим).
78
+ // Приоритет: env `SYNTH_METRICS_ENABLED` > runtime (`settings.json`) >
79
+ // config.yaml `metrics.enabled` > default false.
80
+ const runtimeMetrics = await storage.settings.getMetrics();
81
+ const metricsEnabled = resolveMetricsEnabled({
82
+ configEnabled: backendConfig.synth.metrics.enabled,
83
+ runtimeEnabled: runtimeMetrics.enabled,
84
+ env: process.env,
85
+ }).enabled;
86
+ const metrics = new MetricsRegistry();
87
+ const stopProcessMetrics = metricsEnabled ? registerProcessMetrics(metrics) : null;
88
+ if (metricsEnabled)
89
+ app.use('*', createHttpMetricsMiddleware(metrics));
59
90
  // CORS настраивается после загрузки конфига
60
- // Health (без auth)
61
- app.get('/health', (c) => c.json({ status: 'healthy', version: SYNTH_VERSION, time: nowISO() }));
62
- app.get('/api/v2/health', (c) => c.json({ status: 'healthy', version: SYNTH_VERSION, time: nowISO() }));
91
+ // Health (без auth). ADR-098 (W5): при деградации хранилища status='degraded'
92
+ // + блок storage (аддитивно к {status, version, time}). `degradedInfo`
93
+ // заполняется после сборки контекста хранения ниже (до первого запроса).
94
+ // ADR-094: `/ready` — readiness (200 и при деградации, 503 — только не готов).
95
+ const degradedInfo = storage.degraded ?? null;
96
+ let initialized = false;
97
+ app.route('/', createHealthRoutes({
98
+ getStorageDegraded: () => degradedInfo ?? null,
99
+ getReadiness: () => ({
100
+ ready: initialized,
101
+ storage: degradedInfo ? 'degraded' : 'ok',
102
+ }),
103
+ }));
104
+ // ADR-094: `/metrics` — до auth (скрейп по сети pod'а, опциональный bearer).
105
+ // Токен читается на каждый запрос — правка из UI применяется без рестарта.
106
+ app.route('/', createMetricsRoutes({
107
+ registry: metrics,
108
+ enabled: metricsEnabled,
109
+ getToken: metricsEnabled ? () => resolveMetricsToken(backendConfig.dataDir) : undefined,
110
+ }));
63
111
  // Динамический CORS origin (fail-closed): явный ORIGIN через env `SYNTH_CORS_ORIGIN`;
64
112
  // иначе явный dev-флаг `SYNTH_CORS_ALLOW_ALL=true` (отражать любой origin);
65
113
  // иначе — точное совпадение с белым списком `server.allowedOrigins`.
@@ -75,9 +123,11 @@ export async function createBackendApp(opts = {}) {
75
123
  }),
76
124
  credentials: true,
77
125
  }));
78
- // ADR-052 (этап I): реестр service-key создаётся до auth — резолвер
79
- // `synth_svc_…` нужен аутентификации (паритет с core `server/app.ts`).
80
- const serviceApiKeyStore = new ServiceApiKeyStore({ dataDir: backendConfig.dataDir });
126
+ // ADR-098 (W5): состояние деградации — для health/guard/диагностики
127
+ // (уже проставлено при сборке контекста выше).
128
+ // ADR-052 (этап I): реестр service-key — резолвер ключа `synth_svc_…`
129
+ // нужен аутентификации (паритет с core `server/app.ts`).
130
+ const serviceApiKeyStore = storage.serviceKeys;
81
131
  // ADR-052/O1: идемпотентный bootstrap installer-ключей из env/Secret
82
132
  // (best-effort — ошибка конфигурации не роняет старт, пишется в лог).
83
133
  await applyBootstrapServiceKeys(serviceApiKeyStore, backendConfig.synth.security.bootstrapServiceKeys ?? []);
@@ -120,11 +170,58 @@ export async function createBackendApp(opts = {}) {
120
170
  await next();
121
171
  }));
122
172
  // Зависимости (stores/managers/оркестратор/событийное ядро/шедулер/webhooks).
123
- const deps = await createBackendDeps(backendConfig);
173
+ // Тот же контекст хранения, что собран до `auth`. ADR-094: реестр передаётся
174
+ // только при `metrics.enabled` — иначе доменные коллекторы не подключаются.
175
+ const deps = await createBackendDeps(backendConfig, storage, metricsEnabled ? metrics : undefined, execution);
124
176
  // Auth routes (после profilesStore)
125
- app.route('/auth', createAuthRoutes(auth, backendConfig.auth, deps.profilesStore, deps.dataDir, deps.defaultsStore));
177
+ app.route('/auth', createAuthRoutes(auth, backendConfig.auth, deps.profilesStore, deps.dataDir, deps.defaultsStore,
178
+ // ADR-090 Ф7: сигнал о серверной политике плагинов для публичного
179
+ // дискавери (`/auth/oidc-meta`) — только режим и признак включения
180
+ // слоя, без списка имён.
181
+ {
182
+ enabled: deps.pluginRuntime.config.enabled,
183
+ mode: deps.pluginRuntime.config.hybrid.mode,
184
+ }));
185
+ // ADR-090 Ф7 (Уровень 2): plugin-bound service-key (`plugin_id`)
186
+ // принимается только с заголовком `X-Synth-Plugin-Id` и тем же
187
+ // значением, со scope `plugins:invoke` и — при
188
+ // `plugins.hybrid.mode='allowlist'` — с именем плагина в серверном
189
+ // allow-list. Гейт стоит на границе (после `attachUser`, где уже
190
+ // разрешён service-кредентал), поэтому правило действует на **все**
191
+ // серверные API, а не только на плагинные роуты. Fail-closed: ключ с
192
+ // привязкой без корректного заголовка отвергается всегда.
193
+ app.use('/api/v2/*', requirePluginTokenBinding(() => resolvePluginServerPolicy(deps.pluginRuntime.config)));
194
+ // ADR-098 (W5): деградированное хранилище — managed: доступ только роли
195
+ // ADMIN (остальным 503 STORAGE_DEGRADED), мутации — 503 STORAGE_DEGRADED_READONLY
196
+ // (кроме ремонтных операций maintenance). Guard — после auth-роутов (логин/health
197
+ // не блокируются) и до admin-роутов.
198
+ app.use('/api/*', createStorageDegradedGuard({
199
+ getDegraded: () => degradedInfo,
200
+ isAdmin: (c) => {
201
+ const user = c.get('user');
202
+ return Array.isArray(user?.roles) && user.roles.includes('ADMIN');
203
+ },
204
+ mutationAllowlist: ['/api/v2/maintenance'],
205
+ }));
206
+ // ADR-098 (W5): диагностика деградации (проверка соединения + «нужен рестарт»).
207
+ app.route('/', createStorageStatusRoutes({ getDegraded: () => degradedInfo }));
126
208
  // Роуты API v2 (порядок монтирования — как раньше, см. mount-routes.ts).
127
- mountBackendRoutes(app, auth, { config: backendConfig, deps, serviceApiKeyStore });
209
+ mountBackendRoutes(app, auth, {
210
+ config: backendConfig,
211
+ deps,
212
+ // ADR-094: админ-раздел «Наблюдаемость» — running-флаг, реестр,
213
+ // readiness, backend хранения и uptime.
214
+ metrics: {
215
+ runningEnabled: metricsEnabled,
216
+ getRegistry: () => metrics,
217
+ getReadiness: () => ({
218
+ ready: initialized,
219
+ storage: degradedInfo ? 'degraded' : 'ok',
220
+ }),
221
+ storageBackend: storage.kind,
222
+ getUptimeSec: () => Math.floor(process.uptime()),
223
+ },
224
+ });
128
225
  // 404
129
226
  app.notFound((c) => {
130
227
  return c.json({
@@ -146,7 +243,16 @@ export async function createBackendApp(opts = {}) {
146
243
  processMessage: deps.processMessage,
147
244
  orchestrator: deps.orchestrator,
148
245
  defaultPort: backendConfig.port,
246
+ // ADR-106 Ф3: реестр подтверждений — ответ на `permission_reply`
247
+ // принимает только носитель покрывающего гранта (не «кто видит сессию»).
248
+ approvalRegistry: deps.approvalRegistry,
249
+ // ADR-094: активные WS-соединения — в streams_active (если метрики включены).
250
+ metrics: metricsEnabled ? metrics : undefined,
149
251
  });
252
+ // Композиция завершена — readiness переключается в ready (ADR-094).
253
+ initialized = true;
254
+ if (metricsEnabled)
255
+ setSynthReady(metrics, 1);
150
256
  return {
151
257
  app,
152
258
  dataDir: deps.dataDir,
@@ -160,23 +266,54 @@ export async function createBackendApp(opts = {}) {
160
266
  orchestrator: deps.orchestrator,
161
267
  queueManager: deps.queueManager,
162
268
  settingsStore: deps.settingsStore,
269
+ // ADR-094: реестр метрик и остановка процессных **и** доменных коллекторов
270
+ // (таймеры сессий/хранилища, подписка шины, decision/journal).
271
+ metrics,
272
+ stopMetrics: () => {
273
+ stopProcessMetrics?.stop();
274
+ for (const stop of deps.stopMetricsCollectors) {
275
+ try {
276
+ stop();
277
+ }
278
+ catch {
279
+ // Остановка метрик не должна ломать shutdown.
280
+ }
281
+ }
282
+ },
163
283
  // ADR-089: ядро событий (понадобится на этапах 5–6).
164
284
  eventRouter: deps.eventRouter,
165
285
  requestSessionService: deps.requestSessionService,
166
286
  eventBindingStore: deps.eventBindingStore,
167
287
  eventJournal: deps.eventJournal,
168
288
  ingress: deps.eventIngress,
289
+ // ADR-090 (Ф5б-1): рантайм плагинов — старт-активация в `main.ts`
290
+ // и точки для HTTP API/CLI (Ф5б-2/3).
291
+ pluginRuntime: deps.pluginRuntime,
292
+ mcpManager: deps.mcpManager,
169
293
  // ADR-051 (срез) / ADR-089: реестр расписаний и планировщик.
170
294
  scheduleStore: deps.scheduleStore,
171
295
  scheduler: deps.schedulerService,
172
296
  stopScheduler: () => deps.schedulerService.stop(),
173
297
  stopEphemeralSweeper: deps.stopEphemeralSweeper,
174
298
  stopEventJournalPruner: deps.stopEventJournalPruner,
299
+ stopAnalyticsRollupPruner: deps.stopAnalyticsRollupPruner,
300
+ // Этап 1 roadmap 0.13 (блок 3): retention-очистка вопросов + ожидания.
301
+ stopQuestionPruner: () => {
302
+ deps.stopQuestionPruner();
303
+ deps.questionService?.dispose();
304
+ },
305
+ // Этап 1 roadmap 0.13 (блок 4): retention-очистка реестра фоновых прогонов.
306
+ stopBackgroundRunPruner: () => deps.stopBackgroundRunPruner(),
307
+ // PROP-097 (блок 5b): retention-очистка логов фоновых процессов.
308
+ stopProcessLogPruner: () => deps.stopProcessLogPruner(),
309
+ // ADR-115: GC осиротевших вложений сообщений.
310
+ stopAttachmentPruner: () => deps.stopAttachmentPruner(),
175
311
  // ADR-052 (этап II): реестр подписок и движок webhooks + остановка на shutdown.
176
312
  webhookStore: deps.webhookStore,
177
313
  webhookService: deps.webhookService,
178
314
  stopWebhookService: () => deps.webhookService.stop(),
179
315
  stopWebhookDeliveryPruner: () => deps.stopWebhookDeliveryPruner(),
316
+ stopEgressLogPruner: () => deps.stopEgressLogPruner(),
180
317
  listen,
181
318
  };
182
319
  }
@@ -3,13 +3,29 @@
3
3
  * - запрос с service-key → требуется хотя бы один из `scopes`
4
4
  * (`403 SCOPE_REQUIRED` иначе);
5
5
  * - интерактивные креды (cookie/debug/OIDC/API-key/локальный ключ) → требуем
6
- * роль ADMIN (`403 FORBIDDEN` иначе) — прежнее поведение этих роутов.
6
+ * роль ADMIN: нет аутентификации → `401 UNAUTHORIZED`, аутентифицирован без
7
+ * роли → `403 FORBIDDEN` (семантика HTTP; раньше оба случая склеивались в 403).
7
8
  *
8
9
  * Требует уже отработавшего `attachUser`/`requireAuth` (пользователь/ключ в
9
10
  * контексте). Используется на мутациях реестра MCP (`/servers*`), записи
10
11
  * скиллов и чтении пользователей.
11
12
  */
12
13
  export declare function requireAdminOrScope(...scopes: string[]): import("hono").MiddlewareHandler<any, string, {}, Response>;
14
+ /**
15
+ * Guard «scope **или** роль ADMIN»:
16
+ * - service-key → проходит, если у него есть хотя бы один из `scopes`
17
+ * (`403 SCOPE_REQUIRED` иначе) **или** среди выданных ролей есть `ADMIN`
18
+ * (роль ключа — явное решение администратора, и до введения зонтичных
19
+ * scope'ов именно она давала доступ к таким операциям);
20
+ * - интерактивные креды (cookie/debug/OIDC/API-key/локальный ключ) → требуем
21
+ * роль ADMIN: нет аутентификации → `401 UNAUTHORIZED`, аутентифицирован без
22
+ * роли → `403 FORBIDDEN` (семантика HTTP; раньше оба случая склеивались в 403).
23
+ *
24
+ * Отличие от `requireAdminOrScope`: там для service-key проверяются **только**
25
+ * scope'ы (роль ADMIN ключа не учитывается) — здесь учитывается, чтобы
26
+ * зонтичный scope не отбирал права у ключей с ролью ADMIN.
27
+ */
28
+ export declare function requireAdminRoleOrScope(...scopes: string[]): import("hono").MiddlewareHandler<any, string, {}, Response>;
13
29
  /**
14
30
  * Guard «service-key → scope»: для service-key требует хотя бы один из `scopes`;
15
31
  * интерактивные креды пропускает без изменений (их гейтит `requireAuth`/логика
@@ -1,6 +1,7 @@
1
1
  import { createMiddleware } from 'hono/factory';
2
2
  import { getServiceCredential } from '@itphx/synth-core';
3
- import { hasServiceScope } from '@itphx/synth-shared';
3
+ import { hasAnyServiceScope, hasServiceScope } from '@itphx/synth-shared';
4
+ import { GlobalRole } from '@itphx/synth-shared/types';
4
5
  import { t } from '../lib/i18n.js';
5
6
  /**
6
7
  * ADR-052/O1: комбинированные guard'ы «ADMIN **или** scope» для эндпоинтов,
@@ -15,6 +16,10 @@ import { t } from '../lib/i18n.js';
15
16
  function scopeDenied(c) {
16
17
  return c.json({ error: { code: 'SCOPE_REQUIRED', message: t('errors.forbidden.scopeRequired', undefined, c) } }, 403);
17
18
  }
19
+ /** `true`, если пользователь аутентифицирован (в контексте есть `user`). */
20
+ function isAuthenticated(c) {
21
+ return !!c.get('user');
22
+ }
18
23
  /** `true`, если в контексте ADMIN (роли synthetic service-пользователя или человека). */
19
24
  function isAdmin(c) {
20
25
  const user = c.get('user');
@@ -25,7 +30,8 @@ function isAdmin(c) {
25
30
  * - запрос с service-key → требуется хотя бы один из `scopes`
26
31
  * (`403 SCOPE_REQUIRED` иначе);
27
32
  * - интерактивные креды (cookie/debug/OIDC/API-key/локальный ключ) → требуем
28
- * роль ADMIN (`403 FORBIDDEN` иначе) — прежнее поведение этих роутов.
33
+ * роль ADMIN: нет аутентификации → `401 UNAUTHORIZED`, аутентифицирован без
34
+ * роли → `403 FORBIDDEN` (семантика HTTP; раньше оба случая склеивались в 403).
29
35
  *
30
36
  * Требует уже отработавшего `attachUser`/`requireAuth` (пользователь/ключ в
31
37
  * контексте). Используется на мутациях реестра MCP (`/servers*`), записи
@@ -41,6 +47,44 @@ export function requireAdminOrScope(...scopes) {
41
47
  await next();
42
48
  return;
43
49
  }
50
+ if (!isAuthenticated(c)) {
51
+ return c.json({ error: { code: 'UNAUTHORIZED', message: t('auth.unauthorized', undefined, c) } }, 401);
52
+ }
53
+ if (!isAdmin(c)) {
54
+ return c.json({ error: { code: 'FORBIDDEN', message: t('auth.forbidden', undefined, c) } }, 403);
55
+ }
56
+ await next();
57
+ });
58
+ }
59
+ /**
60
+ * Guard «scope **или** роль ADMIN»:
61
+ * - service-key → проходит, если у него есть хотя бы один из `scopes`
62
+ * (`403 SCOPE_REQUIRED` иначе) **или** среди выданных ролей есть `ADMIN`
63
+ * (роль ключа — явное решение администратора, и до введения зонтичных
64
+ * scope'ов именно она давала доступ к таким операциям);
65
+ * - интерактивные креды (cookie/debug/OIDC/API-key/локальный ключ) → требуем
66
+ * роль ADMIN: нет аутентификации → `401 UNAUTHORIZED`, аутентифицирован без
67
+ * роли → `403 FORBIDDEN` (семантика HTTP; раньше оба случая склеивались в 403).
68
+ *
69
+ * Отличие от `requireAdminOrScope`: там для service-key проверяются **только**
70
+ * scope'ы (роль ADMIN ключа не учитывается) — здесь учитывается, чтобы
71
+ * зонтичный scope не отбирал права у ключей с ролью ADMIN.
72
+ */
73
+ export function requireAdminRoleOrScope(...scopes) {
74
+ return createMiddleware(async (c, next) => {
75
+ const cred = getServiceCredential(c);
76
+ if (cred) {
77
+ const hasScope = hasAnyServiceScope(cred.scopes, scopes);
78
+ const adminKey = Array.isArray(cred.roles) && cred.roles.includes(GlobalRole.ADMIN);
79
+ if (!hasScope && !adminKey) {
80
+ return scopeDenied(c);
81
+ }
82
+ await next();
83
+ return;
84
+ }
85
+ if (!isAuthenticated(c)) {
86
+ return c.json({ error: { code: 'UNAUTHORIZED', message: t('auth.unauthorized', undefined, c) } }, 401);
87
+ }
44
88
  if (!isAdmin(c)) {
45
89
  return c.json({ error: { code: 'FORBIDDEN', message: t('auth.forbidden', undefined, c) } }, 403);
46
90
  }
@@ -32,18 +32,8 @@ export declare function createAuthMiddleware(config: AuthMiddlewareConfig): {
32
32
  message: string;
33
33
  };
34
34
  }, 401, "json">)>;
35
- requireAdmin: import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
36
- error: {
37
- code: string;
38
- message: string;
39
- };
40
- }, 403, "json">)>;
41
- requirePermission: (...roles: string[]) => import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
42
- error: {
43
- code: string;
44
- message: string;
45
- };
46
- }, 403, "json">)>;
35
+ requireAdmin: import("hono").MiddlewareHandler<any, string, {}, Response>;
36
+ requirePermission: (...roles: string[]) => import("hono").MiddlewareHandler<any, string, {}, Response>;
47
37
  isAdmin: (c: {
48
38
  get(key: "user"): unknown;
49
39
  }) => boolean;
@@ -168,10 +168,25 @@ export function createAuthMiddleware(config) {
168
168
  c.set('user', user);
169
169
  await next();
170
170
  });
171
+ /**
172
+ * Семантика HTTP для ролевых guard'ов (`requireAdmin`/`requirePermission`):
173
+ * нет аутентификации → `401 UNAUTHORIZED`; аутентифицирован, но роли не хватает
174
+ * → `403 FORBIDDEN`. Возвращает готовый 401-ответ, если пользователя в контексте
175
+ * нет (иначе `null`). Раньше оба случая склеивались в 403, и анонимный запрос к
176
+ * ADMIN-роуту получал 403 вместо 401.
177
+ */
178
+ const ensureAuthenticated = (c) => {
179
+ if (c.get('user'))
180
+ return null;
181
+ return c.json({ error: { code: 'UNAUTHORIZED', message: t('auth.unauthorized', undefined, c) } }, 401);
182
+ };
171
183
  // Middleware: требовать роль ADMIN
172
184
  const requireAdmin = createMiddleware(async (c, next) => {
185
+ const unauthenticated = ensureAuthenticated(c);
186
+ if (unauthenticated)
187
+ return unauthenticated;
173
188
  const user = c.get('user');
174
- if (!user || !user.roles.includes('ADMIN')) {
189
+ if (!user.roles.includes('ADMIN')) {
175
190
  return c.json({ error: { code: 'FORBIDDEN', message: t('auth.forbidden', undefined, c) } }, 403);
176
191
  }
177
192
  await next();
@@ -193,8 +208,11 @@ export function createAuthMiddleware(config) {
193
208
  const isAdmin = (c) => hasRole(c, 'ADMIN');
194
209
  // Middleware: требовать одну из указанных ролей (например, ADMIN/AUDITOR)
195
210
  const requirePermission = (...roles) => createMiddleware(async (c, next) => {
211
+ const unauthenticated = ensureAuthenticated(c);
212
+ if (unauthenticated)
213
+ return unauthenticated;
196
214
  const user = c.get('user');
197
- if (!user || !roles.some((r) => user.roles.includes(r))) {
215
+ if (!roles.some((r) => user.roles.includes(r))) {
198
216
  return c.json({ error: { code: 'FORBIDDEN', message: t('auth.forbidden', undefined, c) } }, 403);
199
217
  }
200
218
  await next();
@@ -64,6 +64,13 @@ export declare class OidcClient {
64
64
  * Роли: из id_token, если пусто — из access_token (client roles учитываются).
65
65
  */
66
66
  verifyTokens(idToken: string, accessToken: string): Promise<OidcUser>;
67
+ /**
68
+ * ADR-099: JWKS-набор с **явным** транспортом доверия TLS/CA (`egressFetch`),
69
+ * а не через глобальный dispatcher процесса — точка не зависит от глобального
70
+ * состояния (`applyGlobalTlsTrust` остаётся основным каналом для прочих fetch).
71
+ * jose 6 отдаёт кастомный транспорт через символ `customFetch`.
72
+ */
73
+ private _remoteJwks;
67
74
  /** Допустимые `aud` id_token: clientId (+ дополнительные из конфига). */
68
75
  private _idTokenAudience;
69
76
  /** Допустимые `aud` access_token: clientId ИЛИ `account` (+ дополнительные). */
package/dist/auth/oidc.js CHANGED
@@ -1,4 +1,6 @@
1
- import { jwtVerify, createRemoteJWKSet } from 'jose';
1
+ import { jwtVerify, createRemoteJWKSet, customFetch } from 'jose';
2
+ // ADR-099: дискавери/токен-эндпоинты/JWKS OIDC — через единый транспорт доверия TLS/CA.
3
+ import { egressFetch } from '@itphx/synth-core';
2
4
  /** Audience access_token по умолчанию (Keycloak): клиент либо `account`. */
3
5
  const DEFAULT_ACCESS_TOKEN_AUDIENCE = 'account';
4
6
  /** Известные роли Synth (в realm роли записаны в нижнем регистре). */
@@ -20,7 +22,8 @@ export class OidcClient {
20
22
  if (this._discovery)
21
23
  return this._discovery;
22
24
  const url = `${this.config.issuer}/.well-known/openid-configuration`;
23
- const res = await fetch(url);
25
+ // ADR-099: дискавери — через единый транспорт доверия TLS/CA.
26
+ const res = await egressFetch(url);
24
27
  if (!res.ok) {
25
28
  throw new Error(`OIDC discovery failed: ${res.status} ${url}`);
26
29
  }
@@ -57,7 +60,8 @@ export class OidcClient {
57
60
  client_id: this.config.clientId,
58
61
  client_secret: this.config.clientSecret,
59
62
  });
60
- const res = await fetch(discovery.token_endpoint, {
63
+ // ADR-099: обмен кода на токены — через единый транспорт доверия TLS/CA.
64
+ const res = await egressFetch(discovery.token_endpoint, {
61
65
  method: 'POST',
62
66
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
63
67
  body: body.toString(),
@@ -85,7 +89,8 @@ export class OidcClient {
85
89
  password,
86
90
  scope: 'openid',
87
91
  });
88
- const res = await fetch(discovery.token_endpoint, {
92
+ // ADR-099: ROPC-вход — через единый транспорт доверия TLS/CA.
93
+ const res = await egressFetch(discovery.token_endpoint, {
89
94
  method: 'POST',
90
95
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
91
96
  body: body.toString(),
@@ -107,7 +112,7 @@ export class OidcClient {
107
112
  */
108
113
  async verifyToken(token) {
109
114
  const discovery = await this.getDiscovery();
110
- const jwks = createRemoteJWKSet(new URL(discovery.jwks_uri));
115
+ const jwks = this._remoteJwks(discovery.jwks_uri);
111
116
  // Тип bearer-токена заранее неизвестен (id_token или access_token), поэтому
112
117
  // принимаем audience обоих классов: clientId (id_token) и clientId/`account`
113
118
  // (access_token Keycloak). Issuer проверяется всегда.
@@ -123,7 +128,7 @@ export class OidcClient {
123
128
  */
124
129
  async verifyTokens(idToken, accessToken) {
125
130
  const discovery = await this.getDiscovery();
126
- const jwks = createRemoteJWKSet(new URL(discovery.jwks_uri));
131
+ const jwks = this._remoteJwks(discovery.jwks_uri);
127
132
  const { payload: idPayload } = await jwtVerify(idToken, jwks, {
128
133
  issuer: this.config.issuer,
129
134
  // id_token.aud = clientId (+ доп. из конфига).
@@ -139,6 +144,22 @@ export class OidcClient {
139
144
  });
140
145
  return extractUserFromTokens(idPayload, accessPayload, this.config.clientId);
141
146
  }
147
+ /**
148
+ * ADR-099: JWKS-набор с **явным** транспортом доверия TLS/CA (`egressFetch`),
149
+ * а не через глобальный dispatcher процесса — точка не зависит от глобального
150
+ * состояния (`applyGlobalTlsTrust` остаётся основным каналом для прочих fetch).
151
+ * jose 6 отдаёт кастомный транспорт через символ `customFetch`.
152
+ */
153
+ _remoteJwks(jwksUri) {
154
+ return createRemoteJWKSet(new URL(jwksUri), {
155
+ [customFetch]: (url, options) => egressFetch(url, {
156
+ headers: options.headers,
157
+ method: options.method,
158
+ redirect: options.redirect,
159
+ signal: options.signal,
160
+ }),
161
+ });
162
+ }
142
163
  /** Допустимые `aud` id_token: clientId (+ дополнительные из конфига). */
143
164
  _idTokenAudience() {
144
165
  return [...new Set([this.config.clientId, ...(this.config.audience ?? [])])].filter(Boolean);
@@ -0,0 +1,10 @@
1
+ import type { PluginServerPolicy } from '@itphx/synth-shared';
2
+ /**
3
+ * Guard plugin-bound токена (Ф7): монтируется **после** резолва
4
+ * service-кредентал и **до** роутов, поэтому правило действует на все
5
+ * серверные API, а не только на плагинные.
6
+ *
7
+ * `getPolicy` — живой серверный allow-list (`plugins.hybrid`); политика
8
+ * меняется рестартом (инвариант 24), поэтому берётся из работающего рантайма.
9
+ */
10
+ export declare function requirePluginTokenBinding(getPolicy: () => PluginServerPolicy | undefined): import("hono").MiddlewareHandler<any, string, {}, Response>;