Add a WebDAV endpoint to mount the Drive as a network drive

Mount normal (server-encrypted) spaces in Finder / Windows Explorer / rsync / Cyberduck.

- routes/webdav.ts: class-1 WebDAV + stubbed locks — OPTIONS, PROPFIND (depth 0/1), GET, HEAD,
  PUT, MKCOL, DELETE, MOVE, LOCK/UNLOCK, PROPPATCH (COPY → 501). PUT reuses storeUserFile, so
  quota/AV/versioning/webhooks all apply. Vault folders are excluded.
- Auth is HTTP Basic where the PASSWORD is an API token; folder-restricted tokens are refused.
- server.ts: register the custom WebDAV verbs via addHttpMethod and mount /dav OUTSIDE the CORS
  scope — @fastify/cors uses strictPreflight and would answer WebDAV's OPTIONS with 400/204,
  hiding the DAV headers. Browser routes are now wrapped so CORS applies only to them.
- Unit tests for the path/href/XML helpers + routing (custom verb reaches the handler, /dav is
  outside CORS). Account ▸ WebDAV card + docs/API.md section. FR/EN parity (453).

NOTE: needs a real-client mount test (Finder/Windows/rclone) — can't be exercised in CI.

Author: softpython2884

apps/api/src/routes/webdav.ts

