fix(dav): stop advertising unimplemented production methods

.github/workflows/one-shot-dav-production-contract.yml

@@ -0,0 +1,56 @@
+name: One-shot DAV production contract integration
+
+on:
+  push:
+    branches: [fix/dav-capability-truthfulness-20260809]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: one-shot-dav-production-contract
+  cancel-in-progress: false
+
+jobs:
+  document-compile-commit:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout exact branch head
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: fix/dav-capability-truthfulness-20260809
+          fetch-depth: 0
+
+      - name: Record the product contract in CHANGELOG
+        shell: python3 {0}
+        run: |
+          from pathlib import Path
+
+          path = Path('CHANGELOG.md')
+          source = path.read_text(encoding='utf-8')
+          anchor = '## [Unreleased]\n'
+          section = '''## [Unreleased]\n\n### DAV 프로덕션 기능 정합성\n\n- DAV 라우터가 실제 구현된 `OPTIONS`·`PROPFIND`만 등록·광고하도록 축소했습니다. GET/PUT/DELETE/MKCOL/REPORT/PROPPATCH/COPY/MOVE/LOCK/UNLOCK의 성공형 501 스텁을 제거해 미지원 동작은 표준 `405 Method Not Allowed`로 처리하고, WebDAV service의 하드코딩된 demo 계정·폴더·성공형 no-op attachment sync API도 삭제했습니다. 계정·폴더·writeback intent는 데이터베이스와 서버 권한 경계에서만 결정됩니다.\n'''
+          if source.count(anchor) != 1:
+              raise SystemExit('expected exactly one Unreleased changelog anchor')
+          path.write_text(source.replace(anchor, section, 1), encoding='utf-8')
+
+      - name: Compile changed Python modules
+        run: |
+          python3 -m compileall -q backend/api/dav.py backend/services/webdav_service.py backend/tests/test_dav_api.py backend/tests/test_dav_sync.py
+
+      - name: Commit verified documentation and remove one-shot workflow
+        run: |
+          set -euo pipefail
+          git rm .github/workflows/one-shot-dav-production-contract.yml
+          git add CHANGELOG.md
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit -m 'docs(changelog): record DAV production contract'
+          git push origin HEAD:fix/dav-capability-truthfulness-20260809

backend/api/dav.py

@@ -13,8 +13,11 @@
 
 router = APIRouter(prefix="/dav", tags=["dav"])
 
+IMPLEMENTED_DAV_METHODS = ("OPTIONS", "PROPFIND")
+
 
 def _normalize_dav_authorization_path(path: str) -> str:
+    """Decode a DAV path within a bounded authorization-normalization loop."""
     normalized_path = path.replace("\\", "/")
     for _ in range(100):
         decoded_path = unquote(normalized_path).replace("\\", "/")
@@ -25,6 +28,7 @@ def _normalize_dav_authorization_path(path: str) -> str:
 
 
 def _dav_path_owner_user_id(path: str) -> str | None:
+    """Return the owner segment for a traversal-safe DAV path."""
     path = _normalize_dav_authorization_path(path)
     if any(segment in {".", ".."} for segment in path.split("/")):
         return None
@@ -36,6 +40,7 @@ def _dav_path_owner_user_id(path: str) -> str | None:
 
 
 def _ensure_dav_owner_scope(path: str, auth_context: AuthContext) -> None:
