docs: HMAC promote runbook and OSCAL/CAB field contract

[cursor]

Why

#21 and #23 shipped HMAC approvals, API-key gating, and OSCAL/CAB exports with table-level notes. Operators still had no mint/promote curl path, ARCHITECTURE still listed 7 CI suites, and the HMAC-without-API-key pairing hole on main was easy to miss.

This is documentation only. Behavior is verified against serve.py, core/promote/{tokens,gate,promote,connectors}.py, evidence/{oscal,cab}.py, and .github/workflows/test.yml.

Docs added/updated

• docs/DEVELOPER.md — §7 HMAC approval + promote runbook; CI suite list corrected (9, tokens_test is in CI); v1 bind + pairing table.
• docs/EVIDENCE.md — OSCAL/CAB field contract, filenames, intents_that_hold rule, to_oscal/to_cab do not verify.
• docs/ARCHITECTURE.md — component map + §6 gate notes; new §11 exports and §12 HMAC; tech-stack CI count 9.
• docs/index.html — Pages honesty for HMAC pairing, inert live connector, OSCAL/CAB limits; quickstart lists tokens_test + oscal_test.
• docs/GO_LIVE.md, docs/PHASES.md, README.md, CHANGELOG.md — pointers and the pairing-hole note.

Codepaths covered

• POST /api/approve/mint, POST /api/preflight/promote, GET /api/status
• core/promote/tokens.py v1 (aegis1. / approver + bundle sha256 + expiry)
• core/promote/gate.py G1–G5 (G1 is bundler.verify, not verify_seal)
• core/promote/connectors.py (dry_run default; live is DisabledLiveConnector)
• POST /api/preflight/evidence/{oscal,cab} via _verified_bundle

Knowledge gaps addressed

