cvc-catalog-sync-plugin 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/SECURITY.md CHANGED
@@ -4,7 +4,8 @@
4
4
 
5
5
  | Version | DSH | Support |
6
6
  | --- | --- | --- |
7
- | 1.x | `>=0.2.2-rc.3 <0.4.0` | security fixes |
7
+ | 2.x | `>=0.2.2-rc.3 <0.4.0` | security fixes |
8
+ | 1.x | `>=0.2.2-rc.3 <0.4.0` | no longer maintained; update to 2.x |
8
9
 
9
10
  ## Reporting a vulnerability
10
11
 
@@ -18,37 +19,128 @@ Please do not open a public issue for a security problem.
18
19
  You can expect an initial answer within 7 days and a fix or a mitigation plan
19
20
  within 30 days for confirmed reports.
20
21
 
21
- ## Scope
22
+ ## What the plugin talks to
22
23
 
23
- The plugin makes network requests only to addresses from its own configuration:
24
+ Everything the plugin fetches comes from the plugin's own configuration. There is
25
+ no telemetry, no analytics, and no other outbound host.
24
26
 
25
- - `GET {baseURL}/models` with the credential that DSH resolves by name
26
- (`apiKeyEnv`);
27
- - `GET` to each configured installer URL (default
28
- `https://ru.cheapvibecode.ru/idhw` and `/idhl`);
29
- - the settings page talks only to the plugin's own `/cvc-catalog-sync` routes on
30
- the same origin.
27
+ | Request | When | Data sent | Data received |
28
+ | --- | --- | --- | --- |
29
+ | `GET {baseURL}/models` | catalog sync needs a catalog; coefficients refresh their map | `Authorization: Bearer <key>` | model list, multipliers, modalities |
30
+ | `GET {apiRoot}/v1/balance` | the balance panel is opened or refreshed, or the interval fires | `Authorization: Bearer <key>` | `token_balance` |
31
+ | `GET <installerUrl>` (`/idhw`, `/idhl`) | a catalog run needs reasoning levels and the cached map expired | nothing, a plain download | the installer text, from which the `reasoningLevels` literal is read |
31
32
 
32
- There is no telemetry, no analytics, and no other outbound host. The package has
33
- zero runtime dependencies.
33
+ `apiRoot` is the provider route's `baseURL` with a trailing `/v1` removed, so the
34
+ balance request goes to the host the route already names. The installer URLs are
35
+ plain `GET`s without a key; they are the same files a user would download to
36
+ install CheapVibeCode by hand.
34
37
 
35
- The plugin writes two configuration rows of the DSH profile patch
36
- (`llm-pi-ai` models and `subagent-model-selection-settings.allowedModels`) and
37
- never puts the API key value into logs, responses, or the browser.
38
+ The browser half sends nothing to the provider. It reads the plugin's own
39
+ routes on the same origin as the DSH web UI:
38
40
 
