Files
crank/_bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md
T
bsodfather 028d8183c3
CI / Rust Checks (pull_request) Successful in 22m34s
CI / UI Checks (pull_request) Successful in 8s
CI / Frontend E2E (pull_request) Failing after 23s
CI / Community Image Smoke (pull_request) Successful in 16m20s
CI / Deploy (pull_request) Has been skipped
docs(story): complete 2.10 auto run result
2026-09-27 23:45:07 +03:00

32 KiB
Raw Blame History

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
_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
oversized

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

2026-09-27 — Review pass

  • verdicts: 13 findings — high 9, medium 1, low 2, false 1, maybe-false 0
  • findings:
    • [high] [patch] camelCase clientSecret/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 и benign 1.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-based alternative_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 и добавить тест. Сканер использует sibling name/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, второй — на устаревшей advisory RUSTSEC-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 этой истории нет.