@itphx/synth-backend 0.13.4 → 0.13.8

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 (45) hide show
  1. package/dist/app/deps.d.ts +8 -0
  2. package/dist/app/deps.js +126 -9
  3. package/dist/app/mount-routes.js +155 -32
  4. package/dist/app/public-routes.d.ts +2 -0
  5. package/dist/app/public-routes.js +11 -0
  6. package/dist/app.d.ts +1 -1
  7. package/dist/app.js +31 -0
  8. package/dist/auth/api-key.d.ts +19 -0
  9. package/dist/auth/api-key.js +56 -0
  10. package/dist/auth/middleware.js +7 -3
  11. package/dist/events/hub.js +4 -1
  12. package/dist/init.d.ts +1 -0
  13. package/dist/init.js +96 -0
  14. package/dist/lib/app-config.js +12 -1
  15. package/dist/lib/bind-host.d.ts +10 -0
  16. package/dist/lib/bind-host.js +32 -0
  17. package/dist/lib/i18n.js +10 -0
  18. package/dist/main.js +4 -1
  19. package/dist/middleware/rate-limiter.d.ts +4 -1
  20. package/dist/middleware/rate-limiter.js +15 -2
  21. package/dist/routes/auth.js +5 -20
  22. package/dist/routes/llm.js +65 -7
  23. package/dist/routes/mcp-remote.d.ts +23 -0
  24. package/dist/routes/mcp-remote.js +152 -0
  25. package/dist/routes/mcp.d.ts +11 -6
  26. package/dist/routes/mcp.js +35 -6
  27. package/dist/routes/projects.d.ts +1 -1
  28. package/dist/routes/projects.js +11 -2
  29. package/dist/routes/providers.d.ts +4 -1
  30. package/dist/routes/providers.js +19 -99
  31. package/dist/routes/sessions.d.ts +15 -6
  32. package/dist/routes/sessions.js +257 -183
  33. package/package.json +4 -4
  34. package/dist/routes/audit.d.ts +0 -17
  35. package/dist/routes/audit.js +0 -64
  36. package/dist/routes/context.d.ts +0 -4
  37. package/dist/routes/context.js +0 -93
  38. package/dist/routes/debug.d.ts +0 -3
  39. package/dist/routes/debug.js +0 -30
  40. package/dist/routes/gateway-patterns.d.ts +0 -9
  41. package/dist/routes/gateway-patterns.js +0 -57
  42. package/dist/routes/logs.d.ts +0 -24
  43. package/dist/routes/logs.js +0 -100
  44. package/dist/routes/mcp-registry.d.ts +0 -28
  45. package/dist/routes/mcp-registry.js +0 -483