39
- Out of scope: vulnerabilities in DSH itself, in the CheapVibeCode API, or in the
40
- models the catalog describes — report those to their maintainers.
41
+ - `GET /cvc/state`, `PUT /cvc/config`, `POST /cvc/run` — the settings page;
42
+ - `GET /cvc/coefficients` — the model badges;
43
+ - `GET /cvc/balance` — the balance button and panel;
44
+ - `GET /cvc/health` — a version probe.
45
+
46
+ A request with `Sec-Fetch-Site: cross-site` is refused with `403`, a write
47
+ (`PUT` or `POST`) without `application/json` with `415`, and a body over 64 KB
48
+ with `413`.
49
+
50
+ ## The API key
51
+
52
+ The key is resolved on the host through `ctx.credentials` by the name the route
53
+ declares (`apiKeyEnv`), and only two things ever leave the host about it:
54
+
55
+ - the `Authorization` header of the requests listed above;
56
+ - the boolean `keySet: true|false` in the answers of the settings routes, the
57
+ balance route and the `cvc_balance` tool. The keys themselves never leave the
58
+ host.
59
+
60
+ The value does not enter the browser, the JSON answers or the logs. Errors are
61
+ reported in two ways, both without the key:
62
+
63
+ - the catalog and the installer requests raise `CvcApiError` with the provider's
64
+ own message, passed through `redact(text, key)` in `lib/cvc-api.js`, which
65
+ replaces the key with `***` before the text is stored, logged or shown;
66
+ - the balance request reports a per-provider error as a code plus the HTTP status
67
+ (`unauthorized (HTTP 403)`), deliberately without the upstream body, because that
68
+ body could echo the request headers.
69
+
70
+ The key is only ever placed in the `Authorization` header of the requests above.
71
+
72
+ A `401` or `403` from the provider is treated as a normal failed request: the
73
+ answer says which provider failed and why, the panel keeps showing the previous
74
+ numbers, and nothing is retried in a loop. A `403` from the browser fence
75
+ (`Sec-Fetch-Site: cross-site`) and a `403` from the provider are different
76
+ things and are reported separately.
77
+
78
+ ## What the plugin writes
79
+
80
+ | Target | Written by | Condition |
81
+ | --- | --- | --- |
82
+ | `llm-pi-ai.providers.<provider>.models` in the profile patch | catalog sync | an apply run, only when the built list differs from the current one |
83
+ | `subagent-model-selection-settings.allowedModels` | catalog sync | `syncAllowlist` on, an apply run, only when the list changes |
84
+ | the plugin's own row config | the settings page | the **Save** button |
85
+ | `localStorage` key `cvc:panel-pos` | the balance panel | the user drags the panel |
86
+
87
+ Coefficients write nothing: they only read. The balance function writes nothing
88
+ either; its "spend since the previous reading" delta lives in the memory of the
89
+ DSH process and disappears on restart.
90
+
91
+ Writes to the patch go through `ctx.configEditor.edit()`, which keeps the rest of
92
+ the file, its comments and other plugins' rows. The plugin has no other file
93
+ access: it does not read the profile directory, does not scan the disk, and does
94
+ not spawn processes.
95
+
96
+ ## The browser half
97
+
98
+ - It is shipped compiled as `client.js`; the sources are in `src/client/**` and
99
+ CI rebuilds the file on every push, so the committed artefact cannot drift from
100
+ the sources silently.
101
+ - It renders the settings page, the coefficient badges and the balance panel. It
102
+ does not read the conversation, the prompt, the model output or the DOM outside
103
+ the two attributes it needs: `data-model-id` and `data-provider-id` on the model
104
+ rows the DSH selector draws.
105
+ - The balance panel uses `localStorage` for one key (`cvc:panel-pos`) and does not
106
+ write anywhere else.
107
+ - A switched-off function registers no route and no UI. A browser tab left open
108
+ from an older version that still calls `/cvc-catalog-sync`, `/cvc-model-coeff`
109
+ or `/cvc-balance` gets `404`.
110
+
111
+ ## Dependencies
112
+
113
+ The package ships no bundled runtime dependencies. The host half imports one peer
114
+ dependency, `@deepseek-ai/schemastery` (`>=3.18.4 <4`), which is resolved from the
115
+ DSH installation and is declared optional so that a profile install does not fail
116
+ when the host provides it already. The browser half uses `react` from the DSH
117
+ client loader and nothing else. Build tooling (`tsdown`, `typescript`,
118
+ `schemastery` for tests) is a development dependency and is not installed for
119
+ users of the published package.
120
+
121
+ ## Out of scope
122
+
123
+ Vulnerabilities in DSH itself, in the CheapVibeCode API, in the installers the
124
+ plugin downloads, or in the models the catalog describes — report those to their
125
+ maintainers.
41
126
 
42
127
  ## Hardening in this repository
43
128
 
