@itphx/synth-shared 0.10.1 → 0.12.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 (104) hide show
  1. package/dist/config/defaults.js +172 -3
  2. package/dist/config/env-overrides.d.ts +33 -1
  3. package/dist/config/env-overrides.js +191 -5
  4. package/dist/config/execution.d.ts +66 -0
  5. package/dist/config/execution.js +146 -0
  6. package/dist/config/index.d.ts +4 -0
  7. package/dist/config/index.js +4 -0
  8. package/dist/config/loader.js +19 -0
  9. package/dist/config/proxy.d.ts +415 -0
  10. package/dist/config/proxy.js +1567 -0
  11. package/dist/config/resolve.d.ts +67 -0
  12. package/dist/config/resolve.js +187 -1
  13. package/dist/config/tls-runtime.d.ts +78 -0
  14. package/dist/config/tls-runtime.js +356 -0
  15. package/dist/config/tls.d.ts +215 -0
  16. package/dist/config/tls.js +394 -0
  17. package/dist/config/types.d.ts +1571 -2835
  18. package/dist/config/types.js +717 -58
  19. package/dist/i18n/index.d.ts +1 -1
  20. package/dist/i18n/index.js +279 -0
  21. package/dist/index.d.ts +24 -3
  22. package/dist/index.js +25 -2
  23. package/dist/model-metadata.d.ts +10 -0
  24. package/dist/protocols/index.d.ts +0 -1
  25. package/dist/schemas/index.d.ts +1014 -2231
  26. package/dist/schemas/index.js +222 -14
  27. package/dist/types/analytics.d.ts +113 -0
  28. package/dist/types/analytics.js +61 -0
  29. package/dist/types/authority.d.ts +464 -0
  30. package/dist/types/authority.js +445 -0
  31. package/dist/types/background.d.ts +96 -0
  32. package/dist/types/background.js +24 -0
  33. package/dist/types/bus-events.d.ts +23 -1
  34. package/dist/types/catalog.d.ts +349 -0
  35. package/dist/types/catalog.js +393 -0
  36. package/dist/types/decision.d.ts +28 -337
  37. package/dist/types/egress.d.ts +114 -0
  38. package/dist/types/egress.js +68 -0
  39. package/dist/types/events.d.ts +54 -2
  40. package/dist/types/external-credentials.d.ts +352 -0
  41. package/dist/types/external-credentials.js +200 -0
  42. package/dist/types/fs.d.ts +11 -0
  43. package/dist/types/fs.js +11 -0
  44. package/dist/types/hooks.d.ts +50 -9
  45. package/dist/types/index.d.ts +23 -0
  46. package/dist/types/index.js +55 -0
  47. package/dist/types/llm-filters.d.ts +150 -0
  48. package/dist/types/llm-filters.js +54 -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 +101 -5
  52. package/dist/types/mcp.js +127 -5
  53. package/dist/types/message.d.ts +45 -1
  54. package/dist/types/pack.d.ts +1102 -0
  55. package/dist/types/pack.js +1003 -0
  56. package/dist/types/permission.d.ts +31 -15
  57. package/dist/types/permission.js +1 -1
  58. package/dist/types/pipeline-engine.d.ts +453 -0
  59. package/dist/types/pipeline-engine.js +440 -0
  60. package/dist/types/pipeline.d.ts +275 -0
  61. package/dist/types/pipeline.js +212 -0
  62. package/dist/types/plugin-audit.d.ts +110 -0
  63. package/dist/types/plugin-audit.js +185 -0
  64. package/dist/types/plugin-hybrid.d.ts +85 -0
  65. package/dist/types/plugin-hybrid.js +68 -0
  66. package/dist/types/plugin-lock.d.ts +95 -0
  67. package/dist/types/plugin-lock.js +1 -0
  68. package/dist/types/plugin-protocol.d.ts +221 -0
  69. package/dist/types/plugin-protocol.js +322 -0
  70. package/dist/types/plugin-runtime.d.ts +25 -0
  71. package/dist/types/plugin-runtime.js +11 -0
  72. package/dist/types/plugin-scan.d.ts +159 -0
  73. package/dist/types/plugin-scan.js +166 -0
  74. package/dist/types/plugin-tools.d.ts +51 -0
  75. package/dist/types/plugin-tools.js +72 -0
  76. package/dist/types/project.d.ts +14 -0
  77. package/dist/types/prompt-blocks.d.ts +102 -0
  78. package/dist/types/prompt-blocks.js +24 -0
  79. package/dist/types/prompt.d.ts +47 -4
  80. package/dist/types/provider.d.ts +11 -0
  81. package/dist/types/question.d.ts +153 -0
  82. package/dist/types/question.js +65 -0
  83. package/dist/types/schedules.d.ts +26 -3
  84. package/dist/types/semver.d.ts +48 -0
  85. package/dist/types/semver.js +218 -0
  86. package/dist/types/service-keys.d.ts +41 -3
  87. package/dist/types/service-keys.js +44 -2
  88. package/dist/types/session.d.ts +54 -1
  89. package/dist/types/steering.d.ts +74 -0
  90. package/dist/types/steering.js +75 -0
  91. package/dist/types/tools.d.ts +125 -5
  92. package/dist/types/tools.js +75 -0
  93. package/dist/types/trust.d.ts +31 -0
  94. package/dist/types/trust.js +27 -0
  95. package/dist/types/webhooks.d.ts +1 -1
  96. package/dist/types/worktree.d.ts +170 -0
  97. package/dist/types/worktree.js +101 -0
  98. package/dist/utils/index.d.ts +46 -1
  99. package/dist/utils/index.js +145 -12
  100. package/dist/utils/reasoning.d.ts +16 -0
  101. package/dist/utils/reasoning.js +37 -0
  102. package/dist/version.d.ts +1 -1
  103. package/dist/version.js +1 -1
  104. package/package.json +2 -2
