@itphx/synth-shared 0.10.0 → 0.11.3

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 (83) hide show
  1. package/dist/config/defaults.js +60 -14
  2. package/dist/config/env-overrides.d.ts +7 -4
  3. package/dist/config/env-overrides.js +46 -13
  4. package/dist/config/index.d.ts +3 -0
  5. package/dist/config/index.js +3 -0
  6. package/dist/config/loader.d.ts +2 -2
  7. package/dist/config/loader.js +23 -4
  8. package/dist/config/proxy.d.ts +415 -0
  9. package/dist/config/proxy.js +1565 -0
  10. package/dist/config/resolve.d.ts +77 -10
  11. package/dist/config/resolve.js +203 -17
  12. package/dist/config/tls-runtime.d.ts +78 -0
  13. package/dist/config/tls-runtime.js +356 -0
  14. package/dist/config/tls.d.ts +215 -0
  15. package/dist/config/tls.js +394 -0
  16. package/dist/config/types.d.ts +1820 -334
  17. package/dist/config/types.js +320 -54
  18. package/dist/i18n/index.d.ts +1 -1
  19. package/dist/i18n/index.js +18 -10
  20. package/dist/index.d.ts +11 -2
  21. package/dist/index.js +11 -2
  22. package/dist/interfaces/index.d.ts +3 -3
  23. package/dist/protocols/index.d.ts +0 -1
  24. package/dist/schemas/index.d.ts +230 -105
  25. package/dist/schemas/index.js +121 -74
  26. package/dist/skills/frontmatter.js +1 -1
  27. package/dist/types/agent.d.ts +30 -0
  28. package/dist/types/agent.js +1 -0
  29. package/dist/types/analytics.d.ts +113 -0
  30. package/dist/types/analytics.js +61 -0
  31. package/dist/types/bus-events.d.ts +7 -0
  32. package/dist/types/bus-events.js +1 -0
  33. package/dist/types/commands.d.ts +10 -10
  34. package/dist/types/commands.js +2 -2
  35. package/dist/types/decision.d.ts +16 -16
  36. package/dist/types/decision.js +4 -4
  37. package/dist/types/egress.d.ts +114 -0
  38. package/dist/types/egress.js +68 -0
  39. package/dist/types/events.d.ts +22 -23
  40. package/dist/types/fs.d.ts +55 -0
  41. package/dist/types/fs.js +27 -0
  42. package/dist/types/git.d.ts +63 -0
  43. package/dist/types/git.js +1 -0
  44. package/dist/types/hooks.d.ts +24 -4
  45. package/dist/types/index.d.ts +15 -1165
  46. package/dist/types/index.js +44 -244
  47. package/dist/types/llm.d.ts +32 -0
  48. package/dist/types/llm.js +8 -0
  49. package/dist/types/maintenance.d.ts +39 -0
  50. package/dist/types/maintenance.js +11 -0
  51. package/dist/types/mcp.d.ts +169 -0
  52. package/dist/types/mcp.js +119 -0
  53. package/dist/types/message.d.ts +63 -0
  54. package/dist/types/message.js +12 -0
  55. package/dist/types/permission.d.ts +9 -7
  56. package/dist/types/permission.js +1 -1
  57. package/dist/types/project.d.ts +134 -0
  58. package/dist/types/project.js +67 -0
  59. package/dist/types/prompt.d.ts +237 -0
  60. package/dist/types/prompt.js +15 -0
  61. package/dist/types/provider.d.ts +84 -0
  62. package/dist/types/provider.js +35 -0
  63. package/dist/types/schedules.d.ts +8 -8
  64. package/dist/types/schedules.js +1 -1
  65. package/dist/types/service-keys.d.ts +10 -10
  66. package/dist/types/service-keys.js +3 -3
  67. package/dist/types/session.d.ts +268 -0
  68. package/dist/types/session.js +13 -0
  69. package/dist/types/skills.d.ts +11 -11
  70. package/dist/types/skills.js +6 -6
  71. package/dist/types/tools.d.ts +3 -3
  72. package/dist/types/user.d.ts +113 -0
  73. package/dist/types/user.js +31 -0
  74. package/dist/types/webhooks.d.ts +6 -6
  75. package/dist/types/webhooks.js +1 -1
  76. package/dist/utils/glob.d.ts +1 -1
  77. package/dist/utils/glob.js +1 -1
  78. package/dist/utils/index.d.ts +15 -0
  79. package/dist/utils/index.js +55 -2
  80. package/dist/utils/workspace.js +1 -1
  81. package/dist/version.d.ts +1 -1
  82. package/dist/version.js +1 -1
  83. package/package.json +1 -1
@@ -1,9 +1,10 @@
1
1
  import type { SynthConfig } from './types.js';
2
2
  import type { WorkspaceOutsideRootPolicy } from '../types/index.js';
3
+ import { type PostgresSslMode } from './tls.js';
3
4
  export type DeployMode = 'user' | 'docker' | 'server' | 'dev';