package/dist/app.d.ts CHANGED
@@ -13,7 +13,7 @@ export interface CreateBackendAppOptions {
13
13
  dataDir?: string;
14
14
  /** Debug auth: переопределяет SYNTH_AUTH_DEBUG (тестовые ключи admin-key-123 и т.п.). */
15
15
  authDebug?: boolean;
16
- /** Единый API-ключ (роль ADMIN): переопределяет SYNTH_API_KEY. */
16
+ /** Единый API-ключ (роли из `auth.apiKeyRoles`, дефолт USER): переопределяет SYNTH_API_KEY. */
17
17
  apiKey?: string;
18
18
  /** Порт: переопределяет SYNTH_PORT. 0 — эфемерный (для тестов). */
19
19
  port?: number;
package/dist/app.js CHANGED
@@ -28,6 +28,7 @@ import { createAuthRoutes } from './routes/auth.js';
28
28
  import { t } from './lib/i18n.js';
29
29
  import { createBackendDeps, createBackendStorage } from './app/deps.js';
30
30
  import { mountBackendRoutes } from './app/mount-routes.js';
31
+ import { isPublicApiV2Path } from './app/public-routes.js';
31
32
  import { createBackendListen } from './app/listen.js';
32
33
  /**
33
34
  * Backend-приложение Synth (managed): `createBackendApp` без прослушивания порта.
@@ -94,12 +95,17 @@ export async function createBackendApp(opts = {}) {
94
95
  // ADR-094: `/ready` — readiness (200 и при деградации, 503 — только не готов).
95
96
  const degradedInfo = storage.degraded ?? null;
96
97
  let initialized = false;
98
+ // F4 (аудит S1): эффективное состояние LLM-шлюза (`deps.gatewayConfig.enabled`,
99
+ // с учётом runtime-тумблера из UI) — для предупреждения в `/health`/`/ready`.
100
+ // deps создаются ниже: геттер ленивый (до сборки — поля нет).
101
+ let depsRef = null;
97
102
  app.route('/', createHealthRoutes({
98
103
  getStorageDegraded: () => degradedInfo ?? null,
99
104
  getReadiness: () => ({
100
105
  ready: initialized,
101
106
  storage: degradedInfo ? 'degraded' : 'ok',
102
107
  }),
108
+ getLlmGatewayState: () => depsRef ? (depsRef.gatewayConfig?.enabled ? 'enabled' : 'disabled') : null,
103
109
  }));
104
110
  // ADR-094: `/metrics` — до auth (скрейп по сети pod'а, опциональный bearer).
105
111
  // Токен читается на каждый запрос — правка из UI применяется без рестарта.
@@ -173,6 +179,9 @@ export async function createBackendApp(opts = {}) {
173
179
  // Тот же контекст хранения, что собран до `auth`. ADR-094: реестр передаётся
174
180
  // только при `metrics.enabled` — иначе доменные коллекторы не подключаются.
175
181
  const deps = await createBackendDeps(backendConfig, storage, metricsEnabled ? metrics : undefined, execution);
182
+ // F4 (аудит S1): health-геттер состояния LLM-шлюза читает эффективный конфиг
183
+ // (`deps.gatewayConfig` — config + runtime-тумблер), который готов только здесь.
184
+ depsRef = deps;
176
185
  // Auth routes (после profilesStore)
177
186
  app.route('/auth', createAuthRoutes(auth, backendConfig.auth, deps.profilesStore, deps.dataDir, deps.defaultsStore,
178
187
  // ADR-090 Ф7: сигнал о серверной политике плагинов для публичного
@@ -182,6 +191,28 @@ export async function createBackendApp(opts = {}) {
182
191
  enabled: deps.pluginRuntime.config.enabled,
183
192
  mode: deps.pluginRuntime.config.hybrid.mode,
184
193
  }));
194
+ // F6 (аудит §6.1) — единый fail-closed гейт на границе `/api/v2/*`.
195
+ //
196
+ // Роутеры создаются фабриками с `{ requireAuth }`, но сама граница
197
+ // приложения проверку не гарантировала: новый роутер, смонтированный без
198
+ // guard'а, становился анонимным (перепись маршрутов покрывала 3 роутера
199
+ // из 59). Здесь — последняя проверка для всего дерева API, кроме
200
+ // allowlist публичных путей (`app/public-routes.ts`; строго метод+путь,
201
+ // без wildcard по префиксу).
202
+ //
203
+ // Порядок важен: после `attachUser` (service-key и cookie-пользователь уже
204
+ // в контексте — `requireAuth` берёт его оттуда без повторной проверки) и
205
+ // `/auth`-роутов, до plugin-bound guard'а (он различает только
206
+ // service-key, аноним до него не доходит), guard'а деградации и
207
+ // монтирования роутов. Проверок внутри обработчиков не добавляем —
208
+ // там остаются только RBAC/область доступа (инвариант 16).
209
+ app.use('/api/v2/*', createMiddleware(async (c, next) => {
210
+ if (isPublicApiV2Path(c.req.method, c.req.path)) {
211
+ await next();
212
+ return;
213
+ }
214
+ return auth.requireAuth(c, next);
215
+ }));
185
216
  // ADR-090 Ф7 (Уровень 2): plugin-bound service-key (`plugin_id`)
186
217
  // принимается только с заголовком `X-Synth-Plugin-Id` и тем же
187
218
  // значением, со scope `plugins:invoke` и — при
@@ -0,0 +1,19 @@
1
+ import { GlobalRole } from '@itphx/synth-shared';
2
+ /** Допустимые роли для `auth.apiKeyRoles` (порядок — для текста ошибки). */
3
+ export declare const ALLOWED_API_KEY_ROLES: readonly GlobalRole[];
4
+ /** Роль по умолчанию для API-ключа: базовый пользователь, не ADMIN. */
5
+ export declare const DEFAULT_API_KEY_ROLE: GlobalRole;
6
+ /**
7
+ * Сравнить представленный ключ с ожидаемым за постоянное время.
8
+ *
9
+ * Дайджесты sha256 всегда одной длины (32 байта), поэтому `timingSafeEqual`
10
+ * не бросает на разной длине входных строк и не раскрывает её. Пустая строка
11
+ * с любой стороны → `false` (незаданный ключ не аутентифицирует никого).
12
+ */
13
+ export declare function apiKeyEquals(presented: string | null | undefined, expected: string | null | undefined): boolean;
14
+ /**
15
+ * Роли пользователя API-ключа из конфигурации: явный список либо `['USER']`.
16
+ * Неизвестная роль — ошибка конфигурации (fail-closed): молча выдать меньше
17
+ * прав нельзя (это скрытая поломка доступа), выдать больше — тем более.
18
+ */
19
+ export declare function resolveApiKeyRoles(configured: readonly string[] | undefined): GlobalRole[];
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Единый API-ключ backend (`auth.apiKey` / `SYNTH_API_KEY`).
3
+ *
4
+ * Два независимых правила (аудит F5):
5
+ * 1. Сравнение ключа — **постоянное по времени**: равные по длине sha256-дайджесты
6
+ * (`timingSafeEqual`), поэтому ни содержимое, ни длина представленного ключа
7
+ * не утекают через тайминг. Пустой конфиг/пустой заголовок → не совпадает.
8
+ * 2. Роли пользователя ключа — **только явная настройка** (`auth.apiKeyRoles`):
9
+ * дефолт `USER`; права ADMIN не выдаются по факту наличия ключа.
10
+ */
11
+ import { createHash, timingSafeEqual } from 'node:crypto';
12
+ import { GlobalRole } from '@itphx/synth-shared';
13
+ /** Допустимые роли для `auth.apiKeyRoles` (порядок — для текста ошибки). */
14
+ export const ALLOWED_API_KEY_ROLES = [
15
+ GlobalRole.ADMIN,
16
+ GlobalRole.USER,
17
+ GlobalRole.LEAD,
18
+ GlobalRole.AUDITOR,
19
+ ];
20
+ /** Роль по умолчанию для API-ключа: базовый пользователь, не ADMIN. */
21
+ export const DEFAULT_API_KEY_ROLE = GlobalRole.USER;
22
+ function digest(value) {
23
+ return createHash('sha256').update(value, 'utf8').digest();
24
+ }
25
+ /**
26
+ * Сравнить представленный ключ с ожидаемым за постоянное время.
27
+ *
28
+ * Дайджесты sha256 всегда одной длины (32 байта), поэтому `timingSafeEqual`
29
+ * не бросает на разной длине входных строк и не раскрывает её. Пустая строка
30
+ * с любой стороны → `false` (незаданный ключ не аутентифицирует никого).
31
+ */
32
+ export function apiKeyEquals(presented, expected) {
33
+ if (!presented || !expected)
34
+ return false;
35
+ return timingSafeEqual(digest(presented), digest(expected));
36
+ }
37
+ /**
38
+ * Роли пользователя API-ключа из конфигурации: явный список либо `['USER']`.
39
+ * Неизвестная роль — ошибка конфигурации (fail-closed): молча выдать меньше
40
+ * прав нельзя (это скрытая поломка доступа), выдать больше — тем более.
41
+ */
42
+ export function resolveApiKeyRoles(configured) {
43
+ if (!configured || configured.length === 0)
44
+ return [DEFAULT_API_KEY_ROLE];
45
+ const roles = [];
46
+ for (const value of configured) {
47
+ if (!ALLOWED_API_KEY_ROLES.includes(value)) {
48
+ throw new Error(`[config] auth.apiKeyRoles: неизвестная роль "${value}"; ` +
49
+ `допустимо: ${ALLOWED_API_KEY_ROLES.join(', ')}`);
50
+ }
51
+ const role = value;
52
+ if (!roles.includes(role))
53
+ roles.push(role);
54
+ }
55
+ return roles.length > 0 ? roles : [DEFAULT_API_KEY_ROLE];
56
+ }
@@ -3,6 +3,7 @@ import { createMiddleware } from 'hono/factory';
3
3
  import { getCookie, setCookie, deleteCookie } from 'hono/cookie';
4
4
  import { t } from '../lib/i18n.js';
5
5
  import { createLazyOidcClient } from './oidc.js';
6
+ import { apiKeyEquals, resolveApiKeyRoles } from './api-key.js';
6
7
  const SESSION_COOKIE = 'user_session';
7
8
  /**
8
9
  * Флаг `Secure` cookie сессии: по умолчанию `true`; локальная http-разработка
@@ -117,14 +118,17 @@ export function createAuthMiddleware(config) {
117
118
  // 4. API Key mode (продакшен без OIDC)
118
119
  if (!config.debugMode && !config.oidc?.enabled && config.apiKey) {
119
120
  const apiKey = extractBearerToken(c.req.header('Authorization'));
120
- if (apiKey === config.apiKey) {
121
+ // Постоянное по времени сравнение (аудит F5): неверный/пустой ключ → не
122
+ // аутентифицирован; роли — из явной настройки, по умолчанию USER.
123
+ if (apiKeyEquals(apiKey, config.apiKey)) {
124
+ const roles = resolveApiKeyRoles(config.apiKeyRoles);
121
125
  return {
122
126
  id: 'api',
123
127
  username: 'api',
124
- roles: ['ADMIN'],
128
+ roles,
125
129
  preferredLanguage: 'ru',
126
130
  createdAt: '',
127
- teamRole: 'ADMIN',
131
+ teamRole: roles[0] ?? 'USER',
128
132
  notes: '',
129
133
  interviewCompleted: false,
130
134
  };
@@ -90,9 +90,12 @@ export class EventHub {
90
90
  const subs = this.clientSubs.get(client);
91
91
  if (!subs || subs.has(ALL_SESSIONS_KEY))
92
92
  return;
93
+ // `userFacing`: клиент (WS/SSE) обслуживает пользователя и может ответить
94
+ // на `permission.asked`. Без флага подтверждение считалось бы «некому
95
+ // показать»: у watch-all клиентов per-session подписок нет.
93
96
  const unsub = this.eventBus.subscribeAll((event) => {
94
97
  this._deliver(client, event);
95
- });
98
+ }, { userFacing: true });
96
99
  subs.set(ALL_SESSIONS_KEY, unsub);
97
100
  }
98
101
  /**
package/dist/init.d.ts ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/init.js ADDED
@@ -0,0 +1,96 @@
1
+ // Обёртка дочернего процесса в контейнере backend (вторая ступень после
2
+ // sh-инициализатора `docker/init.sh`, см. ниже «Чего обёртка НЕ делает»).
3
+ //
4
+ // Зачем обёртка. С `CMD ["node","dist/main.js"]` приложение само становится
5
+ // PID 1 (в Docker/K8s это первый процесс, у которого нет родителя). PID 1
6
+ // обязан **пожинать** осиротевших детей (`waitpid`): иначе завершившиеся
7
+ // процессы остаются зомби, занимают слоты PID и ломают `kill(pid, 0)` —
8
+ // «процесс ещё жив» для давно мёртвого (аудит 0.13.4 §5.2: 38–42 зомби и
9
+ // падающие abort-тесты).
10
+ //
11
+ // Что делает обёртка:
12
+ // 1. запускает `node dist/main.js` (тот же `process.execPath`, тот же argv/env,
13
+ // тот же cwd) в **отдельной process group** (`detached: true`) — поэтому
14
+ // сигнал можно отправить всей группе (`kill(-pid)`), а не только шефу;
15
+ // 2. пробрасывает SIGTERM/SIGINT/SIGHUP группе дочернего процесса (Docker и
16
+ // K8s шлют сигнал только PID 1 — сама обёртка);
17
+ // 3. ждёт завершения ребёнка и выходит с **тем же кодом** — включая 75
18
+ // (graceful restart, ADR-092 п. 7 / инвариант 24) и 128+N при гибели от
19
+ // сигнала; супервизор (Docker `restart`/K8s `restartPolicy`) видит
20
+ // исходный код, а не код обёртки;
21
+ // 4. ошибка запуска/отсутствие цели — код 1 и понятная строка в stderr.
22
+ //
23
+ // Чего обёртка НЕ делает — reaping. Пожинать осиротевших детей умеет только
24
+ // PID 1, и для этого нужен `waitpid(-1)`; Node/libuv так не может: libuv ждёт
25
+ // лишь pid'ы своих child-handle'ов (`waitpid(process->pid)`), а усыновлённые
26
+ // сироты остаются зомби. Поэтому в контейнере PID 1 — sh-скрипт
27
+ // `docker/init.sh` (`synth-init`), а эта обёртка — его дочерний процесс
28
+ // (см. шапку `docker/Dockerfile.backend`).
29
+ //
30
+ // Это **не** замена graceful shutdown приложения: SIGTERM доходит до main.js,
31
+ // и тот закрывает сервер/очередь как раньше (см. `main.ts`).
32
+ //
33
+ // `SYNTH_INIT_ENTRY` переопределяет цель запуска — только для тестов и ручной
34
+ // отладки (в образе он не задаётся, дефолт — `dist/main.js` рядом с обёрткой).
35
+ import { spawn } from 'node:child_process';
36
+ import { existsSync } from 'node:fs';
37
+ import { constants } from 'node:os';
38
+ import { dirname, join, resolve } from 'node:path';
39
+ import { fileURLToPath } from 'node:url';
40
+ /** Сигналы, которые обёртка пересылает дочернему процессу (вся группа). */
41
+ const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
42
+ /**
43
+ * Код выхода по сигналу — как у оболочки: 128 + номер сигнала
44
+ * (SIGKILL → 137, SIGTERM → 143). `undefined` — сигнал неизвестен.
45
+ */
46
+ function signalExitCode(signal) {
47
+ const number = constants.signals[signal];
48
+ return typeof number === 'number' ? 128 + number : 1;
49
+ }
50
+ /** Скрипт-цель: `dist/main.js` рядом с обёрткой (или `SYNTH_INIT_ENTRY`). */
51
+ function resolveEntry() {
52
+ const override = process.env.SYNTH_INIT_ENTRY?.trim();
53
+ if (override !== undefined && override.length > 0)
54
+ return resolve(process.cwd(), override);
55
+ return join(dirname(fileURLToPath(import.meta.url)), 'main.js');
56
+ }
57
+ function main() {
58
+ const entry = resolveEntry();
59
+ if (!existsSync(entry)) {
60
+ // Внятная причина вместо стектрейса node «Cannot find module»: в образе
61
+ // цель — `dist/main.js` рядом с обёрткой, её отсутствие = битая сборка.
62
+ console.error(`[init] цель запуска не найдена: ${entry}`);
63
+ process.exit(1);
64
+ }
65
+ const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
66
+ cwd: process.cwd(),
67
+ env: process.env,
68
+ stdio: 'inherit',
69
+ // Своя process group (setsid): `kill(-pid, sig)` накрывает и потомков,
70
+ // оставшихся от дочернего процесса (`sh -c '… &'`, обёртки команд).
71
+ detached: true,
72
+ });
73
+ const forward = (signal) => {
74
+ if (child.pid === undefined)
75
+ return;
76
+ try {
77
+ process.kill(-child.pid, signal);
78
+ }
79
+ catch {
80
+ // Группы уже нет (ребёнок завершился) — нечего пересылать.
81
+ }
82
+ };
83
+ for (const signal of FORWARDED_SIGNALS) {
84
+ process.on(signal, () => forward(signal));
85
+ }
86
+ child.on('error', (err) => {
87
+ console.error(`[init] не удалось запустить ${entry}: ${err.message}`);
88
+ process.exit(1);
89
+ });
90
+ child.on('exit', (code, signal) => {
91
+ // Код ребёнка сохраняется как есть (75 — рестарт, 0 — штатный выход);
92
+ // гибель от сигнала переводится в 128+N, как в оболочке.
93
+ process.exit(code ?? (signal === null ? 1 : signalExitCode(signal)));
94
+ });
95
+ }
96
+ main();
@@ -1,4 +1,5 @@
1
1
  import { loadConfig, resolveDataDir, resolvePort, resolveWorkspacesRoot, resolveMaxUploadBytes, resolveMaxReadBytes, resolveMaxPreviewBytes } from '@itphx/synth-shared';
