@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
@@ -24,6 +24,27 @@ export interface EventIdentity {
24
24
  /** Роли для маппинга на RBAC. */
25
25
  roles?: string[];
26
26
  }
27
+ /**
28
+ * ADR-115 × ADR-089: ссылка на вложение внешнего события.
29
+ *
30
+ * Шлюз (Telegram/VK/…) сначала загружает байты в staging (`POST /api/v2/attachments`)
31
+ * и передаёт в событии **ссылку** на объект blob-хранилища — сами байты через
32
+ * событие не идут. Метаданные дублируются в событии, чтобы адресат мог проверить
33
+ * их совпадение со sidecar объекта (подмена ссылки на чужой/изменённый объект
34
+ * отклоняется на приёме).
35
+ */
36
+ export interface EventAttachmentRef {
37
+ /** Путь объекта в blob-хранилище (`attachments/<sha2>/<sha256>`). */
38
+ blobPath: string;
39
+ /** SHA-256 содержимого (content-addressed). */
40
+ sha256: string;
41
+ /** MIME-тип по содержимому. */
42
+ mime: string;
43
+ /** Размер в байтах. */
44
+ size: number;
45
+ /** Имя файла (санитайз; в `blobPath` не входит). */
46
+ name?: string;
47
+ }
27
48
  /** ADR-089: нормализованное внешнее событие (источник-специфика — в `payload`). */
