@itphx/synth-shared 0.10.1 → 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 (46) hide show
  1. package/dist/config/defaults.js +49 -3
  2. package/dist/config/env-overrides.d.ts +4 -1
  3. package/dist/config/env-overrides.js +37 -4
  4. package/dist/config/index.d.ts +3 -0
  5. package/dist/config/index.js +3 -0
  6. package/dist/config/loader.js +19 -0
  7. package/dist/config/proxy.d.ts +415 -0
  8. package/dist/config/proxy.js +1565 -0
  9. package/dist/config/resolve.d.ts +67 -0
  10. package/dist/config/resolve.js +187 -1
  11. package/dist/config/tls-runtime.d.ts +78 -0
  12. package/dist/config/tls-runtime.js +356 -0
  13. package/dist/config/tls.d.ts +215 -0
  14. package/dist/config/tls.js +394 -0
  15. package/dist/config/types.d.ts +1536 -50
  16. package/dist/config/types.js +273 -7
  17. package/dist/i18n/index.d.ts +1 -1
  18. package/dist/i18n/index.js +2 -0
  19. package/dist/index.d.ts +11 -2
  20. package/dist/index.js +11 -2
  21. package/dist/protocols/index.d.ts +0 -1
  22. package/dist/schemas/index.d.ts +134 -9
  23. package/dist/schemas/index.js +51 -4
  24. package/dist/types/analytics.d.ts +113 -0
  25. package/dist/types/analytics.js +61 -0
  26. package/dist/types/egress.d.ts +114 -0
  27. package/dist/types/egress.js +68 -0
  28. package/dist/types/events.d.ts +0 -1
  29. package/dist/types/fs.d.ts +11 -0
  30. package/dist/types/fs.js +11 -0
  31. package/dist/types/hooks.d.ts +20 -0
  32. package/dist/types/index.d.ts +3 -0
  33. package/dist/types/index.js +6 -0
  34. package/dist/types/maintenance.d.ts +39 -0
  35. package/dist/types/maintenance.js +11 -0
  36. package/dist/types/mcp.d.ts +68 -3
  37. package/dist/types/mcp.js +83 -4
  38. package/dist/types/permission.d.ts +7 -5
  39. package/dist/types/prompt.d.ts +3 -2
  40. package/dist/types/session.d.ts +0 -1
  41. package/dist/types/webhooks.d.ts +1 -1
  42. package/dist/utils/index.d.ts +15 -0
  43. package/dist/utils/index.js +53 -0
  44. package/dist/version.d.ts +1 -1
  45. package/dist/version.js +1 -1
  46. package/package.json +1 -1
