32 KiB
title, type, created, status, baseline_revision, review_loop_iteration, followup_review_recommended, context, warnings, deferred
| title | type | created | status | baseline_revision | review_loop_iteration | followup_review_recommended | context | warnings | deferred | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2.10 — Привязать security schemes через безопасный import API | feature | 2026-09-13 | done | c562d5368d |
0 | true |
|
|
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. При создании Operationauth_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
2026-09-27 — Review pass
- verdicts: 13 findings — high 9, medium 1, low 2, false 1, maybe-false 0
- findings:
[high][patch]camelCaseclientSecret/accessTokenне распознаются —sensitive_keyприводит регистр, но сравнивает только целые слова или_-границы; literal может остаться в source. Исправить распознавание и покрыть canary. Вsecurity_literals.rsдобавлена проверка camelCase; canary-тест проходит.[high][patch]числовые/boolean credential values пропускаются —walkобрабатывает лишь строки, хотя значения под чувствительным ключом тоже являются literal; заменить их безопасным redaction marker и покрыть тестом. Вwalkскаляры под sensitive context заменяются[REDACTED]; null оставлен без finding, тест проходит.[high][patch]JWT в generic example пропускается — путь и значение могут не содержать текстовых маркеров; добавить строгую JWT-эвристику и canary-тест.is_jwtпроверяет форму и длины сегментов; JWT canary и benign1.2.3проверены.[high][patch]secret в query URL пропускается — проверяется userinfo, но не ключи query вродеaccess_token; отклонять такой source до persistence и проверять отсутствие canary в IR. Добавлена проверка чувствительных query keys с redaction; OAuth URL fixture проверяет и безопасный, и секретный вариант.[high][patch]Cookie/Set-Cookie example пропускается — response header example без словаtokenне получает sensitive context; покрыть header/cookie примеры. Добавлен контекст Cookie/Set-Cookie и canary-тест.[medium][patch]credential как ключ объекта example остаётся в pointer/source tree — для распознаваемого token-shaped ключа значение редактируется, а имя ключа нет; редактировать весь example object и указывать безопасный parent pointer. JWT-shaped key приводит к redaction всего example object с parent pointer; canary-тест проходит.[low][patch]transaction-level auth error не локализуется —From<RegistryError>всегда выдаёт английский текст, хотяcreate_openapi_importзнает locale; преобразовать этот вариант на границе import API. В import Apply вариант RegistryError преобразуется с locale; Ru integration test проходит.[low][patch]документация не уточняет zero-basedalternative_index— код индексируетVecнапрямую; добавить одну фразу. Вdocs/openapi-import.mdдобавлено явное правило нулевой индексации.[high][patch]AC-12 не проверяет перечисленные literal paths — тесты не содержат camelCase/JWT/query URL/Cookie; добавить canary-fixtures к исправлению сканера.scanner_redacts_contextual_credentials_non_strings_jwts_and_cookie_examplesи OAuth URL fixture добавлены и прошли.[high][patch]тест redacted bearer hint не проверяет safe finding — сейчас проверяется только отсутствие canary в IR; добавить проверку source location и сериализованного finding. Проверяются точный safe pointer, код finding и сериализованный report без canary.[high][patch]edge-case слой подтвердил camelCase/JWT пропуски — тот жеsensitive_keyиlooks_secret_value, что в строках 1 и 3; покрывается тем же исправлением. Закрыто общей scanner patch и canary-тестами строк 1 и 3.[high][patch]query API-key parameter с произвольным example пропускается — имя параметра и example обходятся отдельно,in: queryне включает sensitive context; связать context с именемapi_keyи добавить тест. Сканер использует siblingname/inдля example context; canary-тест проходит.[false][reject]API rejection вместо redacted preview finding не означает отсутствия finding —normalize.rsсоздаётsecret_literal_redactedв IR, а admin API до persistence отклоняет опасный upload с безопасной ошибкой; контракт не требует сохранять небезопасный source ради preview.
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
cargo test -p crank-import --all-targets— PASS: 99 tests; security metadata, inheritance, OR/AND, Swagger 2.0, redaction, JWT/cookie/query credential canaries.cargo test -p admin-api --test integration -- --test-threads=1— PASS: 88 integration tests; upload, mappings, workspace isolation, Secret availability, replay и digest drift.cargo test -p crank-runtime --all-targets— PASS: 83 tests; существующий trusted auth path не менялся.cargo test -p crank-registry --test integration import_auth_binding -- --test-threads=1— PASS: 5 tests; transaction revalidation и no-partial-Draft race.just rust-code-health,just dependencies,just fmt-check,just clippy— PASS после разнесения oversized модулей, обновленияrustlsвCargo.lockдо 0.23.45 и исправления формата теста.just verify— PASS: полный workspace gate завершился с exit 0 (через pipe/tee). Первый прогон остановился на file-size gate, второй — на устаревшей advisoryRUSTSEC-2026-0285, третий — наclippy, четвёртый — наrustfmt, пятый и шестой запуск упали вcrank-artifacts::real_process_write_limit_leaves_no_partial_final_blobиз-за перенаправления stdout в обычный файл: дочерний тест ставитRLIMIT_FSIZE=1, и его собственный вывод попал под лимит. Это воспроизведено отдельной командой с редиректом; без него scoped target прошёл 7/7. Финальный полный прогон через pipe/teeпрошёл; код теста не менялся.- После review patch повторный
just verify— PASS (exit 0): все workspace tests, fmt, clippy, code health и dependency gate. Включены новые scanner canaries и исправленная локализация ошибки binding.
Matrix test audit: Schemes, Effective security и Alternatives покрыты crates/crank-import/tests/security_schemes.rs; Binding, Credential availability, Shared Secret и Stale source — apps/admin-api/tests/integration/openapi_import/security.rs и crates/crank-registry/tests/integration/import_auth_binding.rs; Secret source — importer scanner tests, primary/external upload integration и telemetry canary tests. Все указанные story tests и полный workspace 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 к данной остановке не применяется.
2026-09-27 — повторный Auto Run Result
Status: done
Реализованы typed security schemes и OR/AND requirements в IR/preview, безопасный выбор Auth Profile при import, повторная проверка Secret/profile в транзакции перед созданием Draft, redaction credential literals и совместимость исторического replay. Небезопасный source отклоняется до сохранения artifacts. Документирован API contract; ATDD сценарии и матрица AC покрыты тестами.
Изменённые файлы:
crates/crank-import/src/rest/{model,security,security_literals,normalize*,openapi3*,swagger2*,payload,legacy_payload,mod}.rs— typed security metadata, effective requirements, безопасный scan/redaction и совместимый replay.apps/admin-api/src/{dto,error,service/imports*}.rs— API выбора Auth Profile, проверка mapping и безопасная локализованная ошибка.crates/crank-registry/src/{model,error,lib,postgres/import_job}.rs— повторная transaction-level проверка binding до создания Draft.crates/crank-import/tests/security_schemes.rs,apps/admin-api/tests/integration/openapi_import*,apps/admin-api/tests/integration/openapi_source*,crates/crank-registry/tests/integration*— acceptance и regression tests, включая race, replay и credential canaries.docs/openapi-import.md— контракт import API и индексация alternatives._bmad-output/test-artifacts/atdd-{checklist,summary}-2-10-security-schemes-secrets.*— RED/GREEN и результаты проверок.Cargo.lock— обновлениеrustlsдля dependency gate.- Этот spec — матрица AC, Review Triage Log, Verification и итоговый статус.
Review: 13 findings; 12 исправлены (9 high, 1 medium, 2 low), отложенных нет. Один finding отклонён как false: он утверждал, что API rejection не показывает redacted preview finding, но pure importer формирует secret_literal_redacted, а Admin API намеренно отклоняет опасный upload до сохранения source; AC не требует сохранять небезопасный source ради preview. Открытых intent gaps нет. Повторный just verify прошёл с exit 0 после всех review patches; importer 99/99, Admin API integration 88/88, registry auth-binding 5/5, runtime 83/83.
Остаточный риск: распознавание произвольных секретов без явного контекста остаётся эвристическим. Рекомендована независимая follow-up проверка scanner coverage при дальнейшем расширении форматов. Внешних действий оператора для AC этой истории нет.