+    """Require the DAV path owner to match the authenticated user."""
     owner_user_id = _dav_path_owner_user_id(path)
     if owner_user_id is None:
         raise HTTPException(
@@ -51,10 +56,12 @@ def _ensure_dav_owner_scope(path: str, auth_context: AuthContext) -> None:
 
 
 def _dav_path_segments(path: str) -> list[str]:
+    """Return non-empty DAV path segments."""
     return [segment for segment in path.strip("/").split("/") if segment]
 
 
 def _dav_multistatus_xml(responses: list[str]) -> str:
+    """Render one DAV multistatus document from validated response fragments."""
     response_xml = "\n".join(responses)
     if response_xml:
         response_xml = f"\n{response_xml}\n"
@@ -68,6 +75,7 @@ def _dav_response_xml(
     display_name: str,
     is_collection: bool = True,
 ) -> str:
+    """Render one escaped DAV response element."""
     resourcetype = "<D:collection/>" if is_collection else ""
     escaped_href = escape_xml_text(href)
     escaped_display_name = escape_xml_text(display_name)
@@ -84,6 +92,7 @@ def _dav_response_xml(
 
 
 def _dav_xml_response(responses: list[str]) -> Response:
+    """Return a DAV 207 multistatus response."""
     return Response(
         content=_dav_multistatus_xml(responses),
         media_type="application/xml",
@@ -92,13 +101,15 @@ def _dav_xml_response(responses: list[str]) -> Response:
 
 
 def _dav_depth(request: Request) -> str:
+    """Normalize supported DAV Depth values to zero or one."""
     depth = request.headers.get("Depth", "1").strip().lower()
     if depth == "0":
         return "0"
     return "1"
 
 
 def _project_folder_response(path_owner_user_id: str, folder: dict) -> str:
+    """Render one project-folder collection response."""
     folder_uid = str(folder["folder_uid"])
     project_name = str(folder["project_name"])
     return _dav_response_xml(
@@ -115,6 +126,7 @@ async def _handle_project_propfind(
     auth_context: AuthContext,
     db: AsyncSession,
 ) -> Response:
+    """Return tenant-scoped project collection metadata for PROPFIND."""
     segments = _dav_path_segments(path)
     if len(segments) < 2 or segments[1] != "projects":
         raise HTTPException(status_code=404, detail="DAV collection not found")
@@ -158,73 +170,37 @@ async def _handle_project_propfind(
 
 @router.api_route(
     "/{path:path}",
-    methods=["PROPFIND", "REPORT", "MKCOL", "GET", "PUT", "DELETE", "OPTIONS"],
+    methods=list(IMPLEMENTED_DAV_METHODS),
 )
 async def dav_handler(
     request: Request,
     path: str,
     auth_context: AuthContext = Depends(get_auth_context),
     db: AsyncSession = Depends(get_db),
-):
-    """
-    Route the authenticated DAV surface that is implemented for this slice.
+) -> Response:
+    """Serve only the authenticated DAV capabilities implemented in production.
 
-    Collection discovery is served from the server-side project registry.
-    Provider-backed writeback stays fail-closed until source capability and
-    ETag/If-Match enforcement are available through signed writeback intents.
+    ScopeWeave-compatible clients can discover project collections through
+    ``PROPFIND``. Provider-backed mutation verbs are deliberately not registered;
+    the framework returns ``405 Method Not Allowed`` rather than advertising a
+    handler that can only return ``501 Not Implemented``.
     """
     _ensure_dav_owner_scope(path, auth_context)
     safe_path = repr(path)[1:-1]
     logger.info("DAV Request: %s /%s", request.method, safe_path)
 
     if request.method == "OPTIONS":
-        headers = {
-            "DAV": "1, 2, 3, calendar-access, addressbook",
-            "Allow": (
-                "OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE, MKCOL, "
-                "PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT"
-            ),
-        }
-        return Response(status_code=200, headers=headers)
-
-    if request.method == "PROPFIND":
-        return await _handle_project_propfind(
-            request=request,
-            path=path,
-            auth_context=auth_context,
-            db=db,
-        )
-
-    if request.method == "PUT":
-        body = await request.body()
-        safe_path = repr(path)[1:-1]
-        logger.info("DAV PUT received %s bytes at /%s", len(body), safe_path)
-        logger.warning(
-            "DAV PUT rejected at /%s: provider-backed DAV writeback is not "
-            "implemented; signed writeback-intent API is required",
-            safe_path,
-        )
         return Response(
-            content=(
-                "Provider-backed DAV writeback is not implemented; use signed "
-                "writeback-intent APIs until source, capability, and "
-                "ETag/If-Match checks are enforced."
-            ),
-            media_type="text/plain",
-            status_code=501,
+            status_code=200,
+            headers={
+                "DAV": "1",
+                "Allow": ", ".join(IMPLEMENTED_DAV_METHODS),
+            },
         )
 
-    logger.warning(
-        "DAV %s rejected at /%s: method is not implemented for the "
-        "provider-backed DAV gateway",
-        request.method,
-        safe_path,
-    )
-    return Response(
-        content=(
-            "Provider-backed DAV method is not implemented; use supported "
-            "PROPFIND/OPTIONS discovery or signed writeback-intent APIs."
-        ),
-        media_type="text/plain",
-        status_code=501,
+    return await _handle_project_propfind(
+        request=request,
+        path=path,
+        auth_context=auth_context,
+        db=db,
     )

backend/docs/dav-production-capabilities.md

@@ -0,0 +1,48 @@
+# DAV Production Capability Contract
+
+Naruon exposes only DAV operations that have complete tenant authorization,
+persisted data, deterministic tests, and production handlers.
+
+## Supported DAV methods
+
+| Method | Status | Production behavior |
+| --- | --- | --- |
+| `OPTIONS` | Supported | Returns `DAV: 1` and advertises only `OPTIONS, PROPFIND`. |
+| `PROPFIND` | Supported | Returns tenant-scoped project collections from PostgreSQL. |
+
+The router does not register `GET`, `PUT`, `DELETE`, `MKCOL`, `REPORT`,
+`PROPPATCH`, `COPY`, `MOVE`, `LOCK`, or `UNLOCK`. FastAPI therefore returns
+`405 Method Not Allowed` rather than exposing success-shaped or `501` stubs.
+Mutation is available only through Naruon's authenticated writeback-intent
+workflow until each DAV verb has provider capability discovery, precondition
+handling (`ETag`/`If-Match` where applicable), durable audit evidence, and real
+connector execution.
+
+## Data and identity boundary
+
+- DAV paths must contain the authenticated owner user ID.
+- Project folders come from the persisted `project_folder` registry and are
+  scoped by user and organization.
+- Connected WebDAV accounts come from `webdav_account` records; hard-coded demo
+  accounts and folders are forbidden.
+- Runtime code must not return successful attachment synchronization when no
+  provider write occurred.
+- XML values are escaped and request-path control characters are encoded before
+  logging.
+
+## Verification
+
+Every changed DAV capability requires:
+
+1. a fail-first API regression;
+2. tenant and owner authorization tests;
+3. positive provider or database integration evidence;
+4. negative tests for unsupported methods and stale preconditions;
+5. production statement and branch coverage of 100%; and
+6. exact-head security and required checks before merge.
+
+## Primary standard — APA 7th
+
+Dusseault, L. (2007). *HTTP extensions for Web Distributed Authoring and
+Versioning (WebDAV)* (RFC 4918). Internet Engineering Task Force.
+https://doi.org/10.17487/RFC4918