129
+ - CI on every push and pull request: `npm ci`, the test suite on Node 20, 22 and
130
+ 24, a rebuild of `client.js` on Node 22 with `git diff --exit-code`, and a check
131
+ of the npm tarball contents (`tools/assert-pack.mjs`) so a missing or unexpected
132
+ file fails before publishing.
44
133
  - Dependabot alerts, security updates, and weekly version updates for npm and
45
134
  GitHub Actions.
46
- - CodeQL code scanning (`security-and-quality`) on every push and pull request.
135
+ - CodeQL code scanning (`security-and-quality`) on every push and pull request,
136
+ plus a weekly scheduled run.
47
137
  - GitHub secret scanning with push protection.
48
138
  - OpenSSF Scorecard results published to the code-scanning dashboard.
49
139
  - Third-party actions pinned to commit SHAs.
50
140
  - npm releases with provenance through npm Trusted Publishing from GitHub
51
- Actions.
141
+ Actions: the publish workflow runs only for a published release, checks that
142
+ the tag matches `package.json`, runs the tests and the build check, and refuses
143
+ to publish an already existing version.
52
144
 
53
145
  ## Accepted findings
54
146
 
@@ -74,7 +166,8 @@ protection, pinned actions, and provenance on npm releases.
74
166
 
75
167
  | Версия | DSH | Поддержка |
76
168
  | --- | --- | --- |
77
- | 1.x | `>=0.2.2-rc.3 <0.4.0` | исправления безопасности |
169
+ | 2.x | `>=0.2.2-rc.3 <0.4.0` | исправления безопасности |
170
+ | 1.x | `>=0.2.2-rc.3 <0.4.0` | не поддерживается; обновитесь до 2.x |
78
171
 
79
172
  ## Как сообщить об уязвимости
80
173
 
@@ -88,31 +181,138 @@ protection, pinned actions, and provenance on npm releases.
88
181
  Первый ответ — в течение 7 дней, исправление или план смягчения для
89
182
  подтверждённой проблемы — в течение 30 дней.
90
183
 
91
- ## Область
184
+ ## К чему обращается плагин
185
+
186
+ Всё, что плагин забирает из сети, задано его собственной конфигурацией.
187
+ Телеметрии и аналитики нет, других внешних адресов тоже.
188
+
189
+ | Запрос | Когда | Что уходит | Что приходит |
190
+ | --- | --- | --- | --- |
191
+ | `GET {baseURL}/models` | синхронизации нужен каталог; коэффициенты обновляют карту | `Authorization: Bearer <ключ>` | список моделей, множители, модальности |
192
+ | `GET {apiRoot}/v1/balance` | панель баланса открыта или обновлена, либо сработал интервал | `Authorization: Bearer <ключ>` | `token_balance` |
193
+ | `GET <адрес установщика>` (`/idhw`, `/idhl`) | прогону каталога нужны уровни, а кэш карты истёк | ничего, обычная загрузка | текст установщика, из которого читается литерал `reasoningLevels` |
92
194
 
93
- Плагин делает сетевые запросы только по адресам из своей конфигурации:
195
+ `apiRoot` — это `baseURL` маршрута провайдера без хвостового `/v1`, поэтому
196
+ запрос баланса идёт на тот же хост, который уже назван в маршруте. Адреса
197
+ установщиков запрашиваются обычным `GET` без ключа: это те же файлы, которые
198
+ пользователь скачал бы, устанавливая CheapVibeCode руками.
94
199
 
95
- - `GET {baseURL}/models` с ключом, который DSH разрешает по имени (`apiKeyEnv`);
96
- - `GET` по каждому настроенному адресу установщика (по умолчанию
97
- `https://ru.cheapvibecode.ru/idhw` и `/idhl`);
98
- - страница настроек ходит только в собственные маршруты `/cvc-catalog-sync` на
99
- том же origin.
200
+ Браузерная половина провайдеру не отправляет ничего. Она читает собственные
201
+ маршруты плагина на том же origin, что и веб-интерфейс DSH:
100
202
 