@@ -0,0 +1,356 @@
1
+ /**
2
+ * ADR-099: bootstrap-хранилище runtime-настроек доверия TLS (`security-tls.json`).
3
+ *
4
+ * Файл `{dataDir}/security-tls.json` (0600, каталог 0700, атомарная запись
5
+ * tmp→rename) читается **до** подключения к PostgreSQL: настройки TLS нужны,
6
+ * чтобы это подключение вообще стало возможным, поэтому они не могут жить в БД.
7
+ *
8
+ * В JSON — только пути к PEM-файлам (материалы лежат в `{dataDir}/secrets/tls/`,
9
+ * 0600); единственное исключение — `caPem` (публичный сертификат, вставляется
10
+ * текстом из UI). Приватные ключи и PEM-содержимое наружу не отдаются.
11
+ */
12
+ import { X509Certificate, createPublicKey, createPrivateKey } from 'node:crypto';
13
+ import { readFileSync } from 'node:fs';
14
+ import { mkdir, chmod, rename, writeFile } from 'node:fs/promises';
15
+ import { join, dirname, basename } from 'node:path';
16
+ import { atomicWrite } from '../utils/index.js';
17
+ import { isPemContent } from './tls.js';
18
+ /** Имя bootstrap-файла в `{dataDir}`. */
19
+ export const TLS_RUNTIME_FILENAME = 'security-tls.json';
20
+ /** Подкаталог загруженных PEM-материалов (`{dataDir}/secrets/tls`). */
21
+ export const TLS_SECRETS_SUBDIR = 'secrets/tls';
22
+ /** Имена файлов материалов, которыми управляет API (внешние пути не трогаем). */
23
+ export const TLS_MATERIAL_NAMES = {
24
+ ca: 'ca.pem',
25
+ clientCert: 'client.crt',
26
+ clientKey: 'client.key',
27
+ };
28
+ const CERT_MARKER = /-----BEGIN CERTIFICATE-----/;
29
+ const KEY_MARKER = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
30
+ const SAFE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
31
+ /** Путь bootstrap-файла. */
32
+ export function tlsRuntimePath(dataDir) {
33
+ return join(dataDir, TLS_RUNTIME_FILENAME);
34
+ }
35
+ /** Каталог PEM-материалов. */
36
+ export function tlsSecretsDir(dataDir) {
37
+ return join(dataDir, TLS_SECRETS_SUBDIR);
38
+ }
39
+ /**
40
+ * Путь материала по безопасному имени (`ca.pem`, `client.crt`, `<id>.key`).
41
+ * Имя — только basename без `..`/разделителей (fail-closed).
42
+ */
43
+ export function tlsSecretFilePath(dataDir, name) {
44
+ if (!SAFE_NAME_RE.test(name) || name.includes('..')) {
45
+ throw new Error(`[tls] недопустимое имя файла материала: "${name}"`);
46
+ }
47
+ return join(tlsSecretsDir(dataDir), name);
48
+ }
49
+ /** Имя файла материала маппинга (`<mappingId>.crt` / `<mappingId>.key`). */
50
+ export function tlsMappingFileName(id, kind) {
51
+ if (!SAFE_NAME_RE.test(id) || id.includes('..')) {
52
+ throw new Error(`[tls] недопустимый id маппинга: "${id}"`);
53
+ }
54
+ return `${id}.${kind === 'cert' ? 'crt' : 'key'}`;
55
+ }
56
+ /**
57
+ * Читает bootstrap-настройки TLS. Файла нет — `undefined` (поведение прежнее,
58
+ * системное доверие). Невалидный JSON/материалы — fail-closed с понятной
59
+ * ошибкой (никакого тихого фоллбэка на системное доверие).
60
+ */
61
+ export function readTlsRuntimeSettings(dataDir) {
62
+ const path = tlsRuntimePath(dataDir);
63
+ let raw;
64
+ try {
65
+ raw = readFileSync(path, 'utf-8');
66
+ }
67
+ catch (err) {
68
+ if (err.code === 'ENOENT')
69
+ return undefined;
70
+ const reason = err instanceof Error ? err.message : String(err);
71
+ throw new Error(`[config] security-tls.json: не удалось прочитать файл "${path}": ${reason}`);
72
+ }
73
+ let parsed;
74
+ try {
75
+ parsed = JSON.parse(raw);
76
+ }
77
+ catch (err) {
78
+ const reason = err instanceof Error ? err.message : String(err);
79
+ throw new Error(`[config] security-tls.json: невалидный JSON (${reason})`);
80
+ }
81
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
82
+ throw new Error('[config] security-tls.json: ожидается JSON-объект');
83
+ }
84
+ const settings = parsed;
85
+ validateTlsRuntimeSettings(settings);
86
+ return settings;
87
+ }
88
+ /**
89
+ * Сохраняет bootstrap-настройки (атомарно, 0600; каталог — 0700).
90
+ * Материалы должны уже существовать (см. `writeTlsSecretFile`).
91
+ */
92
+ export async function writeTlsRuntimeSettings(dataDir, settings) {
93
+ validateTlsRuntimeSettings(settings);
94
+ const path = tlsRuntimePath(dataDir);
95
+ const payload = `${JSON.stringify(settings, null, 2)}\n`;
96
+ await mkdir(dirname(path), { recursive: true, mode: 0o700 });
97
+ await chmod(dirname(path), 0o700).catch(() => { });
98
+ await atomicWrite((p, d) => writeFile(p, d, { encoding: 'utf-8', mode: 0o600 }), (o, n) => rename(o, n), path, payload);
99
+ await chmod(path, 0o600).catch(() => { });
100
+ }
101
+ /**
102
+ * Записывает материал (CA/сертификат/ключ) в `{dataDir}/secrets/tls/<name>`
103
+ * атомарно, режим 0600; каталог — 0700. Возвращает путь.
104
+ */
105
+ export async function writeTlsSecretFile(dataDir, name, content) {
106
+ const path = tlsSecretFilePath(dataDir, name);
107
+ const dir = dirname(path);
108
+ await mkdir(dir, { recursive: true, mode: 0o700 });
109
+ await chmod(dir, 0o700).catch(() => { });
110
+ await atomicWrite((p, d) => writeFile(p, d, { encoding: 'utf-8', mode: 0o600 }), (o, n) => rename(o, n), path, content);
111
+ await chmod(path, 0o600).catch(() => { });
112
+ return path;
113
+ }
114
+ /** Читает материал из `secrets/tls` (для валидации/статуса). */
115
+ export function readTlsSecretFile(dataDir, name) {
116
+ const path = tlsSecretFilePath(dataDir, name);
117
+ try {
118
+ return readFileSync(path, 'utf-8');
119
+ }
120
+ catch (err) {
121
+ if (err.code === 'ENOENT')
122
+ return undefined;
123
+ throw err;
124
+ }
125
+ }
126
+ /**
127
+ * Валидирует runtime-настройки: уникальные id, корректные host-паттерны,
128
+ * парность cert/key, читаемость и PEM-формат, соответствие сертификата ключу
129
+ * (сравнение публичных ключей). Ошибки не содержат PEM-содержимого.
130
+ */
131
+ export function validateTlsRuntimeSettings(settings) {
132
+ if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
133
+ throw new Error('[config] security.tls: runtime-настройки должны быть объектом');
134
+ }
135
+ if (settings.caFile !== undefined && settings.caPem !== undefined) {
136
+ throw new Error("[config] security.tls: 'caFile' и 'caPem' взаимоисключащи (runtime-настройки)");
137
+ }
138
+ if (settings.caPem !== undefined) {
139
+ validatePemText(settings.caPem, 'runtime.caPem', CERT_MARKER, 'CERTIFICATE');
140
+ }
141
+ if (settings.caFile !== undefined) {
142
+ validateCertificateFile(settings.caFile, 'runtime.caFile');
143
+ }
144
+ if (settings.defaultClient !== undefined) {
145
+ validateClientPair(settings.defaultClient, 'runtime.defaultClient');
146
+ }
147
+ const mappings = settings.mappings ?? [];
148
+ if (!Array.isArray(mappings)) {
149
+ throw new Error('[config] security.tls: runtime.mappings должен быть массивом');
150
+ }
151
+ const ids = new Set();
152
+ for (const [index, mapping] of mappings.entries()) {
153
+ const where = `runtime.mappings[${index}]`;
154
+ if (!mapping || typeof mapping !== 'object') {
155
+ throw new Error(`[config] security.tls: ${where} должен быть объектом`);
156
+ }
157
+ const id = typeof mapping.id === 'string' ? mapping.id.trim() : '';
158
+ if (!id || !SAFE_NAME_RE.test(id) || id.includes('..')) {
159
+ throw new Error(`[config] security.tls: ${where}.id пуст или содержит недопустимые символы`);
160
+ }
161
+ if (id === 'default') {
162
+ throw new Error(`[config] security.tls: ${where}.id="default" зарезервирован`);
163
+ }
164
+ if (ids.has(id)) {
165
+ throw new Error(`[config] security.tls: дубликат id маппинга "${id}"`);
166
+ }
167
+ ids.add(id);
168
+ if (!Array.isArray(mapping.hosts) || mapping.hosts.length === 0) {
169
+ throw new Error(`[config] security.tls: ${where}.hosts должен быть непустым массивом`);
170
+ }
171
+ for (const pattern of mapping.hosts) {
172
+ if (!isValidHostPattern(pattern)) {
173
+ throw new Error(`[config] security.tls: ${where}.hosts: недопустимый паттерн "${String(pattern)}"`);
174
+ }
175
+ }
176
+ validateClientPair(mapping, where);
177
+ }
178
+ }
179
+ /** `true` — корректный host-паттерн (`host`, `*.suffix`, `*`). */
180
+ export function isValidHostPattern(pattern) {
181
+ if (typeof pattern !== 'string')
182
+ return false;
183
+ const value = pattern.trim().toLowerCase();
184
+ if (value === '')
185
+ return false;
186
+ if (value === '*')
187
+ return true;
188
+ if (value.startsWith('*.')) {
189
+ const suffix = value.slice(2);
190
+ return suffix !== '' && !suffix.includes('*') && isValidHostname(suffix);
191
+ }
192
+ return !value.includes('*') && isValidHostname(value);
193
+ }
194
+ /** Грубая проверка hostname/IP (без схемы/порта/слэшей). */
195
+ function isValidHostname(value) {
196
+ if (value === '' || value.length > 253)
197
+ return false;
198
+ if (value.includes('/') || value.includes(':') || value.includes('@'))
199
+ return false;
200
+ return /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(value);
201
+ }
202
+ function validateClientPair(pair, where) {
203
+ const hasCert = typeof pair.certFile === 'string' && pair.certFile !== '';
204
+ const hasKey = typeof pair.keyFile === 'string' && pair.keyFile !== '';
205
+ if (hasCert !== hasKey) {
206
+ throw new Error(`[config] security.tls: ${where}: mTLS требует и certFile, и keyFile (задайте оба либо ни одного)`);
207
+ }
208
+ if (!hasCert || !hasKey)
209
+ return;
210
+ const cert = readFileOrThrow(pair.certFile, `${where}.certFile`);
211
+ const key = readFileOrThrow(pair.keyFile, `${where}.keyFile`);
212
+ validatePemText(cert, `${where}.certFile`, CERT_MARKER, 'CERTIFICATE');
213
+ validatePemText(key, `${where}.keyFile`, KEY_MARKER, 'PRIVATE KEY');
214
+ assertCertMatchesKey(cert, key, where);
215
+ }
216
+ function validateCertificateFile(path, where) {
217
+ const content = readFileOrThrow(path, where);
218
+ validatePemText(content, where, CERT_MARKER, 'CERTIFICATE');
219
+ }
220
+ function readFileOrThrow(path, where) {
221
+ try {
222
+ return readFileSync(path, 'utf-8');
223
+ }
224
+ catch (err) {
225
+ const reason = err instanceof Error ? err.message : String(err);
226
+ throw new Error(`[config] security.tls: ${where}: не удалось прочитать файл "${path}": ${reason}`);
227
+ }
228
+ }
229
+ function validatePemText(content, where, marker, kind) {
230
+ if (!isPemContent(content) || !marker.test(content)) {
231
+ throw new Error(`[config] security.tls: ${where} не содержит PEM (ожидается "-----BEGIN ${kind}-----")`);
232
+ }
233
+ }
234
+ /** Сравнивает публичный ключ сертификата и приватного ключа (SPKI DER). */
235
+ export function assertCertMatchesKey(certPem, keyPem, where = 'client') {
236
+ let certPublic;
237
+ let keyPublic;
238
+ try {
239
+ certPublic = new X509Certificate(certPem).publicKey.export({ type: 'spki', format: 'der' });
240
+ }
241
+ catch {
242
+ throw new Error(`[config] security.tls: ${where}: не удалось разобрать сертификат (PEM/X509)`);
243
+ }
244
+ try {
245
+ keyPublic = createPublicKey(createPrivateKey(keyPem))
246
+ .export({ type: 'spki', format: 'der' });
247
+ }
248
+ catch {
249
+ throw new Error(`[config] security.tls: ${where}: не удалось разобрать приватный ключ ` +
250
+ '(PEM/PKCS#8 либо зашифрованный ключ без пароля)');
251
+ }
252
+ if (!certPublic.equals(keyPublic)) {
253
+ throw new Error(`[config] security.tls: ${where}: сертификат и приватный ключ не соответствуют друг другу`);
254
+ }
255
+ }
256
+ /**
257
+ * Валидирует CA-бандл (1+ сертификатов) и возвращает метаданные для API/аудита.
258
+ * Невалидный/пустой PEM → ошибка без PEM-содержимого.
259
+ */
260
+ export function validateCaPem(pem) {
261
+ if (typeof pem !== 'string' || pem.trim() === '') {
262
+ throw new Error('[config] security.tls.caPem: ожидается непустой PEM-бандл');
263
+ }
264
+ const blocks = extractPemBlocks(pem, 'CERTIFICATE');
265
+ if (blocks.length === 0 || !isPemContent(pem)) {
266
+ throw new Error('[config] security.tls.caPem: не содержит PEM-сертификат (-----BEGIN CERTIFICATE-----)');
267
+ }
268
+ const subjects = [];
269
+ for (const [index, block] of blocks.entries()) {
270
+ let subject;
271
+ try {
272
+ subject = normalizeSubject(new X509Certificate(block).subject);
273
+ }
274
+ catch {
275
+ throw new Error(`[config] security.tls.caPem: не удалось разобрать сертификат #${index + 1} (X509)`);
276
+ }
277
+ if (subject)
278
+ subjects.push(subject);
279
+ }
280
+ return { count: blocks.length, subjects };
281
+ }
282
+ /**
283
+ * Валидирует клиентскую пару `certPem`/`keyPem` (PEM + соответствие публичных
284
+ * ключей). Возвращает subject сертификата (без PEM).
285
+ */
286
+ export function validateClientPem(certPem, keyPem) {
287
+ if (typeof certPem !== 'string' || certPem.trim() === '') {
288
+ throw new Error('[config] security.tls: certPem: ожидается непустой PEM-сертификат');
289
+ }
290
+ if (typeof keyPem !== 'string' || keyPem.trim() === '') {
291
+ throw new Error('[config] security.tls: keyPem: ожидается непустой PEM-ключ');
292
+ }
293
+ validatePemText(certPem, 'certPem', CERT_MARKER, 'CERTIFICATE');
294
+ validatePemText(keyPem, 'keyPem', KEY_MARKER, 'PRIVATE KEY');
295
+ assertCertMatchesKey(certPem, keyPem, 'certPem/keyPem');
296
+ const subject = certificateSubjectFromPem(certPem);
297
+ return subject !== undefined ? { certSubject: subject } : {};
298
+ }
299
+ /**
300
+ * Subject сертификата (для read-only статуса API) — без PEM-содержимого.
301
+ * Невалидный PEM → `undefined` (статус не должен падать из-за отображения).
302
+ */
303
+ export function certificateSubjectFromPem(pem) {
304
+ if (!pem)
305
+ return undefined;
306
+ try {
307
+ return normalizeSubject(new X509Certificate(pem).subject);
308
+ }
309
+ catch {
310
+ return undefined;
311
+ }
312
+ }
313
+ /** Subject первого сертификата в файле (статус). */
314
+ export function certificateSubjectFromFile(path) {
315
+ if (!path)
316
+ return undefined;
317
+ try {
318
+ return certificateSubjectFromPem(readFileSync(path, 'utf-8'));
319
+ }
320
+ catch {
321
+ return undefined;
322
+ }
323
+ }
324
+ /** Subject'ы всех сертификатов PEM-бандла (CA может содержать несколько). */
325
+ export function certificateSubjectsFromPem(pem) {
326
+ if (!pem)
327
+ return [];
328
+ const subjects = [];
329
+ for (const block of extractPemBlocks(pem, 'CERTIFICATE')) {
330
+ const subject = certificateSubjectFromPem(block);
331
+ if (subject)
332
+ subjects.push(subject);
333
+ }
334
+ return subjects;
335
+ }
336
+ /** Количество сертификатов в PEM-бандле. */
337
+ export function countCertificates(pem) {
338
+ if (!pem)
339
+ return 0;
340
+ return extractPemBlocks(pem, 'CERTIFICATE').length;
341
+ }
342
+ function extractPemBlocks(pem, kind) {
343
+ const re = new RegExp(`-----BEGIN ${kind}-----[\\s\\S]*?-----END ${kind}-----`, 'g');
344
+ return pem.match(re) ?? [];
345
+ }
346
+ function normalizeSubject(subject) {
347
+ return subject
348
+ .split('\n')
349
+ .map((line) => line.trim())
350
+ .filter(Boolean)
351
+ .join(', ');
352
+ }
353
+ /** Имя файла материала маппинга без пути (для статуса). */
354
+ export function materialBasename(path) {
355
+ return basename(path);
356
+ }
@@ -0,0 +1,215 @@
1
+ import type { SecurityTlsConfig } from './types.js';
2
+ /** Минимальный срез конфига, достаточный резолверу (совместим с `SynthConfig`). */
3
+ export interface TlsConfigSource {
4
+ security?: {
5
+ tls?: SecurityTlsConfig;
6
+ } | undefined;
7
+ }
8
+ /** Источник эффективного значения параметра доверия TLS. */
9
+ export type TlsSource = 'env' | 'runtime' | 'config' | 'none';
10
+ /** Клиентский материал (mTLS): сертификат + ключ — только парой. */
11
+ export interface TlsClientMaterial {
12
+ certFile?: string;
13
+ keyFile?: string;
14
+ }
15
+ /**
16
+ * Runtime-настройки bootstrap-хранилища `{dataDir}/security-tls.json`.
17
+ * Читаются до подключения к PostgreSQL; редактируются из UI (будущий этап).
18
+ * В JSON — пути к PEM-файлам (кроме публичного `caPem`).
19
+ */
20
+ export interface TlsRuntimeSettings {
21
+ caFile?: string;
22
+ caPem?: string;
23
+ rejectUnauthorized?: boolean;
24
+ /** Глобальный клиентский профиль (mTLS) по умолчанию. */
25
+ defaultClient?: TlsClientMaterial;
26
+ /** Per-host клиентские профили (порядок = приоритет первого совпадения). */
27
+ mappings?: TlsMappingSettings[];
28
+ }
29
+ /** Per-host маппинг клиентского сертификата (runtime). */
30
+ export interface TlsMappingSettings {
31
+ id: string;
32
+ hosts: string[];
33
+ certFile: string;
34
+ keyFile: string;
35
+ label?: string;
36
+ }
37
+ /** Эффективный клиентский TLS-профиль (пути; чтение PEM — на стороне core/драйвера). */
38
+ export interface TlsClientProfile {
39
+ /** `default` либо id маппинга. */
40
+ id: string;
41
+ /** Host-паттерны (`[]` для профиля по умолчанию). */
42
+ hosts: string[];
43
+ label?: string;
44
+ certFile: string;
45
+ keyFile: string;
46
+ source: TlsSource;
47
+ /** `true` — источник env/config (UI только показывает, не редактирует). */
48
+ readOnly: boolean;
49
+ }
50
+ /** Эффективная конфигурация `security.tls` (env > runtime > config.yaml). */
51
+ export interface ResolvedTlsConfig {
52
+ /** Путь к PEM-файлу доверенного CA (взаимоисключающ с `caPem`). */
53
+ caFile?: string;
54
+ /** PEM доверенного CA (взаимоисключающ с `caFile`). */
55
+ caPem?: string;
56
+ /** Путь к PEM-файлу клиентского сертификата (mTLS). */
57
+ certFile?: string;
58
+ /** Путь к PEM-файлу приватного ключа клиента (mTLS). */
59
+ keyFile?: string;
60
+ /** Проверять сертификат сервера (по умолчанию `true`). */
61
+ rejectUnauthorized: boolean;
62
+ }
63
+ /** Эффективное доверие с уже прочитанным и проверенным CA (для построения dispatcher). */
64
+ export interface ResolvedTlsTrust {
65
+ /** `true` — доверие явно сконфигурировано (CA/клиентский серт/`rejectUnauthorized: false`). */
66
+ enabled: boolean;
67
+ /** PEM CA: содержимое `caPem` либо прочитанный `caFile`. */
68
+ ca?: string;
69
+ /** Путь к PEM-файлу клиентского сертификата (чтение — на стороне core). */
70
+ certFile?: string;
71
+ /** Путь к PEM-файлу приватного ключа клиента (чтение — на стороне core). */
72
+ keyFile?: string;
73
+ rejectUnauthorized: boolean;
74
+ }
75
+ /** Эффективные клиентские профили + источники (ADR-099, per-host mTLS). */
76
+ export interface ResolvedTlsProfiles {
77
+ /** Глобальный профиль по умолчанию (env/runtime/config). */
78
+ default?: TlsClientProfile;
79
+ /** Per-host маппинги (runtime; порядок сохраняется). */
80
+ mappings: TlsClientProfile[];
81
+ caFile?: string;
82
+ caPem?: string;
83
+ rejectUnauthorized: boolean;
84
+ sources: {
85
+ ca: TlsSource;
86
+ rejectUnauthorized: TlsSource;
87
+ defaultClient: TlsSource;
88
+ };
89
+ }
90
+ /** Env-имена секции `security.tls` (ADR-023). */
91
+ export declare const TLS_ENV: {
92
+ readonly caFile: "SYNTH_TLS_CA_FILE";
93
+ readonly caPem: "SYNTH_TLS_CA_PEM";
94
+ readonly certFile: "SYNTH_TLS_CERT_FILE";
95
+ readonly keyFile: "SYNTH_TLS_KEY_FILE";
96
+ readonly rejectUnauthorized: "SYNTH_TLS_REJECT_UNAUTHORIZED";
97
+ };
98
+ /** `true`, если строка содержит PEM-блок. */
99
+ export declare function isPemContent(value: string): boolean;
100
+ /**
101
+ * Сливает env, runtime (bootstrap) и config.yaml для `security.tls`
102
+ * (ADR-023): приоритет **поле-уровнево** `env > runtime > config`. Пустая
103
+ * строка env — «не задано». `caFile` и `caPem` взаимоисключащи: после слияния
104
+ * оба непусты (в т.ч. из разных источников) → ошибка конфигурации (fail-closed).
105
+ */
106
+ export declare function resolveTlsConfig(config: TlsConfigSource | undefined, env?: NodeJS.ProcessEnv, runtime?: TlsRuntimeSettings): ResolvedTlsConfig;
107
+ /**
108
+ * Эффективные клиентские профили (mTLS) + CA/rejectUnauthorized с источниками.
109
+ *
110
+ * Приоритет поле-уровневый: `env > runtime > config`. Клиентская пара
111
+ * `certFile`/`keyFile` собирается по полям; неполная пара (серт без ключа или
112
+ * наоборот) — fail-closed: mTLS без ключа/серта не работает, а «тихий» выбор
113
+ * одного источника скрыл бы опечатку. Маппинги — только runtime (редактируемые).
114
+ */
115
+ export declare function resolveTlsProfiles(config: TlsConfigSource | undefined, env?: NodeJS.ProcessEnv, runtime?: TlsRuntimeSettings): ResolvedTlsProfiles;
116
+ /**
117
+ * Выбирает клиентский профиль по host: точное совпадение, `*.suffix` (поддомены)
118
+ * либо `*` (все хосты), регистронезависимо; **первое** совпадение в порядке
119
+ * маппингов, затем профиль по умолчанию, иначе `undefined` (без клиентского серта).
120
+ */
121
+ export declare function selectTlsClientProfile(profiles: Pick<ResolvedTlsProfiles, 'default' | 'mappings'>, host: string | undefined): TlsClientProfile | undefined;
122
+ /** Матчинг одного паттерна (`host` | `*.suffix` | `*`); регистронезависимо. */
123
+ export declare function matchTlsHostPattern(pattern: string, rawHost: string): boolean;
124
+ /** Нормализует host (нижний регистр, без точки в конце и скобок IPv6). */
125
+ export declare function normalizeTlsHost(rawHost: string | undefined): string | undefined;
126
+ /**
127
+ * Эффективное доверие с прочитанным CA. Fail-closed: `caFile` задан, но файл
128
+ * отсутствует/не читается/не PEM → внятная ошибка (никакого тихого фоллбэка на
129
+ * системное доверие, иначе опечатка в пути молча ломает доверие к корпоративному CA).
130
+ * `caPem` также проверяется на PEM-блок.
131
+ */
132
+ export declare function resolveTlsTrust(config: TlsConfigSource | undefined, env?: NodeJS.ProcessEnv, runtime?: TlsRuntimeSettings): ResolvedTlsTrust;
133
+ /**
134
+ * Эффективный TLS-режим PostgreSQL (`storage.postgres.sslmode`).
135
+ * `verify-ca` — **алиас** `verify-full` (см. `normalizePostgresSslMode`).
136
+ */
137
+ export type PostgresSslMode = 'disable' | 'require' | 'verify-full';
138
+ /** Допустимые значения `sslmode` (в порядке документации; `verify-ca` — алиас). */
139
+ export declare const POSTGRES_SSL_MODES: readonly PostgresSslMode[];
140
+ /**
141
+ * Алиасы `sslmode`, нормализуемые к канонической форме. `verify-ca`
142
+ * (`pg-connection-string` v2 трактует его как `verify-full`) — принимаем как
143
+ * `verify-full` **с предупреждением**: тихая трактовка «с проверкой hostname»
144
+ * сюрпризом не будет.
145
+ */
146
+ export declare const POSTGRES_SSL_MODE_ALIASES: Readonly<Record<string, PostgresSslMode>>;
147
+ /**
148
+ * Нормализует `sslmode` (`disable`/`require`/`verify-full`, алиас `verify-ca` →
149
+ * `verify-full` с warn). Пусто — `undefined` (прежнее поведение, без TLS).
150
+ * Неизвестное значение — `undefined` (вызывающий решает: env → warn + игнор,
151
+ * config — Zod отвергает на схеме).
152
+ */
153
+ export declare function normalizePostgresSslMode(raw: string | undefined): PostgresSslMode | undefined;
154
+ /**
155
+ * TLS-параметры, запрещённые в `dsn`. `pg` накладывает распарсенный
156
+ * `connectionString` **поверх** явного конфига (`Object.assign({}, config,
157
+ * parse(connectionString))`), поэтому `sslmode`/`sslrootcert`/… из DSN молча
158
+ * перекрывают переданный `ssl`-объект — вплоть до отключения TLS. Запрещаем их
159
+ * в DSN, чтобы политика доверия задавалась **только** в `storage.postgres.sslmode`
160
+ * + `security.tls`.
161
+ */
162
+ export declare const DSN_TLS_PARAMS: readonly ["sslmode", "sslrootcert", "sslcert", "sslkey", "sslnegotiation", "uselibpqcompat", "ssl"];
163
+ /**
164
+ * Находит TLS-параметры в строке подключения (URL-форма `?sslmode=…` и
165
+ * libpq-подобная `sslmode=…`). Возвращает уникальные имена (нижний регистр);
166
+ * пусто — DSN «чистый» по TLS.
167
+ */
168
+ export declare function findDsnTlsParams(dsn: string | undefined): string[];
169
+ /** Вход построителя TLS-опций PostgreSQL-соединения (единый источник доверия). */
170
+ export interface PostgresSslBuildInput {
171
+ /** `storage.postgres.sslmode` (сырое значение; нормализуется внутри). */
172
+ sslmode?: string;
173
+ /** Legacy `storage.postgres.ssl` (используется, только если `sslmode` не задан). */
174
+ ssl?: boolean;
175
+ /** Строка подключения (из DSN берётся host, если он не задан в `host`). */
176
+ connectionString?: string;
177
+ /** Host (для `servername` в `verify-full`, если не задан DSN). */
178
+ host?: string;
179
+ /** `security.tls` (источник CA/mTLS). */
180
+ config?: TlsConfigSource;
181
+ /** Env для резолва `security.tls` (ADR-023). */
182
+ env?: NodeJS.ProcessEnv;
183
+ /**
184
+ * ADR-099: runtime bootstrap-настройки TLS (`{dataDir}/security-tls.json`) —
185
+ * per-host клиентские профили и CA/rejectUnauthorized (env > runtime > config).
186
+ */
187
+ runtime?: TlsRuntimeSettings;
188
+ }
189
+ /** Результат построителя: значение для `pg`-конфига `ssl` (если задано). */
190
+ export interface PostgresSslBuildResult {
191
+ /**
192
+ * Значение `ssl` для `pg`: `false` (без TLS), `true` (системное доверие) либо
193
+ * объект опций (`rejectUnauthorized`/`ca`/`cert`/`key`/`servername`).
194
+ * Не задано — `ssl` в `pg`-конфиг не проставляется (прежнее поведение).
195
+ */
196
+ ssl?: boolean | Record<string, unknown>;
197
+ }
198
+ /**
199
+ * Собирает `ssl`-опции `pg` из **единого** источника доверия (ADR-099):
200
+ *
201
+ * | sslmode | ssl-опции `pg` |
202
+ * |----------------|----------------------------------------------------------------------|
203
+ * | не задан | прежнее поведение: `ssl` из legacy-поля либо ничего (без TLS) |
204
+ * | `disable` | `false` (TLS выключен явно) |
205
+ * | `require` | `{ rejectUnauthorized: false }` (+ `cert`/`key` при mTLS) |
206
+ * | `verify-full` | `{ rejectUnauthorized: true, ca, cert?, key?, servername? }` |
207
+ * | `verify-ca` | алиас `verify-full` (нормализуется с предупреждением) |
208
+ *
209
+ * **Fail-closed**: `verify-full` без сконфигурированного CA (`security.tls`)
210
+ * бросает ошибку — никакого тихого `rejectUnauthorized: false`.
211
+ * mTLS (`certFile`/`keyFile`) добавляется в `require`/`verify-full`.
212
+ * Для `verify-full` без DSN `servername` = host (кроме IP — SNI по IP запрещён);
213
+ * `pg` и сам выводит `servername` из host, явное значение — для прозрачности.
214
+ */
215
+ export declare function buildPostgresSslOptions(input: PostgresSslBuildInput): PostgresSslBuildResult;