Document OpenAPI auth requirements

[keilogic]

Summary

Bounty #656
Refs #656

Fixes the OpenAPI contract mismatch reported in #656 (comment).

Protected routes already reject anonymous requests at runtime, but the public OpenAPI document currently publishes those routes without auth/security metadata or documented 401 responses. This adds explicit OpenAPI auth metadata without changing runtime authorization behavior.

Implementation

• Adds MergeWorkAdminToken and MergeWorkGitHubSession OpenAPI security schemes.
• Adds per-operation security and 401 response metadata for admin-token routes:
  • /api/v1/admin/webhook-events
  • /api/v1/bounties creation
  • /api/v1/reconciliation/payouts
  • bounty pay/close routes
  • treasury proposal create/execute routes
• Adds per-operation security and 401 response metadata for GitHub-session routes:
  • bounty attempt create/release routes
  • wallet link and GitHub claim routes
  • treasury proposal challenge route
• Keeps public read-only routes unauthenticated in OpenAPI.

Validation

.\.venv\Scripts\python.exe -m pytest tests/test_openapi_request_bodies.py tests/test_bounty_api.py tests/test_treasury_proposals.py tests/test_wallet_api.py tests/test_bounty_attempts.py -q
# 133 passed, 1 warning

.\.venv\Scripts\python.exe -m pytest -q
# 675 passed, 1 warning

.\.venv\Scripts\python.exe scripts\docs_smoke.py
# docs smoke ok

.\.venv\Scripts\python.exe -m mypy app
# Success: no issues found in 38 source files

.\.venv\Scripts\python.exe scripts\check_agents.py
# AGENTS.md ok

.\.venv\Scripts\python.exe -m ruff check app/openapi_request_bodies.py app/main.py app/bounty_api.py app/bounty_attempts.py app/treasury_routes.py app/wallet_api.py tests/test_openapi_request_bodies.py
# All checks passed

.\.venv\Scripts\python.exe -m ruff format --check app/openapi_request_bodies.py app/main.py app/bounty_api.py app/bounty_attempts.py app/treasury_routes.py app/wallet_api.py tests/test_openapi_request_bodies.py
# 7 files already formatted

git merge-tree --write-tree origin/main HEAD
# clean tree 2c8ce39bec9cde781fd26355b8ac8abafe3addc1

git diff --check origin/main...HEAD
# clean

Scope

No admin token handling, GitHub session handling, wallet signing, ledger mutation, proposal execution, payout execution, challenge submission, private data, bridge/exchange/cash-out behavior, or MRWK price behavior is changed.

Summary by CodeRabbit

• Documentation

  • API docs now include explicit security schemes for admin-token and GitHub-session auth, show which protected endpoints require authentication, and include a standardized 401 error response.

• Tests

  • Added tests that validate the generated OpenAPI spec documents auth requirements and 401 responses for protected routes, and confirm public endpoints remain unauthenticated.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 25870839-9d10-4b38-841d-ddbd3a497097

📥 Commits

Reviewing files that changed from the base of the PR and between d79b616 and 0c71416.

📒 Files selected for processing (1)

• tests/test_openapi_request_bodies.py

---

📝 Walkthrough

Walkthrough

PR adds OpenAPI authentication documentation to protected API endpoints. Defines security scheme objects for admin token and GitHub session auth, installs them into the FastAPI schema, applies auth metadata to routes via a helper function, and validates the security model in a new test.

Changes

OpenAPI Authentication

Layer / File(s)	Summary
OpenAPI auth schema definitions and helper app/openapi_request_bodies.py	Defines MergeWorkAdminToken and MergeWorkGitHubSession security schemes, AUTH_ERROR_RESPONSE for 401 errors, ADMIN_TOKEN_AUTH and GITHUB_SESSION_AUTH config objects, and with_openapi_auth(extra, auth) helper to merge request metadata with auth configuration.
App-level OpenAPI schema installation app/main.py	Imports OPENAPI_SECURITY_SCHEMES and adds _install_openapi_security_schemes(app) that wraps app.openapi to inject security schemes into the generated OpenAPI document; invoked during app creation.
Admin-token endpoint documentation app/bounty_api.py, app/treasury_routes.py	Adds with_openapi_auth(..., ADMIN_TOKEN_AUTH) to multiple admin-protected endpoints (bounty admin routes and treasury create/execute proposal endpoints) and updates related imports.
GitHub-session endpoint documentation app/bounty_attempts.py, app/treasury_routes.py, app/wallet_api.py	Adds with_openapi_auth(..., GITHUB_SESSION_AUTH) to bounty-attempts creation/release, treasury create-challenge, and wallet link/claim endpoints and updates related imports.
OpenAPI security validation test tests/test_openapi_request_bodies.py	New test validates security scheme definitions, verifies selected admin and GitHub-session routes require the correct security entries and include a 401 response, and confirms a public endpoint has no security requirement.