101
- Телеметрии и аналитики нет, других внешних адресов тоже. Зависимостей ноль.
203
+ - `GET /cvc/state`, `PUT /cvc/config`, `POST /cvc/run` — страница настроек;
204
+ - `GET /cvc/coefficients` — бейджи моделей;
205
+ - `GET /cvc/balance` — кнопка и панель баланса;
206
+ - `GET /cvc/health` — проверка версии.
102
207
 
103
- Плагин пишет две строки профильного патча DSH (`llm-pi-ai` и
104
- `subagent-model-selection-settings.allowedModels`) и не выводит значение ключа
105
- в логи, ответы или браузер.
208
+ Запрос с `Sec-Fetch-Site: cross-site` отклоняется с `403`, запись (`PUT` или
209
+ `POST`) без `application/json` — с `415`, тело больше 64 КБ — с `413`.
106
210
 
107
- Вне области: уязвимости самого DSH, API CheapVibeCode и описанных в каталоге
108
- моделей — о них сообщайте их авторам.
211
+ ## Ключ
212
+
213
+ Ключ разрешается на хосте через `ctx.credentials` по имени, которое объявляет
214
+ маршрут (`apiKeyEnv`), и наружу из хоста выходят только две вещи:
215
+
216
+ - заголовок `Authorization` перечисленных выше запросов;
217
+ - булев `keySet: true|false` в ответах маршрутов настроек, маршрута баланса и
218
+ инструмента `cvc_balance`. Сами ключи хост не покидают.
219
+
220
+ Само значение не попадает в браузер, в JSON-ответы и в логи. Ошибки сообщаются
221
+ двумя способами, и ни в одном нет ключа:
222
+
223
+ - запросы каталога и установщика поднимают `CvcApiError` с собственным сообщением
224
+ провайдера, прошедшим через `redact(text, key)` в `lib/cvc-api.js`, который
225
+ заменяет ключ на `***`, прежде чем текст будет сохранён, залогирован или
226
+ показан;
227
+ - запрос баланса сообщает ошибку провайдера кодом и HTTP-статусом
228
+ (`unauthorized (HTTP 403)`), намеренно без тела апстрима: тело может повторять
229
+ заголовки запроса.
230
+
231
+ Ключ помещается только в заголовок `Authorization` запросов выше.
232
+
233
+ `401` или `403` от провайдера — обычный неудачный запрос: ответ говорит, какой
234
+ провайдер отказал и почему, панель продолжает показывать прошлые цифры, а цикл
235
+ повторов не запускается. `403` от браузерного фенса (`Sec-Fetch-Site:
236
+ cross-site`) и `403` от провайдера — разные вещи и сообщаются раздельно.
237
+
238
+ ## Что плагин записывает
239
+
240
+ | Куда | Кто пишет | Условие |
241
+ | --- | --- | --- |
242
+ | `llm-pi-ai.providers.<провайдер>.models` в профильном патче | синхронизация каталога | прогон с применением, только если собранный список отличается от текущего |
243
+ | `subagent-model-selection-settings.allowedModels` | синхронизация каталога | `syncAllowlist` включён, прогон с применением, список изменился |
244
+ | конфиг собственной строки плагина | страница настроек | кнопка **Сохранить** |
245
+ | ключ `localStorage` `cvc:panel-pos` | панель баланса | пользователь перетащил панель |
246
+
247
+ Коэффициенты не пишут ничего: они только читают. Баланс тоже ничего не
248
+ записывает; дельта «с прошлого замера» живёт в памяти процесса DSH и исчезает
249
+ при перезапуске.
250
+
251
+ Запись в патч идёт через `ctx.configEditor.edit()`, который сохраняет остальной
252
+ файл, комментарии и строки чужих плагинов. Другого доступа к файлам у плагина
253
+ нет: он не читает каталог профиля, не сканирует диск и не запускает процессы.
254
+
255
+ ## Браузерная половина
256
+
257
+ - Она поставляется собранной в `client.js`; исходники — в `src/client/**`, и CI
258
+ пересобирает файл на каждый push, поэтому закоммиченный артефакт не может
259
+ молча разойтись с исходниками.
260
+ - Она рисует страницу настроек, бейджи коэффициентов и панель баланса. Она не
261
+ читает переписку, запрос, вывод модели и DOM за пределами двух нужных ей
262
+ атрибутов: `data-model-id` и `data-provider-id` на строках моделей, которые
263
+ рисует селектор DSH.
264
+ - Панель баланса использует `localStorage` для одного ключа (`cvc:panel-pos`) и
265
+ больше никуда не пишет.
266
+ - Выключенная функция не регистрирует ни маршрута, ни элемента интерфейса.
267
+ Вкладка, оставшаяся с прежней версией и всё ещё вызывающая
268
+ `/cvc-catalog-sync`, `/cvc-model-coeff` или `/cvc-balance`, получает `404`.
269
+
270
+ ## Зависимости
271
+
272
+ В пакете нет встроенных runtime-зависимостей. Хост-половина импортирует одну
273
+ peer-зависимость, `@deepseek-ai/schemastery` (`>=3.18.4 <4`), которая
274
+ разрешается из установки DSH и объявлена необязательной, чтобы установка в
275
+ профиль не падала, когда хост её уже предоставляет. Браузерная половина берёт
276
+ `react` из загрузчика клиента DSH и больше ничего. Сборочный инструментарий
277
+ (`tsdown`, `typescript`, `schemastery` для тестов) — dev-зависимость, и
278
+ пользователям опубликованного пакета он не устанавливается.
279
+
280
+ ## Вне области
281
+
282
+ Уязвимости самого DSH, API CheapVibeCode, установщиков, которые скачивает
283
+ плагин, и описанных в каталоге моделей — о них сообщайте их авторам.
109
284
 