• How to mint a bound token and dry-run promote on community :8088
• AEGIS_APPROVE_KEY without AEGIS_API_KEY is an unauthenticated mint on current main (do not treat draft fix: refuse HMAC mint when API auth is unset #28 as shipped)
• v1 tokens are not bound to grounded config or inventory (do not treat open feat(promote): bind HMAC v2 tokens to config hash and inventory #25 as shipped)
• OSCAL is AEGIS-shaped AR, not a FedRAMP package; CAB rollback was not executed in the twin
• connector=live is still inert

Out of scope

Unmerged #25 (HMAC v2), #27 (PIV/SSH/Batfish), and #28 (startup refuse HMAC-without-API-key).

  

Summary by Sourcery

Document the current HMAC promotion and OSCAL/CAB evidence workflows, including their operational limits and known authentication pairing gap.

Enhancements:

• Document the HMAC approval and dry-run promotion workflow, including token scope, API-key pairing requirements, gate behavior, and the inert live connector.
• Define the OSCAL and CAB export contracts, verification boundaries, filenames, and honesty constraints.
• Align architecture, developer, website, phase, go-live, README, and changelog documentation with the current API behavior and nine-suite CI configuration.

Documentation:

• Add operator curl examples and troubleshooting guidance for minting bound HMAC tokens and promoting bundles on the community server.
• Document that OSCAL exports are AEGIS-shaped assessment results rather than FedRAMP packages and that CAB rollback is not verified in the twin.

[sourcery-ai]

Reviewer's Guide

Documentation-only update that aligns operator, architecture, website, and release guidance with the shipped HMAC promotion and OSCAL/CAB implementations, while explicitly documenting verification limits, inert live behavior, nine-suite CI coverage, and the unresolved HMAC-without-API-key security pairing.

Sequence diagram for HMAC mint and dry-run promotion

sequenceDiagram
    participant Operator
    participant Serve as serve.py
    participant Tokens as tokens.py
    participant Gate as gate.py
    participant Connector as DryRunConnector

    Operator->>Serve: GET /api/status
    Serve-->>Operator: auth and approval mode
    Operator->>Serve: POST /api/preflight/run
    Serve-->>Operator: bundle with integrity.sha256
    Operator->>Serve: POST /api/approve/mint
    Serve->>Tokens: mint_token()
    Tokens-->>Serve: aegis1 token
    Serve-->>Operator: token
    Operator->>Serve: POST /api/preflight/promote
    Serve->>Gate: evaluate()
    Gate->>Tokens: verify_approval()
    Tokens-->>Gate: verified approval
    Gate-->>Serve: GateDecision
    Serve->>Connector: push()
    Connector-->>Serve: dry-run promotion record
    Serve-->>Operator: promotion record

Loading

Flow diagram for OSCAL and CAB verification boundaries

flowchart TD
    Request[Evidence export request]
    Verified[_verified_bundle]
    Hash[Verify integrity.sha256]
    OSCAL[to_oscal]
    CAB[to_cab]
    OSCALFile[OSCAL AR JSON]
    CABFile[CAB one-pager JSON]
    Seal[POST /api/seal/verify]

    Request --> Verified
    Verified --> Hash
    Hash --> OSCAL
    Hash --> CAB
    OSCAL --> OSCALFile
    CAB --> CABFile
    Seal -. separate origin-authenticity path .-> Verified

Loading

File-Level Changes

Change	Details	Files
Added an operator-facing HMAC approval and promotion runbook, including key pairing, token constraints, API curl examples, promotion record fields, and connector behavior.	Documented the mint → dry-run promote workflow and status endpoint. Specified HMAC v1 binding, TTL, approver validation, and token storage rules. Highlighted the current unauthenticated-mint risk when HMAC is configured without an API key. Clarified G1–G5 behavior, asserted-unverified mode, and inert live connector semantics.	docs/DEVELOPER.md docs/ARCHITECTURE.md docs/index.html CHANGELOG.md docs/GO_LIVE.md docs/PHASES.md README.md
Defined the OSCAL and CAB export contracts and their verification and honesty boundaries.	Documented routes, filenames, schemas, field mappings, and export limitations. Clarified that pure exporters do not verify and that HTTP-layer verification uses bundle integrity only. Specified findings, observations, rollback, convergence, and intents_that_hold semantics. Explicitly distinguished OSCAL-shaped output from a FedRAMP package and CAB planning from verified rollback.	docs/EVIDENCE.md docs/ARCHITECTURE.md docs/index.html CHANGELOG.md README.md
Corrected documentation about CI coverage and linked the new operator and auditor guidance throughout the documentation set.	Updated the CI inventory from seven/eight to nine suites, including tokens_test and oscal_test. Added cross-links for HMAC promotion and OSCAL/CAB evidence guidance. Recorded the HMAC/API-key pairing hole and unshipped scope limitations without implying behavior changes.	docs/DEVELOPER.md docs/ARCHITECTURE.md docs/index.html CHANGELOG.md docs/GO_LIVE.md docs/PHASES.md README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[cursor]

Draft PR review — agent report

Two open drafts, both Cursor-authored. No other open drafts. No gap-scan.

PR	Verdict
#28	FIX applied → MERGE
#29	CLOSE

#28 — FIX applied → MERGE

On current main (71fc8ff, after #25/#27) POST /api/approve/mint still only checks hmac_configured(). _guard_api() is a no-op when AEGIS_API_KEY is unset, so HMAC-only deploys remain an unauthenticated signing oracle for v1 and v2 tokens. The original draft was the right guard but sat on pre-#25 1192c49. Rebased onto main on this PR branch (not a second PR): kept mint_token_for_bundle v2, added _require_api_key_for_hmac() SystemExit plus request-time 503, and sent X-Aegis-Key on the v2 mint/promote API checks. Local: api_test 55 PASS, tokens_test 34 PASS, promote_test 200 PASS (hmac_v2_ok / drift denied), oscal_test 25 PASS. GitHub mergeable; CI is the remaining gate.

#29 — CLOSE

Docs-only draft on the same stale 1192c49. It treats HMAC v1 as current, tells operators not to treat open #25 as shipped, and would overwrite docs/index.html copy that already documents mint_token_for_bundle() v2 (2516c75 landed). The pairing-hole runbook would also be the wrong policy once #28 merges. The OSCAL/CAB field tables are incremental but are not one small fix from mergeable — they live inside a rewrite that regresses shipped v2 docs. Close; do not merge.