From c562d5368d810d1730f5d392ae0c6c106143a97c Mon Sep 17 00:00:00 2001 From: bsodfather Date: Sun, 13 Sep 2026 11:58:16 +0300 Subject: [PATCH] docs: resolve secret lifecycle scope for story 2.10 --- .../spec-2-10-security-schemes-secrets.md | 185 ++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 _bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md diff --git a/_bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md b/_bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md new file mode 100644 index 0000000..25b9bb4 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md @@ -0,0 +1,185 @@ +--- +title: '2.10 — Привязать security schemes через безопасный import API' +type: feature +created: '2026-09-13' +status: blocked +review_loop_iteration: 0 +followup_review_recommended: false +context: + - '_bmad-output/project-context.md' + - '_bmad-output/implementation-artifacts/epic-2-context.md' + - '_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md' + - '_bmad-output/implementation-artifacts/spec-2-9-http-contract.md' +warnings: [oversized] +deferred: [] +--- + + + +## Intent + +**Problem:** Importer не сохраняет security schemes и effective authentication requirements. Import API создаёт Operations с пустым auth binding, а raw upload сохраняется до security analysis. + +**Approach:** Сохранить typed security metadata и OR/AND semantics в IR/preview; предоставить workspace-scoped выбор совместимого Auth Profile и повторную проверку binding перед атомарным Apply. Сохранять только ссылки, исключая credential values из artifacts и результатов. + +## Boundaries & Constraints + +**Always:** Выполнить AC Story 2.10 для OpenAPI 3.0/3.1 и Swagger 2.0; сохранить детерминированность и исторический replay, workspace isolation, typed error/redaction и существующие architectural boundaries. `sprint-status.yaml` принадлежит оркестратору: не записывать и не откатывать его. Статусы спринта не являются доказательством проверки AC. + +**Never:** Raw credentials, ciphertext или secret hashes в source snapshot/IR/plan/export/diagnostics; silent collapse OR в AND или выбор первой alternative; создание actionable Draft при unresolved required auth; попутная реализация mapping UI Story 2.11 или полной qualification Story 2.14. Независимый отзыв/status/tombstone lifecycle Auth Profile остаётся вне scope Story 2.10; доступность binding определяется существованием и workspace профиля, а также существующим lifecycle связанных Secrets согласно решению ниже. + + + +### Решение пользователя: доступность Auth Profile (2026-09-13) + +Для Story 2.10 формулировка «отозванный Auth Profile» означает недоступный binding вследствие недоступности любого необходимого связанного Secret по существующим правилам active/current version. Это не независимый отзыв профиля. Preview проверяет существование профиля, его принадлежность текущему workspace, совместимость и доступность необходимых Secrets; Apply повторяет авторитетную проверку в registry transaction до создания Draft, включая изменение состояния после preview. + +При общем Secret профилей A и B отключение Secret отклоняет оба binding. При активном Secret с доступной текущей версией оба binding допустимы при выполнении остальных проверок. Независимое отключение только A при сохранении B не требуется и не реализуется в этой истории: status/tombstone и управление отзывом Auth Profile остаются отложенными. Negative test с disabled Secret доказывает только недоступность credential, а не независимый отзыв профиля. Отсутствующие/удалённые и foreign-workspace profile refs отклоняются без раскрытия foreign metadata. + + + +## I/O & Edge-Case Matrix + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|---------------|---------------------------|----------------| +| Schemes | Bearer/basic/API key header/query/cookie | Typed names, locations и format hints без credentials | Unsupported mapping явно отражён | +| Effective security | Global rule, operation override, explicit no-auth | Сохраняется specification inheritance/override | Invalid requirement не становится actionable | +| Alternatives | OR и AND requirements | Все OR alternatives сохраняются; unsupported AND блокирует affected candidate | Finding объясняет потерянную semantics | +| Binding | Compatible current-workspace profile либо unresolved | Только typed reference; unresolved required auth блокирует Apply | Foreign/missing reference не раскрывает metadata | +| Credential availability | Профиль отсутствует/удалён, принадлежит другому workspace либо любой необходимый связанный Secret недоступен по существующим правилам active/current version | Reference отклоняется при preview и повторно в transaction Apply до Draft | Ошибка не раскрывает metadata foreign profile | +| Shared Secret | Профили A и B используют один Secret | При активном Secret с доступной текущей версией оба binding допустимы при выполнении остальных проверок; отключение общего Secret блокирует оба | Независимый отзыв только A не входит в scope и не заявляется как проверенный | +| Secret source | Literal в example/default/extension/userinfo/header | Redacted finding; raw value отсутствует в persisted/observable output | Проверка до записи source artifact | +| Stale source | Security source изменён после preview | Digest mismatch, новый preview и подтверждение mappings | Нет mutation | + + + +## Code Map + +- `crates/crank-import/src/rest/model.rs` — `NormalizedIr`, `NormalizedOperation`, `RestImportOperation`, `ImportOperationCandidate` пока не содержат security metadata. `NORMALIZER_VERSION` / `PROJECTION_VERSION` равны v4. `NormalizedIr.source_tree` сохраняет весь canonical document. +- `crates/crank-import/src/rest/{openapi3.rs,swagger2.rs}` — `parse_document_v2` не читает security schemes/requirements; здесь начинается parser → IR путь. +- `crates/crank-import/src/rest/{normalize.rs,normalize_projection.rs,payload.rs}` — `canonicalize`, `operation_from_normalized`, `candidate_from_operation` проводят semantics через IR к candidate. +- `crates/crank-import/src/rest/metadata_findings.rs` — `collect_secret_like_examples` только добавляет warning для example/examples, не удаляя raw value. `normalize_finding_validation.rs` повторяет узкую эвристику. +- `apps/admin-api/src/service/imports.rs:54` — после upload validation вызывается `put_registered` до parse; raw source записывается с sensitivity Internal. `preview_openapi_import` сохраняет job/digests; `create_openapi_import_with_locale` перепроверяет verified source/preview. При создании Operation `auth_profile_ref` задаётся `None`; `openapi_application_key` пока не включает mappings. +- `apps/admin-api/src/service/imports/{job_contract.rs,external_references.rs}` — исторический replay и immutable external snapshots; защита source должна распространяться на external inputs. +- `apps/admin-api/src/{app.rs,dto.rs}` — существующие `POST /imports/openapi/preview` и `POST /imports/openapi/{job_id}/create`, preview/create payloads; выбора auth alternative/profile пока нет. +- `crates/crank-registry/src/postgres/import_job.rs` — `apply_import_job_transaction` является атомарной границей создания Operations; финальная auth revalidation нужна здесь, иначе service lookup оставляет race. +- `crates/crank-core/src/auth.rs` — `AuthProfile` имеет identity/workspace/kind/config/timestamps, но не status. `AuthConfig` поддерживает Bearer/Basic/ApiKeyHeader/ApiKeyQuery, без cookie. +- `crates/crank-core/src/operation.rs` — `ExecutionConfig.auth_profile_ref` допускает один `AuthProfileId`; AND из нескольких schemes не поддержан текущим runtime. +- `crates/crank-runtime/src/auth.rs` — `ResolvedAuth::{from_profile,apply}`; существующие trusted credential injection rules необходимо сохранить. +- `apps/admin-api/src/service.rs` — `validate_registry_operation_in_workspace` и `resolve_operation_auth`; `crates/crank-registry/src/postgres/auth.rs` — workspace-scoped profile lookup. +- `_bmad-output/implementation-artifacts/1-10-lifecycle-auth-profiles-machine-keys.md:223` и `_bmad-output/implementation-artifacts/deferred-work.md:17` — отдельный status/tombstone lifecycle Auth Profile явно отложен; существующая проверка active Secret не равна отзыву отдельного профиля. + +## Tasks & Acceptance + +**Execution (intent gap разрешён пользователем 2026-09-13; реализация выполняется при повторном запуске оркестратора):** + +- [ ] `crates/crank-import/src/rest/{model.rs,openapi3.rs,swagger2.rs,normalize.rs,normalize_projection.rs,payload.rs}` — добавить typed schemes и effective requirements, deterministic OR/AND projection, source coverage и blockers без credentials. +- [ ] `crates/crank-import/src/rest/{metadata_findings.rs,normalize_finding_validation.rs}`, `apps/admin-api/src/service/imports.rs`, `apps/admin-api/src/service/imports/external_references.rs` — проверять secret-bearing inputs до persistence и исключить raw values из IR/diagnostics. +- [ ] `apps/admin-api/src/{app.rs,dto.rs,service/imports.rs}` — предоставить выбор/revalidation alternative и совместимых workspace profiles, включить mappings в application digest, сохранять только profile reference. +- [ ] `crates/crank-registry/src/postgres/import_job.rs` — проверять существование и workspace профиля, совместимость binding и доступность всех необходимых связанных Secrets по существующим правилам active/current version в transaction перед mutation; независимый lifecycle профиля не добавлять. +- [ ] `apps/admin-api/src/service/imports/job_contract.rs` — сохранить исторический v4 replay при изменении normalizer/projection contract. +- [ ] `crates/crank-import/tests/`, `apps/admin-api/tests/integration/openapi_import/`, `crates/crank-runtime/tests/` — покрыть все строки матрицы и AC fixtures/negative tests, в том числе race, foreign refs, redaction canaries и digest mismatch. +- [ ] `docs/openapi-import.md` — описать security API, поддерживаемые mappings, blockers и revalidation; не обещать непроверенные semantics. + +**Acceptance Criteria (из Story 2.10; семантика доступности binding уточнена решением пользователя 2026-09-13):** + +**Given** OpenAPI 3.x `components.securitySchemes` или Swagger 2.0 `securityDefinitions` +**When** importer анализирует schemes +**Then** bearer HTTP, basic HTTP и API key в header/query/cookie преобразуются в typed security metadata +**And** source names, locations и применимые format hints сохраняются без credential values. + +**Given** global security requirement +**When** Operation не задаёт собственный override +**Then** candidate наследует global requirement согласно specification semantics +**And** operation-level requirement или explicit no-auth корректно заменяет global rule. + +**Given** security requirement с несколькими alternatives +**When** source определяет OR-семантику +**Then** preview сохраняет все допустимые alternatives и позволяет выбрать поддерживаемый вариант +**And** importer не объединяет alternatives в ложное обязательное AND. + +**Given** security requirement, требующий несколько schemes одновременно +**When** source определяет AND-семантику +**Then** candidate сохраняет составное требование, если runtime contract его поддерживает +**And** иначе affected Operation получает blocker finding с перечислением несохраняемой semantics. + +**Given** bearer, basic или API-key requirement +**When** формируется preview +**Then** администратору предлагается выбрать совместимый Auth Profile из текущего workspace либо оставить явный unresolved binding +**And** unresolved required authentication блокирует actionable Draft/Apply для affected Operation. + +**Given** выбранный Auth Profile +**When** создаётся candidate или ImportPlan +**Then** сохраняется только typed `AuthProfileRef` и scheme metadata +**And** raw secret, password, token, API key, hash или encrypted ciphertext не копируется в source snapshot, IR, findings, plan или Operation export. + +**Given** OAuth2, OpenID Connect, mutual TLS или неизвестная scheme +**When** release scope не поддерживает автоматическое mapping +**Then** importer создаёт explicit manual-configuration/unsupported finding +**And** не извлекает client secret, token URL credential, example token или vendor-extension secret. + +**Given** OpenAPI document содержит literal credential в example, default, extension, URL userinfo или header example +**When** security analysis выполняется +**Then** значение не используется как credential и создаёт redacted secret finding +**And** raw value не появляется в preview UI, logs, traces, metrics или diagnostics. + +**Given** Auth Profile отсутствует/удалён, принадлежит другому workspace либо любой необходимый связанный Secret недоступен по существующим правилам active/current version +**When** preview либо Apply проверяет binding +**Then** reference отклоняется до создания Draft +**And** ошибка не раскрывает metadata foreign profile. + +**Given** профили A и B используют один активный Secret с доступной текущей версией +**When** проверяются binding этих профилей +**Then** оба binding допустимы при выполнении остальных проверок +**And** после отключения общего Secret оба binding отклоняются до создания Draft; тест с disabled Secret не является доказательством независимого отзыва Auth Profile, который остаётся вне scope. + +**Given** исходная security scheme изменилась после preview +**When** старый ImportPlan пытаются применить к новому source +**Then** plan digest mismatch блокирует Apply +**And** требуется новый preview и явное подтверждение Auth Profile mappings. + +**Given** security scheme test suite +**When** выполняются fixtures и negative tests +**Then** покрыты global/operation overrides, no-auth, bearer/basic/API-key locations, OR/AND requirements, OAuth/OpenID/unknown schemes, secret-like examples, missing/deleted и cross-workspace profile refs, недоступные Secrets по правилам active/current version и блокировка обоих профилей при отключении общего Secret +**And** redaction tests и `just verify` проходят. + +## Spec Change Log + +- 2026-09-13 — Пользователь выбрал вариант 1: сохранить существующий lifecycle Secrets; независимый отзыв Auth Profile остаётся отложенным. Уточнены intent, AC, матрица и transaction predicate. Запись Auto Run Result ниже сохранена как историческое свидетельство остановки; требуемое в ней решение принято. Статус переустанавливает оркестратор. + +## Review Triage Log + +## Design Notes + +Pure importer хранит schemes/requirements, но не читает Auth Profiles или Secrets. Workspace-safe lookup принадлежит admin service, authoritative проверка непосредственно перед созданием Draft — registry transaction. Текущий единичный profile reference позволяет выдавать blocker для unsupported AND: это прямо предусмотрено AC и не требует расширения runtime до составного auth. + +Проверка literal credentials до `put_registered` позволяет отвергать небезопасный source без изменения bytes принятого immutable snapshot; AC не требует успешного preview для документа с literal secret. Новые формы import API и внутреннее представление alternatives сами по себе являются инженерными решениями, не основанием для остановки. + +## Verification + +**Commands (не запускались; production code не изменён):** + +- `cargo test -p crank-import --all-targets` — schemes, inheritance, OR/AND, deterministic projection и redaction. +- `cargo test -p admin-api --test integration -- --test-threads=1` — реальные upload/binding/revalidation/Apply, no-mutation и workspace isolation. +- `cargo test -p crank-runtime --all-targets` — auth resolution и trusted injection. +- `just verify` — обязательный полный gate после реализации. + +## Auto Run Result + +Status: blocked +Blocking condition: intent gap + +Планирование остановлено до ATDD и реализации. Код, migration, API и tests не изменены. Обновлён локальный epic context и подготовлен этот spec; прохождение AC не заявляется. `sprint-status.yaml` не изменялся и не откатывался. + +### Требуемое решение + +Определить, что означает «Auth Profile был отозван» в AC Story 2.10: + +- Проверять только существующий lifecycle связанных Secrets (active/current version), считая профиль недоступным при отключении credential, а отдельный lifecycle профиля оставить отложенным. +- Ввести в этой истории независимый отзыв Auth Profile (status/tombstone и соответствующее управление), который запрещает только этот profile ref, сохраняя работоспособность другого профиля с тем же Secret. + +Наблюдаемое различие: профили A и B с одним активным Secret. Независимый отзыв A должен отклонить binding A и сохранить binding B; отключение общего Secret отклоняет оба. `AuthProfile` сейчас не имеет status, а отдельный lifecycle явно отложен в Story 1.10 и deferred-work. Поэтому нельзя считать negative test с disabled Secret доказательством независимого отзыва Auth Profile, либо расширить lifecycle/domain/storage scope молча. + +Основание остановки: правило `step-02-plan.md`, INSTRUCTIONS 5: “Multiple defensible readings of the intent that lead to observably different outcomes, with nothing in the intent to select between them, are an intent gap — do not resolve one by picking a reading.” + +Это пробел нормативного scope, а не внешнее действие оператора. AC не требуют покупки домена, выдачи реального API key или действий в vendor console; `awaiting-operator` к данной остановке не применяется.