@itphx/synth-shared 0.12.4 → 0.13.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/config/defaults.js +125 -5
  2. package/dist/config/env-overrides.d.ts +23 -4
  3. package/dist/config/env-overrides.js +103 -4
  4. package/dist/config/index.d.ts +1 -0
  5. package/dist/config/index.js +1 -0
  6. package/dist/config/loader.d.ts +8 -0
  7. package/dist/config/loader.js +6 -1
  8. package/dist/config/redact.d.ts +22 -0
  9. package/dist/config/redact.js +53 -0
  10. package/dist/config/resolve.d.ts +17 -0
  11. package/dist/config/resolve.js +40 -1
  12. package/dist/config/tls.d.ts +7 -4
  13. package/dist/config/tls.js +10 -23
  14. package/dist/config/types.d.ts +496 -11
  15. package/dist/config/types.js +348 -6
  16. package/dist/i18n/index.d.ts +1 -1
  17. package/dist/i18n/index.js +317 -3
  18. package/dist/index.d.ts +4 -4
  19. package/dist/index.js +4 -4
  20. package/dist/model-metadata.d.ts +10 -0
  21. package/dist/model-metadata.js +10 -0
  22. package/dist/schemas/index.d.ts +378 -21
  23. package/dist/schemas/index.js +282 -5
  24. package/dist/types/agent.d.ts +8 -1
  25. package/dist/types/bus-events.d.ts +60 -2
  26. package/dist/types/egress.d.ts +2 -2
  27. package/dist/types/egress.js +2 -2
  28. package/dist/types/file-kind.d.ts +40 -0
  29. package/dist/types/file-kind.js +157 -0
  30. package/dist/types/fs.d.ts +54 -1
  31. package/dist/types/fs.js +43 -0
  32. package/dist/types/git.d.ts +88 -0
  33. package/dist/types/git.js +101 -1
  34. package/dist/types/host-pattern.d.ts +41 -0
  35. package/dist/types/host-pattern.js +143 -0
  36. package/dist/types/index.d.ts +4 -0
  37. package/dist/types/index.js +13 -1
  38. package/dist/types/llm.d.ts +95 -0
  39. package/dist/types/llm.js +58 -0
  40. package/dist/types/maintenance.d.ts +1 -1
  41. package/dist/types/mcp.d.ts +90 -0
  42. package/dist/types/mcp.js +11 -0
  43. package/dist/types/message-stream.d.ts +389 -0
  44. package/dist/types/message-stream.js +41 -0
  45. package/dist/types/message.d.ts +49 -0
  46. package/dist/types/pack.d.ts +6 -6
  47. package/dist/types/permission.d.ts +39 -3
  48. package/dist/types/pipeline-engine.d.ts +2 -2
  49. package/dist/types/project.d.ts +30 -0
  50. package/dist/types/project.js +16 -0
  51. package/dist/types/prompt.d.ts +4 -2
  52. package/dist/types/provider.d.ts +280 -0
  53. package/dist/types/provider.js +289 -0
  54. package/dist/types/service-keys.d.ts +6 -3
  55. package/dist/types/service-keys.js +6 -1
  56. package/dist/types/session.d.ts +178 -3
  57. package/dist/types/skills.d.ts +6 -0
  58. package/dist/types/tools.d.ts +57 -0
  59. package/dist/types/tools.js +49 -1
  60. package/dist/types/user.d.ts +7 -0
  61. package/dist/types/worktree.d.ts +1 -1
  62. package/dist/utils/index.js +1 -1
  63. package/dist/utils/reasoning.d.ts +18 -2
  64. package/dist/utils/reasoning.js +16 -7
  65. package/dist/version.d.ts +1 -1
  66. package/dist/version.js +1 -1
  67. package/package.json +4 -3
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Классификация файла проекта по расширению — **browser-safe** контракт
3
+ * (только чистые функции и константы, без `node:*` и без zod-схем): его
4
+ * импортирует UI (`@itphx/synth-shared/types`), чтобы клиент и сервер
5
+ * одинаково понимали, что за файл и можно ли его отдавать inline.
6
+ *
7
+ * Единый источник истины — здесь: `isTextFile()` в core (`server/fs-workspace.ts`)
8
+ * отвечает на другой вопрос («это текст или бинарь — по содержимому») и не
9
+ * дублируется здесь. Этот модуль отвечает на вопрос «какого семейства файл
10
+ * по расширению» (для выбора превью и MIME).
11
+ */
12
+ const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown']);
13
+ const IMAGE_EXTENSIONS = new Set([
14
+ '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.svg',
15
+ '.avif', '.tif', '.tiff',
16
+ ]);
17
+ const VIDEO_EXTENSIONS = new Set([
18
+ '.mp4', '.m4v', '.webm', '.mov', '.ogv', '.avi', '.mkv',
19
+ ]);
20
+ const AUDIO_EXTENSIONS = new Set([
21
+ '.mp3', '.wav', '.ogg', '.oga', '.flac', '.m4a', '.aac', '.opus',
22
+ ]);
23
+ const CODE_EXTENSIONS = new Set([
24
+ '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts',
25
+ '.py', '.rb', '.rs', '.go', '.java', '.kt', '.kts', '.swift',
26
+ '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.php', '.lua', '.pl', '.pm',
27
+ '.sh', '.bash', '.zsh', '.fish', '.ps1', '.bat', '.cmd',
28
+ '.vue', '.svelte', '.astro',
29
+ '.html', '.htm', '.css', '.scss', '.sass', '.less',
30
+ '.sql', '.graphql', '.gql', '.proto', '.prisma',
31
+ '.tf', '.tfvars', '.gradle', '.m', '.mm',
32
+ '.ex', '.exs', '.erl', '.hs', '.clj', '.groovy', '.dart', '.r', '.jl', '.nim', '.zig',
33
+ // Конфиги
34
+ '.yaml', '.yml', '.json', '.jsonl', '.toml', '.xml',
35
+ ]);
36
+ const TEXT_EXTENSIONS = new Set([
37
+ '.txt', '.csv', '.log', '.env', '.ini', '.cfg', '.conf',
38
+ '.rst', '.adoc', '.org',
39
+ '.tex', '.bib', '.patch', '.diff', '.srt', '.vtt',
40
+ ]);
41
+ /** Расширение пути в нижнем регистре (с точкой); без расширения — `''`. */
42
+ function extensionOf(path) {
43
+ const name = path.split(/[\\/]/).pop() ?? path;
44
+ const dot = name.lastIndexOf('.');
45
+ // Точка в начале имени (`.gitignore`) — расширения нет.
46
+ if (dot <= 0)
47
+ return '';
48
+ return name.slice(dot).toLowerCase();
49
+ }
50
+ /**
51
+ * Семейство файла по расширению (регистронезависимо).
52
+ *
53
+ * Неизвестное расширение (и файл без расширения) → `binary` — консервативно:
54
+ * такой файл нельзя отдавать inline (см. `INLINE_PREVIEW_KINDS`).
55
+ */
56
+ export function fileKind(path) {
57
+ const ext = extensionOf(path);
58
+ if (!ext)
59
+ return 'binary';
60
+ if (MARKDOWN_EXTENSIONS.has(ext))
61
+ return 'markdown';
62
+ if (IMAGE_EXTENSIONS.has(ext))
63
+ return 'image';
64
+ if (VIDEO_EXTENSIONS.has(ext))
65
+ return 'video';
66
+ if (AUDIO_EXTENSIONS.has(ext))
67
+ return 'audio';
68
+ if (ext === '.pdf')
69
+ return 'pdf';
70
+ if (CODE_EXTENSIONS.has(ext))
71
+ return 'code';
72
+ if (TEXT_EXTENSIONS.has(ext))
73
+ return 'text';
74
+ return 'binary';
75
+ }
76
+ /** MIME по расширению; `binary`/неизвестное → `application/octet-stream`. */
77
+ const MIME_BY_EXTENSION = {
78
+ // Изображения
79
+ '.png': 'image/png',
80
+ '.jpg': 'image/jpeg',
81
+ '.jpeg': 'image/jpeg',
82
+ '.gif': 'image/gif',
83
+ '.webp': 'image/webp',
84
+ '.bmp': 'image/bmp',
85
+ '.ico': 'image/x-icon',
86
+ '.svg': 'image/svg+xml',
87
+ '.avif': 'image/avif',
88
+ '.tif': 'image/tiff',
89
+ '.tiff': 'image/tiff',
90
+ // Видео
91
+ '.mp4': 'video/mp4',
92
+ '.m4v': 'video/mp4',
93
+ '.webm': 'video/webm',
94
+ '.mov': 'video/quicktime',
95
+ '.ogv': 'video/ogg',
96
+ '.avi': 'video/x-msvideo',
97
+ '.mkv': 'video/x-matroska',
98
+ // Аудио
99
+ '.mp3': 'audio/mpeg',
100
+ '.wav': 'audio/wav',
101
+ '.ogg': 'audio/ogg',
102
+ '.oga': 'audio/ogg',
103
+ '.flac': 'audio/flac',
104
+ '.m4a': 'audio/mp4',
105
+ '.aac': 'audio/aac',
106
+ '.opus': 'audio/opus',
107
+ // Документы
108
+ '.pdf': 'application/pdf',
109
+ // Текст/код
110
+ '.md': 'text/markdown',
111
+ '.markdown': 'text/markdown',
112
+ '.mdown': 'text/markdown',
113
+ '.json': 'application/json',
114
+ '.jsonl': 'application/json',
115
+ '.xml': 'application/xml',
116
+ '.yaml': 'application/yaml',
117
+ '.yml': 'application/yaml',
118
+ '.toml': 'application/toml',
119
+ '.csv': 'text/csv',
120
+ '.html': 'text/html',
121
+ '.htm': 'text/html',
122
+ '.css': 'text/css',
123
+ '.js': 'text/javascript',
124
+ '.mjs': 'text/javascript',
125
+ '.cjs': 'text/javascript',
126
+ };
127
+ /**
128
+ * MIME-тип файла по расширению (регистронезависимо).
129
+ *
130
+ * `binary`/неизвестное расширение → `application/octet-stream`; текст, код и
131
+ * markdown → `text/plain` (или точный MIME из таблицы выше).
132
+ *
133
+ * ⚠️ MIME **не** определяет, можно ли отдавать файл inline: этим занимается
134
+ * allow-list `INLINE_PREVIEW_KINDS` (см. `GET /api/v2/fs/raw`).
135
+ */
136
+ export function fileMime(path) {
137
+ const ext = extensionOf(path);
138
+ if (!ext)
139
+ return 'application/octet-stream';
140
+ const known = MIME_BY_EXTENSION[ext];
141
+ if (known)
142
+ return known;
143
+ const kind = fileKind(path);
144
+ if (kind === 'markdown' || kind === 'code' || kind === 'text')
145
+ return 'text/plain';
146
+ return 'application/octet-stream';
147
+ }
148
+ /**
149
+ * Семейства файлов, которые разрешено отдавать **inline** (в `<img>`,
150
+ * `<video>`, `<audio>`, `<embed>`), а не как вложение.
151
+ *
152
+ * HTML/CSS/JS и прочий текст/код **в списке нет** — иначе `text/html`
153
+ * исполнился бы в origin приложения (XSS). Правило — на сервере:
154
+ * `GET /api/v2/fs/raw` для kind вне списка отдаёт `application/octet-stream`
155
+ * + `Content-Disposition: attachment`.
156
+ */
157
+ export const INLINE_PREVIEW_KINDS = ['image', 'video', 'audio', 'pdf'];
@@ -10,7 +10,13 @@ export declare enum FsErrorCode {
10
10
  ALREADY_EXISTS = "ALREADY_EXISTS",
11
11
  DIR_NOT_EMPTY = "DIR_NOT_EMPTY",
12
12
  /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
13
- WORKSPACE_OUTSIDE_ROOT_DENIED = "WORKSPACE_OUTSIDE_ROOT_DENIED"
13
+ WORKSPACE_OUTSIDE_ROOT_DENIED = "WORKSPACE_OUTSIDE_ROOT_DENIED",
14
+ /**
15
+ * Чтение файла отказано: размер больше лимита чтения либо файл бинарный
16
+ * (HTTP 413). Машинный код ответа — `FILE_TOO_LARGE`, подробности —
17
+ * в `details` (`maxReadBytes`/`size`/`reason`).
18
+ */
19
+ FILE_TOO_LARGE = "FILE_TOO_LARGE"
14
20
  }
