@itphx/synth-shared 0.11.3 → 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 (92) hide show
  1. package/dist/config/defaults.js +126 -3
  2. package/dist/config/env-overrides.d.ts +29 -0
  3. package/dist/config/env-overrides.js +155 -2
  4. package/dist/config/execution.d.ts +66 -0
  5. package/dist/config/execution.js +146 -0
  6. package/dist/config/index.d.ts +1 -0
  7. package/dist/config/index.js +1 -0
  8. package/dist/config/proxy.js +3 -1
  9. package/dist/config/resolve.d.ts +8 -8
  10. package/dist/config/resolve.js +7 -7
  11. package/dist/config/types.d.ts +1287 -4037
  12. package/dist/config/types.js +461 -68
  13. package/dist/i18n/index.d.ts +1 -1
  14. package/dist/i18n/index.js +277 -0
  15. package/dist/index.d.ts +14 -2
  16. package/dist/index.js +16 -2
  17. package/dist/model-metadata.d.ts +10 -0
  18. package/dist/schemas/index.d.ts +980 -2322
  19. package/dist/schemas/index.js +183 -22
  20. package/dist/types/analytics.d.ts +6 -6
  21. package/dist/types/analytics.js +4 -4
  22. package/dist/types/authority.d.ts +464 -0
  23. package/dist/types/authority.js +445 -0
  24. package/dist/types/background.d.ts +96 -0
  25. package/dist/types/background.js +24 -0
  26. package/dist/types/bus-events.d.ts +23 -1
  27. package/dist/types/catalog.d.ts +349 -0
  28. package/dist/types/catalog.js +393 -0
  29. package/dist/types/decision.d.ts +28 -337
  30. package/dist/types/egress.d.ts +1 -1
  31. package/dist/types/egress.js +1 -1
  32. package/dist/types/events.d.ts +54 -1
  33. package/dist/types/external-credentials.d.ts +352 -0
  34. package/dist/types/external-credentials.js +200 -0
  35. package/dist/types/hooks.d.ts +33 -12
  36. package/dist/types/index.d.ts +20 -0
  37. package/dist/types/index.js +50 -1
  38. package/dist/types/llm-filters.d.ts +150 -0
  39. package/dist/types/llm-filters.js +54 -0
  40. package/dist/types/mcp.d.ts +33 -2
  41. package/dist/types/mcp.js +44 -1
  42. package/dist/types/message.d.ts +45 -1
  43. package/dist/types/pack.d.ts +1102 -0
  44. package/dist/types/pack.js +1003 -0
  45. package/dist/types/permission.d.ts +25 -11
  46. package/dist/types/permission.js +1 -1
  47. package/dist/types/pipeline-engine.d.ts +453 -0
  48. package/dist/types/pipeline-engine.js +440 -0
  49. package/dist/types/pipeline.d.ts +275 -0
  50. package/dist/types/pipeline.js +212 -0
  51. package/dist/types/plugin-audit.d.ts +110 -0
  52. package/dist/types/plugin-audit.js +185 -0
  53. package/dist/types/plugin-hybrid.d.ts +85 -0
  54. package/dist/types/plugin-hybrid.js +68 -0
  55. package/dist/types/plugin-lock.d.ts +95 -0
  56. package/dist/types/plugin-lock.js +1 -0
  57. package/dist/types/plugin-protocol.d.ts +221 -0
  58. package/dist/types/plugin-protocol.js +322 -0
  59. package/dist/types/plugin-runtime.d.ts +25 -0
  60. package/dist/types/plugin-runtime.js +11 -0
  61. package/dist/types/plugin-scan.d.ts +159 -0
  62. package/dist/types/plugin-scan.js +166 -0
  63. package/dist/types/plugin-tools.d.ts +51 -0
  64. package/dist/types/plugin-tools.js +72 -0
  65. package/dist/types/project.d.ts +14 -0
  66. package/dist/types/prompt-blocks.d.ts +102 -0
  67. package/dist/types/prompt-blocks.js +24 -0
  68. package/dist/types/prompt.d.ts +45 -3
  69. package/dist/types/provider.d.ts +11 -0
  70. package/dist/types/question.d.ts +153 -0
  71. package/dist/types/question.js +65 -0
  72. package/dist/types/schedules.d.ts +26 -3
  73. package/dist/types/semver.d.ts +48 -0
  74. package/dist/types/semver.js +218 -0
  75. package/dist/types/service-keys.d.ts +41 -3
  76. package/dist/types/service-keys.js +44 -2
  77. package/dist/types/session.d.ts +54 -0
  78. package/dist/types/steering.d.ts +74 -0
  79. package/dist/types/steering.js +75 -0
  80. package/dist/types/tools.d.ts +125 -5
  81. package/dist/types/tools.js +75 -0
  82. package/dist/types/trust.d.ts +31 -0
  83. package/dist/types/trust.js +27 -0
  84. package/dist/types/worktree.d.ts +170 -0
  85. package/dist/types/worktree.js +101 -0
  86. package/dist/utils/index.d.ts +31 -1
  87. package/dist/utils/index.js +92 -12
  88. package/dist/utils/reasoning.d.ts +16 -0
  89. package/dist/utils/reasoning.js +37 -0
  90. package/dist/version.d.ts +1 -1
  91. package/dist/version.js +1 -1
  92. package/package.json +2 -2
