Files
crank/_bmad-output/implementation-artifacts/spec-2-10-security-schemes-secrets.md
T

21 KiB
Raw Blame History

title, type, created, status, review_loop_iteration, followup_review_recommended, context, warnings, deferred
title type created status review_loop_iteration followup_review_recommended context warnings deferred
2.10 — Привязать security schemes через безопасный import API feature 2026-09-13 blocked 0 false
_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

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 к данной остановке не применяется.