Repository navigation
docs(security): define the migration boundary for protected Swagger UI header forwarding #830
Description
Context
At main@9127b17, register_openapi_routes(..., docs_key_forwarding=None) intentionally keeps legacy ?code= forwarding for protected docs and emits a DeprecationWarning (src/azure_functions_openapi/docs_routes.py:88-99,133-145). The safer header mode already exists in swagger_ui.py, and the documented plan says that the default will change in a future pre-1.0 minor. This is a tracked migration decision, not a new exploit claim. The related feature PR #823 is merged but no open issue tracks the precise default-change migration.
Acceptance Checklist
- Document which supported consumers rely on implicit query forwarding and how to opt into explicit
headerorquerybehavior. - Choose the release/compatibility boundary for switching the protected default to
headerwithout changing anonymous docs. - Add/keep regressions that header mode forwards a function key only to the same-origin spec download, rejects redirects, removes the page query, and never forwards credentials to Try-it-out requests.
- Preserve explicit legacy
querymode during the announced compatibility period; reflect the observable change in release notes.
Out of scope
Redesigning Swagger UI, creating another browser runner, or merging before the existing browser verification decision (#825).
Evidence
src/azure_functions_openapi/docs_routes.py:45-59,88-99,133-145; src/azure_functions_openapi/swagger_ui.py:91-120 at 9127b17; merged PR #823.
Activity
yeongseon commentedon Oct 25, 2026
Verified against origin/main at 2968098: docs_routes.py still intentionally maps protected docs_key_forwarding=None to legacy query forwarding and warns at registration; explicit header/query/none modes and anonymous no-forwarding behavior already exist. README.md and docs/security.md announce only a future pre-1.0 minor, not a specific release. PR #833 now supplies the advisory Chromium lane requested by #825. This issue still needs a maintainer compatibility decision: identify supported consumers relying on implicit query forwarding and select the release boundary/compatibility period. Repository source cannot establish external consumer usage, and choosing a version or claiming consumer validation would be guessing. No default or release metadata was changed. Leaving this issue open pending that decision; the browser/redirect/Try-it-out regression tests remain in place.