@itphx/synth-shared 0.13.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 (50) hide show
  1. package/dist/config/defaults.js +28 -1
  2. package/dist/config/env-overrides.d.ts +23 -4
  3. package/dist/config/env-overrides.js +74 -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/tls.d.ts +7 -4
  11. package/dist/config/tls.js +10 -23
  12. package/dist/config/types.d.ts +102 -4
  13. package/dist/config/types.js +73 -0
  14. package/dist/i18n/index.d.ts +1 -1
  15. package/dist/i18n/index.js +129 -0
  16. package/dist/index.d.ts +3 -3
  17. package/dist/index.js +3 -3
  18. package/dist/model-metadata.d.ts +10 -0
  19. package/dist/model-metadata.js +10 -0
  20. package/dist/schemas/index.d.ts +288 -11
  21. package/dist/schemas/index.js +228 -2
  22. package/dist/types/bus-events.d.ts +2 -2
  23. package/dist/types/egress.d.ts +2 -2
  24. package/dist/types/egress.js +2 -2
  25. package/dist/types/git.d.ts +83 -0
  26. package/dist/types/git.js +101 -1
  27. package/dist/types/host-pattern.d.ts +41 -0
  28. package/dist/types/host-pattern.js +143 -0
  29. package/dist/types/index.d.ts +2 -0
  30. package/dist/types/index.js +7 -1
  31. package/dist/types/maintenance.d.ts +1 -1
  32. package/dist/types/mcp.d.ts +90 -0
  33. package/dist/types/mcp.js +11 -0
  34. package/dist/types/message-stream.d.ts +41 -0
  35. package/dist/types/permission.d.ts +13 -3
  36. package/dist/types/project.d.ts +30 -0
  37. package/dist/types/project.js +16 -0
  38. package/dist/types/prompt.d.ts +4 -2
  39. package/dist/types/service-keys.d.ts +6 -3
  40. package/dist/types/service-keys.js +6 -1
  41. package/dist/types/session.d.ts +8 -0
  42. package/dist/types/skills.d.ts +6 -0
  43. package/dist/types/tools.d.ts +36 -0
  44. package/dist/types/tools.js +48 -0
  45. package/dist/types/user.d.ts +7 -0
  46. package/dist/types/worktree.d.ts +1 -1
  47. package/dist/utils/index.js +1 -1
  48. package/dist/version.d.ts +1 -1
  49. package/dist/version.js +1 -1
  50. package/package.json +3 -2
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { MessageRole, GlobalRole, ProjectRole, StatusMessageType, PROJECT_ICON_KEYS, PROJECT_COLOR_KEYS, isKnownScope, isWebhookEventPattern, ANALYTICS_FAMILIES, ANALYTICS_DIMENSIONS, ANALYTICS_EXPORT_FORMATS, STEER_MODES, DEFAULT_STEER_MODE, EFFORT_LEVELS, } from '../types/index.js';
2
+ import { MessageRole, GlobalRole, ProjectRole, StatusMessageType, PROJECT_ICON_KEYS, PROJECT_COLOR_KEYS, isKnownScope, isWebhookEventPattern, ANALYTICS_FAMILIES, ANALYTICS_DIMENSIONS, ANALYTICS_EXPORT_FORMATS, STEER_MODES, DEFAULT_STEER_MODE, EFFORT_LEVELS, SSH_KEY_USAGES, MAX_SSH_ALLOW_HOSTS, MAX_SSH_ALLOW_PORTS, isValidHostRule, HOST_RULE_FORMAT_HINT, MARKDOWN_LIMITS, TODO_STATUSES, TODO_PRIORITIES, } from '../types/index.js';
3
3
  import { ToolCapability } from '../types/tools.js';
