@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.
- package/dist/config/defaults.js +49 -3
- package/dist/config/env-overrides.d.ts +4 -1
- package/dist/config/env-overrides.js +37 -4
- package/dist/config/index.d.ts +3 -0
- package/dist/config/index.js +3 -0
- package/dist/config/loader.js +19 -0
- package/dist/config/proxy.d.ts +415 -0
- package/dist/config/proxy.js +1565 -0
- package/dist/config/resolve.d.ts +67 -0
- package/dist/config/resolve.js +187 -1
- package/dist/config/tls-runtime.d.ts +78 -0
- package/dist/config/tls-runtime.js +356 -0
- package/dist/config/tls.d.ts +215 -0
- package/dist/config/tls.js +394 -0
- package/dist/config/types.d.ts +1536 -50
- package/dist/config/types.js +273 -7
- package/dist/i18n/index.d.ts +1 -1
- package/dist/i18n/index.js +2 -0
- package/dist/index.d.ts +11 -2
- package/dist/index.js +11 -2
- package/dist/protocols/index.d.ts +0 -1
- package/dist/schemas/index.d.ts +134 -9
- package/dist/schemas/index.js +51 -4
- package/dist/types/analytics.d.ts +113 -0
- package/dist/types/analytics.js +61 -0
- package/dist/types/egress.d.ts +114 -0
- package/dist/types/egress.js +68 -0
- package/dist/types/events.d.ts +0 -1
- package/dist/types/fs.d.ts +11 -0
- package/dist/types/fs.js +11 -0
- package/dist/types/hooks.d.ts +20 -0
- package/dist/types/index.d.ts +3 -0
- package/dist/types/index.js +6 -0
- package/dist/types/maintenance.d.ts +39 -0
- package/dist/types/maintenance.js +11 -0
- package/dist/types/mcp.d.ts +68 -3
- package/dist/types/mcp.js +83 -4
- package/dist/types/permission.d.ts +7 -5
- package/dist/types/prompt.d.ts +3 -2
- package/dist/types/session.d.ts +0 -1
- package/dist/types/webhooks.d.ts +1 -1
- package/dist/utils/index.d.ts +15 -0
- package/dist/utils/index.js +53 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Egress-политика исходящих запросов (web/инструкции/скиллы/webhooks/providers/MCP).
|
|
3
|
+
*
|
|
4
|
+
* Единый формат политики (`mode` + `list` + `exceptions`) используется всеми
|
|
5
|
+
* потребителями; `webhooks` дополнительно поддерживает `mode: 'off'` (dev, без
|
|
6
|
+
* проверок и без требования https). Семантика:
|
|
7
|
+
* - `exceptions` — allow-правила, проверяются **первыми** (точный hostname,
|
|
8
|
+
* `*.suffix`, CIDR/IP); hostname-правило разрешает сразу, CIDR — по резолву;
|
|
9
|
+
* - `deny` + `list` — блок, если хотя бы один resolved-адрес в `list`;
|
|
10
|
+
* - `allow` + `list` — разрешено, если ВСЕ resolved-адреса в `list` (или exception);
|
|
11
|
+
* - `off` (только webhooks) — проверок нет, `requireHttps = false`.
|
|
12
|
+
*
|
|
13
|
+
* Литеральные `localhost`/`*.localhost`/`*.local`/`*.internal` и приватные IP
|
|
14
|
+
* блокируются самой политикой (дефолтный `list`), а не отдельным зашитым списком;
|
|
15
|
+
* exception может их разрешить.
|
|
16
|
+
*
|
|
17
|
+
* Дефолтный `list` — **общий канонический список** `DEFAULT_MCP_PRIVATE_CIDRS`
|
|
18
|
+
* (`types/mcp.ts`): он же — дефолт `mcp.networkPolicy` и встроенный fallback
|
|
19
|
+
* `engine/net/egress-guard.ts`. Списков «заблокированных адресов» в коде больше
|
|
20
|
+
* нет, поэтому расширять блокировки нужно только этот список.
|
|
21
|
+
*/
|
|
22
|
+
import { DEFAULT_MCP_PRIVATE_CIDRS } from './mcp.js';
|
|
23
|
+
export const EGRESS_POLICY_MODES = ['deny', 'allow'];
|
|
24
|
+
export const WEBHOOKS_EGRESS_POLICY_MODES = ['deny', 'allow', 'off'];
|
|
25
|
+
/** Скоупы настраиваемой egress-политики (settings/egress). */
|
|
26
|
+
export const EGRESS_POLICY_SCOPES = ['tools', 'webhooks'];
|
|
27
|
+
/**
|
|
28
|
+
* Дефолтная политика встроенных инструментов: deny служебных диапазонов
|
|
29
|
+
* (`DEFAULT_MCP_PRIVATE_CIDRS` — общий канонический список, см. `types/mcp.ts`).
|
|
30
|
+
*/
|
|
31
|
+
export const DEFAULT_EGRESS_TOOLS_POLICY = {
|
|
32
|
+
mode: 'deny',
|
|
33
|
+
list: [...DEFAULT_MCP_PRIVATE_CIDRS],
|
|
34
|
+
exceptions: [],
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* Дефолтная политика webhooks: deny служебных диапазонов (тот же общий список)
|
|
38
|
+
* + обязательный https.
|
|
39
|
+
*/
|
|
40
|
+
export const DEFAULT_EGRESS_WEBHOOKS_POLICY = {
|
|
41
|
+
mode: 'deny',
|
|
42
|
+
list: [...DEFAULT_MCP_PRIVATE_CIDRS],
|
|
43
|
+
exceptions: [],
|
|
44
|
+
};
|
|
45
|
+
/** Дефолт журнала внешних запросов: включён, хранить 7 дней. */
|
|
46
|
+
export const DEFAULT_EGRESS_LOG = {
|
|
47
|
+
enabled: true,
|
|
48
|
+
retentionDays: 7,
|
|
49
|
+
};
|
|
50
|
+
/** Скоупы (источники) внешних запросов в журнале egress. */
|
|
51
|
+
export const EGRESS_REQUEST_SCOPES = [
|
|
52
|
+
'web_fetch',
|
|
53
|
+
'web_search',
|
|
54
|
+
'skills',
|
|
55
|
+
'instructions',
|
|
56
|
+
'webhooks',
|
|
57
|
+
'providers',
|
|
58
|
+
'mcp',
|
|
59
|
+
];
|
|
60
|
+
export const EGRESS_REQUEST_STATUSES = ['allowed', 'blocked', 'error'];
|
|
61
|
+
/**
|
|
62
|
+
* ADR-099 (D1): фактический маршрут запроса — через прокси, напрямую либо
|
|
63
|
+
* direct-фоллбек после недоступного прокси (`proxy.fallbackDirect`).
|
|
64
|
+
*/
|
|
65
|
+
export const EGRESS_REQUEST_VIAS = ['proxy', 'direct', 'fallback'];
|
|
66
|
+
/** Скоупы изменений egress-политик/прокси в security-аудите. */
|
|
67
|
+
export const SECURITY_AUDIT_SCOPES = ['tools', 'webhooks', 'mcp', 'proxy', 'tls'];
|
|
68
|
+
export const SECURITY_AUDIT_ACTIONS = ['update', 'reset'];
|
package/dist/types/events.d.ts
CHANGED
|
@@ -208,7 +208,6 @@ export interface SessionRequest {
|
|
|
208
208
|
icon?: string;
|
|
209
209
|
/** Канонический ключ цвета (PROJECT_COLOR_KEYS). */
|
|
210
210
|
color?: string;
|
|
211
|
-
engine?: string;
|
|
212
211
|
/** Происхождение сессии (`user`/`fork`/`subagent`) — паритет с createSession. */
|
|
213
212
|
sessionOrigin?: SessionOrigin;
|
|
214
213
|
settings?: Partial<SessionSettings>;
|
package/dist/types/fs.d.ts
CHANGED
|
@@ -42,3 +42,14 @@ export interface FsError {
|
|
|
42
42
|
error: string;
|
|
43
43
|
code: FsErrorCode;
|
|
44
44
|
}
|
|
45
|
+
/**
|
|
46
|
+
* Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
|
|
47
|
+
* Щедро, но ограничивает DoS (тело буферизуется в память целиком). Переопределяется
|
|
48
|
+
* конфигом (`storage.maxUploadBytes` / env `SYNTH_MAX_UPLOAD_BYTES`) или опцией
|
|
49
|
+
* фабрики `createFsRoutes` (`FsRoutesOptions.maxUploadBytes`, для тестов).
|
|
50
|
+
*/
|
|
51
|
+
export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
|
|
52
|
+
/** Нижняя граница настраиваемого лимита загрузки (байт) — нельзя «залимитировать всё». */
|
|
53
|
+
export declare const MIN_UPLOAD_BYTES = 1024;
|
|
54
|
+
/** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
|
|
55
|
+
export declare const MAX_UPLOAD_BYTES_LIMIT: number;
|
package/dist/types/fs.js
CHANGED
|
@@ -14,3 +14,14 @@ export var FsErrorCode;
|
|
|
14
14
|
/** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
|
|
15
15
|
FsErrorCode["WORKSPACE_OUTSIDE_ROOT_DENIED"] = "WORKSPACE_OUTSIDE_ROOT_DENIED";
|
|
16
16
|
})(FsErrorCode || (FsErrorCode = {}));
|
|
17
|
+
/**
|
|
18
|
+
* Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
|
|
19
|
+
* Щедро, но ограничивает DoS (тело буферизуется в память целиком). Переопределяется
|
|
20
|
+
* конфигом (`storage.maxUploadBytes` / env `SYNTH_MAX_UPLOAD_BYTES`) или опцией
|
|
21
|
+
* фабрики `createFsRoutes` (`FsRoutesOptions.maxUploadBytes`, для тестов).
|
|
22
|
+
*/
|
|
23
|
+
export const DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
|
|
24
|
+
/** Нижняя граница настраиваемого лимита загрузки (байт) — нельзя «залимитировать всё». */
|
|
25
|
+
export const MIN_UPLOAD_BYTES = 1024;
|
|
26
|
+
/** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
|
|
27
|
+
export const MAX_UPLOAD_BYTES_LIMIT = 2 * 1024 * 1024 * 1024;
|
package/dist/types/hooks.d.ts
CHANGED
|
@@ -17,6 +17,17 @@ export interface HookResult {
|
|
|
17
17
|
reason?: string;
|
|
18
18
|
patch?: Record<string, unknown>;
|
|
19
19
|
}
|
|
20
|
+
/**
|
|
21
|
+
* PROP-102: оси атрибуции для сборщиков аналитики (`user`/`project`) — заполняются
|
|
22
|
+
* на месте эмита, где значения уже под рукой (без чтения сессии в подписчике).
|
|
23
|
+
* Необязательны: без них подписчик резолвит сессию по id (если она ещё есть).
|
|
24
|
+
*/
|
|
25
|
+
export interface HookAnalyticsAxes {
|
|
26
|
+
/** Владелец/пользователь сессии (`Session.userId`), ось `user`. */
|
|
27
|
+
userId?: string;
|
|
28
|
+
/** Проект сессии (`Session.projectId`), ось `project`. */
|
|
29
|
+
projectId?: string;
|
|
30
|
+
}
|
|
20
31
|
/** ADR-030: карта контекста по имени хука (минимально необходимые поля). */
|
|
21
32
|
export interface HookContextMap {
|
|
22
33
|
pre_tool_use: {
|
|
@@ -29,15 +40,24 @@ export interface HookContextMap {
|
|
|
29
40
|
input: unknown;
|
|
30
41
|
output?: unknown;
|
|
31
42
|
duration: number;
|
|
43
|
+
/** PROP-102: сессия вызова и оси атрибуции активности (ADR-030). */
|
|
44
|
+
sessionId?: string;
|
|
45
|
+
userId?: string;
|
|
46
|
+
projectId?: string;
|
|
32
47
|
};
|
|
33
48
|
session_start: {
|
|
34
49
|
sessionId: string;
|
|
35
50
|
projectId?: string;
|
|
36
51
|
agent?: string;
|
|
52
|
+
userId?: string;
|
|
37
53
|
};
|
|
38
54
|
session_end: {
|
|
39
55
|
sessionId: string;
|
|
40
56
|
summary?: string;
|
|
57
|
+
userId?: string;
|
|
58
|
+
projectId?: string;
|
|
59
|
+
/** PROP-102: сессия архивирована (а не удалена) — мера `sessions_archived`. */
|
|
60
|
+
archived?: boolean;
|
|
41
61
|
};
|
|
42
62
|
plan_approved: {
|
|
43
63
|
sessionId: string;
|
package/dist/types/index.d.ts
CHANGED
package/dist/types/index.js
CHANGED
|
@@ -47,3 +47,9 @@ export * from './decision.js';
|
|
|
47
47
|
export * from './service-keys.js';
|
|
48
48
|
// ADR-052 (этап II): исходящие webhooks — типы и матчер событий — re-exported from webhooks.ts
|
|
49
49
|
export * from './webhooks.js';
|
|
50
|
+
// ADR-092 (остаток): аудит-журнал обслуживания инстанса — re-exported from maintenance.ts
|
|
51
|
+
export * from './maintenance.js';
|
|
52
|
+
// Egress-политика, журнал внешних запросов и аудит security-политик
|
|
53
|
+
export * from './egress.js';
|
|
54
|
+
// Аналитика и отчётность инстанса: суточные роллапы (PROP-102)
|
|
55
|
+
export * from './analytics.js';
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR-092 (остаток): аудит-журнал обслуживания инстанса.
|
|
3
|
+
*
|
|
4
|
+
* Append-only журнал операций жизненного цикла (`synth backup`/`restore`/
|
|
5
|
+
* `migrate`/`update`/`rollback`/`uninstall`, экспорт/импорт) — «что, когда и
|
|
6
|
+
* кем» менялось в инстансе. Журнал не является частью доменных данных: его
|
|
7
|
+
* события лишь фиксируют факт операции и её итог. Хранилище — доменный порт
|
|
8
|
+
* `MaintenanceAuditRepository` (ADR-096), файловая реализация —
|
|
9
|
+
* `{dataDir}/audit/maintenance.jsonl`.
|
|
10
|
+
*/
|
|
11
|
+
/** ADR-092: вид операции обслуживания инстанса. */
|
|
12
|
+
export type MaintenanceAuditOp = 'backup.created' | 'backup.failed' | 'backup.deleted' | 'restore.scheduled' | 'restore.cancelled' | 'restore.applied' | 'restore.failed' | 'migrate.applied' | 'migrate.failed' | 'update.applied' | 'rollback.applied' | 'update.failed' | 'uninstall.purge' | 'export.created' | 'import.applied' | 'restart.requested';
|
|
13
|
+
/** ADR-092: итог операции обслуживания. */
|
|
14
|
+
export type MaintenanceAuditStatus = 'ok' | 'failed' | 'scheduled';
|
|
15
|
+
/**
|
|
16
|
+
* ADR-092: одна запись аудит-журнала обслуживания инстанса.
|
|
17
|
+
*
|
|
18
|
+
* Пишется best-effort (ошибка записи не ломает операцию). `id` формирует
|
|
19
|
+
* вызывающий (`ma_<uuid>`), `ts` — ISO-8601. `actor` — инициатор (`userId` при
|
|
20
|
+
* API/UI, `'cli'` при командной строке, `'startup'` при применении на старте).
|
|
21
|
+
*/
|
|
22
|
+
export interface MaintenanceAuditEntry {
|
|
23
|
+
/** `ma_<uuid>`, уникален в пределах инстанса. */
|
|
24
|
+
id: string;
|
|
25
|
+
/** Метка события, ISO-8601. */
|
|
26
|
+
ts: string;
|
|
27
|
+
/** Вид операции обслуживания. */
|
|
28
|
+
op: MaintenanceAuditOp;
|
|
29
|
+
/** Итог операции. */
|
|
30
|
+
status: MaintenanceAuditStatus;
|
|
31
|
+
/** Инициатор: `userId` (API/UI) | `'cli'` | `'startup'`. */
|
|
32
|
+
actor?: string;
|
|
33
|
+
/** Версия пакета (`SYNTH_VERSION`) на момент операции. */
|
|
34
|
+
version?: string;
|
|
35
|
+
/** Детали операции (поля зависят от `op`). */
|
|
36
|
+
details?: Record<string, unknown>;
|
|
37
|
+
/** Текст ошибки при `status === 'failed'`. */
|
|
38
|
+
error?: string;
|
|
39
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ADR-092 (остаток): аудит-журнал обслуживания инстанса.
|
|
3
|
+
*
|
|
4
|
+
* Append-only журнал операций жизненного цикла (`synth backup`/`restore`/
|
|
5
|
+
* `migrate`/`update`/`rollback`/`uninstall`, экспорт/импорт) — «что, когда и
|
|
6
|
+
* кем» менялось в инстансе. Журнал не является частью доменных данных: его
|
|
7
|
+
* события лишь фиксируют факт операции и её итог. Хранилище — доменный порт
|
|
8
|
+
* `MaintenanceAuditRepository` (ADR-096), файловая реализация —
|
|
9
|
+
* `{dataDir}/audit/maintenance.jsonl`.
|
|
10
|
+
*/
|
|
11
|
+
export {};
|
package/dist/types/mcp.d.ts
CHANGED
|
@@ -51,10 +51,75 @@ export type McpNetworkPolicyMode = (typeof MCP_NETWORK_POLICY_MODES)[number];
|
|
|
51
51
|
export interface McpNetworkPolicy {
|
|
52
52
|
mode: McpNetworkPolicyMode;
|
|
53
53
|
list: string[];
|
|
54
|
+
/**
|
|
55
|
+
* Allow-правила-исключения (точный hostname, `*.suffix`, CIDR/IP).
|
|
56
|
+
* Проверяются первыми; формат/семантика общие с `egress.tools`/`egress.webhooks`.
|
|
57
|
+
*/
|
|
58
|
+
exceptions?: string[];
|
|
54
59
|
}
|
|
55
|
-
/**
|
|
56
|
-
|
|
57
|
-
|
|
60
|
+
/**
|
|
61
|
+
* Служебные/специальные адресные диапазоны, запрещённые по умолчанию (SSRF/egress).
|
|
62
|
+
*
|
|
63
|
+
* **Единственный источник истины** для всех egress-политик: `mcp.networkPolicy`,
|
|
64
|
+
* `egress.tools`, `egress.webhooks` (`types/egress.ts`) и встроенный fallback
|
|
65
|
+
* guard'а (`core/engine/net/egress-guard.ts` → `isBlockedIp` без политики).
|
|
66
|
+
* Отдельных списков «заблокированных адресов» в коде больше нет: расширять
|
|
67
|
+
* нужно этот список, иначе политика и guard разойдутся (промис не будет
|
|
68
|
+
* подкреплён кодом).
|
|
69
|
+
*
|
|
70
|
+
* **Правило отбора:** диапазоны, которые не маршрутизируются в публичном
|
|
71
|
+
* интернете (IANA IPv4/IPv6 Special-Purpose Address Registry) либо непригодны
|
|
72
|
+
* как цель исходящего HTTP-запроса (multicast, limited broadcast).
|
|
73
|
+
*
|
|
74
|
+
* IPv4:
|
|
75
|
+
* - `0.0.0.0/8` — «this network»; `0.0.0.0` на Linux ведёт на localhost;
|
|
76
|
+
* - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` — RFC1918 (private);
|
|
77
|
+
* - `100.64.0.0/10` — CGNAT (RFC 6598); в ряде облаков это адрес метаданных
|
|
78
|
+
* (напр. Alibaba `100.100.100.200`);
|
|
79
|
+
* - `127.0.0.0/8` — loopback;
|
|
80
|
+
* - `169.254.0.0/16` — link-local (в т.ч. `169.254.169.254` — метаданные облака);
|
|
81
|
+
* - `192.0.0.0/24` — IETF protocol assignments (RFC 6890), включая well-known
|
|
82
|
+
* NAT64-префиксы `192.0.0.170/171` (RFC 6052): через них внутренний IPv4
|
|
83
|
+
* достигается по IPv6-адресу и v4-список его не ловит;
|
|
84
|
+
* - `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` — TEST-NET-1/2/3
|
|
85
|
+
* (RFC 5737): SSRF-риска не несут (не маршрутизируются), но заблокированы
|
|
86
|
+
* вместе со всеми прочими служебными диапазонами — список самосогласован
|
|
87
|
+
* («всё специальное»), риск-оценка не нужна по каждому адресу, а вернуть
|
|
88
|
+
* конкретный адрес можно явным exception политики;
|
|
89
|
+
* - `192.88.99.0/24` — 6to4 relay anycast (RFC 7526, deprecated);
|
|
90
|
+
* - `198.18.0.0/15` — benchmarking (RFC 2544);
|
|
91
|
+
* - `224.0.0.0/4` — multicast: цель для SSRF во внутренние multicast-группы
|
|
92
|
+
* (mDNS/SSDP и т.п.);
|
|
93
|
+
* - `240.0.0.0/4` — reserved (RFC 1112);
|
|
94
|
+
* - `255.255.255.255/32` — limited broadcast.
|
|
95
|
+
*
|
|
96
|
+
* IPv6:
|
|
97
|
+
* - `::/128` — unspecified, на части стеков эквивалентен loopback;
|
|
98
|
+
* - `::1/128` — loopback;
|
|
99
|
+
* - `::ffff:0:0/96` — IPv4-mapped IPv6. Mapped-запись — типичная попытка обхода
|
|
100
|
+
* (v4-диапазоны её не ловят), легитимные адреса приходят обычным v4/v6,
|
|
101
|
+
* поэтому mapped-форма блокируется целиком; `isIpInCidr` дополнительно
|
|
102
|
+
* приводит mapped к вложенному IPv4 (`::ffff:127.0.0.1` ← `127.0.0.0/8`);
|
|
103
|
+
* - `100::/64` — discard-only (RFC 6666);
|
|
104
|
+
* - `2001:2::/48` — benchmarking (IPv6);
|
|
105
|
+
* - `2001:db8::/32` — documentation (IPv6);
|
|
106
|
+
* - `2002::/16` — 6to4 (RFC 7526, deprecated): адрес вшивает IPv4, поэтому
|
|
107
|
+
* недостижим для v4-списка;
|
|
108
|
+
* - `fc00::/7` — ULA;
|
|
109
|
+
* - `fe80::/10` — link-local;
|
|
110
|
+
* - `ff00::/8` — multicast.
|
|
111
|
+
*
|
|
112
|
+
* Осознанно НЕ включены (иначе ломается легитимный egress):
|
|
113
|
+
* - `64:ff9b::/96` (NAT64 well-known prefix) и `64:ff9b:1::/48` (local-use
|
|
114
|
+
* NAT64, RFC 8215) — на IPv6-only сетях с DNS64 резолвер отдаёт
|
|
115
|
+
* синтезированные AAAA именно из этих префиксов; их блокировка заблокировала
|
|
116
|
+
* бы весь исходящий трафик к публичным хостам;
|
|
117
|
+
* - глобально маршрутизируемые служебные блоки (`192.31.196.0/24` AS112-v4,
|
|
118
|
+
* `192.52.193.0/24` AMT, `192.175.48.0/24` AS112, `2001:4860::/32` и т.п.) —
|
|
119
|
+
* это обычные публичные адреса.
|
|
120
|
+
*/
|
|
121
|
+
export declare const DEFAULT_MCP_PRIVATE_CIDRS: readonly ["0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8", "169.254.0.0/16", "172.16.0.0/12", "192.0.0.0/24", "192.0.2.0/24", "192.88.99.0/24", "192.168.0.0/16", "198.18.0.0/15", "198.51.100.0/24", "203.0.113.0/24", "224.0.0.0/4", "240.0.0.0/4", "255.255.255.255/32", "::/128", "::1/128", "::ffff:0:0/96", "100::/64", "2001:2::/48", "2001:db8::/32", "2002::/16", "fc00::/7", "fe80::/10", "ff00::/8"];
|
|
122
|
+
/** Дефолтная политика: deny служебных диапазонов (ADR-071 §2.3.1). */
|
|
58
123
|
export declare const DEFAULT_MCP_NETWORK_POLICY: McpNetworkPolicy;
|
|
59
124
|
export declare const MCP_SERVER_LEVELS: readonly ["system", "project", "session"];
|
|
60
125
|
export type McpServerLevel = (typeof MCP_SERVER_LEVELS)[number];
|
package/dist/types/mcp.js
CHANGED
|
@@ -4,21 +4,100 @@ 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
|
-
/**
|
|
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
|
-
'
|
|
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
|
|
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'];
|
|
@@ -39,13 +39,15 @@ export interface PermissionDecision {
|
|
|
39
39
|
/**
|
|
40
40
|
* ADR-070 §2.9.1: тул недоступен не по жёсткому запрету, а из-за текущего
|
|
41
41
|
* режима (`mode`), роли агента (`role`), отсутствия внешней программы
|
|
42
|
-
* окружения (`dependency`)
|
|
43
|
-
* (`workspace`)
|
|
44
|
-
*
|
|
45
|
-
*
|
|
42
|
+
* окружения (`dependency`), не заданного рабочего каталога проекта
|
|
43
|
+
* (`workspace`) или недоступного хранилища (`storage`, PROP-032 W5 —
|
|
44
|
+
* деградированный read-only режим). Отличие от `deny`-политики: доступ
|
|
45
|
+
* открывается переключением режима / делегированием / установкой программы /
|
|
46
|
+
* заданием workspace / восстановлением хранилища, поэтому модель получает
|
|
47
|
+
* соответствующую подсказку (messageId).
|
|
46
48
|
*/
|
|
47
49
|
unavailable?: {
|
|
48
|
-
reason: 'mode' | 'role' | 'dependency' | 'workspace';
|
|
50
|
+
reason: 'mode' | 'role' | 'dependency' | 'workspace' | 'storage';
|
|
49
51
|
};
|
|
50
52
|
}
|
|
51
53
|
/**
|
package/dist/types/prompt.d.ts
CHANGED
|
@@ -109,9 +109,10 @@ export interface PromptToolDetail {
|
|
|
109
109
|
* Причина недоступности: `mode` (переключить режим), `role` (делегировать),
|
|
110
110
|
* `admin_disabled` (жёстко отключён администратором через `tools.disabled`),
|
|
111
111
|
* `dependency` (в окружении нет нужной программы — git/rg/sh),
|
|
112
|
-
* `workspace` (не задан рабочий каталог проекта)
|
|
112
|
+
* `workspace` (не задан рабочий каталог проекта),
|
|
113
|
+
* `storage` (хранилище недоступно — деградированный read-only режим, PROP-032).
|
|
113
114
|
*/
|
|
114
|
-
reason?: 'mode' | 'role' | 'admin_disabled' | 'dependency' | 'workspace';
|
|
115
|
+
reason?: 'mode' | 'role' | 'admin_disabled' | 'dependency' | 'workspace' | 'storage';
|
|
115
116
|
/** ADR-071 §2.1: источник инструмента (`built-in` — слой `tools`). */
|
|
116
117
|
source: 'built-in';
|
|
117
118
|
/** ADR-071 §2.6: длина `JSON.stringify` LLM-определения тула (как слой `tools`). */
|
package/dist/types/session.d.ts
CHANGED
package/dist/types/webhooks.d.ts
CHANGED
|
@@ -33,7 +33,7 @@ export interface WebhookSubscription {
|
|
|
33
33
|
/** Обязательная метка (уникальна глобально по инстансу, регистронезависимо). */
|
|
34
34
|
label: string;
|
|
35
35
|
description?: string;
|
|
36
|
-
/** Целевой URL (https; http — только при `webhooks.
|
|
36
|
+
/** Целевой URL (https; http — только при `egress.webhooks.mode: 'off'`). */
|
|
37
37
|
url: string;
|
|
38
38
|
/** Паттерны событий (exact или `prefix.*`); пусто — дефолтный набор. */
|
|
39
39
|
events: string[];
|
package/dist/utils/index.d.ts
CHANGED
|
@@ -4,6 +4,21 @@ export declare function formatISODate(date: Date): string;
|
|
|
4
4
|
export declare function nowISO(): string;
|
|
5
5
|
export declare function safeJsonParse<T>(data: string, fallback: T): T;
|
|
6
6
|
export declare function atomicWrite(writeFile: (path: string, data: string) => Promise<void>, rename: (oldPath: string, newPath: string) => Promise<void>, targetPath: string, data: string): Promise<void>;
|
|
7
|
+
/**
|
|
8
|
+
* Удаляет NUL-символы (`\u0000`) из строки. PostgreSQL не принимает U+0000
|
|
9
|
+
* ни в `text` («invalid byte sequence for encoding "UTF8": 0x00»), ни в `jsonb`
|
|
10
|
+
* (`JSON.stringify` даёт escape `\u0000` → «unsupported Unicode escape
|
|
11
|
+
* sequence»), поэтому недоверенный текст (ответ модели, вывод тулов/файлов/
|
|
12
|
+
* shell/веба) чистится до записи. Остальные символы не меняются; исходная
|
|
13
|
+
* строка возвращается, если NUL-байтов нет.
|
|
14
|
+
*/
|
|
15
|
+
export declare function stripNullBytes(value: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* Рекурсивно удаляет NUL-байты из строк в массивах/plain-объектах.
|
|
18
|
+
* `Date`, `Buffer` и прочие non-plain объекты возвращаются как есть.
|
|
19
|
+
* Если изменений нет — возвращается исходное значение (та же ссылка).
|
|
20
|
+
*/
|
|
21
|
+
export declare function stripNullBytesDeep<T>(value: T): T;
|
|
7
22
|
export declare class AsyncLock {
|
|
8
23
|
private _locked;
|
|
9
24
|
private _waiting;
|
package/dist/utils/index.js
CHANGED
|
@@ -29,6 +29,59 @@ export async function atomicWrite(writeFile, rename, targetPath, data) {
|
|
|
29
29
|
await writeFile(tmpPath, data);
|
|
30
30
|
await rename(tmpPath, targetPath);
|
|
31
31
|
}
|
|
32
|
+
// Санитизация недоверенного текста (U+0000)
|
|
33
|
+
/**
|
|
34
|
+
* Удаляет NUL-символы (`\u0000`) из строки. PostgreSQL не принимает U+0000
|
|
35
|
+
* ни в `text` («invalid byte sequence for encoding "UTF8": 0x00»), ни в `jsonb`
|
|
36
|
+
* (`JSON.stringify` даёт escape `\u0000` → «unsupported Unicode escape
|
|
37
|
+
* sequence»), поэтому недоверенный текст (ответ модели, вывод тулов/файлов/
|
|
38
|
+
* shell/веба) чистится до записи. Остальные символы не меняются; исходная
|
|
39
|
+
* строка возвращается, если NUL-байтов нет.
|
|
40
|
+
*/
|
|
41
|
+
export function stripNullBytes(value) {
|
|
42
|
+
return value.includes('\u0000') ? value.replace(/\u0000/g, '') : value;
|
|
43
|
+
}
|
|
44
|
+
/** Обычный объект-литерал (`{}` или `Object.create(null)`), не класс/Date/Buffer. */
|
|
45
|
+
function isPlainObjectValue(value) {
|
|
46
|
+
const proto = Object.getPrototypeOf(value);
|
|
47
|
+
return proto === Object.prototype || proto === null;
|
|
48
|
+
}
|
|
49
|
+
function stripNullBytesDeepInternal(value) {
|
|
50
|
+
if (typeof value === 'string')
|
|
51
|
+
return stripNullBytes(value);
|
|
52
|
+
if (Array.isArray(value)) {
|
|
53
|
+
let changed = false;
|
|
54
|
+
const result = value.map((item) => {
|
|
55
|
+
const next = stripNullBytesDeepInternal(item);
|
|
56
|
+
if (next !== item)
|
|
57
|
+
changed = true;
|
|
58
|
+
return next;
|
|
59
|
+
});
|
|
60
|
+
return changed ? result : value;
|
|
61
|
+
}
|
|
62
|
+
// Date/Buffer/классы/Map/Set и прочие non-plain объекты не трогаем:
|
|
63
|
+
// их содержимое не является текстом домена.
|
|
64
|
+
if (typeof value === 'object' && value !== null && isPlainObjectValue(value)) {
|
|
65
|
+
let changed = false;
|
|
66
|
+
const result = Object.create(Object.getPrototypeOf(value));
|
|
67
|
+
for (const [key, item] of Object.entries(value)) {
|
|
68
|
+
const next = stripNullBytesDeepInternal(item);
|
|
69
|
+
if (next !== item)
|
|
70
|
+
changed = true;
|
|
71
|
+
result[key] = next;
|
|
72
|
+
}
|
|
73
|
+
return changed ? result : value;
|
|
74
|
+
}
|
|
75
|
+
return value;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Рекурсивно удаляет NUL-байты из строк в массивах/plain-объектах.
|
|
79
|
+
* `Date`, `Buffer` и прочие non-plain объекты возвращаются как есть.
|
|
80
|
+
* Если изменений нет — возвращается исходное значение (та же ссылка).
|
|
81
|
+
*/
|
|
82
|
+
export function stripNullBytesDeep(value) {
|
|
83
|
+
return stripNullBytesDeepInternal(value);
|
|
84
|
+
}
|
|
32
85
|
// Асинхронный Mutex
|
|
33
86
|
export class AsyncLock {
|
|
34
87
|
_locked = false;
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const SYNTH_VERSION = "0.
|
|
1
|
+
export declare const SYNTH_VERSION = "0.11.3";
|
package/dist/version.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const SYNTH_VERSION = '0.
|
|
1
|
+
export const SYNTH_VERSION = '0.11.3';
|