Possibly related PRs

• ramimbo/mergework#393: Both touch app/bounty_api.py's admin-authenticated bounty endpoints—this PR adjusts their openapi_extra auth metadata while that PR restructures those same routes.
• ramimbo/mergework#742: Both modify OpenAPI metadata wiring in overlapping modules/endpoints (app/openapi_request_bodies.py, treasury, wallet, and bounty-related route decorators`).

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Document OpenAPI auth requirements' accurately names the changed surface and directly reflects the core objective of adding OpenAPI authentication metadata.
Description check	✅ Passed	The description includes all required sections from the template: Summary with bounty/issue references, Evidence (confusion addressed and intended files), expected PR size context, comprehensive Test Evidence validation, and MRWK reference. Scope is also clearly defined.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Mergework Public Artifact Hygiene	✅ Passed	PR modifies source code and tests only; adds OpenAPI auth metadata with no investment, price, cash-out, or private security claims.
Bounty Pr Focus	✅ Passed	PR does not reference a "Bounty #N" or "Refs #N" pattern; it references issue #656. Check instruction is conditional on such a reference, making it inapplicable to this PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 83948891-3f1b-4972-a3a3-37b5fdcc1734

📥 Commits

Reviewing files that changed from the base of the PR and between 68845a6 and d79b616.

📒 Files selected for processing (7)

• app/bounty_api.py
• app/bounty_attempts.py
• app/main.py
• app/openapi_request_bodies.py
• app/treasury_routes.py
• app/wallet_api.py
• tests/test_openapi_request_bodies.py

[jakerated-r]

Reviewed current head d79b616 as a non-author for bounty #654.\n\nEvidence checked:\n- Confirmed the PR keeps runtime authorization behavior unchanged while documenting protected OpenAPI operations with explicit security metadata and 401 responses.\n- Inspected app/openapi_request_bodies.py, app/main.py, app/bounty_api.py, app/bounty_attempts.py, app/treasury_routes.py, app/wallet_api.py, and tests/test_openapi_request_bodies.py.\n- Verified admin-token protected operations document MergeWorkAdminToken: /api/v1/admin/webhook-events, bounty create/pay/close, payout reconciliation, and treasury proposal create/execute.\n- Verified GitHub-session protected operations document MergeWorkGitHubSession: attempt create/release, wallet link, GitHub claim, and treasury challenge.\n- Verified public operations remain unauthenticated in the OpenAPI schema where expected, including GET /api/v1/bounties, wallet registration, and wallet transfers.\n- Checked CodeRabbit's test-hardening note; I agree stronger exact-response assertions would be harmless, but I did not find a functional blocker because the implementation and a direct OpenAPI probe both validate the documented auth contract.\n\nValidation run locally on this exact head:\n- Focused API/auth suite: 222 passed, 1 warning.\n- Full pytest: 675 passed, 1 warning.\n- Direct OpenAPI probe: /openapi.json returned 200; protected routes had expected security schemes plus 401 responses; selected public routes had no security entry.\n- Ruff check: passed.\n- Ruff format check: 39 files already formatted.\n- Mypy app: success, no issues in 38 source files.\n- Docs smoke: ok.\n- AGENTS check: ok.\n- git diff --check: passed.\n- Merge-tree against origin/main: clean tree 2262636ef4cd5651d994e07f2d00878ad682c9a5.\n\nNo blocking concerns from this review.

[keilogic]

Thanks for the review. I pushed 0c71416 to tighten the OpenAPI auth test: it now asserts the full GitHub session security scheme and the exact shared 401 response payload for protected admin and session routes.

Validation:

• focused OpenAPI auth test
• Ruff check for the touched test file
• full pytest suite
• hosted Quality/readiness/docs/image and CodeRabbit are green on the current head

[amuuuune]

Withdrawn. Please do not consider this review for bounty #654.

[ramimbo]

Maintainer queue hold: #656 currently has 0 effective awards remaining because the final slot is covered by pending proposal #118. This PR is not accepted or payable under #656 in this state.

The successor issues #798/#799 are still pending create_bounty proposals and are not claimable until execution/finalization. Leaving this open with mrwk:needs-info; after a live successor exists, maintainers can decide whether to reroute, merge without a bounty claim, or close as duplicate/superseded.