🎨 Palette: Swagger UI 인증 정보 유지 기능 추가

.jules/palette.md

@@ -5,5 +5,10 @@
 
 ## 2026-08-04 - Backend API Developer Experience
 
-**Learning:** 백엔드 전용 프로젝트(프론트엔드가 없는 경우)에서는 'UX(사용자 경험)'가 주로 'DX(개발자 경험)'로 해석됩니다. OpenAPI/Swagger 스키마에 `json_schema_extra={"example": ...}`와 같은 구체적인 예시를 추가하면 API를 사용하는 개발자들의 인터페이스 이해도를 높일 수 있습니다.
-**Action:** 향후 백엔드 API 중심의 프로젝트에서는 Pydantic 스키마 정의에 풍부한 문서화와 예제 데이터가 포함되어 있는지 확인하여 개발자 경험을 개선할 것입니다.
+**Learning:** 백엔드 전용 프로젝트에서는 Swagger UI와 OpenAPI 스키마도 실제 사용자 인터페이스입니다. 예제와 설명은 개발자가 계약을 이해하는 데 직접 영향을 주므로, Pydantic 스키마의 실제 제약과 어긋나지 않는 범위에서 구체적으로 제공해야 합니다.
+**Action:** API 스키마를 바꿀 때는 생성된 OpenAPI와 `/docs` 동작을 함께 검증하고, 예제 데이터가 실제 검증 규칙을 통과하는지 확인합니다.
+
+## 2026-09-01 - Swagger UI authorization persistence
+
+**Learning:** Swagger UI의 `persistAuthorization`은 새로고침 뒤에도 인증 값을 유지하지만 기본값은 `false`입니다. 개발 편의를 위해 이를 켜더라도 운영·공용 브라우저까지 일괄 적용하면 Bearer 토큰의 브라우저 잔존 범위를 불필요하게 늘립니다. 또한 FastAPI 기본 Swagger UI는 외부 정적 자산과 인라인 초기화 스크립트를 사용하므로 `default-src 'none'`만 적용하면 UI 자체가 실행되지 않습니다.
+**Action:** `persistAuthorization`은 명시적 development runtime에서만 활성화합니다. `/docs`에 필요한 CSP 예외는 문서 경로에만 한정하고, API 응답의 기본 `default-src 'none'` 경계는 유지합니다. 설정 변경은 생성된 Swagger HTML, CSP 헤더, 비문서 경로의 보안 헤더 회귀 테스트로 검증합니다.

docs/product-technical-gap-baseline.md