package/dist/types/mcp.js CHANGED
@@ -1,24 +1,103 @@
1
1
  // --- MCP: реестр серверов и сетевой доступ (ADR-071 §2.3.1/§2.5) ---
2
- /** Версия схемы записи реестра MCP — для будущей миграции (PROP-032). */
2
+ /** Версия схемы записи реестра MCP — для будущей миграции (ADR-096). */
3
3
  export const MCP_REGISTRY_SCHEMA_VERSION = 1;
4
4
  export const MCP_REGISTRY_ORIGINS = ['instance', 'user'];
5
5
  export const MCP_REGISTRY_TRUST_LEVELS = ['builtin', 'community'];
6
6
  export const MCP_NETWORK_POLICY_MODES = ['allow', 'deny'];
7
- /** Приватные/служебные диапазоны, запрещённые по умолчанию (SSRF/egress). */
7
+ /**
8
+ * Служебные/специальные адресные диапазоны, запрещённые по умолчанию (SSRF/egress).
9
+ *
10
+ * **Единственный источник истины** для всех egress-политик: `mcp.networkPolicy`,
11
+ * `egress.tools`, `egress.webhooks` (`types/egress.ts`) и встроенный fallback
12
+ * guard'а (`core/engine/net/egress-guard.ts` → `isBlockedIp` без политики).
13
+ * Отдельных списков «заблокированных адресов» в коде больше нет: расширять
14
+ * нужно этот список, иначе политика и guard разойдутся (промис не будет
15
+ * подкреплён кодом).
16
+ *
17
+ * **Правило отбора:** диапазоны, которые не маршрутизируются в публичном
18
+ * интернете (IANA IPv4/IPv6 Special-Purpose Address Registry) либо непригодны
19
+ * как цель исходящего HTTP-запроса (multicast, limited broadcast).
20
+ *
21
+ * IPv4:
22
+ * - `0.0.0.0/8` — «this network»; `0.0.0.0` на Linux ведёт на localhost;
23
+ * - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` — RFC1918 (private);
24
+ * - `100.64.0.0/10` — CGNAT (RFC 6598); в ряде облаков это адрес метаданных
25
+ * (напр. Alibaba `100.100.100.200`);
26
+ * - `127.0.0.0/8` — loopback;
27
+ * - `169.254.0.0/16` — link-local (в т.ч. `169.254.169.254` — метаданные облака);
28
+ * - `192.0.0.0/24` — IETF protocol assignments (RFC 6890), включая well-known
29
+ * NAT64-префиксы `192.0.0.170/171` (RFC 6052): через них внутренний IPv4
30
+ * достигается по IPv6-адресу и v4-список его не ловит;
31
+ * - `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` — TEST-NET-1/2/3
32
+ * (RFC 5737): SSRF-риска не несут (не маршрутизируются), но заблокированы
33
+ * вместе со всеми прочими служебными диапазонами — список самосогласован
34
+ * («всё специальное»), риск-оценка не нужна по каждому адресу, а вернуть
35
+ * конкретный адрес можно явным exception политики;
36
+ * - `192.88.99.0/24` — 6to4 relay anycast (RFC 7526, deprecated);
37
+ * - `198.18.0.0/15` — benchmarking (RFC 2544);
38
+ * - `224.0.0.0/4` — multicast: цель для SSRF во внутренние multicast-группы
39
+ * (mDNS/SSDP и т.п.);
40
+ * - `240.0.0.0/4` — reserved (RFC 1112);
41
+ * - `255.255.255.255/32` — limited broadcast.
42
+ *
43
+ * IPv6:
44
+ * - `::/128` — unspecified, на части стеков эквивалентен loopback;
45
+ * - `::1/128` — loopback;
46
+ * - `::ffff:0:0/96` — IPv4-mapped IPv6. Mapped-запись — типичная попытка обхода
47
+ * (v4-диапазоны её не ловят), легитимные адреса приходят обычным v4/v6,
48
+ * поэтому mapped-форма блокируется целиком; `isIpInCidr` дополнительно
49
+ * приводит mapped к вложенному IPv4 (`::ffff:127.0.0.1` ← `127.0.0.0/8`);
50
+ * - `100::/64` — discard-only (RFC 6666);
51
+ * - `2001:2::/48` — benchmarking (IPv6);
52
+ * - `2001:db8::/32` — documentation (IPv6);
53
+ * - `2002::/16` — 6to4 (RFC 7526, deprecated): адрес вшивает IPv4, поэтому
54
+ * недостижим для v4-списка;
55
+ * - `fc00::/7` — ULA;
56
+ * - `fe80::/10` — link-local;
57
+ * - `ff00::/8` — multicast.
58
+ *
59
+ * Осознанно НЕ включены (иначе ломается легитимный egress):
60
+ * - `64:ff9b::/96` (NAT64 well-known prefix) и `64:ff9b:1::/48` (local-use
61
+ * NAT64, RFC 8215) — на IPv6-only сетях с DNS64 резолвер отдаёт
62
+ * синтезированные AAAA именно из этих префиксов; их блокировка заблокировала
63
+ * бы весь исходящий трафик к публичным хостам;
64
+ * - глобально маршрутизируемые служебные блоки (`192.31.196.0/24` AS112-v4,
65
+ * `192.52.193.0/24` AMT, `192.175.48.0/24` AS112, `2001:4860::/32` и т.п.) —
66
+ * это обычные публичные адреса.
67
+ */
8
68
  export const DEFAULT_MCP_PRIVATE_CIDRS = [
69
+ '0.0.0.0/8',
9
70
  '10.0.0.0/8',
10
- '172.16.0.0/12',
11
- '192.168.0.0/16',
71
+ '100.64.0.0/10',
12
72
  '127.0.0.0/8',
13
73
  '169.254.0.0/16',
74
+ '172.16.0.0/12',
75
+ '192.0.0.0/24',
76
+ '192.0.2.0/24',
77
+ '192.88.99.0/24',
78
+ '192.168.0.0/16',
79
+ '198.18.0.0/15',
80
+ '198.51.100.0/24',
81
+ '203.0.113.0/24',
82
+ '224.0.0.0/4',
83
+ '240.0.0.0/4',
84
+ '255.255.255.255/32',
85
+ '::/128',
14
86
  '::1/128',
87
+ '::ffff:0:0/96',
88
+ '100::/64',
89
+ '2001:2::/48',
90
+ '2001:db8::/32',
91
+ '2002::/16',
15
92
  'fc00::/7',
16
93
  'fe80::/10',
94
+ 'ff00::/8',
17
95
  ];
