[CL-SEC-Q2] admin.agents.routes: admin-secret step-up на agent-control мутации #794

Merged

andrei merged 1 commit from feature/claude-sec-q2-admin-agents-secret-gate into master

2026-06-20 17:00:04 +00:00

andrei commented

2026-06-20 15:53:18 +00:00

Owner

Что сделано

Добавлен step-up admin-secret-фактор requireAdminSecretVerified на 4 privileged agent-control маршрута в api/src/routes/admin.agents.routes.ts:

PATCH /agents/:id (меняет trustScore / monthlyBudgetUsd / isActive);
POST /agents/:id/pause, /resume, /wakeup (триггерят Paperclip-control).

Новый структурный тест admin.agents.routes.test.ts (обход router.stack) гарантирует gate. В admin.agents.sync.test.ts добавлен passthrough-mock gate — его UUID-валидационные тесты монтируют реальный роутер и должны достигать хендлера (auth-присутствие покрывает новый dedicated тест).

Зачем

MEDIUM-finding аудита (SEC-Q2-2026), A01 Broken Access Control. Эти маршруты были защищены только adminApiKeyOrJwt + rate-limit, без step-up секрета, который sibling money/admin-роутеры уже требуют (gate per-router opt-in, глобально на /admin его нет).

AUDIT: SEC-Q2-2026.

Residual (НЕ в этом PR — cross-service)

Paperclip-вызовы доверяют статичному заголовку x-instance-admin: true. Замена на shared secret (PAPERCLIP_ADMIN_SECRET) требует lock-step изменения на стороне Paperclip-runtime (отдельный repo), который будет его валидировать — иначе либо сломается agent-control, либо мы шлём заголовок, который Paperclip игнорирует (нулевой выигрыш). Exposure ограничен bind Paperclip на 127.0.0.1. Задокументировано комментарием в коде, вынесено в координированный api+Paperclip PR.

План тестирования

TDD: новый тест RED (4/4 fail) -> GREEN (4/4 pass).
vitest run src/routes + agents service — 318/318.
mock-sync: admin.agents.sync.test.ts UUID-тесты снова зелёные после passthrough-mock.
tsc --noEmit чисто; eslint 0 ошибок; pre-push 189 integration + build green.

Где могу ошибаться

pause/resume/wakeup теперь требуют секрет — если admin-фронт не шлёт x-admin-secret, появится verify-secret шаг.
Residual по заголовку оставлен сознательно — односторонний фикс рискует сломать fleet-control.

## Что сделано Добавлен step-up admin-secret-фактор `requireAdminSecretVerified` на 4 privileged agent-control маршрута в `api/src/routes/admin.agents.routes.ts`: - `PATCH /agents/:id` (меняет trustScore / monthlyBudgetUsd / isActive); - `POST /agents/:id/pause`, `/resume`, `/wakeup` (триггерят Paperclip-control). Новый структурный тест `admin.agents.routes.test.ts` (обход `router.stack`) гарантирует gate. В `admin.agents.sync.test.ts` добавлен passthrough-mock gate — его UUID-валидационные тесты монтируют реальный роутер и должны достигать хендлера (auth-присутствие покрывает новый dedicated тест). ## Зачем MEDIUM-finding аудита (SEC-Q2-2026), A01 Broken Access Control. Эти маршруты были защищены только `adminApiKeyOrJwt` + rate-limit, без step-up секрета, который sibling money/admin-роутеры уже требуют (gate per-router opt-in, глобально на `/admin` его нет). AUDIT: SEC-Q2-2026. ## Residual (НЕ в этом PR — cross-service) Paperclip-вызовы доверяют статичному заголовку `x-instance-admin: true`. Замена на shared secret (`PAPERCLIP_ADMIN_SECRET`) требует lock-step изменения на стороне Paperclip-runtime (отдельный repo), который будет его валидировать — иначе либо сломается agent-control, либо мы шлём заголовок, который Paperclip игнорирует (нулевой выигрыш). Exposure ограничен bind Paperclip на 127.0.0.1. Задокументировано комментарием в коде, вынесено в координированный api+Paperclip PR. ## План тестирования - TDD: новый тест RED (4/4 fail) -> GREEN (4/4 pass). - `vitest run src/routes` + agents service — 318/318. - mock-sync: `admin.agents.sync.test.ts` UUID-тесты снова зелёные после passthrough-mock. - `tsc --noEmit` чисто; `eslint` 0 ошибок; pre-push 189 integration + build green. ## Где могу ошибаться - `pause/resume/wakeup` теперь требуют секрет — если admin-фронт не шлёт `x-admin-secret`, появится verify-secret шаг. - Residual по заголовку оставлен сознательно — односторонний фикс рискует сломать fleet-control.

andrei added 1 commit

2026-06-20 15:53:19 +00:00

[CL-SEC-Q2] admin.agents.routes: admin-secret step-up на agent-control мутации

CI / Contracts (pull_request) Successful in 1m50s

Details

CI / Telegram Mini App (pull_request) Successful in 1m14s

Details

CI / Python SDK (pull_request) Successful in 25s

Details

CI / Secrets Scan (pull_request) Successful in 12s

Details

CI / Prisma Migrate Gate (pull_request) Successful in 1m32s

Details

PR Janitor / janitor (pull_request) Successful in 9s

Details

CI / API (pull_request) Successful in 12m4s

Details

CI / App (pull_request) Successful in 13m49s

Details

8ab4956c43

AUDIT: SEC-Q2-2026 — MEDIUM hardening sweep (broken-access-control A01).

Что:
PATCH /agents/:id (update trustScore/budget/isActive), POST /agents/:id/pause,
/resume, /wakeup были защищены только admin-auth + rate-limit, без step-up
secret-фактора requireAdminSecretVerified. Эти маршруты меняют fleet-state и
триггерят Paperclip-control. Добавлен gate на все 4.

Тест admin.agents.routes.test.ts (обход router.stack) гарантирует gate.
admin.agents.sync.test.ts: добавлен passthrough-mock gate, т.к. его UUID-тесты
монтируют реальный роутер — auth-присутствие проверяет новый dedicated тест.

Residual (НЕ в этом PR): Paperclip-вызовы доверяют статичному заголовку
x-instance-admin:true. Замена на shared secret требует lock-step изменения на
стороне Paperclip-runtime (отдельный repo) — задокументировано комментарием,
вынесено в координированный api+Paperclip PR. Exposure ограничен bind на 127.0.0.1.

Тесты: TDD RED->GREEN; routes+agents suites 318/318; tsc + eslint чисто.

andrei referenced this pull request

2026-06-20 16:28:12 +00:00

[CL-SEC-Q2] config: fail-closed на ENABLE_ADMIN_API_KEY_AUTH=true в prod #797

forgejo-actions scheduled this pull request to auto merge when all checks succeed

2026-06-20 16:30:50 +00:00

andrei merged commit a6940cb07b into master

2026-06-20 17:00:04 +00:00

andrei referenced this pull request from a commit

2026-06-20 17:00:06 +00:00

[CL-SEC-Q2] admin.agents.routes: admin-secret step-up на agent-control мутации (#794)

andrei deleted branch feature/claude-sec-q2-admin-agents-secret-gate

2026-06-20 17:00:07 +00:00