15
21
  export interface FileEntry {
16
22
  name: string;
@@ -22,6 +28,11 @@ export interface FileEntry {
22
28
  export interface DirectoryListResult {
23
29
  path: string;
24
30
  entries: FileEntry[];
31
+ /**
32
+ * Обход прерван по лимиту записей (`maxDepth > 0`): ответ — неполный.
33
+ * `maxDepth = 0` (по умолчанию) лимит не применяется → `false`.
34
+ */
35
+ truncated?: boolean;
25
36
  }
26
37
  export interface FileReadResult {
27
38
  path: string;
@@ -41,6 +52,11 @@ export interface FileMkdirBody {
41
52
  export interface FsError {
42
53
  error: string;
43
54
  code: FsErrorCode;
55
+ /**
56
+ * Подробности отказа (аддитивно): например, `maxReadBytes`/`size`/`reason`
57
+ * для `FILE_TOO_LARGE`. Клиент читает их машинно, не разбирая текст.
58
+ */
59
+ details?: Record<string, unknown>;
44
60
  }
45
61
  /**
46
62
  * Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
@@ -53,3 +69,40 @@ export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
53
69
  export declare const MIN_UPLOAD_BYTES = 1024;
54
70
  /** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
55
71
  export declare const MAX_UPLOAD_BYTES_LIMIT: number;
72
+ /**
73
+ * Лимит чтения файла (`GET /api/v2/fs/read`) по умолчанию, байт: 5 МиБ.
74
+ * Файл больше лимита (или бинарный) → `413` с машинным кодом `FILE_TOO_LARGE`
75
+ * и `details.maxReadBytes`; содержимое в память не читается (размер известен
76
+ * из `stat`). Переопределяется конфигом (`storage.maxReadBytes` / env
77
+ * `SYNTH_MAX_READ_BYTES`) или опцией фабрики `createFsRoutes`
78
+ * (`FsRoutesOptions.maxReadBytes`, для тестов).
79
+ */
80
+ export declare const DEFAULT_MAX_READ_BYTES: number;
81
+ /** Нижняя граница настраиваемого лимита чтения (байт). */
82
+ export declare const MIN_READ_BYTES = 1024;
83
+ /** Верхняя граница настраиваемого лимита чтения (байт): 512 МиБ (файл читается в память). */
84
+ export declare const MAX_READ_BYTES_LIMIT: number;
85
+ /**
86
+ * Лимит предпросмотра файла (`GET /api/v2/fs/raw`) по умолчанию, байт: 100 МиБ.
87
+ * Медиа-файлы (видео/аудио/изображения) заметно крупнее текстовых, поэтому
88
+ * лимит предпросмотра отдельный от `DEFAULT_MAX_READ_BYTES` (5 МиБ — чтение
89
+ * текста). Файл больше лимита → `413` с машинным кодом `FILE_TOO_LARGE` и
90
+ * `details.maxPreviewBytes`. Переопределяется конфигом
91
+ * (`storage.maxPreviewBytes` / env `SYNTH_MAX_PREVIEW_BYTES`) или опцией
92
+ * фабрики `createFsRoutes` (`FsRoutesOptions.maxPreviewBytes`, для тестов).
93
+ */
94
+ export declare const DEFAULT_MAX_PREVIEW_BYTES: number;
95
+ /** Нижняя граница настраиваемого лимита предпросмотра (байт). */
96
+ export declare const MIN_PREVIEW_BYTES = 1024;
97
+ /** Верхняя граница настраиваемого лимита предпросмотра (байт): 512 МиБ. */
98
+ export declare const MAX_PREVIEW_BYTES_LIMIT: number;
99
+ /**
100
+ * Жёсткий предел глубины рекурсивного листинга (`GET /api/v2/fs?maxDepth=`):
101
+ * значение из запроса ограничивается этим числом (было 10).
102
+ */
103
+ export declare const MAX_FS_LIST_DEPTH = 3;
104
+ /**
105
+ * Общий предел числа записей в рекурсивном листинге (`GET /api/v2/fs?maxDepth>0`):
106
+ * при достижении обход прекращается, в ответе `truncated: true`.
107
+ */
108
+ export declare const MAX_FS_LIST_ENTRIES = 10000;
package/dist/types/fs.js CHANGED
@@ -13,6 +13,12 @@ export var FsErrorCode;
13
13
  FsErrorCode["DIR_NOT_EMPTY"] = "DIR_NOT_EMPTY";
14
14
  /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
15
15
  FsErrorCode["WORKSPACE_OUTSIDE_ROOT_DENIED"] = "WORKSPACE_OUTSIDE_ROOT_DENIED";
16
+ /**
17
+ * Чтение файла отказано: размер больше лимита чтения либо файл бинарный
18
+ * (HTTP 413). Машинный код ответа — `FILE_TOO_LARGE`, подробности —
19
+ * в `details` (`maxReadBytes`/`size`/`reason`).
20
+ */
21
+ FsErrorCode["FILE_TOO_LARGE"] = "FILE_TOO_LARGE";
16
22
  })(FsErrorCode || (FsErrorCode = {}));
17
23
  /**
18
24
  * Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
@@ -25,3 +31,40 @@ export const DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
25
31
  export const MIN_UPLOAD_BYTES = 1024;
26
32
  /** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
27
33
  export const MAX_UPLOAD_BYTES_LIMIT = 2 * 1024 * 1024 * 1024;
34
+ /**
35
+ * Лимит чтения файла (`GET /api/v2/fs/read`) по умолчанию, байт: 5 МиБ.
36
+ * Файл больше лимита (или бинарный) → `413` с машинным кодом `FILE_TOO_LARGE`
37
+ * и `details.maxReadBytes`; содержимое в память не читается (размер известен
38
+ * из `stat`). Переопределяется конфигом (`storage.maxReadBytes` / env
39
+ * `SYNTH_MAX_READ_BYTES`) или опцией фабрики `createFsRoutes`
40
+ * (`FsRoutesOptions.maxReadBytes`, для тестов).
41
+ */
42
+ export const DEFAULT_MAX_READ_BYTES = 5 * 1024 * 1024;
43
+ /** Нижняя граница настраиваемого лимита чтения (байт). */
44
+ export const MIN_READ_BYTES = 1024;
45
+ /** Верхняя граница настраиваемого лимита чтения (байт): 512 МиБ (файл читается в память). */
46
+ export const MAX_READ_BYTES_LIMIT = 512 * 1024 * 1024;
47
+ /**
48
+ * Лимит предпросмотра файла (`GET /api/v2/fs/raw`) по умолчанию, байт: 100 МиБ.
49
+ * Медиа-файлы (видео/аудио/изображения) заметно крупнее текстовых, поэтому
50
+ * лимит предпросмотра отдельный от `DEFAULT_MAX_READ_BYTES` (5 МиБ — чтение
51
+ * текста). Файл больше лимита → `413` с машинным кодом `FILE_TOO_LARGE` и
52
+ * `details.maxPreviewBytes`. Переопределяется конфигом
53
+ * (`storage.maxPreviewBytes` / env `SYNTH_MAX_PREVIEW_BYTES`) или опцией
54
+ * фабрики `createFsRoutes` (`FsRoutesOptions.maxPreviewBytes`, для тестов).
55
+ */
56
+ export const DEFAULT_MAX_PREVIEW_BYTES = 100 * 1024 * 1024;
57
+ /** Нижняя граница настраиваемого лимита предпросмотра (байт). */
58
+ export const MIN_PREVIEW_BYTES = 1024;
59
+ /** Верхняя граница настраиваемого лимита предпросмотра (байт): 512 МиБ. */
60
+ export const MAX_PREVIEW_BYTES_LIMIT = 512 * 1024 * 1024;
61
+ /**
62
+ * Жёсткий предел глубины рекурсивного листинга (`GET /api/v2/fs?maxDepth=`):
63
+ * значение из запроса ограничивается этим числом (было 10).
64
+ */
65
+ export const MAX_FS_LIST_DEPTH = 3;
66
+ /**
67
+ * Общий предел числа записей в рекурсивном листинге (`GET /api/v2/fs?maxDepth>0`):
68
+ * при достижении обход прекращается, в ответе `truncated: true`.
69
+ */
70
+ export const MAX_FS_LIST_ENTRIES = 10_000;
@@ -14,6 +14,38 @@ export interface GitRepoConfig {
14
14
  sshKeyId?: string;
15
15
  lastFetch?: string;
16
16
  }
17
+ /**
18
+ * PROP-124: способы использования SSH-ключа.
19
+ *
20
+ * - `git` — ключ подставляется в git-операции (`GIT_SSH_COMMAND`), как раньше;
21
+ * - `ssh` — ключ выдаётся командам вызова (режим инстанса `agent`) или
22
+ * адресным тулам (режим `tools`).
23
+ *
24
+ * Поле `usages` опционально ради обратной совместимости: у ключей, созданных
25
+ * до Ф1, его нет — при чтении нормализуется в `['git']` (fail-closed).
26
+ */
27
+ export type SSHKeyUsage = 'git' | 'ssh';
28
+ /** Канонический список типов использования SSH-ключа (PROP-124). */
29
+ export declare const SSH_KEY_USAGES: readonly ["git", "ssh"];
30
+ /**
31
+ * PROP-124: режим работы инстанса с SSH-ключами.
32
+ *
33
+ * - `tools` — ключ попадает к потребителю через argv адресных тулов (`-i`),
34
+ * политика хостов/портов на ключе обязательна;
35
+ * - `agent` — ключ выдаётся через эфемерный `ssh-agent` на время вызова,
36
+ * фильтрация по хостам не применяется (ограничение — на стороне хоста,
37
+ * `authorized_keys`).
38
+ *
39
+ * Дефолт — `tools` (fail-closed: без явного выбора ключ в окружение команд не
40
+ * попадает).
41
+ */
42
+ export type SshMode = 'tools' | 'agent';
43
+ /** Канонический список режимов инстанса (PROP-124). */
44
+ export declare const SSH_MODES: readonly ["tools", "agent"];
45
+ /** Предел числа хостов в политике ключа (PROP-124) — `allowHosts`. */
46
+ export declare const MAX_SSH_ALLOW_HOSTS = 50;
47
+ /** Предел числа портов в политике ключа (PROP-124) — `allowPorts`. */
48
+ export declare const MAX_SSH_ALLOW_PORTS = 10;
17
49
  /**
18
50
  * ADR-076: SSH-ключ агента — отдельная сущность реестра (не в
19
51
  * `AgentDefinition`). Секреты `privateKey`/`passphrase` шифруются at-rest
@@ -28,11 +60,62 @@ export interface SSHKey {
28
60
  passphrase?: string;
29
61
  /** Привязка к агентам: один ключ может обслуживать несколько агентов. */
30
62
  agentIds: string[];
63
+ /**
64
+ * PROP-124: способы использования ключа (`git`/`ssh`). Отсутствует у ключей,
65
+ * созданных до Ф1 → при чтении нормализуется в `['git']`.
66
+ */
67
+ usages?: SSHKeyUsage[];
68
+ /**
69
+ * PROP-124: политика хостов (режим `tools`): точный hostname, `*.suffix`,
70
+ * IP-литерал или CIDR. В режиме `agent` не применяется.
71
+ */
72
+ allowHosts?: string[];
73
+ /**
74
+ * PROP-124: политика портов (режим `tools`): 1..65535; пусто — 22 (ssh).
75
+ */
76
+ allowPorts?: number[];
31
77
  createdAt: string;
32
78
  updatedAt?: string;
33
79
  }
34
80
  /** Публичное представление ключа (без `privateKey`/`passphrase`). */
35
81
  export type SSHKeyMeta = Omit<SSHKey, 'privateKey' | 'passphrase'>;
82
+ /**
83
+ * PROP-124: нормализация типов использования ключа.
84
+ *
85
+ * Поле отсутствует (ключ создан до Ф1) → `['git']` (fail-closed: git-путь
86
+ * работает как раньше). Явно пустой массив сохраняется пустым — но записать
87
+ * его больше нельзя (см. `validateSshKeyPolicy`): в таких легаси-записях ключ
88
+ * не проходит гейт ни для git, ни для ssh.
89
+ */
90
+ export declare function normalizeSshKeyUsages(usages: readonly SSHKeyUsage[] | undefined): SSHKeyUsage[];
91
+ /**
92
+ * PROP-124: нормализация списка хостов — отсутствует → `[]`; элементы
93
+ * обрезаются от пробелов, пустые отбрасываются.
94
+ */
95
+ export declare function normalizeSshKeyAllowHosts(hosts: readonly string[] | undefined): string[];
96
+ /**
97
+ * PROP-124: нормализация списка портов — отсутствует → `[]`.
98
+ * Порты-дубликаты сохраняются (смысла дедуплицировать нет, порядок важен
99
+ * только для отображения).
100
+ */
101
+ export declare function normalizeSshKeyAllowPorts(ports: readonly number[] | undefined): number[];
102
+ /** Результат проверки политики SSH-ключа (PROP-124). */
103
+ export type SshKeyPolicyValidation = {
104
+ ok: true;
105
+ } | {
106
+ ok: false;
107
+ message: string;
108
+ };
109
+ /**
110
+ * PROP-124: проверка политики ключа — типы использования, правила хостов и
111
+ * порты. Fail-closed: любое нарушение → отказ с понятным сообщением
112
+ * (`message` — для ответа API `400 VALIDATION_ERROR`).
113
+ */
114
+ export declare function validateSshKeyPolicy(input: {
115
+ usages?: readonly SSHKeyUsage[];
116
+ allowHosts?: readonly string[];
117
+ allowPorts?: readonly number[];
118
+ }): SshKeyPolicyValidation;
36
119
  export interface RepoStatus {
37
120
  path: string;
38
121
  isRepo: boolean;
@@ -60,4 +143,9 @@ export interface CommitFileInfo {
60
143
  export interface CommitDetail extends CommitInfo {
61
144
  files: CommitFileInfo[];
62
145
  diff: string;
146
+ /**
147
+ * Diff обрезан по лимиту размера (`MAX_COMMIT_DIFF_BYTES`): поле присутствует
148
+ * и равно `true`, когда diff неполон. Отсутствует — diff отдан целиком.
149
+ */
150
+ diff_truncated?: boolean;
63
151
  }
package/dist/types/git.js CHANGED
@@ -1 +1,101 @@
1
- export {};
1
+ // --- Git ---
2
+ import { HOST_RULE_FORMAT_HINT, isValidHostRule } from './host-pattern.js';
3
+ /** Канонический список типов использования SSH-ключа (PROP-124). */
4
+ export const SSH_KEY_USAGES = ['git', 'ssh'];
5
+ /** Канонический список режимов инстанса (PROP-124). */
6
+ export const SSH_MODES = ['tools', 'agent'];
7
+ /** Предел числа хостов в политике ключа (PROP-124) — `allowHosts`. */
8
+ export const MAX_SSH_ALLOW_HOSTS = 50;
9
+ /** Предел числа портов в политике ключа (PROP-124) — `allowPorts`. */
10
+ export const MAX_SSH_ALLOW_PORTS = 10;
11
+ /**
12
+ * PROP-124: нормализация типов использования ключа.
13
+ *
14
+ * Поле отсутствует (ключ создан до Ф1) → `['git']` (fail-closed: git-путь
15
+ * работает как раньше). Явно пустой массив сохраняется пустым — но записать
16
+ * его больше нельзя (см. `validateSshKeyPolicy`): в таких легаси-записях ключ
17
+ * не проходит гейт ни для git, ни для ssh.
18
+ */
19
+ export function normalizeSshKeyUsages(usages) {
20
+ if (usages === undefined)
21
+ return ['git'];
22
+ return [...usages];
23
+ }
24
+ /**
25
+ * PROP-124: нормализация списка хостов — отсутствует → `[]`; элементы
26
+ * обрезаются от пробелов, пустые отбрасываются.
27
+ */
28
+ export function normalizeSshKeyAllowHosts(hosts) {
29
+ if (!hosts)
30
+ return [];
31
+ return hosts.map((host) => host.trim()).filter((host) => host !== '');
32
+ }
33
+ /**
34
+ * PROP-124: нормализация списка портов — отсутствует → `[]`.
35
+ * Порты-дубликаты сохраняются (смысла дедуплицировать нет, порядок важен
36
+ * только для отображения).
37
+ */
38
+ export function normalizeSshKeyAllowPorts(ports) {
39
+ if (!ports)
40
+ return [];
41
+ return [...ports];
42
+ }
43
+ /**
44
+ * PROP-124: проверка политики ключа — типы использования, правила хостов и
45
+ * порты. Fail-closed: любое нарушение → отказ с понятным сообщением
46
+ * (`message` — для ответа API `400 VALIDATION_ERROR`).
47
+ */
48
+ export function validateSshKeyPolicy(input) {
49
+ if (input.usages) {
50
+ // Пустой список — «ключ, который ничего не умеет»: не годен ни для git,
51
+ // ни для ssh. Запрещён на записи (и в API-схеме, и в хранилищах).
52
+ if (input.usages.length === 0) {
53
+ return {
54
+ ok: false,
55
+ message: `usages: нужен хотя бы один способ использования (${SSH_KEY_USAGES.join('|')})`,
56
+ };
57
+ }
58
+ for (const usage of input.usages) {
59
+ if (!SSH_KEY_USAGES.includes(usage)) {
60
+ return { ok: false, message: `usages: недопустимое значение "${usage}" (ожидается ${SSH_KEY_USAGES.join('|')})` };
61
+ }
62
+ }
63
+ }
64
+ if (input.allowHosts) {
65
+ if (input.allowHosts.length > MAX_SSH_ALLOW_HOSTS) {
66
+ return {
67
+ ok: false,
68
+ message: `allowHosts: не больше ${MAX_SSH_ALLOW_HOSTS} правил на ключ`,
69
+ };
70
+ }
71
+ for (const raw of input.allowHosts) {
72
+ const rule = typeof raw === 'string' ? raw.trim() : '';
73
+ if (!rule) {
74
+ return { ok: false, message: 'allowHosts: пустые правила недопустимы' };
75
+ }
76
+ if (!isValidHostRule(rule)) {
77
+ return {
78
+ ok: false,
79
+ message: `allowHosts: невалидный шаблон хоста "${rule}" — ${HOST_RULE_FORMAT_HINT}`,
80
+ };
81
+ }
82
+ }
83
+ }
84
+ if (input.allowPorts) {
85
+ if (input.allowPorts.length > MAX_SSH_ALLOW_PORTS) {
86
+ return {
87
+ ok: false,
88
+ message: `allowPorts: не больше ${MAX_SSH_ALLOW_PORTS} портов на ключ`,
89
+ };
90
+ }
91
+ for (const port of input.allowPorts) {
92
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
93
+ return {
94
+ ok: false,
95
+ message: `allowPorts: недопустимый порт "${port}" (ожидается целое 1..65535)`,
96
+ };
97
+ }
98
+ }
99
+ }
100
+ return { ok: true };
101
+ }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Единая семантика правил хоста (ADR-099 — TLS/proxy; PROP-124 — политика
3
+ * SSH-ключей).
4
+ *
5
+ * Модуль **browser-safe** (без `node:*`): его читают и роуты ядра, и UI
6
+ * (`@itphx/synth-shared/types`). Поэтому реализация `normalizeTlsHost` /
7
+ * `matchTlsHostPattern` живёт здесь, а `config/tls.ts` её переиспользует —
8
+ * второй матчер шаблонов хоста в кодовой базе не заводим (ADR-099: семантика
9
+ * шаблона хоста общая для TLS, egress-политики и SSH).
10
+ *
11
+ * Грамматика правила:
12
+ * - **точный hostname** (`git.example.com`);
13
+ * - **`*.suffix`** — только поддомены (сам `suffix` требует отдельного правила);
14
+ * - **IP-литерал** (`10.0.0.5`) и **CIDR** (`10.0.0.0/8`) — адресные правила,
15
+ * которые матчатся **только по IP-литералу** хоста (никогда по hostname);
16
+ * - одиночный **`*`** («любой хост») — **недопустим** в правилах политики
17
+ * (fail-closed): иначе исключение разрешило бы любой адрес. В TLS-профилях
18
+ * `*` допустим (см. `matchTlsHostPattern`) — там это явный выбор админа.
19
+ */
20
+ /** Нормализует host (нижний регистр, без точки в конце и скобок IPv6). */
21
+ export declare function normalizeTlsHost(rawHost: string | undefined): string | undefined;
22
+ /**
23
+ * Матчинг одного шаблона (`host` | `*.suffix` | `*`); регистронезависимо.
24
+ *
25
+ * `*` («любой хост») здесь допустим — им пользуются TLS-профили per-host
26
+ * (ADR-099). Для **политик** (`allowHosts` SSH-ключа) `*` недопустим —
27
+ * это проверяет `isValidHostRule`.
28
+ */
29
+ export declare function matchTlsHostPattern(pattern: string, rawHost: string): boolean;
30
+ /** IP-литерал любого семейства. */
31
+ export declare function isIpLiteral(value: string): boolean;
32
+ /**
33
+ * Валидна ли одна запись правила хоста: точный hostname, `*.suffix`, IP-литерал
34
+ * или CIDR. Пустые строки, regex-подобные записи и одиночный `*` — невалидны.
35
+ *
36
+ * Семантика — та же, что у egress-политики (`isValidEgressRule` в ядре), но
37
+ * реализация browser-safe: правило проверяется и в роутах ядра, и в UI.
38
+ */
39
+ export declare function isValidHostRule(raw: string): boolean;
40
+ /** Подсказка по допустимому виду правила — для сообщений об ошибке. */
41
+ export declare const HOST_RULE_FORMAT_HINT = "\u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F hostname (git.example.com), \u043F\u043E\u0434\u0434\u043E\u043C\u0435\u043D\u044B (*.corp.example), IP-\u043B\u0438\u0442\u0435\u0440\u0430\u043B \u0438\u043B\u0438 CIDR (10.0.0.0/8)";