@@ -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'];
@@ -1,9 +1,10 @@
1
1
  /**
2
- * ADR-030: контракты hook-шины событий агента и интеграций. Система хуков не
3
- * реализована в рантайме (Plugin SDK — отдельный этап), здесь только типы:
4
- * имена хуков, режим выполнения, результат и карта контекстов.
2
+ * ADR-030: контракты hook-шины событий агента и интеграций. Здесь только типы
3
+ * (имена хуков, режим выполнения, результат и карта контекстов); сама шина —
4
+ * `HookBus` в core, внешний фасад — Plugin SDK (ADR-090).
5
5
  */
6
6
  import type { SynthEvent, EventInitiator } from './events.js';
7
+ import type { SessionMode } from './session.js';
7
8
  /** ADR-030: имена хуков жизненного цикла агента и интеграций (ADR-089). */
8
9
  export type HookName = 'pre_tool_use' | 'post_tool_use' | 'session_start' | 'session_end' | 'plan_approved' | 'plan_rejected' | 'agent_spawned' | 'agent_completed' | 'agent_failed' | 'permission_denied' | 'external_event' | 'message_received' | 'callback' | 'session_requested' | 'schedule_fired';
9
10
  /**
@@ -18,7 +19,7 @@ export interface HookResult {
18
19
  patch?: Record<string, unknown>;
19
20
  }
20
21
  /**
21
- * PROP-102: оси атрибуции для сборщиков аналитики (`user`/`project`) — заполняются
22
+ * ADR-102: оси атрибуции для сборщиков аналитики (`user`/`project`) — заполняются
22
23
  * на месте эмита, где значения уже под рукой (без чтения сессии в подписчике).
23
24
  * Необязательны: без них подписчик резолвит сессию по id (если она ещё есть).
24
25
  */
@@ -28,6 +29,13 @@ export interface HookAnalyticsAxes {
28
29
  /** Проект сессии (`Session.projectId`), ось `project`. */
29
30
  projectId?: string;
30
31
  }
32
+ /**
33
+ * ADR-030 / ADR-090 Ф0: вид входящего сообщения для `message_received`.
34
+ * - `user` — сообщение человека (UI/CLI/API);
35
+ * - `scheduler` — срабатывание расписания (автор `Scheduler`, ADR-051);
36
+ * - `external` — доставка внешнего события (webhook/шлюз, `metadata.source`).
37
+ */
38
+ export type MessageReceivedKind = 'user' | 'scheduler' | 'external';
31
39
  /** ADR-030: карта контекста по имени хука (минимально необходимые поля). */
32
40
  export interface HookContextMap {
33
41
  pre_tool_use: {
@@ -40,7 +48,7 @@ export interface HookContextMap {
40
48
  input: unknown;
41
49
  output?: unknown;
42
50
  duration: number;
43
- /** PROP-102: сессия вызова и оси атрибуции активности (ADR-030). */
51
+ /** ADR-102: сессия вызова и оси атрибуции активности (ADR-030). */
44
52
  sessionId?: string;
45
53
  userId?: string;
46
54
  projectId?: string;
@@ -56,7 +64,7 @@ export interface HookContextMap {
56
64
  summary?: string;
57
65
  userId?: string;
58
66
  projectId?: string;
59
- /** PROP-102: сессия архивирована (а не удалена) — мера `sessions_archived`. */
67
+ /** ADR-102: сессия архивирована (а не удалена) — мера `sessions_archived`. */
60
68
  archived?: boolean;
61
69
  };
62
70
  plan_approved: {
@@ -90,11 +98,18 @@ export interface HookContextMap {
90
98
  event: SynthEvent;
91
99
  };
92
100
  message_received: {
93
- source: string;
94
- chatKey?: string;
95
- threadKey?: string;
96
- from?: string;
97
- text?: string;
101
+ /** Сессия, в которую пришло сообщение. */
102
+ sessionId: string;
103
+ /** Эффективный агент хода (`message.agentRole` либо настройка сессии). */
104
+ agent?: string;
105
+ /** Режим сессии на момент приёма (`plan`/`act`/`yolo`). */
106
+ mode?: SessionMode;
107
+ /** Вид входящего сообщения (см. {@link MessageReceivedKind}). */
108
+ kind: MessageReceivedKind;
109
+ /** Внешний источник (`message.metadata.source`) для `kind: 'external'`. */
110
+ source?: string;
111
+ /** `message.metadata.type` — тип сообщения, если задан. */
112
+ type?: string;
98
113
  };
99
114
  callback: {
100
115
  source: string;
@@ -110,7 +125,13 @@ export interface HookContextMap {
110
125
  };
111
126
  schedule_fired: {
112
127
  scheduleId: string;
128
+ /** Имя расписания (для логов/уведомлений). */
129
+ name?: string;
130
+ /** Режим цели расписания (`bound`/`ephemeral`/`queue`/`pipeline`). */
131
+ target?: 'bound' | 'ephemeral' | 'queue' | 'pipeline';
132
+ /** Cron-выражение (если расписание задано через `cron`). */
113
133
  cron?: string;
114
- payload?: unknown;
134
+ /** Триггер срабатывания (`cron`/`manual`/`catchup`). */
135
+ trigger?: 'cron' | 'manual' | 'catchup';
115
136
  };
116
137
  }