From cf8b1ce9619a5ff0b895ebe4128a93e5f75d2100 Mon Sep 17 00:00:00 2001 From: Yeongseon Choe Date: Mon, 26 Oct 2026 00:22:18 +0900 Subject: [PATCH 1/2] docs(security): define the migration boundary for protected Swagger UI header forwarding --- README.md | 3 ++- docs/api.md | 6 ++++-- docs/security.md | 28 ++++++++++++++++++++++++++-- 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4903161a..bbfb8565 100644 --- a/README.md +++ b/README.md @@ -331,7 +331,8 @@ memory. The key must authorize both functions. Prefer edge authentication in production. The default `None` retains legacy query forwarding with a `DeprecationWarning` for protected registrations; select `"header"`, `"none"` (no forwarding), or explicitly `"query"` (legacy exposure). The default -will become `"header"` in a future minor release before 1.0. +will become `"header"` in a later minor release before 1.0, not in the release that +first warns; see [Protecting documentation routes](docs/security.md#protecting-documentation-routes).
Advanced: describe the schema with raw JSON Schema instead of Pydantic diff --git a/docs/api.md b/docs/api.md index a0ea4e6d..3c8645fb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -92,8 +92,10 @@ controls protected documentation keys: | `"none"` | No forwarding; suitable for edge authentication or an anonymous spec | | `None` (default) | Legacy query behavior with a caller-facing `DeprecationWarning` for protected registrations | -Anonymous routes never forward keys or warn. Explicit values suppress the warning; -the default will become `"header"` in a future minor release before 1.0. The +Anonymous routes never forward keys or warn. Explicit values suppress the warning. +The default will become `"header"` no earlier than the minor release after the one +that first warns, and before 1.0; see the +[migration boundary](security.md#protecting-documentation-routes). The initial page navigation can still expose the key in access logs before browser URL replacement. A function-scoped key authorizes only its own function; the key must authorize both the docs and JSON functions. Prefer production edge auth. diff --git a/docs/security.md b/docs/security.md index 2b2a2c29..742b4bdc 100644 --- a/docs/security.md +++ b/docs/security.md @@ -105,10 +105,34 @@ it cannot read or forward a header from the initial page request. and emits a `DeprecationWarning` once per protected registration. Silence it by choosing `"header"` explicitly (recommended), or `"none"` for edge-authenticated or intentionally anonymous specifications. Explicit `"query"` retains the old -key-in-HTML/spec-URL exposure and is only a compatibility escape hatch. The -default will change to `"header"` in a future minor release before 1.0. +key-in-HTML/spec-URL exposure and is only a compatibility escape hatch. Anonymous registrations never forward a page key, in any mode. +**Who is affected.** Only protected registrations (`auth_level` other than +`ANONYMOUS`) that leave `docs_key_forwarding` unset. Anonymous docs never forward +a key and never change. + +| Your setup | What to do | +| --- | --- | +| Opens `/api/docs?code=` in a browser and relies on Swagger UI loading the spec | Set `"header"`. The page behaves the same; the key moves from the spec URL to an `x-functions-key` header on the spec download only. | +| Edge authentication (API Management, Easy Auth) already protects the routes | Set `"none"`. No key is needed in the page. | +| Scripts or tools that read the spec URL out of the served HTML and expect `?code=` in it | Set `"query"` to keep the old output for now, or switch them to send `x-functions-key` to `/api/openapi.json` directly. | +| Anonymous docs | Nothing. No warning, no change. | + +**Compatibility boundary.** This package is pre-1.0, so the default is changed in a +minor release, not a patch: + +1. The release that first ships the `DeprecationWarning` keeps the default at legacy + `"query"` behavior. No output changes for existing callers. +2. The default changes to `"header"` no earlier than the next minor release after + that, and always before 1.0. That release is announced with a breaking-change + marker so it appears in the release notes (see the Title Convention in + `CONTRIBUTING.md`). +3. Explicit `"query"` keeps working through that change. Removing it would be a + separate, later decision and would be announced the same way. + +The switch only affects protected registrations that left the argument unset. + ### 3. Enforce access at the platform edge For identity-aware or policy-based access, keep the documentation endpoints From 4d460e6a4611df14040df133573512d5d09eb798 Mon Sep 17 00:00:00 2001 From: Yeongseon Choe Date: Mon, 26 Oct 2026 08:26:50 +0900 Subject: [PATCH 2/2] docs(security): qualify edge-authentication guidance for header forwarding --- docs/security.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/security.md b/docs/security.md index 742b4bdc..4b6de399 100644 --- a/docs/security.md +++ b/docs/security.md @@ -115,7 +115,8 @@ a key and never change. | Your setup | What to do | | --- | --- | | Opens `/api/docs?code=` in a browser and relies on Swagger UI loading the spec | Set `"header"`. The page behaves the same; the key moves from the spec URL to an `x-functions-key` header on the spec download only. | -| Edge authentication (API Management, Easy Auth) already protects the routes | Set `"none"`. No key is needed in the page. | +| Edge authentication (API Management, Easy Auth) protects the routes **and** the registration uses `auth_level=ANONYMOUS`, or the edge supplies the backend function key itself | Set `"none"`. The page does not need to forward a key. | +| Edge authentication in front of routes that still use `auth_level=FUNCTION` and expect the caller's key | Keep `"header"`. `"none"` would stop sending the key and the spec download would fail authentication even though `/api/docs?code=...` loads. | | Scripts or tools that read the spec URL out of the served HTML and expect `?code=` in it | Set `"query"` to keep the old output for now, or switch them to send `x-functions-key` to `/api/openapi.json` directly. | | Anonymous docs | Nothing. No warning, no change. |