4
4
  /**
5
5
  * Экземпляр zod, которым построены **все** схемы этого пакета.
@@ -243,13 +243,50 @@ export const projectUpdateSchema = z.object({
243
243
  repos: z.array(z.union([z.string(), gitRepoConfigSchema])).optional(),
244
244
  memory: projectMemoryUpdateSchema.optional(),
245
245
  });
246
- /** ADR-076: тело создания SSH-ключа (`POST /api/v2/ssh-keys`). */
246
+ /**
247
+ * PROP-124: правило хоста в политике SSH-ключа.
248
+ *
249
+ * Семантика — общая с ADR-099 (`matchTlsHostPattern`/`isValidHostRule`):
250
+ * точный hostname, `*.suffix` (только поддомены), IP-литерал или CIDR.
251
+ * Одиночный `*` («любой хост») недопустим — fail-closed.
252
+ */
253
+ const sshHostRuleSchema = z
254
+ .string()
255
+ .max(253)
256
+ .refine((value) => isValidHostRule(value), {
257
+ message: `невалидный шаблон хоста: ${HOST_RULE_FORMAT_HINT}`,
258
+ });
259
+ /**
260
+ * ADR-076: тело создания SSH-ключа (`POST /api/v2/ssh-keys`).
261
+ *
262
+ * PROP-124: дополнительно принимает `usages` (`git`/`ssh`), `allowHosts`
263
+ * (правила хостов) и `allowPorts` (порты 1..65535) — политику ключа для
264
+ * режима инстанса `tools`.
265
+ */
247
266
  export const sshKeyCreateSchema = z.object({
248
267
  name: z.string().min(1).max(200),
249
268
  type: z.string().optional(),
250
269
  privateKey: z.string().min(1),
251
270
  passphrase: z.string().optional(),
252
271
  agentIds: z.array(z.string()).optional(),
272
+ /**
273
+ * PROP-124: способы использования ключа (`git`/`ssh`).
274
+ *
275
+ * Пустой список **недопустим**: ключ без назначения бесполезен (не годится
276
+ * ни для git, ни для ssh) — это тихая ловушка, в которой можно застрять,
277
+ * сняв оба флажка. Если поле передано — в нём должно быть хотя бы одно
278
+ * значение (`400 VALIDATION_ERROR`).
279
+ */
280
+ usages: z
281
+ .array(z.enum(SSH_KEY_USAGES))
282
+ .min(1, {
283
+ message: `usages: нужен хотя бы один способ использования (${SSH_KEY_USAGES.join('|')})`,
284
+ })
285
+ .optional(),
286
+ /** PROP-124: правила хостов (режим `tools`); лимит — `MAX_SSH_ALLOW_HOSTS`. */
287
+ allowHosts: z.array(sshHostRuleSchema).max(MAX_SSH_ALLOW_HOSTS).optional(),
288
+ /** PROP-124: порты (режим `tools`); лимит — `MAX_SSH_ALLOW_PORTS`. */
289
+ allowPorts: z.array(z.number().int().min(1).max(65535)).max(MAX_SSH_ALLOW_PORTS).optional(),
253
290
  });
254
291
  /** ADR-076: тело обновления SSH-ключа (без id/createdAt). */
255
292
  export const sshKeyUpdateSchema = sshKeyCreateSchema.partial();
@@ -1051,3 +1088,192 @@ export const mediaPartSchema = z.object({
1051
1088
  durationMs: z.number().int().min(0).optional(),
1052
1089
  transcript: z.string().optional(),
1053
1090
  });