28
49
  export interface SynthEvent {
29
50
  /** `'evt_<uuid>'`, уникален в пределах инстанса. */
@@ -38,6 +59,13 @@ export interface SynthEvent {
38
59
  dedupKey: string;
39
60
  /** Время события, ISO-8601. */
40
61
  ts: string;
62
+ /**
63
+ * ADR-115 × ADR-089: вложения события — ссылки на объекты blob-хранилища.
64
+ * Аддитивное поле: события без вложений его не несут. Если поле непусто,
65
+ * `dedupKey` обязан быть задан явно (иначе ключ идемпотентности менялся бы
66
+ * от содержимого вложений).
67
+ */
68
+ attachments?: EventAttachmentRef[];
41
69
  }
42
70
  /** ADR-089: устойчивая привязка внешнего адреса к сессии/шаблону. */
43
71
  export interface EventBinding {
@@ -93,6 +121,19 @@ export interface EventBindingApiKeyCreated extends EventBindingApiKey {
93
121
  /** Plaintext-секрет; возвращается единственный раз при создании. */
94
122
  key: string;
95
123
  }
124
+ /**
125
+ * ADR-089: ссылка на шаг пайплайна — «эта сессия — шаг `step` пайплайна `id`».
126
+ *
127
+ * Ссылка живёт в цели правила маршрутизации (`ephemeral`/`bind`) и прокидывается
128
+ * в решение Router'а: на ней строится учёт экземпляров пайплайна и гейты
129
+ * (напр. правило по событию `draft_approved` — это гейт «после approve»).
130
+ */
131
+ export interface PipelineRef {
132
+ /** id пайплайна (определения/экземпляра). */
133
+ id: string;
134
+ /** id шага внутри пайплайна. */
135
+ step: string;
136
+ }
96
137
  /**
97
138
  * ADR-089: цель правила маршрутизации (та же семантика, что у
98
139
  * `EventBinding`/`ScheduleTarget`).
@@ -105,6 +146,7 @@ export type EventRouteTarget = {
105
146
  agentTemplate?: string;
106
147
  project?: string;
107
148
  ttl?: string;
149
+ pipeline?: PipelineRef;
108
150
  } | {
109
151
  mode: 'queue';
110
152
  sessionId: string;
@@ -118,6 +160,7 @@ export type EventRouteTarget = {
118
160
  mode: 'bind';
119
161
  agentTemplate?: string;
120
162
  project?: string;
163
+ pipeline?: PipelineRef;
121
164
  };
122
165
  /** ADR-089: условие срабатывания правила (AND по заполненным полям). */
123
166
  export interface EventRouteMatch {
@@ -165,6 +208,7 @@ type RouteDecisionKind = {
165
208
  agentTemplate: string;
166
209
  ttl: string;
167
210
  project?: string;
211
+ pipeline?: PipelineRef;
168
212
  } | {
169
213
  kind: 'queue';
170
214
  owner: string;
@@ -185,8 +229,17 @@ type RouteDecisionKind = {
185
229
  kind: 'bind';
186
230
  agentTemplate: string;
187
231
  project?: string;
232
+ pipeline?: PipelineRef;
188
233
  };
189
- /** ADR-089: решение Router — куда направить событие (или отложить/отбросить). */
234
+ /**
235
+ * ADR-089: решение Router — куда направить событие (или отложить/отбросить).
236
+ *
237
+ * `pipeline` (ссылка на шаг пайплайна) — **семантическое** поле решения, а не
238
+ * диагностическая мета: оно задано только у вариантов `ephemeral`/`bind`
239
+ * (там, где решение порождает сессию) и потому живёт в вариантах
240
+ * `RouteDecisionKind`, а не в `RouteDecisionMeta` (мета — диагностика:
241
+ * `confidence`/`signals`).
242
+ */
190
243
  export type RouteDecision = RouteDecisionKind & RouteDecisionMeta;
191
244
  /** ADR-089: инициатор запроса на сессию. */
192
245
  export type EventInitiator = 'user' | 'agent' | 'external' | 'system';
@@ -208,7 +261,6 @@ export interface SessionRequest {
208
261
  icon?: string;
209
262
  /** Канонический ключ цвета (PROJECT_COLOR_KEYS). */
210
263
  color?: string;
211
- engine?: string;
212
264
  /** Происхождение сессии (`user`/`fork`/`subagent`) — паритет с createSession. */
213
265
  sessionOrigin?: SessionOrigin;
214
266
  settings?: Partial<SessionSettings>;
@@ -0,0 +1,352 @@
1
+ /**
2
+ * ADR-105 (Ф0): «внешний доступ» — сущность слоя доступа к внешним сервисам
3
+ * (коннекторам). Носитель OAuth-кредов (access/refresh-токен) внешнего провайдера.
4
+ *
5
+ * Ключевые свойства модели (ADR-105 §1–§2):
6
+ * - **доступ — ресурс с временем жизни**, а не «ещё один ключ»: у него есть
7
+ * срок (`expiresAt`), статус (`status`) и отзыв (`revokedAt`);
8
+ * - **токен нужен в исходном виде** (его подставляет транспорт), поэтому
9
+ * at-rest он лежит **зашифрованным** мастер-ключом (`enc:v1:…`, ADR-076), а не
10
+ * хешем (как у service-key/binding-key, где секрет только проверяется);
11
+ * - **секрет наружу не отдаётся**: публичная форма — `ExternalCredentialMeta`
12
+ * (метаданные + маска), а `secretEnc`/`refreshEnc` живут только внутри
13
+ * хранилища;
14
+ * - **владелец — часть записи**: `owner.kind` = `user` | `instance` | `local`
15
+ * (инвариант 19: в standalone всё нормализуется к `local`).
16
+ *
17
+ * Модуль browser-safe (zod + чистые функции) — используется и в UI, и в ядре.
18
+ */
19
+ import { z } from 'zod';
20
+ /** Статусы внешнего доступа (ADR-105 §1). */
21
+ export declare const EXTERNAL_CREDENTIAL_STATUSES: readonly ["active", "expired", "revoked", "error"];
22
+ export type ExternalCredentialStatus = (typeof EXTERNAL_CREDENTIAL_STATUSES)[number];
23
+ /**
24
+ * Виды владения доступом (ADR-105 §2):
25
+ * - `user` — конкретный пользователь инстанса;
26
+ * - `instance` — инстансный доступ (выдал `ADMIN`/`LEAD`, владельца-пользователя нет);
27
+ * - `local` — локальный доступ standalone-инстанса (единственный владелец, инвариант 19).
28
+ */
29
+ export declare const EXTERNAL_CREDENTIAL_OWNER_KINDS: readonly ["user", "instance", "local"];
30
+ export type ExternalCredentialOwnerKind = (typeof EXTERNAL_CREDENTIAL_OWNER_KINDS)[number];
31
+ /** Владелец доступа: вид владения + идентификатор (userId / `instance` / `local`). */
32
+ export interface ExternalCredentialOwner {
33
+ kind: ExternalCredentialOwnerKind;
34
+ id: string;
35
+ }
36
+ /**
37
+ * Persisted-запись внешнего доступа (ADR-105 §1). Это **внутренняя** форма
38
+ * хранилища: `secretEnc`/`refreshEnc` — зашифрованные мастер-ключом токены
39
+ * (`enc:v1:…`), наружу (API/UI) они не отдаются — только `ExternalCredentialMeta`.
40
+ */
41
+ export interface ExternalCredential {
42
+ id: string;
43
+ /** Провайдер/коннектор: ключ описания OAuth-провайдера или id MCP-сервера. */
44
+ provider: string;
45
+ /** id записи реестра MCP (ADR-071), если доступ привязан к коннектору. */
46
+ connectorId?: string;
47
+ /** `client_id` приложения/коннектора (публичное значение, не секрет). */
48
+ clientId: string;
49
+ /** Запрошенные scope'ы. */
50
+ scopes: string[];
51
+ /** Владелец доступа (часть записи, не вычисляемое поле). */
52
+ owner: ExternalCredentialOwner;
53
+ /** Опциональная привязка к проекту (доступ уровня проекта виден его участникам). */
54
+ projectId?: string;
55
+ /** Зашифровано мастер-ключом: access-токен (`enc:v1:…`). */
56
+ secretEnc: string;
57
+ /** Зашифровано мастер-ключом: refresh-токен (`enc:v1:…`). */
58
+ refreshEnc?: string;
59
+ /** Текущее состояние доступа. */
60
+ status: ExternalCredentialStatus;
61
+ /** ISO-8601 срок действия access-токена. */
62
+ expiresAt?: string;
63
+ /** ISO-8601 отзыв доступа. */
64
+ revokedAt?: string;
65
+ /** Кто выдал доступ (id пользователя инстанса). */
66
+ createdBy: string;
67
+ /** ISO-8601 создание. */
68
+ createdAt: string;
69
+ /** ISO-8601 последнее использование (best-effort). */
70
+ lastUsedAt?: string;
71
+ /** Фактически выданные провайдером scope'ы (если провайдер их сообщил). */
72
+ scopesGranted?: string[];
73
+ }
74
+ /**
75
+ * Публичные метаданные доступа — единственная форма, которая отдаётся наружу
76
+ * (API/UI). Секрета здесь нет: вместо него `secretMask` (маска) и признак
77
+ * наличия refresh-токена.
78
+ */
79
+ export interface ExternalCredentialMeta {
80
+ id: string;
81
+ provider: string;
82
+ connectorId?: string;
83
+ clientId: string;
84
+ scopes: string[];
85
+ owner: ExternalCredentialOwner;
86
+ projectId?: string;
87
+ status: ExternalCredentialStatus;
88
+ expiresAt?: string;
89
+ revokedAt?: string;
90
+ createdBy: string;
91
+ createdAt: string;
92
+ lastUsedAt?: string;
93
+ scopesGranted?: string[];
94
+ /** Маска секрета (необратимая сводка): секрет наружу не отдаётся никогда. */
95
+ secretMask: string;
96
+ /** Есть ли refresh-токен (сам токен не раскрывается). */
97
+ hasRefreshToken: boolean;
98
+ }
99
+ /**
100
+ * Вход создания доступа (ADR-105 Ф2/F3 — выдача кода). Токены приходят
101
+ * **plaintext** и шифруются мастер-ключом внутри хранилища (ADR-076); наружу
102
+ * plaintext не возвращается.
103
+ */
104
+ export interface CreateExternalCredentialInput {
105
+ /** Явный id записи (импорт/перенос); не задан — сгенерирует хранилище. */
106
+ id?: string;
107
+ provider: string;
108
+ connectorId?: string;
109
+ clientId: string;
110
+ scopes?: string[];
111
+ owner: ExternalCredentialOwner;
112
+ projectId?: string;
113
+ /** Access-токен ( plaintext) — хранилище зашифрует его мастер-ключом. */
114
+ accessToken: string;
115
+ /** Refresh-токен (plaintext, опционально). */
116
+ refreshToken?: string;
117
+ expiresAt?: string;
118
+ scopesGranted?: string[];
119
+ createdBy: string;
120
+ }
121
+ /**
122
+ * Патч обновления токенов (refresh/ротация). `undefined` — поле не трогать.
123
+ * Статус по умолчанию возвращается в `active` (свежий токен).
124
+ */
125
+ export interface UpdateExternalCredentialTokensInput {
126
+ accessToken?: string;
127
+ refreshToken?: string;
128
+ expiresAt?: string;
129
+ scopesGranted?: string[];
130
+ /** Явный статус (напр. `expired`, если провайдер не выдал срок). */
131
+ status?: ExternalCredentialStatus;
132
+ }
133
+ /** Фильтр выборки доступов (владелец/коннектор/провайдер/проект/статус). */
134
+ export interface ExternalCredentialFilter {
135
+ owner?: ExternalCredentialOwner;
136
+ connectorId?: string;
137
+ provider?: string;
138
+ projectId?: string;
139
+ status?: ExternalCredentialStatus;
140
+ }
141
+ export declare const externalCredentialOwnerSchema: z.ZodObject<{
142
+ kind: z.ZodEnum<{
143
+ user: "user";
144
+ instance: "instance";
145
+ local: "local";
146
+ }>;
147
+ id: z.ZodString;
148
+ }, z.core.$strip>;
149
+ export declare const externalCredentialStatusSchema: z.ZodEnum<{
150
+ error: "error";
151
+ active: "active";
152
+ expired: "expired";
153
+ revoked: "revoked";
154
+ }>;
155
+ /** Persisted-запись доступа (внутренняя форма хранилища). */
156
+ export declare const externalCredentialSchema: z.ZodObject<{
157
+ id: z.ZodString;
158
+ provider: z.ZodString;
159
+ connectorId: z.ZodOptional<z.ZodString>;
160
+ clientId: z.ZodString;
161
+ scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
162
+ owner: z.ZodObject<{
163
+ kind: z.ZodEnum<{
164
+ user: "user";
165
+ instance: "instance";
166
+ local: "local";
167
+ }>;
168
+ id: z.ZodString;
169
+ }, z.core.$strip>;
170
+ projectId: z.ZodOptional<z.ZodString>;
171
+ secretEnc: z.ZodString;
172
+ refreshEnc: z.ZodOptional<z.ZodString>;
173
+ status: z.ZodEnum<{
174
+ error: "error";
175
+ active: "active";
176
+ expired: "expired";
177
+ revoked: "revoked";
178
+ }>;
179
+ expiresAt: z.ZodOptional<z.ZodString>;
180
+ revokedAt: z.ZodOptional<z.ZodString>;
181
+ createdBy: z.ZodString;
182
+ createdAt: z.ZodString;
183
+ lastUsedAt: z.ZodOptional<z.ZodString>;
184
+ scopesGranted: z.ZodOptional<z.ZodArray<z.ZodString>>;
185
+ }, z.core.$strip>;
186
+ /** Публичные метаданные доступа (то, что отдаётся в API/UI). */
187
+ export declare const externalCredentialMetaSchema: z.ZodObject<{
188
+ id: z.ZodString;
189
+ provider: z.ZodString;
190
+ connectorId: z.ZodOptional<z.ZodString>;
191
+ clientId: z.ZodString;
192
+ scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
193
+ owner: z.ZodObject<{
194
+ kind: z.ZodEnum<{
195
+ user: "user";
196
+ instance: "instance";
197
+ local: "local";
198
+ }>;
199
+ id: z.ZodString;
200
+ }, z.core.$strip>;
201
+ projectId: z.ZodOptional<z.ZodString>;
202
+ status: z.ZodEnum<{
203
+ error: "error";
204
+ active: "active";
205
+ expired: "expired";
206
+ revoked: "revoked";
207
+ }>;
208
+ expiresAt: z.ZodOptional<z.ZodString>;
209
+ revokedAt: z.ZodOptional<z.ZodString>;
210
+ createdBy: z.ZodString;
211
+ createdAt: z.ZodString;
212
+ lastUsedAt: z.ZodOptional<z.ZodString>;
213
+ scopesGranted: z.ZodOptional<z.ZodArray<z.ZodString>>;
214
+ secretMask: z.ZodString;
215
+ hasRefreshToken: z.ZodBoolean;
216
+ }, z.core.$strip>;
217
+ /** Вход создания доступа (access/refresh-токены — plaintext на входе). */
218
+ export declare const createExternalCredentialInputSchema: z.ZodObject<{
219
+ id: z.ZodOptional<z.ZodString>;
220
+ provider: z.ZodString;
221
+ connectorId: z.ZodOptional<z.ZodString>;
222
+ clientId: z.ZodString;
223
+ scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
224
+ owner: z.ZodObject<{
225
+ kind: z.ZodEnum<{
226
+ user: "user";
227
+ instance: "instance";
228
+ local: "local";
229
+ }>;
230
+ id: z.ZodString;
231
+ }, z.core.$strip>;
232
+ projectId: z.ZodOptional<z.ZodString>;
233
+ accessToken: z.ZodString;
234
+ refreshToken: z.ZodOptional<z.ZodString>;
235
+ expiresAt: z.ZodOptional<z.ZodString>;
236
+ scopesGranted: z.ZodOptional<z.ZodArray<z.ZodString>>;
237
+ createdBy: z.ZodString;
238
+ }, z.core.$strip>;
239
+ /** Патч обновления токенов доступа. */
240
+ export declare const updateExternalCredentialTokensSchema: z.ZodObject<{
241
+ accessToken: z.ZodOptional<z.ZodString>;
242
+ refreshToken: z.ZodOptional<z.ZodString>;
243
+ expiresAt: z.ZodOptional<z.ZodString>;
244
+ scopesGranted: z.ZodOptional<z.ZodArray<z.ZodString>>;
245
+ status: z.ZodOptional<z.ZodEnum<{
246
+ error: "error";
247
+ active: "active";
248
+ expired: "expired";
249
+ revoked: "revoked";
250
+ }>>;
251
+ }, z.core.$strip>;
252
+ export type ExternalCredentialOwnerInput = z.infer<typeof externalCredentialOwnerSchema>;
253
+ export type ExternalCredentialRecord = z.infer<typeof externalCredentialSchema>;
254
+ export type ExternalCredentialMetaInput = z.infer<typeof externalCredentialMetaSchema>;
255
+ export type CreateExternalCredentialRequest = z.infer<typeof createExternalCredentialInputSchema>;
256
+ export type UpdateExternalCredentialTokensRequest = z.infer<typeof updateExternalCredentialTokensSchema>;
257
+ /**
258
+ * Маска секрета доступа — необратимая сводка зашифрованного значения.
259
+ *
260
+ * Секрет наружу не отдаётся **никогда** (ADR-105 §1): вместо него UI/API
261
+ * показывают маску. У OAuth-токенов внешних провайдеров нет осмысленного
262
+ * «префикса» (как `synth_svc_` у service-key), поэтому маска — короткий
263
+ * необратимый отпечаток: он позволяет отличить один записанный токен от
264
+ * другого и заметить ротацию, не раскрывая секрет.
265
+ *
266
+ * Считается по **зашифрованному** значению (AES-GCM с случайным IV — данные
267
+ * высокоэнтропийные), поэтому восстановить из маски plaintext нельзя.
268
+ */
269
+ export declare function maskExternalSecret(encrypted: string): string;
270
+ /**
271
+ * Маппер «запись → метаданные»: убирает зашифрованные секреты и добавляет
272
+ * маску. Единственное место, где секрет «прячется» из публичной выдачи.
273
+ */
274
+ export declare function toExternalCredentialMeta(credential: ExternalCredential): ExternalCredentialMeta;
275
+ /**
276
+ * Способ выдачи доступа (ADR-105 Ф4):
277
+ * - `authorize` — Authorization Code + PKCE (RFC 6749 §4.1, RFC 7636);
278
+ * - `device` — Device Authorization Grant (RFC 8628).
279
+ */
280
+ export declare const OAUTH_CREDENTIAL_FLOWS: readonly ["authorize", "device"];
281
+ export type OAuthCredentialFlow = (typeof OAUTH_CREDENTIAL_FLOWS)[number];
282
+ /**
283
+ * Тело `POST /api/v2/oauth/credentials` (ADR-105 Ф4).
284
+ *
285
+ * Один эндпоинт обслуживает обе фазы выдачи:
286
+ * - **старт** — без `code`/`state`: сервер отдаёт `authorizationUrl` (PKCE) либо
287
+ * `userCode`/`verificationUri` (device flow) и запоминает `state`;
288
+ * - **завершение** — с `code` (обмен кода на токены) либо с `state`
289
+ * (опрос device-flow).
290
+ */
291
+ export declare const oauthCredentialCreateSchema: z.ZodObject<{
292
+ provider: z.ZodString;
293
+ flow: z.ZodDefault<z.ZodEnum<{
294
+ device: "device";
295
+ authorize: "authorize";
296
+ }>>;
297
+ code: z.ZodOptional<z.ZodString>;
298
+ state: z.ZodOptional<z.ZodString>;
299
+ scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
300
+ redirectUri: z.ZodOptional<z.ZodString>;
301
+ projectId: z.ZodOptional<z.ZodString>;
302
+ connectorId: z.ZodOptional<z.ZodString>;
303
+ ownerKind: z.ZodOptional<z.ZodEnum<{
304
+ user: "user";
305
+ instance: "instance";
306
+ }>>;
307
+ }, z.core.$strip>;
308
+ export type OAuthCredentialCreateRequest = z.infer<typeof oauthCredentialCreateSchema>;
309
+ /** Тело `POST /api/v2/oauth/credentials/:id/bind` (привязка к MCP-коннектору). */
310
+ export declare const oauthCredentialBindSchema: z.ZodObject<{
311
+ connectorId: z.ZodString;
312
+ }, z.core.$strip>;
313
+ export type OAuthCredentialBindRequest = z.infer<typeof oauthCredentialBindSchema>;
314
+ /**
315
+ * Операции журнала доступа (ADR-105 Ф4).
316
+ *
317
+ * - `issue` — выдан новый доступ (обмен кода/device-подтверждения);
318
+ * - `refresh` — обновлён access-токен;
319
+ * - `revoke` — доступ отозван (локально и/или у провайдера);
320
+ * - `bind` — доступ привязан к MCP-коннектору;
321
+ * - `use` — токен подставлен в транспорт (MCP).
322
+ */
323
+ export declare const EXTERNAL_CREDENTIAL_AUDIT_OPS: readonly ["issue", "refresh", "revoke", "bind", "use"];
324
+ export type ExternalCredentialAuditOp = (typeof EXTERNAL_CREDENTIAL_AUDIT_OPS)[number];
325
+ /** Итог операции: успех или ошибка (код ошибки — без текста секрета). */
326
+ export type ExternalCredentialAuditOutcome = 'ok' | 'error';
327
+ /**
328
+ * Запись журнала операций со слоем доступов (append-only).
329
+ *
330
+ * **Секретов в записи нет**: ни значения токена, ни `code_verifier`, ни
331
+ * `client_secret`, ни сырых путей — только id доступа, провайдер, операция,
332
+ * актор и код ошибки (ADR-105 §7, §10).
333
+ */
334
+ export interface ExternalCredentialAuditEntry {
335
+ id: string;
336
+ ts: string;
337
+ op: ExternalCredentialAuditOp;
338
+ /** id доступа. */
339
+ credentialId: string;
340
+ /** Ключ OAuth-провайдера. */
341
+ provider: string;
342
+ /** Кто выполнил операцию (id пользователя инстанса; standalone — `local`). */
343
+ actor?: string;
344
+ /** Итог операции. */
345
+ outcome: ExternalCredentialAuditOutcome;
346
+ /** Машинно-читаемый код ошибки (без текста секрета). */
347
+ errorCode?: string;
348
+ /** MCP-коннектор (для `bind`/`use`). */
349
+ connectorId?: string;
350
+ /** Проект (если доступ привязан к проекту). */
351
+ projectId?: string;
352
+ }
@@ -0,0 +1,200 @@
1
+ /**
2
+ * ADR-105 (Ф0): «внешний доступ» — сущность слоя доступа к внешним сервисам
3
+ * (коннекторам). Носитель OAuth-кредов (access/refresh-токен) внешнего провайдера.
4
+ *
5
+ * Ключевые свойства модели (ADR-105 §1–§2):
6
+ * - **доступ — ресурс с временем жизни**, а не «ещё один ключ»: у него есть
7
+ * срок (`expiresAt`), статус (`status`) и отзыв (`revokedAt`);
8
+ * - **токен нужен в исходном виде** (его подставляет транспорт), поэтому
9
+ * at-rest он лежит **зашифрованным** мастер-ключом (`enc:v1:…`, ADR-076), а не
10
+ * хешем (как у service-key/binding-key, где секрет только проверяется);
11
+ * - **секрет наружу не отдаётся**: публичная форма — `ExternalCredentialMeta`
12
+ * (метаданные + маска), а `secretEnc`/`refreshEnc` живут только внутри
13
+ * хранилища;
14
+ * - **владелец — часть записи**: `owner.kind` = `user` | `instance` | `local`
15
+ * (инвариант 19: в standalone всё нормализуется к `local`).
16
+ *
17
+ * Модуль browser-safe (zod + чистые функции) — используется и в UI, и в ядре.
18
+ */
19
+ import { z } from 'zod';
20
+ /** Статусы внешнего доступа (ADR-105 §1). */
21
+ export const EXTERNAL_CREDENTIAL_STATUSES = ['active', 'expired', 'revoked', 'error'];
22
+ /**
23
+ * Виды владения доступом (ADR-105 §2):
24
+ * - `user` — конкретный пользователь инстанса;
25
+ * - `instance` — инстансный доступ (выдал `ADMIN`/`LEAD`, владельца-пользователя нет);
26
+ * - `local` — локальный доступ standalone-инстанса (единственный владелец, инвариант 19).
27
+ */
28
+ export const EXTERNAL_CREDENTIAL_OWNER_KINDS = ['user', 'instance', 'local'];
29
+ // --- Zod-схемы ---
30
+ export const externalCredentialOwnerSchema = z.object({
31
+ kind: z.enum(EXTERNAL_CREDENTIAL_OWNER_KINDS),
32
+ id: z.string().min(1),
33
+ });
34
+ export const externalCredentialStatusSchema = z.enum(EXTERNAL_CREDENTIAL_STATUSES);
35
+ /** Persisted-запись доступа (внутренняя форма хранилища). */
36
+ export const externalCredentialSchema = z.object({
37
+ id: z.string().min(1),
38
+ provider: z.string().min(1),
39
+ connectorId: z.string().min(1).optional(),
40
+ clientId: z.string().min(1),
41
+ scopes: z.array(z.string()).default([]),
42
+ owner: externalCredentialOwnerSchema,
43
+ projectId: z.string().min(1).optional(),
44
+ secretEnc: z.string().min(1),
45
+ refreshEnc: z.string().min(1).optional(),
46
+ status: externalCredentialStatusSchema,
47
+ expiresAt: z.string().optional(),
48
+ revokedAt: z.string().optional(),
49
+ createdBy: z.string().min(1),
50
+ createdAt: z.string().min(1),
51
+ lastUsedAt: z.string().optional(),
52
+ scopesGranted: z.array(z.string()).optional(),
53
+ });
54
+ /** Публичные метаданные доступа (то, что отдаётся в API/UI). */
55
+ export const externalCredentialMetaSchema = z.object({
56
+ id: z.string().min(1),
57
+ provider: z.string().min(1),
58
+ connectorId: z.string().min(1).optional(),
59
+ clientId: z.string().min(1),
60
+ scopes: z.array(z.string()).default([]),
61
+ owner: externalCredentialOwnerSchema,
62
+ projectId: z.string().min(1).optional(),
63
+ status: externalCredentialStatusSchema,
64
+ expiresAt: z.string().optional(),
65
+ revokedAt: z.string().optional(),
66
+ createdBy: z.string().min(1),
67
+ createdAt: z.string().min(1),
68
+ lastUsedAt: z.string().optional(),
69
+ scopesGranted: z.array(z.string()).optional(),
70
+ secretMask: z.string().min(1),
71
+ hasRefreshToken: z.boolean(),
72
+ });
73
+ /** Вход создания доступа (access/refresh-токены — plaintext на входе). */
74
+ export const createExternalCredentialInputSchema = z.object({
75
+ id: z.string().min(1).optional(),
76
+ provider: z.string().min(1),
77
+ connectorId: z.string().min(1).optional(),
78
+ clientId: z.string().min(1),
79
+ scopes: z.array(z.string()).optional(),
80
+ owner: externalCredentialOwnerSchema,
81
+ projectId: z.string().min(1).optional(),
82
+ accessToken: z.string().min(1),
83
+ refreshToken: z.string().min(1).optional(),
84
+ expiresAt: z.string().optional(),
85
+ scopesGranted: z.array(z.string()).optional(),
86
+ createdBy: z.string().min(1),
87
+ });
88
+ /** Патч обновления токенов доступа. */
89
+ export const updateExternalCredentialTokensSchema = z.object({
90
+ accessToken: z.string().min(1).optional(),
91
+ refreshToken: z.string().min(1).optional(),
92
+ expiresAt: z.string().optional(),
93
+ scopesGranted: z.array(z.string()).optional(),
94
+ status: externalCredentialStatusSchema.optional(),
95
+ });
96
+ /**
97
+ * Маска секрета доступа — необратимая сводка зашифрованного значения.
98
+ *
99
+ * Секрет наружу не отдаётся **никогда** (ADR-105 §1): вместо него UI/API
100
+ * показывают маску. У OAuth-токенов внешних провайдеров нет осмысленного
101
+ * «префикса» (как `synth_svc_` у service-key), поэтому маска — короткий
102
+ * необратимый отпечаток: он позволяет отличить один записанный токен от
103
+ * другого и заметить ротацию, не раскрывая секрет.
104
+ *
105
+ * Считается по **зашифрованному** значению (AES-GCM с случайным IV — данные
106
+ * высокоэнтропийные), поэтому восстановить из маски plaintext нельзя.
107
+ */
108
+ export function maskExternalSecret(encrypted) {
109
+ // FNV-1a (64 бит) — достаточно для необратимого отпечатка; крипто-хеш
110
+ // тут не нужен (вход — шифротекст, а не секрет в исходном виде).
111
+ let hash = 0xcbf29ce484222325n;
112
+ const prime = 0x100000001b3n;
113
+ const mask = 0xffffffffffffffffn;
114
+ for (let i = 0; i < encrypted.length; i += 1) {
115
+ hash ^= BigInt(encrypted.charCodeAt(i));
116
+ hash = (hash * prime) & mask;
117
+ }
118
+ return `mask:${hash.toString(16).padStart(16, '0')}`;
119
+ }
120
+ /**
121
+ * Маппер «запись → метаданные»: убирает зашифрованные секреты и добавляет
122
+ * маску. Единственное место, где секрет «прячется» из публичной выдачи.
123
+ */
124
+ export function toExternalCredentialMeta(credential) {
125
+ return {
126
+ id: credential.id,
127
+ provider: credential.provider,
128
+ ...(credential.connectorId !== undefined ? { connectorId: credential.connectorId } : {}),
129
+ clientId: credential.clientId,
130
+ scopes: [...credential.scopes],
131
+ owner: { ...credential.owner },
132
+ ...(credential.projectId !== undefined ? { projectId: credential.projectId } : {}),
133
+ status: credential.status,
134
+ ...(credential.expiresAt !== undefined ? { expiresAt: credential.expiresAt } : {}),
135
+ ...(credential.revokedAt !== undefined ? { revokedAt: credential.revokedAt } : {}),
136
+ createdBy: credential.createdBy,
137
+ createdAt: credential.createdAt,
138
+ ...(credential.lastUsedAt !== undefined ? { lastUsedAt: credential.lastUsedAt } : {}),
139
+ ...(credential.scopesGranted !== undefined
140
+ ? { scopesGranted: [...credential.scopesGranted] }
141
+ : {}),
142
+ secretMask: maskExternalSecret(credential.secretEnc),
143
+ hasRefreshToken: credential.refreshEnc !== undefined && credential.refreshEnc !== '',
144
+ };
145
+ }
146
+ // --- HTTP-контур слоя доступов (ADR-105 Ф4) ---
147
+ /**
148
+ * Способ выдачи доступа (ADR-105 Ф4):
149
+ * - `authorize` — Authorization Code + PKCE (RFC 6749 §4.1, RFC 7636);
150
+ * - `device` — Device Authorization Grant (RFC 8628).
151
+ */
152
+ export const OAUTH_CREDENTIAL_FLOWS = ['authorize', 'device'];
153
+ /**
154
+ * Тело `POST /api/v2/oauth/credentials` (ADR-105 Ф4).
155
+ *
156
+ * Один эндпоинт обслуживает обе фазы выдачи:
157
+ * - **старт** — без `code`/`state`: сервер отдаёт `authorizationUrl` (PKCE) либо
158
+ * `userCode`/`verificationUri` (device flow) и запоминает `state`;
159
+ * - **завершение** — с `code` (обмен кода на токены) либо с `state`
160
+ * (опрос device-flow).
161
+ */
162
+ export const oauthCredentialCreateSchema = z.object({
163
+ /** Ключ OAuth-провайдера (каталог `oauth.providers`). */
164
+ provider: z.string().min(1),
165
+ /** Способ выдачи; по умолчанию — `authorize`. */
166
+ flow: z.enum(OAUTH_CREDENTIAL_FLOWS).default('authorize'),
167
+ /** Код авторизации (завершение `authorize`-фазы). */
168
+ code: z.string().min(1).optional(),
169
+ /** `state` незавершённой выдачи (завершение `authorize`/`device`-фазы). */
170
+ state: z.string().min(1).optional(),
171
+ /** Запрошенные scope'ы (по умолчанию — scope'ы провайдера). */
172
+ scopes: z.array(z.string().min(1)).optional(),
173
+ /** `redirect_uri` (по умолчанию — из описания провайдера). */
174
+ redirectUri: z.string().min(1).optional(),
175
+ /** Привязка доступа к проекту. */
176
+ projectId: z.string().min(1).optional(),
177
+ /** Привязка доступа к MCP-коннектору (id записи реестра). */
178
+ connectorId: z.string().min(1).optional(),
179
+ /**
180
+ * Вид владения: `user` (по умолчанию) или `instance` (инстансный доступ —
181
+ * выдавать может только `ADMIN`/`LEAD`).
182
+ */
183
+ ownerKind: z.enum(['user', 'instance']).optional(),
184
+ });
185
+ /** Тело `POST /api/v2/oauth/credentials/:id/bind` (привязка к MCP-коннектору). */
186
+ export const oauthCredentialBindSchema = z.object({
187
+ /** id или имя записи реестра MCP. */
188
+ connectorId: z.string().min(1),
189
+ });
190
+ // --- Журнал операций со слоем доступов (ADR-105 Ф4) ---
191
+ /**
192
+ * Операции журнала доступа (ADR-105 Ф4).
193
+ *
194
+ * - `issue` — выдан новый доступ (обмен кода/device-подтверждения);
195
+ * - `refresh` — обновлён access-токен;
196
+ * - `revoke` — доступ отозван (локально и/или у провайдера);
197
+ * - `bind` — доступ привязан к MCP-коннектору;
198
+ * - `use` — токен подставлен в транспорт (MCP).
199
+ */
200
+ export const EXTERNAL_CREDENTIAL_AUDIT_OPS = ['issue', 'refresh', 'revoke', 'bind', 'use'];