18
- /** Дефолтная политика: deny приватных диапазонов (ADR-071 §2.3.1). */
96
+ /** Дефолтная политика: deny служебных диапазонов (ADR-071 §2.3.1). */
19
97
  export const DEFAULT_MCP_NETWORK_POLICY = {
20
98
  mode: 'deny',
21
99
  list: [...DEFAULT_MCP_PRIVATE_CIDRS],
100
+ exceptions: [],
22
101
  };
23
102
  // --- MCP: уровни/скоуп и эффективный набор (ADR-071 §2.2/§2.4) ---
24
103
  export const MCP_SERVER_LEVELS = ['system', 'project', 'session'];
@@ -38,3 +117,46 @@ export const MCP_DISABLED_REASONS = [
38
117
  'session_optout',
39
118
  'not_default',
40
119
  ];
120
+ // --- ADR-105 (Ф3): запрет plaintext-секретов в заголовках MCP-коннектора ---
121
+ /**
122
+ * Машинно-читаемый код ошибки записи реестра MCP с plaintext-секретом
123
+ * в заголовках (ADR-105 §5, Ф3).
124
+ *
125
+ * HTTP: `400` с `error.code = "MCP_SECRET_HEADER_FORBIDDEN"`.
126
+ */
127
+ export const MCP_SECRET_HEADER_ERROR_CODE = 'MCP_SECRET_HEADER_FORBIDDEN';
128
+ /**
129
+ * Заголовки, значение которых — **секрет**. В реестре MCP (и в конфиге
130
+ * коннектора) им не место: токен лежит в слое внешних доступов
131
+ * (`ExternalCredential`, ADR-105), а коннектор ссылается на него по id
132
+ * (`auth: { kind: 'credential', credentialId }`).
133
+ *
134
+ * Сравнение — регистронезависимое (HTTP-заголовки нечувствительны к регистру).
135
+ */
136
+ export const FORBIDDEN_MCP_SECRET_HEADERS = [
137
+ 'authorization',
138
+ 'proxy-authorization',
139
+ 'x-api-key',
140
+ 'cookie',
141
+ ];
142
+ /**
143
+ * Найти запрещённые (секретные) заголовки в словаре `headers`.
144
+ *
145
+ * Возвращает **исходные имена** заголовков (как их записал пользователь) —
146
+ * они уходят в сообщение об ошибке (значения — никогда).
147
+ */
148
+ export function findForbiddenMcpSecretHeaders(headers) {
149
+ if (!headers)
150
+ return [];
151
+ const forbidden = new Set(FORBIDDEN_MCP_SECRET_HEADERS);
152
+ return Object.keys(headers).filter((name) => forbidden.has(name.trim().toLowerCase()));
153
+ }
154
+ /**
155
+ * Текст ошибки «секретный заголовок в коннекторе» — **единый** для слоя
156
+ * хранилища, HTTP-роутов (core/backend) и probe (ADR-105 §5, Ф3).
157
+ *
158
+ * Значений заголовков в тексте нет — только их имена.
159
+ */
160
+ export function mcpSecretHeaderErrorMessage(forbidden) {
161
+ return `Заголовки с секретами (${forbidden.join(', ')}) в MCP-коннекторе запрещены — используйте auth.kind='credential' (доступ к внешнему сервису)`;
162
+ }
@@ -1,5 +1,6 @@
1
1
  import type { TokenUsage } from './llm.js';
