webdav: advertise DAV capability on the unauthenticated OPTIONS probe

Windows' WebClient (Mini-Redirector) sends an unauthenticated OPTIONS
first and, on a bare 401, can fail to recognise the server as WebDAV —
surfacing as 0x80070043 'network name not found' and the well-known
intermittent-connect behaviour. Attach DAV/MS-Author-Via/Allow headers to
that challenge so the very first probe identifies the server as WebDAV,
while still requiring a token before any data is returned.

Also expand the Windows troubleshooting docs (UNC-vs-@ssl, WebClient
service restart/negative cache, BasicAuthLevel, 50 MB FileSizeLimit).

Author: softpython2884

apps/api/src/routes/webdav.ts

@@ -158,21 +158,28 @@ export const webdavRoutes: FastifyPluginAsync = async (app) => {
   }
 
   async function handle(req: FastifyRequest, reply: FastifyReply) {
-    const principal = await auth(req, reply);
-    if (!principal) return;
-    const ownerId = principal.ownerId;
-    const segments = pathSegments((req.params as Record<string, string>)['*']);
     const method = req.method;
 
+    // Advertise WebDAV capability on EVERY OPTIONS — including the unauthenticated probe Windows'
+    // Mini-Redirector sends first. Setting DAV/MS-Author-Via/Allow before the auth challenge means
+    // Windows recognises the server as WebDAV on that first request (otherwise it only learns this
+    // on a second, authenticated round-trip, which is a common source of "this isn't a WebDAV
+    // site" / 0x80070043 flakiness). No user data is exposed — these are static capabilities.
     if (method === 'OPTIONS') {
-      return reply
+      reply
         .header('DAV', '1, 2')
         .header('MS-Author-Via', 'DAV')
-        .header('Allow', 'OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCOL, MOVE, COPY, LOCK, UNLOCK')
-        .code(204)
-        .send();
+        .header('Allow', 'OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCOL, MOVE, COPY, LOCK, UNLOCK');
+      const principal = await auth(req, reply);
+      if (!principal) return; // 401 challenge, now carrying the DAV headers above
+      return reply.code(204).send();
     }
 
+    const principal = await auth(req, reply);
+    if (!principal) return;
+    const ownerId = principal.ownerId;
+    const segments = pathSegments((req.params as Record<string, string>)['*']);
+
     const node = await resolvePath(ownerId, segments);
 
     const base = davBase(req);

apps/api/test/webdav.test.ts

@@ -49,10 +49,14 @@ describe('webdav routing (boot smoke-test)', () => {
 
   // No auth header → challenge BEFORE any DB access. Proves the custom methods are routed and
   // that WebDAV sits outside the CORS scope (otherwise OPTIONS would be 400/204 from cors).
-  it('challenges an unauthenticated OPTIONS /dav', async () => {
+  // The 401 still carries the DAV capability headers so Windows' Mini-Redirector detects WebDAV
+  // on its first, unauthenticated probe.
+  it('challenges an unauthenticated OPTIONS /dav but advertises DAV capability', async () => {
     const res = await app.inject({ method: 'OPTIONS', url: '/dav' });
     expect(res.statusCode).toBe(401);
     expect(String(res.headers['www-authenticate'])).toContain('Basic');
+    expect(String(res.headers['dav'])).toContain('1');
+    expect(String(res.headers['ms-author-via'])).toBe('DAV');
   });
 
   it('routes the custom PROPFIND verb', async () => {

docs/API.md

@@ -167,12 +167,37 @@ curl -u "me:ocl_YOUR_TOKEN" -X PROPFIND -H "Depth: 1" https://<host>/api/dav/
 
 ### Windows Explorer
 
-Windows' built-in WebDAV client is strict:
-
-- Use **HTTPS** (you do) and make sure the **WebClient** service is running (`services.msc`).
-- Windows often refuses Basic auth even over HTTPS until you set, in
-  `HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`, the DWORD
-  **`BasicAuthLevel = 2`**, then restart the WebClient service.
-- If it still won't map, test with **rclone**, **Cyberduck** or **WinSCP** first — if those work,
-  it's a Windows-client limitation, not the server.
+Windows' built-in WebDAV client (the *WebClient* / Mini-Redirector service) is strict and its
+errors are misleading — **`0x80070043` "The network name cannot be found"** almost always means
+Windows never completed the WebDAV handshake, **not** that the server is down. Work through these
+in order:
+
+1. **Never use a `\\host\…` UNC path for an internet server.** `\\copper.forgenet.fr\api\dav\`
+   makes Windows try **SMB (port 445)** first, which is blocked over the internet → `0x80070043`.
+   Either:
+   - **Map network drive** with the plain URL `https://copper.forgenet.fr/api/dav/`, **or**
+   - if you must use a UNC path, use the SSL WebDAV form:
+     `\\copper.forgenet.fr@SSL\api\dav\` (add `@443` after `@SSL` if you run on a non-standard port).
+2. **Make sure the WebClient service is running and restart it.** It caches a "this server isn't
+   WebDAV" verdict after any failed attempt — which is exactly why it works *sometimes*. Clearing
+   that cache fixes most intermittent failures. In an **admin** PowerShell / CMD:
+   ```
+   net stop webclient & net start webclient
+   ```
+   (Set its startup type to *Automatic* in `services.msc` so it's always up.)
+3. **Allow Basic auth over HTTPS.** Windows refuses Basic even over TLS until you set, in
+   `HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters`, the DWORD
+   **`BasicAuthLevel = 2`**, then restart WebClient (step 2).
+4. **Raise the download size cap.** Windows refuses files larger than **50 MB** over WebDAV by
+   default. In the same `Parameters` key set the DWORD **`FileSizeLimitInBytes`** to e.g.
+   `4294967295` (≈4 GB, the max) and restart WebClient.
+5. **Credentials:** leave the username as anything (it's ignored) and paste your **`ocl_…` API
+   token as the password**. Use an *unrestricted* token — folder-scoped tokens are refused.
+6. If it still won't map, prove it's Windows and not the server by testing with **rclone**,
+   **Cyberduck** or **WinSCP** — if those connect (they will), it's purely a Windows-client quirk.
+   You can also confirm the server from any machine:
+   ```bash
+   curl -u "me:ocl_YOUR_TOKEN" -X PROPFIND -H "Depth: 1" https://copper.forgenet.fr/api/dav/
+   ```
+   A `207 Multi-Status` with XML = the server and proxy are perfect; the ball is in Windows' court.
 </content>