@@ -0,0 +1,33 @@
+# Product and technical gap baseline
+
+This document records gaps that are observable from the current NewsDOM code, delivery policy, releases, and open integration work. It is not a roadmap commitment; a gap leaves this list only after the corresponding code and evidence are current on the protected integration path.
+
+## Product boundary
+
+NewsDOM API owns the PDF-to-canonical-NewsDOM parsing boundary around MinerU. It accepts an authenticated PDF, validates and bounds the upload, invokes the local MinerU runtime, and returns the repository's NewsDOM response schema. Authentication, parsing and readiness truth stay in this service; consumers such as Naruon use the released API contract rather than source-copying NewsDOM internals.
+
+The latest immutable GitHub release observed while updating this baseline is `v0.2.0` (published 2026-04-24). `CHANGELOG.md` currently describes an unreleased `0.3.0` migration in which parser authentication becomes default-required.
+
+## Current gaps
+
+| Gap | Current evidence | Acceptance |
+| --- | --- | --- |
+| Interactive API documentation security and behavior | PR #775 repairs unconditional Swagger authorization persistence and the global CSP that blocked FastAPI's generated documentation assets. Authorization persistence is development-only; Swagger and ReDoc now receive route-scoped CSP policies in both runtime profiles, the external Swagger validator is disabled, and non-document API responses retain the locked-down CSP. Repository policy still requires a live localhost `/docs` and `/redoc` smoke for documentation changes. | Current-head unit/coverage/docs gates pass; a real browser/local smoke proves `/docs` and `/redoc` render without CSP errors in production and development; a refresh in development preserves Swagger authorization while production does not persist it; screenshots or equivalent browser evidence correspond to the exact tested head. |
+| `0.3.0` release readiness | The changelog still uses an unreleased image placeholder for the authentication migration. The last immutable release is `v0.2.0`. | Protected `develop` evidence is GREEN; package, OpenAPI, container image, SBOM/provenance, rollback instructions and release manifest identify the same version and source; the release tag is immutable and reproducible. |
+| Runtime configuration boundary | `AGENTS.md` records `NEWSDOM_MINERU_BIN` as the remaining raw-environment deployment knob and requires future secrets/credentials/external endpoints to use the canonical KV/credential-registry pattern. | The executable-path override has an explicit deployment/configuration ADR or is moved behind the adopted configuration boundary; no new runtime secret is read directly from process environment. |
+| Real-data parser acceptance | Synthetic fixtures remain suitable for unit tests, but commercial parsing acceptance requires right-cleared representative PDFs and must not publish private/copyrighted inputs. | A private/right-cleared acceptance corpus exercises representative layouts, languages, page counts and failure cases; results are reproducible and published only as non-sensitive metrics/evidence, not source documents. |
+
+## Current PR #775 traceability
+
+The repair sequence on branch `jules-11760207665579123715-6bc329bb` is test-first:
+
+- Swagger RED regression: `31bf14cd6d71e03b0b31320c940c3b79f3d984ca`
+- development-only authorization persistence and initial Swagger CSP fix: `6c4a5846761e4c1eee2d968c690589811de875a7`
+- corrected CSP test oracle: `623b14fc62262fddb8e0d810e72317908cf76ae5`
+- documentation alignment: `bbaed060f1243dc30653c40b2e66c9d93df46474`
+- baseline introduction: `281ace5a3df9f23ef9f43d9984b55d3353c768b5`
+- ReDoc CSP RED: `282d5d9259b578913c7fbe29fce9415bad3c106f`
+- production-route CSP RED expansion: `31d441f67f8f91f072a04bcd5e30b3481256ec0f`
+- route-scoped Swagger/ReDoc causal fix: `d9199541d00a1da1cc732af42f6f59a6e2e59cbe`
+
+GitHub-hosted verification must be evaluated on the final exact head, not on any predecessor listed above. Queued jobs or CodeQL `startup_failure` before source execution are incomplete evidence, not passing gates and not a reason for no-op source churn.

src/newsdom_api/main.py

@@ -27,6 +27,7 @@
 from .config import (
     AuthenticationMode,
     MAX_BEARER_HEADER_BYTES,
+    RuntimeProfile,
     RuntimeSettings,
     load_runtime_settings,
 )
@@ -50,6 +51,25 @@
 SERVICE_UNAVAILABLE_DETAIL = "Service Unavailable"
 LOGGER = logging.getLogger("newsdom_api")
 BEARER_SCHEME = HTTPBearer(auto_error=False, scheme_name="BearerAuth")
+LOCKED_DOWN_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'"
+SWAGGER_DOCS_CSP = (
+    "default-src 'none'; "
+    "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+    "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+    "img-src 'self' data: https://fastapi.tiangolo.com; "
+    "font-src 'self' data: https://cdn.jsdelivr.net; "
+    "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; "
+    "form-action 'self'"
+)
+REDOC_DOCS_CSP = (
+    "default-src 'none'; "
+    "script-src 'self' https://cdn.jsdelivr.net; "
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "
+    "font-src 'self' https://fonts.gstatic.com; "
+    "img-src 'self' data: https://fastapi.tiangolo.com; "
+    "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; "
+    "form-action 'self'"
+)
 
 tags_metadata = [
     {"name": "Parser", "description": "Core PDF parsing endpoints."},
@@ -65,9 +85,14 @@ def _apply_security_headers(response: Response, request: Request) -> Response:
 
     response.headers["X-Content-Type-Options"] = "nosniff"
     response.headers["X-Frame-Options"] = "DENY"
-    response.headers["Content-Security-Policy"] = (
-        "default-src 'none'; frame-ancestors 'none'; base-uri 'none'"
-    )
+    path = request.scope.get("path")
+    if path in {"/docs", "/docs/oauth2-redirect"}:
+        csp = SWAGGER_DOCS_CSP
+    elif path == "/redoc":
+        csp = REDOC_DOCS_CSP
+    else:
+        csp = LOCKED_DOWN_CSP
+    response.headers["Content-Security-Policy"] = csp
     response.headers["Referrer-Policy"] = "no-referrer"
     response.headers["Cache-Control"] = "no-store, no-cache, max-age=0"
     forwarded_proto = request.headers.get("x-forwarded-proto", "")
@@ -321,6 +346,10 @@ def create_app(
             "displayRequestDuration": True,
             "syntaxHighlight.theme": "monokai",
             "tryItOutEnabled": True,
+            "persistAuthorization": (
+                application_settings.runtime_profile is RuntimeProfile.DEVELOPMENT
+            ),
+            "validatorUrl": None,
         },
     )
     application.state.runtime_settings = application_settings