110
285
  ## Что включено в репозитории
111
286
 
287
+ - CI на каждый push и pull request: `npm ci`, набор тестов на Node 20, 22 и 24,
288
+ пересборка `client.js` на Node 22 с `git diff --exit-code` и проверка состава
289
+ npm-тарбола (`tools/assert-pack.mjs`), чтобы пропавший или лишний файл падал
290
+ до публикации.
112
291
  - Dependabot: оповещения, security updates и еженедельные обновления npm и
113
292
  GitHub Actions.
114
- - CodeQL (`security-and-quality`) на каждый push и pull request.
293
+ - CodeQL (`security-and-quality`) на каждый push и pull request, плюс
294
+ еженедельный прогон по расписанию.
115
295
  - Secret scanning с push protection.
116
296
  - OpenSSF Scorecard с публикацией в code scanning.
117
297
  - Сторонние actions закреплены по SHA коммита.
118
- - Публикация в npm с provenance через Trusted Publishing из GitHub Actions.
298
+ - Публикация в npm с provenance через Trusted Publishing из GitHub Actions:
299
+ workflow публикации запускается только для опубликованного релиза, сверяет
300
+ тег с `package.json`, гоняет тесты и проверку сборки и отказывается публиковать
301
+ уже существующую версию.
302
+
303
+ ## Принятые замечания
304
+
305
+ OpenSSF Scorecard сообщает о зрелости репозитория пункты, которые плагин с одним
306
+ сопровождающим не может выполнить по определению. Они приняты, а не
307
+ проигнорированы:
308
+
309
+ | Проверка | Почему остаётся |
310
+ | --- | --- |
311
+ | Code-Review | один сопровождающий, второго ревьюера нет |
312
+ | Branch-Protection | в `main` запрещены удаление и force-push; обязательные ревью или статус-чеки заблокировали бы прямое сопровождение |
313
+ | Maintained | репозиторий молодой |
314
+ | CII-Best-Practices | заявки на бейдж OpenSSF ещё нет |
315
+ | Fuzzing | фазз-цели нет; устойчивость покрыта тестами крайних случаев |
316
+
317
+ Всё, что можно включить, включено: Dependabot, CodeQL, secret scanning с push
318
+ protection, закреплённые actions и provenance у релизов npm.