4
5
  export declare function resolveDeployMode(): DeployMode;
5
6
  /**
6
- * AD-079: базовый home-каталог локального инстанса. Приоритет: явный флаг
7
+ * ADR-079: базовый home-каталог локального инстанса. Приоритет: явный флаг
7
8
  * (`explicitHome`) > env `SYNTH_HOME` > null (XDG-дефолты). Возвращает
8
9
  * абсолютный путь либо null.
9
10
  */
@@ -21,49 +22,115 @@ export declare function resolvePort(config: SynthConfig, envKey: string, configF
21
22
  export declare function resolveWorkspacesRoot(config: SynthConfig, env?: NodeJS.ProcessEnv, home?: string | null): string;
22
23
  export declare function resolveDefaultWorkspace(config: SynthConfig, env?: NodeJS.ProcessEnv, home?: string | null): string;
23
24
  /**
24
- * AD-079: путь к реестру профилей серверов. При заданном home — плоская
25
+ * ADR-079: путь к реестру профилей серверов. При заданном home — плоская
25
26
  * раскладка `<home>/profiles.json`, иначе XDG-дефолт `~/.config/synth/profiles.json`.
26
27
  */
27
28
  export declare function resolveProfilesPath(home?: string | null): string;
28
29
  /**
29
- * AD-079: путь к файлу credentials. При заданном home — плоская раскладка
30
+ * ADR-079: путь к файлу credentials. При заданном home — плоская раскладка
30
31
  * `<home>/credentials.json`, иначе XDG-дефолт `~/.config/synth/credentials.json`.
31
32
  */
32
33
  export declare function resolveCredentialsPath(home?: string | null): string;
33
34
  /**
34
- * AD-075: эффективная политика для абсолютного workspace вне `workspacesRoot`
35
+ * ADR-075: эффективная политика для абсолютного workspace вне `workspacesRoot`
35
36
  * (приоритет: env `SYNTH_WORKSPACE_OUTSIDE_ROOT` > `config.storage.workspaceOutsideRoot` > `''`).
36
37
  * `''` — политика не задана; потребитель подставляет `confirm`.
37
38
  */
38
39
  export declare function resolveWorkspaceOutsideRootPolicy(config: SynthConfig, env?: NodeJS.ProcessEnv): WorkspaceOutsideRootPolicy | '';
39
40
  /**
40
- * AD-076: мастер-ключ шифрования секретов at-rest (SSH-ключи, AES-256-GCM).
41
+ * Максимальный размер загружаемого файла (`POST /api/v2/fs/upload`), в байтах.
42
+ * Приоритет: env `SYNTH_MAX_UPLOAD_BYTES` > `config.storage.maxUploadBytes` >
43
+ * `DEFAULT_MAX_UPLOAD_BYTES` (100 МиБ). Некорректное env-значение (не число или
44
+ * вне границ `MIN_UPLOAD_BYTES`…`MAX_UPLOAD_BYTES_LIMIT`) — warn и фолбэк на
45
+ * config/дефолт (fail-soft, как остальные env-резолверы; не падаем).
46
+ */
47
+ export declare function resolveMaxUploadBytes(config: SynthConfig, env?: NodeJS.ProcessEnv): number;
48
+ /**
49
+ * PROP-032: физический backend хранения. Приоритет (ADR-023): env
50
+ * `SYNTH_STORAGE_BACKEND` > `config.storage.backend` > `'file'`.
51
+ *
52
+ * **Fail-closed**: если значение задано явно (env или config) и не входит в
53
+ * поддерживаемый набор (`file`|`memory`|`postgres`) — бросаем ошибку с внятным
54
+ * текстом (раньше был warn + тихий фоллбэк на `file`, что маскировало
55
+ * опечатку и запускало инстанс не на том backend'е).
56
+ */
57
+ export declare function resolveStorageBackend(config: SynthConfig, env?: NodeJS.ProcessEnv): StorageBackend;
58
+ /** Поддерживаемые физические backend'ы хранения (PROP-032). */
59
+ export type StorageBackend = 'file' | 'memory' | 'postgres';
60
+ /** PROP-032: эффективные параметры PostgreSQL-backend (без пароля — инвариант 13). */
61
+ export interface ResolvedPostgresConfig {
62
+ dsn?: string;
63
+ host?: string;
64
+ port?: number;
65
+ database?: string;
66
+ user?: string;
67
+ schema?: string;
68
+ /** ADR-099/PROP-032: эффективный TLS-режим (нормализованный; `verify-ca` → `verify-full`). */
69
+ sslmode?: PostgresSslMode;
70
+ /** Legacy-флаг TLS (когда `sslmode` не задан). */
71
+ ssl?: boolean;
72
+ poolMax?: number;
73
+ }
74
+ /**
75
+ * PROP-032: параметры PostgreSQL-backend. Приоритет (ADR-023): env
76
+ * (`SYNTH_POSTGRES_*`) > `config.storage.postgres`. **Пароль не включается**
77
+ * (инвариант 13) — см. `resolvePostgresPassword`. Некорректное env-значение
78
+ * (не число/булево) — warn и фолбэк на config (fail-soft, как прочие
79
+ * env-резолверы).
80
+ */
81
+ export declare function resolvePostgresConfig(config: SynthConfig, env?: NodeJS.ProcessEnv): ResolvedPostgresConfig;
82
+ /**
83
+ * PROP-032: пароль PostgreSQL. **Только** env `SYNTH_POSTGRES_PASSWORD` →
84
+ * файл `{dataDir}/secrets/postgres-password` (инвариант 13: в config.yaml
85
+ * секретов нет). Файла нет — `undefined` (решение об ошибке принимает драйвер:
86
+ * для peer/trust-аутентификации пароль не нужен). Читается только, не создаётся.
87
+ */
88
+ export declare function resolvePostgresPassword(opts: {
89
+ dataDir: string;
90
+ }, env?: NodeJS.ProcessEnv): string | undefined;
91
+ /**
92
+ * PROP-032 (W5): политика при недоступности выбранного backend —
93
+ * `fallback-file` (default) | `halt`. Читать через этот резолвер.
94
+ *
95
+ * Приоритет (ADR-023): env `SYNTH_DEGRADED_MODE` > `config.storage.degradedMode` >
96
+ * `fallback-file`. Невалидное env-значение — warn и фолбэк на config (fail-soft,
97
+ * как прочие env-резолверы storage-секции `SYNTH_STORAGE_BACKEND`/`SYNTH_POSTGRES_*`).
98
+ */
99
+ export declare function resolveDegradedMode(config: SynthConfig, env?: NodeJS.ProcessEnv): 'fallback-file' | 'halt';
100
+ /**
101
+ * PROP-032 (W5): каталог файлового фоллбека. Приоритет (ADR-023): env
102
+ * `SYNTH_STORAGE_FALLBACK_DIR` > явный `config.storage.fallbackDir` → `''`
103
+ * (эффективно `{dataDir}/fallback`).
104
+ */
105
+ export declare function resolveStorageFallbackDir(config: SynthConfig, env?: NodeJS.ProcessEnv, home?: string | null): string;
106
+ /**
107
+ * ADR-076: мастер-ключ шифрования секретов at-rest (SSH-ключи, AES-256-GCM).
41
108
  * Приоритет: env `SYNTH_SECRET_KEY` > `config.security.secretKey` > `''`
42
109
  * (пусто — core использует файл `{dataDir}/secrets/master.key`).
43
110
  */
44
111
  export declare function resolveSecretKey(config: SynthConfig, env?: NodeJS.ProcessEnv): string;
45
112
  /**
46
- * AD-069 §9.2: нейтральная сессия без проектных инструкций.
113
+ * ADR-069 §9.2: нейтральная сессия без проектных инструкций.
47
114
  * Приоритет: явный флаг CLI `--ignore-rules`/`--safe-mode` (`explicit`) >
48
115
  * env `SYNTH_IGNORE_RULES` (`1`/`true`). Значение — эффективный
49
116
  * `instructions.enabled=false`.
50
117
  */
51
118
  export declare function resolveIgnoreRules(explicit?: boolean, env?: NodeJS.ProcessEnv): boolean;
52
119
  /**
53
- * AD-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
120
+ * ADR-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
54
121
  * `config.decision.provider`.
55
122
  *
56
123
  * Примечание: тот же env применяется и общим реестром `ENV_OVERRIDES` в
57
- * `loadConfig` (AD-023, ключ `decision.provider`); резолвер сохранён для
124
+ * `loadConfig` (ADR-023, ключ `decision.provider`); резолвер сохранён для
58
125
  * потребителей, читающих конфиг не через `loadConfig`.
59
126
  */
60
127
  export declare function resolveDecisionProvider(config: SynthConfig, env?: NodeJS.ProcessEnv): string;
61
128
  /**
62
- * AD-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
129
+ * ADR-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
63
130
  * `config.decision.model`.
64
131
  *
65
132
  * См. примечание к `resolveDecisionProvider` — env дублируется реестром
66
- * `ENV_OVERRIDES` (AD-023).
133
+ * `ENV_OVERRIDES` (ADR-023).
67
134
  */
68
135
  export declare function resolveDecisionModel(config: SynthConfig, env?: NodeJS.ProcessEnv): string;
69
136
  export declare function ensureDataDir(dataDir: string): Promise<void>;
@@ -1,8 +1,10 @@
1
- import { existsSync } from 'node:fs';
1
+ import { existsSync, readFileSync } from 'node:fs';
2
2
  import { mkdir, writeFile } from 'node:fs/promises';
3
3
  import { join, resolve } from 'node:path';
4
4
  import { dump as dumpYaml } from 'js-yaml';
5
+ import { DEFAULT_MAX_UPLOAD_BYTES, MIN_UPLOAD_BYTES, MAX_UPLOAD_BYTES_LIMIT } from '../types/index.js';
5
6
  import { defaultConfig } from './defaults.js';
7
+ import { normalizePostgresSslMode } from './tls.js';
6
8
  const DATA_SUBDIRS = [
7
9
  'sessions',
8
10
  'projects',
@@ -39,7 +41,7 @@ export function resolveDeployMode() {
39
41
  return 'user';
40
42
  }
41
43
  /**
42
- * AD-079: базовый home-каталог локального инстанса. Приоритет: явный флаг
44
+ * ADR-079: базовый home-каталог локального инстанса. Приоритет: явный флаг
43
45
  * (`explicitHome`) > env `SYNTH_HOME` > null (XDG-дефолты). Возвращает
44
46
  * абсолютный путь либо null.
45
47
  */
@@ -50,7 +52,7 @@ export function resolveHome(explicitHome, env) {
50
52
  return resolve(raw);
51
53
  }
52
54
  export function resolveDataDir(config, env, home) {
53
- // AD-075: нормализуем к абсолютному пути — относительный dataDir ломает
55
+ // ADR-075: нормализуем к абсолютному пути — относительный dataDir ломает
54
56
  // containment-проверки FS (root остаётся относительным, target — абсолютным).
55
57
  const envVar = (env ?? process.env).SYNTH_DATA_DIR;
56
58
  if (envVar)
@@ -58,7 +60,7 @@ export function resolveDataDir(config, env, home) {
58
60
  if (config.storage.dataDir && config.storage.dataDir !== defaultConfig.storage.dataDir) {
59
61
  return resolve(config.storage.dataDir);
60
62
  }
61
- // AD-079: home-каталог задаёт плоскую раскладку (<home>/data) и приоритетнее
63
+ // ADR-079: home-каталог задаёт плоскую раскладку (<home>/data) и приоритетнее
62
64
  // mode-дефолтов, но ниже явных SYNTH_DATA_DIR/config.storage.dataDir.
63
65
  const h = resolveHome(home, env);
64
66
  if (h)
@@ -74,7 +76,7 @@ export function findConfigPath(home) {
74
76
  const explicit = process.env.SYNTH_CONFIG;
75
77
  if (explicit)
76
78
  return explicit;
77
- // AD-079: при заданном home конфиг — строго <home>/config.yaml (приоритетнее
79
+ // ADR-079: при заданном home конфиг — строго <home>/config.yaml (приоритетнее
78
80
  // cwd/XDG); отсутствие файла не откатывается к дефолтам.
79
81
  const h = resolveHome(home);
80
82
  if (h) {
@@ -107,7 +109,7 @@ export function findConfigPath(home) {
107
109
  }
108
110
  }
109
111
  export function defaultConfigPath(mode, home) {
110
- // AD-079: home задаёт плоскую раскладку (<home>/config.yaml) независимо от mode.
112
+ // ADR-079: home задаёт плоскую раскладку (<home>/config.yaml) независимо от mode.
111
113
  const h = resolveHome(home);
112
114
  if (h)
113
115
  return join(h, 'config.yaml');
@@ -132,9 +134,9 @@ export async function ensureConfigFile(targetPath) {
132
134
  }
133
135
  export async function ensureFirstRun(dataDirOverride, configPathOverride, home) {
134
136
  const mode = resolveDeployMode();
135
- // AD-079: home задаёт плоскую раскладку (<home>/config.yaml, <home>/data).
137
+ // ADR-079: home задаёт плоскую раскладку (<home>/config.yaml, <home>/data).
136
138
  const h = resolveHome(home);
137
- // AD-075: относительный --data-dir абсолютизируем на CLI-границе (иначе
139
+ // ADR-075: относительный --data-dir абсолютизируем на CLI-границе (иначе
138
140
  // containment-проверки FS получают относительный root и абсолютный target).
139
141
  const dataDir = resolve(dataDirOverride ?? resolveDataDir(defaultConfig, undefined, h));
140
142
  const configPath = configPathOverride ?? defaultConfigPath(mode, h);
@@ -182,7 +184,7 @@ export function resolveDefaultWorkspace(config, env, home) {
182
184
  return join(dataDir, 'workspaces', 'default');
183
185
  }
184
186
  /**
185
- * AD-079: путь к реестру профилей серверов. При заданном home — плоская
187
+ * ADR-079: путь к реестру профилей серверов. При заданном home — плоская
186
188
  * раскладка `<home>/profiles.json`, иначе XDG-дефолт `~/.config/synth/profiles.json`.
187
189
  */
188
190
  export function resolveProfilesPath(home) {
@@ -192,7 +194,7 @@ export function resolveProfilesPath(home) {
192
194
  return join(homeDir(), '.config', 'synth', 'profiles.json');
193
195
  }
194
196
  /**
195
- * AD-079: путь к файлу credentials. При заданном home — плоская раскладка
197
+ * ADR-079: путь к файлу credentials. При заданном home — плоская раскладка
196
198
  * `<home>/credentials.json`, иначе XDG-дефолт `~/.config/synth/credentials.json`.
197
199
  */
198
200
  export function resolveCredentialsPath(home) {
@@ -202,7 +204,7 @@ export function resolveCredentialsPath(home) {
202
204
  return join(homeDir(), '.config', 'synth', 'credentials.json');
203
205
  }
204
206
  /**
205
- * AD-075: эффективная политика для абсолютного workspace вне `workspacesRoot`
207
+ * ADR-075: эффективная политика для абсолютного workspace вне `workspacesRoot`
206
208
  * (приоритет: env `SYNTH_WORKSPACE_OUTSIDE_ROOT` > `config.storage.workspaceOutsideRoot` > `''`).
207
209
  * `''` — политика не задана; потребитель подставляет `confirm`.
208
210
  */
@@ -216,7 +218,191 @@ export function resolveWorkspaceOutsideRootPolicy(config, env) {
216
218
  return '';
217
219
  }
218
220
  /**
219
- * AD-076: мастер-ключ шифрования секретов at-rest (SSH-ключи, AES-256-GCM).
221
+ * Максимальный размер загружаемого файла (`POST /api/v2/fs/upload`), в байтах.
222
+ * Приоритет: env `SYNTH_MAX_UPLOAD_BYTES` > `config.storage.maxUploadBytes` >
223
+ * `DEFAULT_MAX_UPLOAD_BYTES` (100 МиБ). Некорректное env-значение (не число или
224
+ * вне границ `MIN_UPLOAD_BYTES`…`MAX_UPLOAD_BYTES_LIMIT`) — warn и фолбэк на
225
+ * config/дефолт (fail-soft, как остальные env-резолверы; не падаем).
226
+ */
227
+ export function resolveMaxUploadBytes(config, env) {
228
+ const raw = (env ?? process.env).SYNTH_MAX_UPLOAD_BYTES;
229
+ if (raw) {
230
+ const n = Number(raw);
231
+ if (Number.isFinite(n) && n >= MIN_UPLOAD_BYTES && n <= MAX_UPLOAD_BYTES_LIMIT) {
232
+ return Math.floor(n);
233
+ }
234
+ console.warn(`[config] невалидное значение SYNTH_MAX_UPLOAD_BYTES="${raw}" ` +
235
+ `(ожидается число от ${MIN_UPLOAD_BYTES} до ${MAX_UPLOAD_BYTES_LIMIT}) — игнорируется`);
236
+ }
237
+ return config.storage.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
238
+ }
239
+ /**
240
+ * PROP-032: физический backend хранения. Приоритет (ADR-023): env
241
+ * `SYNTH_STORAGE_BACKEND` > `config.storage.backend` > `'file'`.
242
+ *
243
+ * **Fail-closed**: если значение задано явно (env или config) и не входит в
244
+ * поддерживаемый набор (`file`|`memory`|`postgres`) — бросаем ошибку с внятным
245
+ * текстом (раньше был warn + тихий фоллбэк на `file`, что маскировало
246
+ * опечатку и запускало инстанс не на том backend'е).
247
+ */
248
+ export function resolveStorageBackend(config, env) {
249
+ const raw = (env ?? process.env).SYNTH_STORAGE_BACKEND;
250
+ if (raw !== undefined && raw !== '') {
251
+ if (isStorageBackend(raw))
252
+ return raw;
253
+ throw new Error(`[config] невалидное значение SYNTH_STORAGE_BACKEND="${raw}": ` +
254
+ `ожидается одно из ${STORAGE_BACKENDS.map((b) => `'${b}'`).join(', ')}`);
255
+ }
256
+ const cfg = config.storage.backend;
257
+ if (cfg !== undefined) {
258
+ if (isStorageBackend(cfg))
259
+ return cfg;
260
+ throw new Error(`[config] невалидное значение storage.backend="${String(cfg)}": ` +
261
+ `ожидается одно из ${STORAGE_BACKENDS.map((b) => `'${b}'`).join(', ')}`);
262
+ }
263
+ return 'file';
264
+ }
265
+ const STORAGE_BACKENDS = ['file', 'memory', 'postgres'];
266
+ function isStorageBackend(value) {
267
+ return typeof value === 'string' && STORAGE_BACKENDS.includes(value);
268
+ }
269
+ /**
270
+ * PROP-032: параметры PostgreSQL-backend. Приоритет (ADR-023): env
271
+ * (`SYNTH_POSTGRES_*`) > `config.storage.postgres`. **Пароль не включается**
272
+ * (инвариант 13) — см. `resolvePostgresPassword`. Некорректное env-значение
273
+ * (не число/булево) — warn и фолбэк на config (fail-soft, как прочие
274
+ * env-резолверы).
275
+ */
276
+ export function resolvePostgresConfig(config, env) {
277
+ const e = env ?? process.env;
278
+ const cfg = config.storage.postgres ?? {};
279
+ const result = {};
280
+ const pickString = (envKey, cfgValue) => {
281
+ const envValue = e[envKey];
282
+ if (envValue !== undefined && envValue !== '')
283
+ return envValue;
284
+ return cfgValue !== undefined && cfgValue !== '' ? cfgValue : undefined;
285
+ };
286
+ const dsn = pickString('SYNTH_POSTGRES_DSN', cfg.dsn);
287
+ if (dsn !== undefined)
288
+ result.dsn = dsn;
289
+ const host = pickString('SYNTH_POSTGRES_HOST', cfg.host);
290
+ if (host !== undefined)
291
+ result.host = host;
292
+ const database = pickString('SYNTH_POSTGRES_DATABASE', cfg.database);
293
+ if (database !== undefined)
294
+ result.database = database;
295
+ const user = pickString('SYNTH_POSTGRES_USER', cfg.user);
296
+ if (user !== undefined)
297
+ result.user = user;
298
+ const schema = pickString('SYNTH_POSTGRES_SCHEMA', cfg.schema);
299
+ if (schema !== undefined)
300
+ result.schema = schema;
301
+ const port = resolvePositiveIntEnv(e.SYNTH_POSTGRES_PORT, cfg.port, 'SYNTH_POSTGRES_PORT');
302
+ if (port !== undefined)
303
+ result.port = port;
304
+ const poolMax = resolvePositiveIntEnv(e.SYNTH_POSTGRES_POOL_MAX, cfg.poolMax, 'SYNTH_POSTGRES_POOL_MAX');
305
+ if (poolMax !== undefined)
306
+ result.poolMax = poolMax;
307
+ const ssl = resolveBooleanEnv(e.SYNTH_POSTGRES_SSL, cfg.ssl, 'SYNTH_POSTGRES_SSL');
308
+ if (ssl !== undefined)
309
+ result.ssl = ssl;
310
+ // ADR-099/PROP-032: sslmode (env `SYNTH_POSTGRES_SSLMODE` > config); `verify-ca`
311
+ // — алиас `verify-full` (warn). Невалидное env-значение — warn + фолбэк на
312
+ // config (fail-soft, как прочие env-резолверы).
313
+ const rawEnvSslmode = e.SYNTH_POSTGRES_SSLMODE;
314
+ let sslmode;
315
+ if (rawEnvSslmode !== undefined && rawEnvSslmode !== '') {
316
+ sslmode = normalizePostgresSslMode(rawEnvSslmode);
317
+ if (sslmode === undefined) {
318
+ console.warn(`[config] невалидное значение SYNTH_POSTGRES_SSLMODE="${rawEnvSslmode}" ` +
319
+ `(ожидается disable/require/verify-full/verify-ca) — игнорируется`);
320
+ }
321
+ }
322
+ if (sslmode === undefined && cfg.sslmode !== undefined) {
323
+ sslmode = normalizePostgresSslMode(cfg.sslmode);
324
+ }
325
+ if (sslmode !== undefined)
326
+ result.sslmode = sslmode;
327
+ return result;
328
+ }
329
+ /** Парсит положительное целое из env; невалидно → warn + фолбэк на config. */
330
+ function resolvePositiveIntEnv(rawEnv, cfgValue, envName) {
331
+ if (rawEnv !== undefined && rawEnv !== '') {
332
+ const n = Number(rawEnv);
333
+ if (Number.isFinite(n) && Number.isInteger(n) && n > 0)
334
+ return n;
335
+ console.warn(`[config] невалидное значение ${envName}="${rawEnv}" (ожидается целое > 0) — игнорируется`);
336
+ }
337
+ return cfgValue;
338
+ }
339
+ /** Парсит булево из env (`true`/`1`/`false`/`0`); невалидно → warn + фолбэк на config. */
340
+ function resolveBooleanEnv(rawEnv, cfgValue, envName) {
341
+ if (rawEnv !== undefined && rawEnv !== '') {
342
+ const v = rawEnv.toLowerCase();
343
+ if (v === 'true' || v === '1')
344
+ return true;
345
+ if (v === 'false' || v === '0')
346
+ return false;
347
+ console.warn(`[config] невалидное значение ${envName}="${rawEnv}" (ожидается true/1/false/0) — игнорируется`);
348
+ }
349
+ return cfgValue;
350
+ }
351
+ /**
352
+ * PROP-032: пароль PostgreSQL. **Только** env `SYNTH_POSTGRES_PASSWORD` →
353
+ * файл `{dataDir}/secrets/postgres-password` (инвариант 13: в config.yaml
354
+ * секретов нет). Файла нет — `undefined` (решение об ошибке принимает драйвер:
355
+ * для peer/trust-аутентификации пароль не нужен). Читается только, не создаётся.
356
+ */
357
+ export function resolvePostgresPassword(opts, env) {
358
+ const envValue = (env ?? process.env).SYNTH_POSTGRES_PASSWORD;
359
+ if (envValue)
360
+ return envValue;
361
+ const file = join(opts.dataDir, 'secrets', 'postgres-password');
362
+ if (existsSync(file)) {
363
+ const raw = readFileSync(file, 'utf-8').trim();
364
+ return raw.length > 0 ? raw : undefined;
365
+ }
366
+ return undefined;
367
+ }
368
+ /** PROP-032 (W5): допустимые политики при недоступности backend'а. */
369
+ const DEGRADED_MODES = ['fallback-file', 'halt'];
370
+ function isDegradedMode(value) {
371
+ return typeof value === 'string' && DEGRADED_MODES.includes(value);
372
+ }
373
+ /**
374
+ * PROP-032 (W5): политика при недоступности выбранного backend —
375
+ * `fallback-file` (default) | `halt`. Читать через этот резолвер.
376
+ *
377
+ * Приоритет (ADR-023): env `SYNTH_DEGRADED_MODE` > `config.storage.degradedMode` >
378
+ * `fallback-file`. Невалидное env-значение — warn и фолбэк на config (fail-soft,
379
+ * как прочие env-резолверы storage-секции `SYNTH_STORAGE_BACKEND`/`SYNTH_POSTGRES_*`).
380
+ */
381
+ export function resolveDegradedMode(config, env) {
382
+ const raw = (env ?? process.env).SYNTH_DEGRADED_MODE;
383
+ if (raw !== undefined && raw !== '') {
384
+ if (isDegradedMode(raw))
385
+ return raw;
386
+ console.warn(`[config] невалидное значение SYNTH_DEGRADED_MODE="${raw}" ` +
387
+ `(ожидается ${DEGRADED_MODES.map((m) => `'${m}'`).join(' | ')}) — игнорируется`);
388
+ }
389
+ return config.storage.degradedMode ?? 'fallback-file';
390
+ }
391
+ /**
392
+ * PROP-032 (W5): каталог файлового фоллбека. Приоритет (ADR-023): env
393
+ * `SYNTH_STORAGE_FALLBACK_DIR` > явный `config.storage.fallbackDir` → `''`
394
+ * (эффективно `{dataDir}/fallback`).
395
+ */
396
+ export function resolveStorageFallbackDir(config, env, home) {
397
+ const envVal = (env ?? process.env).SYNTH_STORAGE_FALLBACK_DIR;
398
+ if (envVal)
399
+ return resolve(envVal);
400
+ if (config.storage.fallbackDir)
401
+ return resolve(config.storage.fallbackDir);
402
+ return join(resolveDataDir(config, env, home), 'fallback');
403
+ }
404
+ /**
405
+ * ADR-076: мастер-ключ шифрования секретов at-rest (SSH-ключи, AES-256-GCM).
220
406
  * Приоритет: env `SYNTH_SECRET_KEY` > `config.security.secretKey` > `''`
221
407
  * (пусто — core использует файл `{dataDir}/secrets/master.key`).
222
408
  */
@@ -229,7 +415,7 @@ export function resolveSecretKey(config, env) {
229
415
  return '';
230
416
  }
231
417
  /**
232
- * AD-069 §9.2: нейтральная сессия без проектных инструкций.
418
+ * ADR-069 §9.2: нейтральная сессия без проектных инструкций.
233
419
  * Приоритет: явный флаг CLI `--ignore-rules`/`--safe-mode` (`explicit`) >
234
420
  * env `SYNTH_IGNORE_RULES` (`1`/`true`). Значение — эффективный
235
421
  * `instructions.enabled=false`.
@@ -241,22 +427,22 @@ export function resolveIgnoreRules(explicit, env) {
241
427
  return envVal === '1' || envVal?.toLowerCase() === 'true';
242
428
  }
243
429
  /**
244
- * AD-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
430
+ * ADR-084: имя decision-провайдера. Приоритет: env `SYNTH_DECISION_PROVIDER` >
245
431
  * `config.decision.provider`.
246
432
  *
247
433
  * Примечание: тот же env применяется и общим реестром `ENV_OVERRIDES` в
248
- * `loadConfig` (AD-023, ключ `decision.provider`); резолвер сохранён для
434
+ * `loadConfig` (ADR-023, ключ `decision.provider`); резолвер сохранён для
249
435
  * потребителей, читающих конфиг не через `loadConfig`.
250
436
  */
251
437
  export function resolveDecisionProvider(config, env) {
252
438
  return (env ?? process.env).SYNTH_DECISION_PROVIDER || config.decision.provider;
253
439
  }
254
440
  /**
255
- * AD-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
441
+ * ADR-084: модель decision-слоя. Приоритет: env `SYNTH_DECISION_MODEL` >
256
442
  * `config.decision.model`.
257
443
  *
258
444
  * См. примечание к `resolveDecisionProvider` — env дублируется реестром
259
- * `ENV_OVERRIDES` (AD-023).
445
+ * `ENV_OVERRIDES` (ADR-023).
260
446
  */
261
447
  export function resolveDecisionModel(config, env) {
262
448
  return (env ?? process.env).SYNTH_DECISION_MODEL || config.decision.model;
@@ -0,0 +1,78 @@
1
+ import { type TlsRuntimeSettings } from './tls.js';
2
+ /** Имя bootstrap-файла в `{dataDir}`. */
3
+ export declare const TLS_RUNTIME_FILENAME = "security-tls.json";
4
+ /** Подкаталог загруженных PEM-материалов (`{dataDir}/secrets/tls`). */
5
+ export declare const TLS_SECRETS_SUBDIR = "secrets/tls";
6
+ /** Имена файлов материалов, которыми управляет API (внешние пути не трогаем). */
7
+ export declare const TLS_MATERIAL_NAMES: {
8
+ readonly ca: "ca.pem";
9
+ readonly clientCert: "client.crt";
10
+ readonly clientKey: "client.key";
11
+ };
12
+ /** Путь bootstrap-файла. */
13
+ export declare function tlsRuntimePath(dataDir: string): string;
14
+ /** Каталог PEM-материалов. */
15
+ export declare function tlsSecretsDir(dataDir: string): string;
16
+ /**
17
+ * Путь материала по безопасному имени (`ca.pem`, `client.crt`, `<id>.key`).
18
+ * Имя — только basename без `..`/разделителей (fail-closed).
19
+ */
20
+ export declare function tlsSecretFilePath(dataDir: string, name: string): string;
21
+ /** Имя файла материала маппинга (`<mappingId>.crt` / `<mappingId>.key`). */
22
+ export declare function tlsMappingFileName(id: string, kind: 'cert' | 'key'): string;
23
+ /**
24
+ * Читает bootstrap-настройки TLS. Файла нет — `undefined` (поведение прежнее,
25
+ * системное доверие). Невалидный JSON/материалы — fail-closed с понятной
26
+ * ошибкой (никакого тихого фоллбэка на системное доверие).
27
+ */
28
+ export declare function readTlsRuntimeSettings(dataDir: string): TlsRuntimeSettings | undefined;
29
+ /**
30
+ * Сохраняет bootstrap-настройки (атомарно, 0600; каталог — 0700).
31
+ * Материалы должны уже существовать (см. `writeTlsSecretFile`).
32
+ */
33
+ export declare function writeTlsRuntimeSettings(dataDir: string, settings: TlsRuntimeSettings): Promise<void>;
34
+ /**
35
+ * Записывает материал (CA/сертификат/ключ) в `{dataDir}/secrets/tls/<name>`
36
+ * атомарно, режим 0600; каталог — 0700. Возвращает путь.
37
+ */
38
+ export declare function writeTlsSecretFile(dataDir: string, name: string, content: string): Promise<string>;
39
+ /** Читает материал из `secrets/tls` (для валидации/статуса). */
40
+ export declare function readTlsSecretFile(dataDir: string, name: string): string | undefined;
41
+ /**
42
+ * Валидирует runtime-настройки: уникальные id, корректные host-паттерны,
43
+ * парность cert/key, читаемость и PEM-формат, соответствие сертификата ключу
44
+ * (сравнение публичных ключей). Ошибки не содержат PEM-содержимого.
45
+ */
46
+ export declare function validateTlsRuntimeSettings(settings: TlsRuntimeSettings): void;
47
+ /** `true` — корректный host-паттерн (`host`, `*.suffix`, `*`). */
48
+ export declare function isValidHostPattern(pattern: unknown): boolean;
49
+ /** Сравнивает публичный ключ сертификата и приватного ключа (SPKI DER). */
50
+ export declare function assertCertMatchesKey(certPem: string, keyPem: string, where?: string): void;
51
+ /**
52
+ * Валидирует CA-бандл (1+ сертификатов) и возвращает метаданные для API/аудита.
53
+ * Невалидный/пустой PEM → ошибка без PEM-содержимого.
54
+ */
55
+ export declare function validateCaPem(pem: string): {
56
+ count: number;
57
+ subjects: string[];
58
+ };
59
+ /**
60
+ * Валидирует клиентскую пару `certPem`/`keyPem` (PEM + соответствие публичных
61
+ * ключей). Возвращает subject сертификата (без PEM).
62
+ */
63
+ export declare function validateClientPem(certPem: string, keyPem: string): {
64
+ certSubject?: string;
65
+ };
66
+ /**
67
+ * Subject сертификата (для read-only статуса API) — без PEM-содержимого.
68
+ * Невалидный PEM → `undefined` (статус не должен падать из-за отображения).
69
+ */
70
+ export declare function certificateSubjectFromPem(pem: string | undefined): string | undefined;
71
+ /** Subject первого сертификата в файле (статус). */
72
+ export declare function certificateSubjectFromFile(path: string | undefined): string | undefined;
73
+ /** Subject'ы всех сертификатов PEM-бандла (CA может содержать несколько). */
74
+ export declare function certificateSubjectsFromPem(pem: string | undefined): string[];
75
+ /** Количество сертификатов в PEM-бандле. */
76
+ export declare function countCertificates(pem: string | undefined): number;
77
+ /** Имя файла материала маппинга без пути (для статуса). */
78
+ export declare function materialBasename(path: string): string;