@@ -0,0 +1,297 @@
+/**
+ * Minimal WebDAV (class 1 + stubbed locks) so the Drive can be mounted as a network drive
+ * (Finder, Windows Explorer, rsync/davfs, Cyberduck…). Normal (server-encrypted) folders only —
+ * Zero-Knowledge vaults are decrypted in the browser and can't be served here.
+ *
+ * Auth is HTTP Basic where the PASSWORD is a personal API token (`ocl_…`); the username is
+ * ignored. Read methods need the token's `read` scope, writes need `write`. Folder-restricted
+ * tokens are refused — WebDAV exposes the whole account tree.
+ *
+ * This module is mounted OUTSIDE the CORS scope: @fastify/cors uses strictPreflight and would
+ * answer every WebDAV OPTIONS with 400/204, hiding the DAV capability headers clients rely on.
+ */
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+import type { Readable } from 'node:stream';
+import type { FileObject, Folder } from '@prisma/client';
+import { prisma } from '../db.js';
+import { authenticateToken } from '../services/apiToken.js';
+import { decryptServerFile } from '../services/download.js';
+import { storeUserFile, QuotaExhaustedError } from '../services/upload.js';
+import { FileTooLargeError, InfectedFileError } from '../services/ingest.js';
+import { trashFile, trashFolder } from '../services/trash.js';
+
+const PREFIX = '/dav';
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PROPFIND']);
+
+export function escapeXml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]!);
+}
+
+/** Absolute href for a path, with a trailing slash for collections. */
+export function hrefFor(segments: string[], isCollection: boolean): string {
+  const encoded = segments.map((s) => encodeURIComponent(s)).join('/');
+  const base = encoded ? `${PREFIX}/${encoded}` : `${PREFIX}`;
+  return isCollection ? `${base}/` : base;
+}
+
+/** Split a WebDAV request path (the part after /dav) into decoded, non-empty segments. */
+export function pathSegments(star: string | undefined): string[] {
+  return (star ?? '')
+    .split('/')
+    .filter(Boolean)
+    .map((s) => {
+      try {
+        return decodeURIComponent(s);
+      } catch {
+        return s;
+      }
+    });
+}
+
+type Resolved =
+  | { type: 'root' }
+  | { type: 'folder'; folder: Folder; parentId: string | null }
+  | { type: 'file'; file: FileObject; parentId: string | null }
+  | { type: 'missing'; parentId: string | null; name: string }
+  | { type: 'invalid' };
+
+/** Walk a path's segments, matching folders by name; the last may be a file. */
+async function resolvePath(ownerId: string, segments: string[]): Promise<Resolved> {
+  if (segments.length === 0) return { type: 'root' };
+  let parentId: string | null = null;
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    const folder: Folder | null = await prisma.folder.findFirst({
+      where: { ownerId, parentId, name: segments[i], isZeroKnowledge: false },
+    });
+    if (!folder) return { type: 'invalid' };
+    parentId = folder.id;
+  }
+  const last = segments[segments.length - 1]!;
+  const folder = await prisma.folder.findFirst({ where: { ownerId, parentId, name: last, isZeroKnowledge: false } });
+  if (folder) return { type: 'folder', folder, parentId };
+  const file = await prisma.fileObject.findFirst({
+    where: { ownerId, folderId: parentId, name: last, encMode: 'SERVER', deletedAt: null },
+  });
+  if (file) return { type: 'file', file, parentId };
+  return { type: 'missing', parentId, name: last };
+}
+
+function propXml(segments: string[], isCollection: boolean, name: string, size: number, mtime: Date, mime: string): string {
+  const props = isCollection
+    ? `<D:resourcetype><D:collection/></D:resourcetype>`
+    : `<D:resourcetype/><D:getcontentlength>${size}</D:getcontentlength><D:getcontenttype>${escapeXml(mime)}</D:getcontenttype>`;
+  return (
+    `<D:response><D:href>${escapeXml(hrefFor(segments, isCollection))}</D:href>` +
+    `<D:propstat><D:prop>` +
+    `<D:displayname>${escapeXml(name)}</D:displayname>` +
+    `<D:getlastmodified>${mtime.toUTCString()}</D:getlastmodified>` +
+    props +
+    `</D:prop><D:status>HTTP/1.1 200 OK</D:status></D:propstat></D:response>`
+  );
+}
+
+export const webdavRoutes: FastifyPluginAsync = async (app) => {
+  // Pass request bodies through as raw streams (PUT) and accept any content type (PROPFIND XML).
+  app.addContentTypeParser('*', (_req, payload, done) => done(null, payload));
+
+  const challenge = (reply: FastifyReply) =>
+    reply.code(401).header('WWW-Authenticate', 'Basic realm="OpenCoperLock WebDAV"').send();
+
+  async function auth(req: FastifyRequest, reply: FastifyReply): Promise<{ ownerId: string } | null> {
+    const header = req.headers.authorization;
+    if (!header || !header.startsWith('Basic ')) {
+      challenge(reply);
+      return null;
+    }
+    const decoded = Buffer.from(header.slice('Basic '.length), 'base64').toString('utf8');
+    const idx = decoded.indexOf(':');
+    const pass = idx >= 0 ? decoded.slice(idx + 1) : '';
+    const user = idx >= 0 ? decoded.slice(0, idx) : decoded;
+    const token = pass || user; // clients put the token in the password field
+    const scope = READ_METHODS.has(req.method) ? 'read' : 'write';
+    const result = await authenticateToken(`Bearer ${token}`, scope);
+    if (!result.ok) {
+      challenge(reply);
+      return null;
+    }
+    if (result.token.folderId) {
+      reply.code(403).send('Use an unrestricted API token for WebDAV');
+      return null;
+    }
+    return { ownerId: result.owner.id };
+  }
+
+  // A Destination header is an absolute URL or path; reduce it to /dav segments.
+  function destinationSegments(dest: string | undefined): string[] | null {
+    if (!dest) return null;
+    let path = dest;
+    try {
+      path = new URL(dest).pathname;
+    } catch {
+      /* already a path */
+    }
+    const i = path.indexOf(PREFIX);
+    if (i < 0) return null;
+    return pathSegments(path.slice(i + PREFIX.length));
+  }
+
+  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;
+
+    if (method === 'OPTIONS') {
+      return 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();
+    }
+
+    const node = await resolvePath(ownerId, segments);
+
+    if (method === 'PROPFIND') {
+      if (node.type === 'invalid' || node.type === 'missing') return reply.code(404).send();
+      const depth = String(req.headers.depth ?? '1');
+      const parts: string[] = [];
+      if (node.type === 'root') {
+        parts.push(propXml([], true, 'OpenCoperLock', 0, new Date(), ''));
+      } else if (node.type === 'folder') {
+        parts.push(propXml(segments, true, node.folder.name, 0, node.folder.createdAt, ''));
+      } else {
+        parts.push(propXml(segments, false, node.file.name, Number(node.file.sizeBytes), node.file.createdAt, node.file.mimeType));
+      }
+      if (depth !== '0' && node.type !== 'file') {
+        const parentId = node.type === 'root' ? null : node.folder.id;
+        const [folders, files] = await Promise.all([
+          prisma.folder.findMany({ where: { ownerId, parentId, isZeroKnowledge: false }, orderBy: { name: 'asc' } }),
+          prisma.fileObject.findMany({
+            where: { ownerId, folderId: parentId, encMode: 'SERVER', deletedAt: null },
+            orderBy: { name: 'asc' },
+          }),
+        ]);
+        for (const f of folders) parts.push(propXml([...segments, f.name], true, f.name, 0, f.createdAt, ''));
+        for (const f of files) parts.push(propXml([...segments, f.name], false, f.name, Number(f.sizeBytes), f.createdAt, f.mimeType));
+      }
+      return reply
+        .header('Content-Type', 'application/xml; charset=utf-8')
+        .code(207)
+        .send(`<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">${parts.join('')}</D:multistatus>`);
+    }
+
+    if (method === 'GET' || method === 'HEAD') {
+      if (node.type !== 'file') return reply.code(node.type === 'folder' || node.type === 'root' ? 405 : 404).send();
+      reply
+        .header('Content-Type', node.file.mimeType)
+        .header('Content-Length', Number(node.file.sizeBytes))
+        .header('Last-Modified', node.file.createdAt.toUTCString())
+        .header('Accept-Ranges', 'none');
+      if (method === 'HEAD') return reply.send();
+      return reply.send(decryptServerFile(app.ctx, node.file));
+    }
+
+    if (method === 'PUT') {
+      if (node.type === 'folder' || node.type === 'root') return reply.code(405).send();
+      if (node.type === 'invalid') return reply.code(409).send(); // a parent folder is missing
+      const parentId = node.type === 'file' ? node.file.folderId : node.parentId;
+      const name = node.type === 'file' ? node.file.name : node.name;
+      const mimetype = String(req.headers['content-type'] ?? 'application/octet-stream').split(';')[0]!.trim() || 'application/octet-stream';
+      try {
+        await storeUserFile(app.ctx, { ownerId, folderId: parentId, stream: req.body as Readable, filename: name, mimetype });
+      } catch (err) {
+        if (err instanceof QuotaExhaustedError || err instanceof FileTooLargeError) return reply.code(507).send(); // Insufficient Storage
+        if (err instanceof InfectedFileError) return reply.code(403).send('File rejected by antivirus');
+        throw err;
+      }
+      return reply.code(node.type === 'file' ? 204 : 201).send();
+    }
+
+    if (method === 'MKCOL') {
+      if (node.type !== 'missing') return reply.code(node.type === 'invalid' ? 409 : 405).send();
+      await prisma.folder.create({ data: { ownerId, name: node.name, parentId: node.parentId, isZeroKnowledge: false } });
+      return reply.code(201).send();
+    }
+
+    if (method === 'DELETE') {
+      if (node.type === 'file') await trashFile(ownerId, node.file.id);
+      else if (node.type === 'folder') await trashFolder(ownerId, node.folder.id);
+      else return reply.code(404).send();
+      return reply.code(204).send();
+    }
+
+    if (method === 'MOVE') {
+      if (node.type !== 'file' && node.type !== 'folder') return reply.code(404).send();
+      const destSegs = destinationSegments(req.headers.destination as string | undefined);
+      if (!destSegs || destSegs.length === 0) return reply.code(400).send();
+      const destParent = await resolvePath(ownerId, destSegs.slice(0, -1));
+      const destParentId =
+        destParent.type === 'root' ? null : destParent.type === 'folder' ? destParent.folder.id : undefined;
+      if (destParentId === undefined) return reply.code(409).send();
+      const destName = destSegs[destSegs.length - 1]!;
+      const existing = await resolvePath(ownerId, destSegs);
+      if (existing.type === 'file' || existing.type === 'folder') {
+        if (String(req.headers.overwrite ?? 'T').toUpperCase() === 'F') return reply.code(412).send();
+        if (existing.type === 'file') await trashFile(ownerId, existing.file.id);
+        else await trashFolder(ownerId, existing.folder.id);
+      }
+      if (node.type === 'file') {
+        await prisma.fileObject.update({ where: { id: node.file.id }, data: { folderId: destParentId, name: destName } });
+      } else {
+        await prisma.folder.update({ where: { id: node.folder.id }, data: { parentId: destParentId, name: destName } });
+      }
+      return reply.code(existing.type === 'file' || existing.type === 'folder' ? 204 : 201).send();
+    }
+
+    // Stubbed locking so Finder / Office clients are happy (we are single-writer in practice).
+    if (method === 'LOCK') {
+      const token = `opaquelocktoken:${crypto.randomUUID()}`;
+      return reply
+        .header('Content-Type', 'application/xml; charset=utf-8')
+        .header('Lock-Token', `<${token}>`)
+        .code(200)
+        .send(
+          `<?xml version="1.0" encoding="utf-8"?>\n<D:prop xmlns:D="DAV:"><D:lockdiscovery><D:activelock>` +
+            `<D:locktype><D:write/></D:locktype><D:lockscope><D:exclusive/></D:lockscope>` +
+            `<D:depth>infinity</D:depth><D:timeout>Second-3600</D:timeout>` +
+            `<D:locktoken><D:href>${token}</D:href></D:locktoken></D:activelock></D:lockdiscovery></D:prop>`,
+        );
+    }
+    if (method === 'UNLOCK') return reply.code(204).send();
+    if (method === 'PROPPATCH') {
+      // Pretend property writes (e.g. mtime) succeed so clients don't abort the transfer.
+      return reply
+        .header('Content-Type', 'application/xml; charset=utf-8')
+        .code(207)
+        .send(
+          `<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:"><D:response>` +
+            `<D:href>${escapeXml(hrefFor(segments, node.type === 'folder' || node.type === 'root'))}</D:href>` +
+            `<D:propstat><D:status>HTTP/1.1 200 OK</D:status></D:propstat></D:response></D:multistatus>`,
+        );
+    }
+    if (method === 'COPY') return reply.code(501).send('COPY is not supported');
+
+    return reply.code(405).send();
+  }
+
+  const methods = [
+    'OPTIONS',
+    'GET',
+    'HEAD',
+    'PUT',
+    'DELETE',
+    'PROPFIND',
+    'PROPPATCH',
+    'MKCOL',
+    'MOVE',
+    'COPY',
+    'LOCK',
+    'UNLOCK',
+  ];
+  for (const method of methods) {
+    app.route({ method: method as never, url: '/', handler: handle });
+    app.route({ method: method as never, url: '/*', handler: handle });
+  }
+};