2
+ import { resolveApiKeyRoles } from '../auth/api-key.js';
2
3
  const envStr = (key, fallback = '') => process.env[key] || fallback;
3
4
  const envBool = (key, fallback = false) => process.env[key] ? process.env[key] === 'true' : fallback;
4
5
  const envInt = (key, fallback) => {
@@ -40,6 +41,9 @@ function buildAuthConfig(defaults) {
40
41
  return {
41
42
  debugMode,
42
43
  apiKey: envStr('SYNTH_API_KEY', defaults.apiKey ?? ''),
44
+ // Аудит F5: роли API-ключа — только явная настройка (`auth.apiKeyRoles` /
45
+ // `SYNTH_API_KEY_ROLES`), дефолт USER. Неизвестная роль — ошибка загрузки.
46
+ apiKeyRoles: resolveApiKeyRoles(defaults.apiKeyRoles),
43
47
  testUsers,
44
48
  sessionMaxAgeMinutes: envInt('SYNTH_SESSION_MAX_AGE', defaults.sessionMaxAgeMinutes),
45
49
  oidc: oidcEnabled
@@ -55,7 +59,14 @@ function buildAuthConfig(defaults) {
55
59
  };
56
60
  }
57
61
  export async function loadBackendConfig(options) {
58
- const synth = await loadConfig(options);
62
+ // F4 (аудит S1): профиль backend/managed включает LLM-шлюз по умолчанию —
63
+ // обфускация секретов, аудит каждого запроса и rate limit должны работать
64
+ // «из коробки». Явные config.yaml/env/CLI и runtime-тумблер из UI это
65
+ // перебивают (приоритет выше профиля). Standalone остаётся выключенным.
66
+ const synth = await loadConfig({
67
+ baseDefaults: { llmGateway: { enabled: true } },
68
+ ...options,
69
+ });
59
70
  const auth = buildAuthConfig(synth.auth);
60
71
  const dataDir = resolveDataDir(synth);
61
72
  const workspacesRoot = resolveWorkspacesRoot(synth);
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Признак контейнера: маркер Docker (`/.dockerenv`), окружение Kubernetes
3
+ * (`KUBERNETES_SERVICE_HOST`) либо явный `SYNTH_IN_CONTAINER` (образ/split-режим).
4
+ */
5
+ export declare function detectContainer(env?: NodeJS.ProcessEnv, dockerEnvFileExists?: (path: string) => boolean): boolean;
6
+ /**
7
+ * Итоговый bind-host: `SYNTH_HOST` > контейнер (`0.0.0.0`) > loopback.
8
+ * Пустой `SYNTH_HOST` трактуется как «не задан».
9
+ */
10
+ export declare function resolveBindHost(env: NodeJS.ProcessEnv, isContainer: boolean): string;
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Адрес прослушивания backend (аудит F5, безопасный дефолт).
3
+ *
4
+ * Вне контейнера backend по умолчанию слушает **loopback** (`127.0.0.1`):
5
+ * публикация порта наружу — только явным `SYNTH_HOST`. В контейнере/K8s
6
+ * (образ, Helm-чарт, docker-compose) — `0.0.0.0`, иначе порт не был бы доступен
7
+ * снаружи контейнера.
8
+ *
9
+ * `SYNTH_HOST` приоритетен всегда (явная настройка оператора).
10
+ */
11
+ import { existsSync } from 'node:fs';
12
+ /**
13
+ * Признак контейнера: маркер Docker (`/.dockerenv`), окружение Kubernetes
14
+ * (`KUBERNETES_SERVICE_HOST`) либо явный `SYNTH_IN_CONTAINER` (образ/split-режим).
15
+ */
16
+ export function detectContainer(env = process.env, dockerEnvFileExists = existsSync) {
17
+ if (dockerEnvFileExists('/.dockerenv'))
18
+ return true;
19
+ if (env.KUBERNETES_SERVICE_HOST)
20
+ return true;
21
+ return env.SYNTH_IN_CONTAINER === 'true' || env.SYNTH_IN_CONTAINER === '1';
22
+ }
23
+ /**
24
+ * Итоговый bind-host: `SYNTH_HOST` > контейнер (`0.0.0.0`) > loopback.
25
+ * Пустой `SYNTH_HOST` трактуется как «не задан».
26
+ */
27
+ export function resolveBindHost(env, isContainer) {
28
+ const explicit = env.SYNTH_HOST?.trim();
29
+ if (explicit)
30
+ return explicit;
31
+ return isContainer ? '0.0.0.0' : '127.0.0.1';
32
+ }
package/dist/lib/i18n.js CHANGED
@@ -29,6 +29,11 @@ const en = {
29
29
  'errors.validation.expectedFilesArray': 'expected { files: string[] }',
30
30
  'errors.validation.claimCodeRequired': 'Confirmation code is required',
31
31
  'errors.validation.invalidUsername': 'Invalid username',
32
+ // PROP-054: точечные операции плана/журнала/инвариантов проекта
33
+ 'errors.validation.invalidPlanBody': 'Invalid plan request payload',
34
+ 'errors.validation.invalidLogBody': 'Invalid project log request payload',
35
+ 'errors.validation.invalidInvariantsBody': 'Invalid project invariants payload',
36
+ 'errors.unavailable.remoteProject': 'The operation is not available for a remote project',
32
37
  // ADR-089: приём внешних событий
33
38
  'errors.validation.invalidEvent': 'Invalid event payload',
34
39
  'errors.validation.invalidBinding': 'Invalid binding payload',
@@ -197,6 +202,11 @@ const ru = {
197
202
  'errors.validation.expectedFilesArray': 'expected { files: string[] }',
198
203
  'errors.validation.claimCodeRequired': 'Укажите код подтверждения',
199
204
  'errors.validation.invalidUsername': 'Некорректное имя пользователя',
205
+ // PROP-054: точечные операции плана/журнала/инвариантов проекта
206
+ 'errors.validation.invalidPlanBody': 'Некорректное тело запроса плана',
207
+ 'errors.validation.invalidLogBody': 'Некорректное тело запроса журнала проекта',
208
+ 'errors.validation.invalidInvariantsBody': 'Некорректное тело запроса инвариантов проекта',
209
+ 'errors.unavailable.remoteProject': 'Операция недоступна для удалённого проекта',
200
210
  // ADR-089: приём внешних событий
201
211
  'errors.validation.invalidEvent': 'Некорректное тело события',
202
212
  'errors.validation.invalidBinding': 'Некорректное тело биндинга',
package/dist/main.js CHANGED
@@ -4,8 +4,11 @@
4
4
  // живёт в app.ts — это позволяет поднимать backend in-process в интеграционных
5
5
  // тестах без запуска процесса.
6
6
  import { createBackendApp } from './app.js';
7
+ import { detectContainer, resolveBindHost } from './lib/bind-host.js';
7
8
  import { configureRestart, resolveRestartMode, RESTART_EXIT_CODE, setSynthReady, } from '@itphx/synth-core';
8
- const host = process.env.SYNTH_HOST || '0.0.0.0';
9
+ // Аудит F5: вне контейнера слушаем loopback (наружу — только явным SYNTH_HOST);
10
+ // в контейнере/K8s — 0.0.0.0, иначе порт недоступен снаружи.
11
+ const host = resolveBindHost(process.env, detectContainer(process.env));
9
12
  // ADR-077: fail-closed на старте (неверный `execution.mode` или `remote` —
10
13
  // удалённый исполнитель ещё не реализован, шаг 7 плана) — с понятным текстом.
11
14
  let handle;
@@ -2,10 +2,13 @@ import type { Context } from 'hono';
2
2
  /**
3
3
  * In-memory rate limiter.
4
4
  * Ключ — Authorization header (уникален для каждого пользователя/ключа).
5
+ * `maxRequests` — число запросов в окно; может быть **геттером** — тогда порог
6
+ * вычисляется на каждый запрос (runtime-настройка без рестарта). `<= 0` —
7
+ * без ограничения (счётчик не ведётся).
5
8
  * `message` — опциональный резолвер локализованного текста (i18n); по умолчанию —
6
9
  * общий русский текст (обратная совместимость).
7
10
  */
8
- export declare function createRateLimiter(maxRequests?: number, windowMs?: number, message?: (c: Context) => string): import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
11
+ export declare function createRateLimiter(maxRequests?: number | (() => number), windowMs?: number, message?: (c: Context) => string): import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
9
12
  error: {
10
13
  code: string;
11
14
  message: string;
@@ -2,6 +2,9 @@ import { createMiddleware } from 'hono/factory';
2
2
  /**
3
3
  * In-memory rate limiter.
4
4
  * Ключ — Authorization header (уникален для каждого пользователя/ключа).
5
+ * `maxRequests` — число запросов в окно; может быть **геттером** — тогда порог
6
+ * вычисляется на каждый запрос (runtime-настройка без рестарта). `<= 0` —
7
+ * без ограничения (счётчик не ведётся).
5
8
  * `message` — опциональный резолвер локализованного текста (i18n); по умолчанию —
6
9
  * общий русский текст (обратная совместимость).
7
10
  */
@@ -13,8 +16,15 @@ export function createRateLimiter(maxRequests = 20, windowMs = 60_000, message)
13
16
  if (entry.resetAt <= now)
14
17
  hits.delete(key);
15
18
  }
16
- }, windowMs);
19
+ }, windowMs).unref?.();
17
20
  return createMiddleware(async (c, next) => {
21
+ // Порог вычисляется на каждый запрос: динамический геттер позволяет
22
+ // применять runtime-изменение из админки без пересоздания middleware.
23
+ const limit = typeof maxRequests === 'function' ? maxRequests() : maxRequests;
24
+ if (limit <= 0) {
25
+ await next();
26
+ return;
27
+ }
18
28
  const key = c.req.header('Authorization')
19
29
  || c.req.header('x-forwarded-for')
20
30
  || 'anonymous';
@@ -25,7 +35,10 @@ export function createRateLimiter(maxRequests = 20, windowMs = 60_000, message)
25
35
  hits.set(key, entry);
26
36
  }
27
37
  entry.count += 1;
28
- if (entry.count > maxRequests) {
38
+ if (entry.count > limit) {
39
+ // Аддитивный заголовок: клиенту полезно знать, когда пробовать снова.
40
+ const retryAfter = Math.max(1, Math.ceil((entry.resetAt - Date.now()) / 1000));
41
+ c.header('Retry-After', String(retryAfter));
29
42
  return c.json({ error: { code: 'RATE_LIMITED', message: message ? message(c) : 'Превышен лимит запросов' } }, 429);
30
43
  }
31
44
  await next();
@@ -4,22 +4,14 @@ import { createLazyOidcClient, oidcUserToUser } from '../auth/oidc.js';
4
4
  import { getCookie, setCookie, deleteCookie } from 'hono/cookie';
5
5
  import { t } from '../lib/i18n.js';
6
6
  import { getDefaultLang, setDefaultLang } from '../lib/i18n-config.js';
7
+ import { resolveAppearanceDefaults } from '@itphx/synth-core';
7
8
  import { readFile, writeFile, unlink } from 'node:fs/promises';
8
9
  import { join, resolve, sep } from 'node:path';
9
10
  const OIDC_STATE_COOKIE = 'oidc_state';
10
11
  // Встроенные умолчания оформления (совпадают с тем, что использует UI
11
- // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts).
12
- // `null` — «умолчание не задано»: UI берёт встроенный дефолт.
13
- const BUILT_IN_DEFAULTS = {
14
- themeMode: 'system',
15
- theme: 'synthesis',
16
- uiScaleMobile: null,
17
- uiScaleDesktop: null,
18
- chatViewMode: null,
19
- chatDensity: null,
20
- chatScaleMobile: null,
21
- chatScaleDesktop: null,
22
- };
12
+ // по умолчанию: packages/ui/src/lib/defaults.ts + uiScale.ts) живут в core —
13
+ // один источник для standalone (`GET /auth/defaults`) и managed (здесь),
14
+ // поэтому ответы сборок не расходятся (аудит F13).
23
15
  /**
24
16
  * Поля умолчаний оформления, которые принимает `PUT /defaults`.
25
17
  * Whitelist на границе: тело запроса не должно попадать в стор целиком
@@ -66,14 +58,7 @@ pluginPolicySignal) {
66
58
  return full.startsWith(avatarsRoot + sep) ? full : null;
67
59
  };
68
60
  // Сохранённые умолчания перекрывают встроенные; uiScaleMobile/uiScaleDesktop: null — умолчание не задано.
69
- const resolveDefaults = async () => {
70
- const stored = defaultsStore ? await defaultsStore.loadDefaults() : {};
71
- return {
72
- locale: getDefaultLang(),
73
- ...BUILT_IN_DEFAULTS,
74
- ...stored,
75
- };
76
- };
61
+ const resolveDefaults = async () => resolveAppearanceDefaults(defaultsStore, getDefaultLang());
77
62
  const getOidcClient = createLazyOidcClient(config.oidc);
78
63
  // GET /auth/login — редирект на Keycloak authorize endpoint
79
64
  app.get('/login', async (c) => {
@@ -73,13 +73,44 @@ function mapProviderError(err) {
73
73
  }
74
74
  return { status: 502, code: 'PROVIDER_ERROR', message };
75
75
  }
76
- /** OpenAI-формат usage из TokenUsage ядра. */
76
+ /**
77
+ * OpenAI-формат usage из TokenUsage ядра — **без потерь**.
78
+ *
79
+ * Гибридный `RemoteProvider` (`providers/remote.ts`) читает из ответа прокси
80
+ * `prompt_tokens_details.cached_tokens`, `cache_creation_input_tokens`
81
+ * (Anthropic-совместимый fallback), `completion_tokens_details.reasoning_tokens`
82
+ * и провайдерскую стоимость (`parseUsageCost`). Если прокси отдаёт только
83
+ * `prompt/completion/total_tokens`, локальная статистика в гибриде показывает
84
+ * нули по кэшу/размышлениям/стоимости — поэтому передаём всё.
85
+ *
86
+ * Детали-объекты добавляются только при заданном значении > 0: у провайдера без
87
+ * кэша/размышлений ответ остаётся прежним (`{prompt,completion,total}_tokens`).
88
+ */
77
89
  function toOpenAiUsage(usage) {
78
- return {
90
+ const result = {
79
91
  prompt_tokens: usage.inputTokens ?? 0,
80
92
  completion_tokens: usage.outputTokens ?? 0,
81
93
  total_tokens: usage.totalTokens ?? 0,
82
94
  };
95
+ // ADR-070 §2.3: cache read — та же точка, что читает RemoteProvider.
96
+ if (usage.cacheReadTokens && usage.cacheReadTokens > 0) {
97
+ result.prompt_tokens_details = { cached_tokens: usage.cacheReadTokens };
98
+ }
99
+ if (usage.reasoningTokens && usage.reasoningTokens > 0) {
100
+ result.completion_tokens_details = { reasoning_tokens: usage.reasoningTokens };
101
+ }
102
+ // Anthropic-совместимый fallback: `RemoteProvider._parseUsage` берёт
103
+ // cache write именно отсюда (в OpenAI-формате своего поля нет).
104
+ if (usage.cacheWriteTokens && usage.cacheWriteTokens > 0) {
105
+ result.cache_creation_input_tokens = usage.cacheWriteTokens;
106
+ }
107
+ // Стоимость провайдера приоритетнее каталожной цены (`parseUsageCost`).
108
+ // `0` — достоверная нулевая стоимость, поэтому проверяем само наличие.
109
+ if (usage.cost && Number.isFinite(usage.cost.amount)) {
110
+ result.cost = usage.cost.amount;
111
+ result.currency = usage.cost.currency;
112
+ }
113
+ return result;
83
114
  }
84
115
  /**
85
116
  * Конвертация OpenAI-сообщений в LLMMessage ядра. Из tool-полей заполняются
@@ -254,6 +285,11 @@ export function createLlmRoutes(kit, deps) {
254
285
  });
255
286
  return app;
256
287
  }
288
+ /**
289
+ * Интервал SSE keepalive-комментариев прокси (15 с): не даёт idle-таймаутам
290
+ * посредников закрыть поток, пока провайдер молчит (в т.ч. до первого чанка).
291
+ */
292
+ const KEEPALIVE_INTERVAL_MS = 15_000;
257
293
  /**
258
294
  * SSE-стрим в OpenAI-формате (text/event-stream).
259
295
  * Каждая строка: data: {id, object: 'chat.completion.chunk', created, model,
@@ -279,7 +315,31 @@ function streamCompletions(c, provider, messages, tools, model, transientMap, ch
279
315
  return new Response(new ReadableStream({
280
316
  async start(controller) {
281
317
  const encoder = new TextEncoder();
282
- const send = (obj) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
318
+ // `enqueue` после закрытия контроллера бросает — глушим: клиент мог
319
+ // отключиться, и это не ошибка прокси.
320
+ const enqueue = (chunk) => {
321
+ try {
322
+ controller.enqueue(chunk);
323
+ }
324
+ catch {
325
+ /* stream closed by client */
326
+ }
327
+ };
328
+ const send = (obj) => enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
329
+ // SSE keepalive-комментарии: backend отвечает 200 сразу (только
330
+ // заголовки), а провайдер может долго не прислать первый чанк. Без
331
+ // комментариев посредники рвут соединение по idle-таймауту
332
+ // (nginx `proxy_read_timeout` 300s, Traefik idle) — локальный core
333
+ // видит `fetch failed` на длинных сессиях. Комментарий не является
334
+ // `data:`-кадром и не меняет контракт потока.
335
+ const keepalive = setInterval(() => {
336
+ enqueue(encoder.encode(':\n\n'));
337
+ }, KEEPALIVE_INTERVAL_MS);
338
+ // Таймер не должен держать процесс живым после закрытия потока.
339
+ keepalive.unref?.();
340
+ // Один комментарий сразу при старте: заголовки уже отданы, и
341
+ // соединение активно до первого чанка провайдера.
342
+ enqueue(encoder.encode(':\n\n'));
283
343
  let finalUsage;
284
344
  // Накопленные tool_calls: провайдер (OpenAIProvider) отдаёт полный массив в
285
345
  // каждом content-чанке и в финальном чанке. Прокси шлёт их ОДИН раз отдельным
@@ -357,10 +417,8 @@ function streamCompletions(c, provider, messages, tools, model, transientMap, ch
357
417
  send({ error: { code: mapped.code, message: mapped.message } });
358
418
  }
359
419
  finally {
360
- try {
361
- controller.enqueue(encoder.encode('data: [DONE]\n\n'));
362
- }
363
- catch { /* client disconnected */ }
420
+ clearInterval(keepalive);
421
+ enqueue(encoder.encode('data: [DONE]\n\n'));
364
422
  try {
365
423
  controller.close();
366
424
  }