2
2
  import type { PromptMeta } from './prompt.js';
3
+ import type { AuthorityPrincipal } from './authority.js';
3
4
  export declare enum MessageRole {
4
5
  SYSTEM = "system",
5
6
  USER = "user",
@@ -10,7 +11,44 @@ export declare enum MessageRole {
10
11
  INFO = "info",
11
12
  ERROR = "error"
12
13
  }
13
- export type PartType = 'text' | 'tool_use' | 'tool_result' | 'reasoning' | 'session_reference';
14
+ /**
15
+ * Типы частей сообщения.
16
+ *
17
+ * ADR-115: к текстовым/служебным добавлены медиа-типы (`image`/`audio`/
18
+ * `video`/`file`) — вложения сообщений. Текстовые части не меняются
19
+ * (обратная совместимость).
20
+ */
21
+ export type PartType = 'text' | 'tool_use' | 'tool_result' | 'reasoning' | 'session_reference' | 'image' | 'audio' | 'video' | 'file';
22
+ /** Медиа-типы части сообщения (ADR-115) — вложение. */
23
+ export type MediaPartType = 'image' | 'audio' | 'video' | 'file';
24
+ /**
25
+ * ADR-115 §«Модель контента»: данные медиа-части — ссылка на blob в
26
+ * blob-хранилище + метаданные. Байты в сообщении не лежат (том, ADR-116),
27
+ * поэтому часть переносима и переживает пересборку бэкапа.
28
+ */
29
+ export interface MediaPartData {
30
+ /** Путь объекта в blob-хранилище (`attachments/<sha2>/<sha256>`). */
31
+ blobPath: string;
32
+ /** SHA-256 содержимого (content-addressed, дедуп/GC). */
33
+ sha256: string;
34
+ /** MIME-тип по содержимому. */
35
+ mime: string;
36
+ /** Размер в байтах. */
37
+ size: number;
38
+ /** Имя файла (санитайз; в `blobPath` не входит). */
39
+ name?: string;
40
+ /** Ширина изображения/кадра, px. */
41
+ width?: number;
42
+ /** Высота изображения/кадра, px. */
43
+ height?: number;
44
+ /** Длительность аудио/видео, мс. */
45
+ durationMs?: number;
46
+ /**
47
+ * Текстовая расшифровка (ASR/OCR/извлечение из документа) — подставляется
48
+ * в контекст вместо байтов.
49
+ */
50
+ transcript?: string;
51
+ }
14
52
  export interface Part {
15
53
  id: string;
16
54
  type: PartType;
@@ -53,6 +91,12 @@ export interface Message {
53
91
  reasoning?: string;
54
92
  source?: 'web' | 'cli' | 'api';
55
93
  author?: string;
94
+ /**
95
+ * ADR-106 Ф0: принципал ввода (аддитивное поле). `author` остаётся
96
+ * display-строкой для UI — принципал даёт машиночитаемую атрибуцию
97
+ * («кто это сделал») без изменения существующих потребителей.
98
+ */
99
+ principal?: AuthorityPrincipal;
56
100
  agentRole?: string;
57
101
  metadata?: Record<string, unknown>;
58
102
  /** ADR-070 §2.4: предсказание/валидация prompt-cache для этого хода. */