1091
+ // --- PROP-054: план (ADR-039), ToDo (ADR-039), журнал и инварианты проекта ---
1092
+ //
1093
+ // Контракт «план/ToDo/журнал» (PROP-054, дополнение 2026-11-07): у сущностей
1094
+ // есть Zod-схемы (в shared), а тела мутаций — **strict** (лишнее поле — ошибка
1095
+ // валидации, а не молчаливое игнорирование). При **чтении** (импорт/перенос
1096
+ // между мирами) допустим `passthrough` — старые записи могли нести поля,
1097
+ // которых больше нет в модели.
1098
+ /** Приоритет пункта плана (ADR-039). */
1099
+ export const PLAN_PRIORITIES = ['high', 'medium', 'low'];
1100
+ /** Отношение зависимости пункта плана (ADR-039). */
1101
+ export const PLAN_DEPENDENCY_RELATIONS = ['blocked_by', 'blocks', 'relates_to'];
1102
+ /** Зависимость пункта плана (ADR-039): `projectId` пуст = тот же проект. */
1103
+ export const planDependencySchema = z
1104
+ .object({
1105
+ projectId: z.string().optional(),
1106
+ itemId: z.string().min(1),
1107
+ relation: z.enum(PLAN_DEPENDENCY_RELATIONS),
1108
+ })
1109
+ .passthrough();
1110
+ /** Колонка плана (ADR-039) — статус пункта. */
1111
+ export const planColumnSchema = z
1112
+ .object({
1113
+ id: z.string().min(1),
1114
+ name: z.string().min(1).max(100),
1115
+ order: z.number().int(),
1116
+ wipLimit: z.number().int().min(0).optional(),
1117
+ })
1118
+ .passthrough();
1119
+ /** Пункт плана (ADR-039). `description` — Markdown (лимит `MARKDOWN_LIMITS`). */
1120
+ export const planItemSchema = z
1121
+ .object({
1122
+ id: z.string().min(1),
1123
+ title: z.string().min(1).max(500),
1124
+ description: z.string().max(MARKDOWN_LIMITS.planDescription).optional(),
1125
+ columnId: z.string().min(1),
1126
+ priority: z.enum(PLAN_PRIORITIES),
1127
+ order: z.number().int(),
1128
+ dependsOn: z.array(planDependencySchema).default([]),
1129
+ tags: z.array(z.string()).optional(),
1130
+ createdAt: z.string(),
1131
+ updatedAt: z.string(),
1132
+ })
1133
+ .passthrough();
1134
+ /** План проекта целиком (ADR-039). */
1135
+ export const projectPlanSchema = z
1136
+ .object({
1137
+ version: z.number().int(),
1138
+ updatedAt: z.string(),
1139
+ columns: z.array(planColumnSchema),
1140
+ items: z.array(planItemSchema),
1141
+ })
1142
+ .passthrough();
1143
+ /** Пункт ToDo сессии (ADR-039). `content` — Markdown (лимит `MARKDOWN_LIMITS`). */
1144
+ export const todoItemSchema = z
1145
+ .object({
1146
+ id: z.string().min(1),
1147
+ content: z.string().min(1).max(MARKDOWN_LIMITS.todoContent),
1148
+ status: z.enum(TODO_STATUSES),
1149
+ priority: z.enum(TODO_PRIORITIES),
1150
+ planItemId: z.string().optional(),
1151
+ })
1152
+ .passthrough();
1153
+ /** Запись журнала проекта (PROP-054): `updatedAt`/`updatedBy` — аддитивные. */
1154
+ export const projectLogEntrySchema = z
1155
+ .object({
1156
+ id: z.string().min(1),
1157
+ text: z.string().min(1).max(MARKDOWN_LIMITS.journalEntry),
1158
+ createdAt: z.string(),
1159
+ sessionId: z.string().optional(),
1160
+ author: z.string().optional(),
1161
+ updatedAt: z.string().optional(),
1162
+ updatedBy: z.string().optional(),
1163
+ })
1164
+ .passthrough();
1165
+ // --- Тела HTTP-мутаций плана (PROP-054) — strict ---
1166
+ /** Создание пункта плана. */
1167
+ export const planItemCreateSchema = z
1168
+ .object({
1169
+ title: z.string().min(1).max(500),
1170
+ description: z.string().max(MARKDOWN_LIMITS.planDescription).optional(),
1171
+ columnId: z.string().min(1).optional(),
1172
+ priority: z.enum(PLAN_PRIORITIES).optional(),
1173
+ dependsOn: z.array(planDependencySchema).optional(),
1174
+ tags: z.array(z.string()).optional(),
1175
+ })
1176
+ .strict();
1177
+ /** Точечная правка полей пункта плана (версия не требуется). */
1178
+ export const planItemUpdateSchema = z
1179
+ .object({
1180
+ title: z.string().min(1).max(500).optional(),
1181
+ description: z.string().max(MARKDOWN_LIMITS.planDescription).optional(),
1182
+ priority: z.enum(PLAN_PRIORITIES).optional(),
1183
+ tags: z.array(z.string()).optional(),
1184
+ dependsOn: z.array(planDependencySchema).optional(),
1185
+ })
1186
+ .strict();
1187
+ /**
1188
+ * Перемещение пункта плана: `beforeItemId`/`afterItemId` — соседи-ориентиры
1189
+ * (упорядочивание без ручного `order`); `version` — оптимистичная блокировка.
1190
+ */
1191
+ export const planItemMoveSchema = z
1192
+ .object({
1193
+ columnId: z.string().min(1),
1194
+ beforeItemId: z.string().min(1).optional(),
1195
+ afterItemId: z.string().min(1).optional(),
1196
+ version: z.number().int().optional(),
1197
+ })
1198
+ .strict();
1199
+ /** Создание колонки плана. */
1200
+ export const planColumnCreateSchema = z
1201
+ .object({
1202
+ name: z.string().min(1).max(100),
1203
+ wipLimit: z.number().int().min(0).optional(),
1204
+ })
1205
+ .strict();
1206
+ /** Правка колонки плана (имя/WIP-лимит). */
1207
+ export const planColumnUpdateSchema = z
1208
+ .object({
1209
+ name: z.string().min(1).max(100).optional(),
1210
+ wipLimit: z.number().int().min(0).optional(),
1211
+ })
1212
+ .strict();
1213
+ /**
1214
+ * Удаление колонки: `moveItemsTo` — куда переносятся её пункты (`null` —
1215
+ * удалить вместе с колонкой); `version` — оптимистичная блокировка.
1216
+ */
1217
+ export const planColumnDeleteSchema = z
1218
+ .object({
1219
+ moveItemsTo: z.string().min(1).nullable(),
1220
+ version: z.number().int(),
1221
+ })
1222
+ .strict();
1223
+ /** Порядок колонок плана (полный список id) + версия. */
1224
+ export const planColumnsOrderSchema = z
1225
+ .object({
1226
+ order: z.array(z.string().min(1)),
1227
+ version: z.number().int(),
1228
+ })
1229
+ .strict();
1230
+ // --- Тела HTTP-мутаций ToDo (PROP-054) — strict ---
1231
+ /** Создание пункта ToDo. */
1232
+ export const todoCreateSchema = z
1233
+ .object({
1234
+ content: z.string().min(1).max(MARKDOWN_LIMITS.todoContent),
1235
+ status: z.enum(TODO_STATUSES).optional(),
1236
+ priority: z.enum(TODO_PRIORITIES).optional(),
1237
+ planItemId: z.string().min(1).optional(),
1238
+ })
1239
+ .strict();
1240
+ /** Точечная правка пункта ToDo (`planItemId: null` — отвязать от пункта плана). */
1241
+ export const todoUpdateSchema = z
1242
+ .object({
1243
+ content: z.string().min(1).max(MARKDOWN_LIMITS.todoContent).optional(),
1244
+ status: z.enum(TODO_STATUSES).optional(),
1245
+ priority: z.enum(TODO_PRIORITIES).optional(),
1246
+ planItemId: z.string().min(1).nullable().optional(),
1247
+ })
1248
+ .strict();
1249
+ /** Новый порядок пунктов ToDo (только существующие id; новые — в конец). */
1250
+ export const todoOrderSchema = z
1251
+ .object({
1252
+ ids: z.array(z.string().min(1)),
1253
+ })
1254
+ .strict();
1255
+ /** Очистка пунктов ToDo по статусам (по умолчанию — `completed` + `cancelled`). */
1256
+ export const todoClearSchema = z
1257
+ .object({
1258
+ statuses: z.array(z.enum(TODO_STATUSES)).optional(),
1259
+ })
1260
+ .strict();
1261
+ // --- Тела HTTP-мутаций журнала и инвариантов (PROP-054) — strict ---
1262
+ /** Новая запись журнала проекта (Markdown, лимит `MARKDOWN_LIMITS.journalEntry`). */
1263
+ export const projectLogCreateSchema = z
1264
+ .object({
1265
+ text: z.string().min(1).max(MARKDOWN_LIMITS.journalEntry),
1266
+ })
1267
+ .strict();
1268
+ /** Правка текста записи журнала. */
1269
+ export const projectLogUpdateSchema = z
1270
+ .object({
1271
+ text: z.string().min(1).max(MARKDOWN_LIMITS.journalEntry),
1272
+ })
1273
+ .strict();
1274
+ /** Замена текста инвариантов проекта (Markdown, лимит `MARKDOWN_LIMITS.invariants`). */
1275
+ export const projectInvariantsUpdateSchema = z
1276
+ .object({
1277
+ invariants: z.string().max(MARKDOWN_LIMITS.invariants),
1278
+ })
1279
+ .strict();
@@ -1,6 +1,6 @@
1
1
  import type { WorktreeUpdateAction } from './worktree.js';
