docs: resolve secret lifecycle scope for story 2.10
This commit is contained in:
1 parent
f8ee7c9bfe
commit
c562d5368d
1 file changed
+185
@@ -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-contract>
|
||||
|
||||
## 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 согласно решению ниже.
|
||||
|
||||
<frozen-after-approval>
|
||||
|
||||
### Решение пользователя: доступность 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.
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## 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 |
|
||||
|
||||
</intent-contract>
|
||||
|
||||
## 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` к данной остановке не применяется.
|
||||
Reference in new issue
Block a user