tests/test_swagger_docs_security.py

@@ -0,0 +1,84 @@
+"""Regression tests for the interactive API documentation security boundary."""
+
+from fastapi.testclient import TestClient
+
+from newsdom_api.config import AuthenticationMode, RuntimeProfile, RuntimeSettings
+from newsdom_api.main import create_app
+
+LOCKED_DOWN_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'"
+
+
+def _settings(profile: RuntimeProfile) -> RuntimeSettings:
+    """Build an authenticated runtime configuration for one profile."""
+
+    return RuntimeSettings(
+        authentication_mode=AuthenticationMode.REQUIRED,
+        runtime_profile=profile,
+        api_token="swagger-test-token",
+    )
+
+
+def test_swagger_authorization_persistence_is_development_only() -> None:
+    """Persist bearer authorization only in the explicit development profile."""
+
+    production = TestClient(create_app(_settings(RuntimeProfile.PRODUCTION)))
+    development = TestClient(create_app(_settings(RuntimeProfile.DEVELOPMENT)))
+
+    production_docs = production.get("/docs")
+    development_docs = development.get("/docs")
+
+    assert production_docs.status_code == 200
+    assert development_docs.status_code == 200
+    assert '"persistAuthorization": false' in production_docs.text
+    assert '"persistAuthorization": true' in development_docs.text
+    assert '"validatorUrl": null' in development_docs.text
+
+
+def test_swagger_csp_allows_only_required_origins_in_each_profile() -> None:
+    """Swagger UI can execute in each runtime profile with a route-scoped CSP."""
+
+    for profile in (RuntimeProfile.PRODUCTION, RuntimeProfile.DEVELOPMENT):
+        client = TestClient(create_app(_settings(profile)))
+        response = client.get("/docs")
+
+        assert response.status_code == 200
+        csp = response.headers["Content-Security-Policy"]
+        assert "default-src 'none'" in csp
+        assert "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net" in csp
+        assert "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net" in csp
+        assert "img-src 'self' data: https://fastapi.tiangolo.com" in csp
+        assert "connect-src 'self'" in csp
+        assert "frame-ancestors 'none'" in csp
+        assert "base-uri 'none'" in csp
+        assert "form-action 'self'" in csp
+
+
+def test_redoc_csp_allows_only_required_origins_in_each_profile() -> None:
+    """ReDoc can load its script, fonts, schema and favicon in each profile."""
+
+    for profile in (RuntimeProfile.PRODUCTION, RuntimeProfile.DEVELOPMENT):
+        client = TestClient(create_app(_settings(profile)))
+        response = client.get("/redoc")
+
+        assert response.status_code == 200
+        csp = response.headers["Content-Security-Policy"]
+        assert "default-src 'none'" in csp
+        assert "script-src 'self' https://cdn.jsdelivr.net" in csp
+        assert "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com" in csp
+        assert "font-src 'self' https://fonts.gstatic.com" in csp
+        assert "img-src 'self' data: https://fastapi.tiangolo.com" in csp
+        assert "connect-src 'self'" in csp
+        assert "frame-ancestors 'none'" in csp
+        assert "base-uri 'none'" in csp
+        assert "form-action 'self'" in csp
+
+
+def test_non_docs_responses_keep_the_locked_down_csp() -> None:
+    """The docs exception must not weaken the API response security boundary."""
+
+    for profile in (RuntimeProfile.PRODUCTION, RuntimeProfile.DEVELOPMENT):
+        client = TestClient(create_app(_settings(profile)), base_url="https://testserver")
+        response = client.get("/health")
+
+        assert response.status_code == 200
+        assert response.headers["Content-Security-Policy"] == LOCKED_DOWN_CSP