apps/api/src/server.ts

@@ -21,6 +21,7 @@ import { twoFactorRoutes } from './routes/twofa.js';
 import { accountRoutes } from './routes/account.js';
 import { adminRoutes } from './routes/admin.js';
 import { apiV1Routes } from './routes/api-v1.js';
+import { webdavRoutes } from './routes/webdav.js';
 
 export async function buildServer(ctx: AppContext): Promise<FastifyInstance> {
   const app = Fastify({
@@ -45,7 +46,6 @@ export async function buildServer(ctx: AppContext): Promise<FastifyInstance> {
   app.decorate('ctx', ctx);
 
   await app.register(helmet, { contentSecurityPolicy: false });
-  await app.register(cors, { origin: ctx.env.APP_URL, credentials: true });
   await app.register(cookie, { secret: ctx.env.SESSION_SECRET });
   await app.register(rateLimit, {
     max: ctx.env.RATE_LIMIT_ENABLED ? 300 : 1_000_000,
@@ -62,28 +62,42 @@ export async function buildServer(ctx: AppContext): Promise<FastifyInstance> {
 
   await app.register(authPlugin);
 
-  // Liveness: the process is up. Readiness: dependencies (DB + storage) are usable.
-  app.get('/health', async () => ({ status: 'ok' }));
-  app.get('/ready', async (_req, reply) => {
-    const report = await getHealth(ctx);
-    return reply.code(report.ready ? 200 : 503).send(report);
-  });
-  // Authenticated status for the UI banner (warnings about degraded components).
-  app.get('/status', { preHandler: app.requireAuth }, async () => getHealth(ctx));
+  // Teach Fastify the WebDAV verbs before the routes that use them are registered.
+  for (const m of ['PROPFIND', 'PROPPATCH', 'MKCOL', 'MOVE', 'COPY', 'LOCK', 'UNLOCK']) {
+    app.addHttpMethod(m, { hasBody: ['PROPFIND', 'PROPPATCH', 'MKCOL', 'LOCK'].includes(m) });
+  }
+
+  // WebDAV is mounted OUTSIDE the CORS scope below: @fastify/cors uses strictPreflight and would
+  // answer every WebDAV OPTIONS with 400/204, hiding the DAV capability headers clients need.
+  await app.register(webdavRoutes, { prefix: '/dav' });
+
+  // Everything browser-facing is wrapped so CORS applies only here (not to WebDAV).
+  await app.register(async (web) => {
+    await web.register(cors, { origin: ctx.env.APP_URL, credentials: true });
 
-  await app.register(authRoutes, { prefix: '/auth' });
-  await app.register(folderRoutes, { prefix: '/folders' });
-  await app.register(fileRoutes, { prefix: '/files' });
-  await app.register(trashRoutes, { prefix: '/trash' });
-  await app.register(zkRoutes, { prefix: '/zk' });
-  await app.register(quickRoutes, { prefix: '/quick' });
-  await app.register(remoteRoutes, { prefix: '/remote' });
-  await app.register(shareRoutes, { prefix: '/shares' });
-  await app.register(sharePublicRoutes, { prefix: '/s' });
-  await app.register(twoFactorRoutes, { prefix: '/2fa' });
-  await app.register(accountRoutes, { prefix: '/account' });
-  await app.register(adminRoutes, { prefix: '/admin' });
-  await app.register(apiV1Routes, { prefix: '/api/v1' });
+    // Liveness: the process is up. Readiness: dependencies (DB + storage) are usable.
+    web.get('/health', async () => ({ status: 'ok' }));
+    web.get('/ready', async (_req, reply) => {
+      const report = await getHealth(ctx);
+      return reply.code(report.ready ? 200 : 503).send(report);
+    });
+    // Authenticated status for the UI banner (warnings about degraded components).
+    web.get('/status', { preHandler: web.requireAuth }, async () => getHealth(ctx));
+
+    await web.register(authRoutes, { prefix: '/auth' });
+    await web.register(folderRoutes, { prefix: '/folders' });
+    await web.register(fileRoutes, { prefix: '/files' });
+    await web.register(trashRoutes, { prefix: '/trash' });
+    await web.register(zkRoutes, { prefix: '/zk' });
+    await web.register(quickRoutes, { prefix: '/quick' });
+    await web.register(remoteRoutes, { prefix: '/remote' });
+    await web.register(shareRoutes, { prefix: '/shares' });
+    await web.register(sharePublicRoutes, { prefix: '/s' });
+    await web.register(twoFactorRoutes, { prefix: '/2fa' });
+    await web.register(accountRoutes, { prefix: '/account' });
+    await web.register(adminRoutes, { prefix: '/admin' });
+    await web.register(apiV1Routes, { prefix: '/api/v1' });
+  });
 
   app.setErrorHandler((err: { statusCode?: number; message?: string }, req, reply) => {
     req.log.error({ err }, 'request failed');