fix(dav): stop advertising unimplemented production methods

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