2
2
  import type { MessageAcceptedPayload, QueueStatePayload, MessageDeliveredPayload, MessageEnqueuedPayload, TurnStartedPayload, TurnFinishedPayload, StepStartedPayload, StepFinishedPayload, StepToolsPayload, PartDeltaPayload, PartUpdatedPayload } from './message-stream.js';
3
- export type EventType = 'session.created' | 'session.updated' | 'session.deleted' | 'session.renamed' | 'session.forked' | 'session.fork.created' | 'session.reference.added' | 'session.reference.removed' | 'session.messages.merged' | 'session.messages.cleared' | 'session.moved' | 'project.updated' | 'project.deleted' | 'worktree.updated' | 'fs.changed' | 'message.added' | 'message.updated' | 'message.accepted' | 'queue.state' | 'message.delivered' | 'message.enqueued' | 'message.deleted' | 'turn.started' | 'turn.finished' | 'step.started' | 'step.finished' | 'step.tools.started' | 'step.tools.finished' | 'part.delta' | 'part.updated' | 'steer.dropped' | 'child.message.added' | 'child.session.updated' | 'stream.start' | 'stream.ended' | 'stream.cancelled' | 'stream.error' | 'stream.retry' | 'queue.stalled' | 'permission.asked' | 'permission.replied' | 'permission.hold' | 'question.asked' | 'question.replied' | 'context.summarization_pending' | 'context.summarization_applied' | 'context.summarized' | 'context.sliding_window_applied' | 'context.limit_warning' | 'context.sticky_note_added' | 'context.sticky_note_updated' | 'context.sticky_note_deleted' | 'context.instructions_loaded' | 'tool_call.started' | 'tool_call.result' | 'tool_call.loop' | 'subagent.progress' | 'subagent.retry' | 'subagent.resume.started' | 'subagent.resume.finished' | 'permission.asked' | 'permission.replied' | 'permission.denied' | 'message.quality_check' | 'session.routing_category' | 'plan.approved' | 'plan.updated' | 'todos.updated' | 'skill.invoked' | 'command.invoked' | 'command.inline_shell' | 'event.received' | 'event.routed' | 'binding.changed' | 'pipeline.run.started' | 'pipeline.run.node_started' | 'pipeline.run.node_finished' | 'pipeline.run.awaiting_human' | 'pipeline.run.finished' | 'pipeline.run.failed' | 'pipeline.completed' | 'user_question.asked' | 'user_question.answered' | 'user_question.cancelled' | 'process.started' | 'process.exited' | 'process.stopped' | 'process.detached' | 'child.started' | 'child.completed' | 'child.failed' | 'child.cancelled' | 'error';
3
+ export type EventType = 'session.created' | 'session.updated' | 'session.deleted' | 'session.renamed' | 'session.forked' | 'session.fork.created' | 'session.reference.added' | 'session.reference.removed' | 'session.messages.merged' | 'session.messages.cleared' | 'session.moved' | 'project.updated' | 'project.deleted' | 'worktree.updated' | 'fs.changed' | 'message.added' | 'message.updated' | 'message.accepted' | 'queue.state' | 'message.delivered' | 'message.enqueued' | 'message.deleted' | 'turn.started' | 'turn.finished' | 'step.started' | 'step.finished' | 'step.tools.started' | 'step.tools.finished' | 'part.delta' | 'part.updated' | 'steer.dropped' | 'child.message.added' | 'child.session.updated' | 'stream.start' | 'stream.ended' | 'stream.cancelled' | 'stream.error' | 'stream.retry' | 'queue.stalled' | 'permission.asked' | 'permission.replied' | 'permission.hold' | 'question.asked' | 'question.replied' | 'context.summarization_pending' | 'context.summarization_applied' | 'context.summarization_failed' | 'context.summarized' | 'context.sliding_window_applied' | 'context.limit_warning' | 'context.sticky_note_added' | 'context.sticky_note_updated' | 'context.sticky_note_deleted' | 'context.instructions_loaded' | 'tool_call.started' | 'tool_call.result' | 'tool_call.loop' | 'subagent.progress' | 'subagent.retry' | 'subagent.resume.started' | 'subagent.resume.finished' | 'permission.asked' | 'permission.replied' | 'permission.denied' | 'message.quality_check' | 'session.routing_category' | 'plan.approved' | 'plan.updated' | 'todos.updated' | 'skill.invoked' | 'command.invoked' | 'command.inline_shell' | 'event.received' | 'event.routed' | 'binding.changed' | 'pipeline.run.started' | 'pipeline.run.node_started' | 'pipeline.run.node_finished' | 'pipeline.run.awaiting_human' | 'pipeline.run.finished' | 'pipeline.run.failed' | 'pipeline.completed' | 'user_question.asked' | 'user_question.answered' | 'user_question.cancelled' | 'process.started' | 'process.exited' | 'process.stopped' | 'process.detached' | 'child.started' | 'child.completed' | 'child.failed' | 'child.cancelled' | 'error';
4
4
  export interface BusEvent {
5
5
  type: EventType;
6
6
  sessionId: string;
@@ -21,7 +21,7 @@ export interface BusEvent {
21
21
  eventSeq?: number;
22
22
  }
23
23
  /**
24
- * Payload события `worktree.updated` (ADR-114 §6) — инвентарь worktree'ов
24
+ * Payload события `worktree.updated` (ADR-114 §6) — инвентарь worktree
25
25
  * проекта изменился.
26
26
  *
27
27
  * Событие идёт в **каналы сессий проекта** (инвентарь — ресурс проекта, а не
@@ -93,9 +93,9 @@ export interface EgressRequestLogEntry {
93
93
  actor?: string;
94
94
  }
95
95
  /** Скоупы изменений egress-политик/прокси в security-аудите. */
96
- export declare const SECURITY_AUDIT_SCOPES: readonly ["tools", "webhooks", "mcp", "proxy", "tls", "attachments", "context-window", "context-defaults", "sticky-notes", "agents"];
96
+ export declare const SECURITY_AUDIT_SCOPES: readonly ["tools", "webhooks", "mcp", "proxy", "tls", "attachments", "context-window", "context-defaults", "sticky-notes", "agents", "limits", "permission", "ssh"];
97
97
  export type SecurityAuditScope = (typeof SECURITY_AUDIT_SCOPES)[number];
98
- export declare const SECURITY_AUDIT_ACTIONS: readonly ["update", "reset"];
98
+ export declare const SECURITY_AUDIT_ACTIONS: readonly ["update", "reset", "grant", "revoke"];
99
99
  export type SecurityAuditAction = (typeof SECURITY_AUDIT_ACTIONS)[number];
100
100
  /**
101
101
  * Запись аудита изменений security-политик (append-only). `before`/`after` —
@@ -64,5 +64,5 @@ export const EGRESS_REQUEST_STATUSES = ['allowed', 'blocked', 'error'];
64
64
  */
65
65
  export const EGRESS_REQUEST_VIAS = ['proxy', 'direct', 'fallback'];
66
66
  /** Скоупы изменений egress-политик/прокси в security-аудите. */
67
- export const SECURITY_AUDIT_SCOPES = ['tools', 'webhooks', 'mcp', 'proxy', 'tls', 'attachments', 'context-window', 'context-defaults', 'sticky-notes', 'agents'];
68
- export const SECURITY_AUDIT_ACTIONS = ['update', 'reset'];
67
+ export const SECURITY_AUDIT_SCOPES = ['tools', 'webhooks', 'mcp', 'proxy', 'tls', 'attachments', 'context-window', 'context-defaults', 'sticky-notes', 'agents', 'limits', 'permission', 'ssh'];
68
+ export const SECURITY_AUDIT_ACTIONS = ['update', 'reset', 'grant', 'revoke'];
@@ -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;
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)";