caldav-adapter 9.2.0 → 9.3.0

package/common/xml-encode.js

@@ -0,0 +1,24 @@
+/**
+ * Shared XML entity encoding utility
+ * Centralizes the XML encoding logic to avoid duplication across handlers.
+ */
+
+/**
+ * Encode special characters for XML content to prevent parsing errors
+ * @param {string} str - String to encode
+ * @returns {string} - XML-safe encoded string
+ */
+function encodeXMLEntities(str) {
+  if (typeof str !== 'string') {
+    return str;
+  }
+
+  return str
+    .replaceAll('&', '&') // Must be first to avoid double-encoding
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+module.exports = { encodeXMLEntities };

package/index.js

@@ -14,7 +14,8 @@ const defaults = {
 };
 
 module.exports = function (options) {
-  options = Object.assign(defaults, options);
+  // avoid mutating shared `defaults` object
+  options = { ...defaults, ...options };
 
   const log = winston({ ...options, label: 'index' });
 
@@ -49,10 +50,11 @@ module.exports = function (options) {
   const fillParameters = function (ctx) {
     ctx.state.params = {};
 
+    // use ctx.path instead of ctx.url to avoid query string matching
     let regex;
-    if (calendarRegex.regexp.test(ctx.url)) {
+    if (calendarRegex.regexp.test(ctx.path)) {
       regex = calendarRegex;
-    } else if (principalRegex.regexp.test(ctx.url)) {
+    } else if (principalRegex.regexp.test(ctx.path)) {
       regex = principalRegex;
     }
 
@@ -60,7 +62,7 @@ module.exports = function (options) {
       return;
     }
 
-    const captures = ctx.url.match(regex.regexp);
+    const captures = ctx.path.match(regex.regexp);
     for (let i = 0; i < regex.keys.length; i++) {
       let captured = captures[i + 1];
       if (typeof captured === 'string') {
@@ -134,13 +136,18 @@ module.exports = function (options) {
   };
 
   return async function (ctx, next) {
+    // use 301 permanent redirect per RFC 6764 Section 5
     if (
-      ctx.url.toLowerCase() === '/.well-known/caldav' &&
+      ctx.path.toLowerCase() === '/.well-known/caldav' &&
       !options.disableWellKnown
-    )
-      return ctx.redirect(rootRoute); // TODO: should be 302?
+    ) {
+      ctx.status = 301;
+      ctx.redirect(rootRoute);
+      return;
+    }
 
-    if (!rootRegexp.test(ctx.url)) {
+    // use ctx.path instead of ctx.url
+    if (!rootRegexp.test(ctx.path)) {
       await next();
       return;
     }
@@ -157,9 +164,10 @@ module.exports = function (options) {
     await parseBody(ctx);
     log.verbose('REQUEST BODY', ctx?.request?.body || '<empty>');
 
-    if (calendarRegex.regexp.test(ctx.url)) {
+    // use ctx.path instead of ctx.url
+    if (calendarRegex.regexp.test(ctx.path)) {
       await calendarRoutes(ctx);
-    } else if (principalRegex.regexp.test(ctx.url)) {
+    } else if (principalRegex.regexp.test(ctx.path)) {
       await principalRoutes(ctx);
     } else {
       ctx.redirect(principalRoute);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "caldav-adapter",
   "description": "CalDAV server for Node.js and Koa. Modernized and maintained for Forward Email.",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "author": "Sanders DeNardi and Forward Email LLC",
   "contributors": [
     "Sanders DeNardi <sedenardi@gmail.com> (http://www.sandersdenardi.com/)",
@@ -41,6 +41,11 @@
   "engines": {
     "node": ">=18"
   },
+  "files": [
+    "index.js",
+    "common",
+    "routes"
+  ],
   "homepage": "https://github.com/forwardemail/caldav-adapter",
   "keywords": [
     "caldav",
@@ -63,7 +68,7 @@
   },
   "scripts": {
     "lint": "xo --fix && remark . -qfo && fixpack",
-    "prepare": "husky install",
+    "prepare": "husky install > /dev/null 2>&1 || true",
     "pretest": "npm run lint",
     "test": "npm run test-coverage",
     "test-coverage": "cross-env NODE_ENV=test nyc ava"

package/routes/calendar/calendar/calendar-multiget.js

@@ -36,7 +36,11 @@ module.exports = function (options) {
       }
 
       const hrefParts = href.split('/');
-      const eventId = hrefParts.at(-1).slice(0, -4);
+      const lastPart = hrefParts.at(-1);
+      // Only strip .ics extension if present, to avoid corrupting eventIds
+      const eventId = lastPart.endsWith('.ics')
+        ? lastPart.slice(0, -4)
+        : lastPart;
       const event = await options.data.getEvent(ctx, {
         eventId,
         principalId: ctx.state.params.principalId,

package/routes/calendar/calendar/delete.js

@@ -33,7 +33,7 @@ module.exports = function (options) {
     // (e.g. since we call `setMultistatusResponse` before exec())
     ctx.set('Content-Type', 'text/html; charset="utf-8"');
     ctx.status = 204; // no content
-    ctx.body = '';
+    ctx.body = null;
   };
 
   return {

package/routes/calendar/calendar/propfind.js

@@ -46,6 +46,17 @@ module.exports = function (options) {
     const resp = await calendarResponse(ctx, calendar);
     const resps = [resp];
 
+    //
+    // Performance: check Depth header — if Depth:0 the client only
+    // wants calendar-level properties, not the event listing.
+    // This avoids loading any events from the database.
+    //
+    const depth = ctx.get('depth') || 'infinity';
+    if (depth === '0') {
+      const ms = multistatus(resps);
+      return build(ms);
+    }
+
     const { children } = xml.getWithChildren(
       '/D:propfind/D:prop',
       ctx.request.xml

package/routes/calendar/calendar/put.js

@@ -69,6 +69,23 @@ module.exports = function (options) {
         return;
       }
 
+      //
+      // RFC 7232 Section 3.1: If-Match
+      // Validate ETag to prevent silent concurrent overwrites.
+      //
+      const ifMatch = ctx.get('if-match');
+      if (ifMatch && ifMatch !== '*') {
+        const currentETag = options.data.getETag(ctx, existing);
+        const clientETag = ifMatch.replace(/^"/, '').replace(/"$/, '');
+        const serverETag = currentETag.replace(/^"/, '').replace(/"$/, '');
+        if (clientETag !== serverETag) {
+          log.warn('if-match ETag mismatch, precondition failed');
+          ctx.status = 412;
+          ctx.body = preconditionFail(ctx.url, 'if-match');
+          return;
+        }
+      }
+
       const updateObject = await options.data.updateEvent(ctx, {
         eventId: ctx.state.params.eventId,
         principalId: ctx.state.params.principalId,
@@ -78,7 +95,7 @@ module.exports = function (options) {
       log.debug('event updated');
 
       /* https://tools.ietf.org/html/rfc4791#section-5.3.2 */
-      ctx.status = 201;
+      ctx.status = 204;
       ctx.set('ETag', options.data.getETag(ctx, updateObject));
     } else {
       const newObject = await options.data.createEvent(ctx, {
@@ -91,6 +108,7 @@ module.exports = function (options) {
       /* https://tools.ietf.org/html/rfc4791#section-5.3.2 */
       ctx.status = 201;
       ctx.set('ETag', options.data.getETag(ctx, newObject));
+      ctx.set('Location', ctx.url);
     }
   };
 

package/routes/calendar/calendar/report.js

@@ -40,7 +40,10 @@ module.exports = function (options) {
     const rootAction = rootActions[rootTag];
     log.debug(`report ${rootAction ? 'hit' : 'miss'}: ${rootTag}`);
     if (!rootAction) {
-      return notFound(ctx.url);
+      // RFC 3253 Section 3.6: unsupported report type should return 403
+      ctx.status = 403;
+      ctx.body = notFound(ctx.url);
+      return;
     }
 
     const { responses, other } = await rootAction(ctx, calendar);

package/routes/calendar/calendar/sync-collection.js

@@ -12,6 +12,20 @@ module.exports = function (options) {
   };
 
   return async function (ctx, calendar) {
+    // RFC 6578 Section 3.2 - parse the client's sync-token
+    // to enable incremental sync instead of always returning all events
+    const syncTokenNodes = xml.get(
+      '/D:sync-collection/D:sync-token',
+      ctx.request.xml
+    );
+    let clientSyncToken = null;
+    if (syncTokenNodes && syncTokenNodes.length > 0) {
+      const tokenText = syncTokenNodes[0].textContent;
+      if (tokenText && tokenText.trim() !== '') {
+        clientSyncToken = tokenText.trim();
+      }
+    }
+
     const { children } = xml.getWithChildren(
       '/D:sync-collection/D:prop',
       ctx.request.xml
@@ -20,12 +34,15 @@ module.exports = function (options) {
       return child.localName === 'calendar-data';
     });
 
+    // Pass the client's sync-token to the data layer so it can
+    // return only events changed since that token
     const events = await options.data.getEventsForCalendar(ctx, {
       principalId: ctx.state.params.principalId,
       calendarId: options.data.getCalendarId(ctx, calendar),
       user: ctx.state.user,
       fullData,
-      showDeleted: true
+      showDeleted: true,
+      syncToken: clientSyncToken
     });
     const { responses } = await eventResponse(ctx, events, calendar, children);
 

package/routes/calendar/calendar.js

@@ -39,10 +39,13 @@ module.exports = function (options) {
     const method = ctx.method.toLowerCase();
     const { calendarId } = ctx.state.params;
 
-    // Check for scheduling inbox/outbox routes
-    // These are special endpoints at /cal/:principalId/inbox/ and /cal/:principalId/outbox/
-    const urlLower = ctx.url.toLowerCase();
-    if (urlLower.includes('/inbox') || urlLower.includes('/outbox')) {
+    // use exact calendarId match instead of URL substring
+    // to prevent routing collisions with calendars named "inbox" or "outbox"
+    if (
+      calendarId &&
+      (calendarId.toLowerCase() === 'inbox' ||
+        calendarId.toLowerCase() === 'outbox')
+    ) {
       log.debug('Routing to scheduling handler', { url: ctx.url, method });
       return scheduling.route(ctx);
     }
@@ -80,9 +83,13 @@ module.exports = function (options) {
       try {
         if (typeof calMethods[method].exec === 'function') {
           setMultistatusResponse(ctx);
+          // pass calendar object via ctx.state to avoid
+          // redundant getCalendar() calls inside handlers
+          ctx.state.calendar = calendar;
           ctx.body = await calMethods[method].exec(ctx, calendar);
         } else if (typeof calMethods[method] === 'function') {
           setMultistatusResponse(ctx);
+          ctx.state.calendar = calendar;
           ctx.body = await calMethods[method](ctx, calendar);
         } else {
           log.warn(`method handler not found: ${method}`);

package/routes/calendar/scheduling.js

@@ -152,13 +152,17 @@ module.exports = function (options) {
   async function handleItipRequest(ctx, body) {
     log.debug('Processing iTIP request');
 
+    // RFC 5545 Section 3.1: unfold long content lines before parsing
+    // Folded lines start with CRLF followed by a single whitespace character
+    const unfolded = body.replaceAll(/\r\n[ \t]/g, '');
+
     // Extract METHOD from the iCalendar data
-    const methodMatch = body.match(/method:([a-z]+)/i);
+    const methodMatch = unfolded.match(/method:([a-z]+)/i);
     const method = methodMatch ? methodMatch[1].toUpperCase() : 'REQUEST';
 
     // Extract attendees
     const attendeeMatches =
-      body.match(/attendee[^:]*:mailto:([^\r\n]+)/gi) || [];
+      unfolded.match(/attendee[^:]*:mailto:([^\r\n]+)/gi) || [];
     const attendees = attendeeMatches
       .map((match) => {
         const email = match.match(/mailto:([^\r\n]+)/i);
@@ -327,11 +331,15 @@ module.exports = function (options) {
      */
     async route(ctx) {
       const method = ctx.method.toLowerCase();
-      const url = ctx.url.toLowerCase();
 
-      // Determine if this is inbox or outbox
-      const isInbox = url.includes('/inbox');
-      const isOutbox = url.includes('/outbox');
+      // Use calendarId from route params for reliable inbox/outbox detection
+      // instead of URL substring matching which can collide with calendar names
+      const calId = (
+        (ctx.state.params && ctx.state.params.calendarId) ||
+        ''
+      ).toLowerCase();
+      const isInbox = calId === 'inbox';
+      const isOutbox = calId === 'outbox';
 
       if (method === 'options') {
         if (isOutbox) {

package/routes/calendar/user/propfind.js

@@ -47,6 +47,16 @@ module.exports = function (options) {
       response(ctx.url, props.length > 0 ? status[200] : status[404], props)
     ];
 
+    //
+    // Performance: Depth:0 means the client only wants the collection
+    // itself, not its children (individual calendars).
+    //
+    const depth = ctx.get('depth') || 'infinity';
+    if (depth === '0') {
+      const ms = multistatus(responses);
+      return build(ms);
+    }
+
     const calendars = await options.data.getCalendarsForPrincipal(ctx, {
       principalId: ctx.state.params.principalId,
       user: ctx.state.user

package/routes/principal/mkcalendar.js

@@ -1,57 +1,80 @@
-const _ = require('lodash');
 const xml = require('../../common/xml');
 
 // TODO: need to implement tests for MKCALENDAR
 // <https://github.com/sabre-io/dav/blob/da8c1f226f1c053849540a189262274ef6809d1c/tests/Sabre/CalDAV/PluginTest.php#L142-L428>
+
+function parseSupportedComponents(node) {
+  const comps = [];
+  if (!node.childNodes) return comps;
+  for (const comp of node.childNodes) {
+    if (comp.localName !== 'comp') continue;
+    const name = comp.getAttribute ? comp.getAttribute('name') : null;
+    if (name) comps.push(name.toUpperCase());
+  }
+
+  return comps;
+}
+
 module.exports = function (options) {
   return async function (ctx) {
-    const { children } = xml.getWithChildren(
-      '/CAL:mkcalendar/D:set/D:prop',
-      ctx.request.xml
-    );
-
     const calendar = {};
-    for (const child of children) {
-      if (!child.localName || !child.textContent) continue;
-      switch (child.localName) {
-        case 'displayname': {
-          calendar.name = child.textContent;
 
-          break;
-        }
+    // RFC 4791 Section 5.3.1: the request body is optional
+    if (ctx.request.xml) {
+      const { children } = xml.getWithChildren(
+        '/CAL:mkcalendar/D:set/D:prop',
+        ctx.request.xml
+      );
 
-        case 'calendar-description': {
-          calendar.description = child.textContent;
+      for (const child of children) {
+        if (!child.localName || !child.textContent) continue;
+        switch (child.localName) {
+          case 'displayname': {
+            calendar.name = child.textContent;
 
-          break;
-        }
+            break;
+          }
 
-        case 'calendar-timezone': {
-          calendar.timezone = child.textContent;
+          case 'calendar-description': {
+            calendar.description = child.textContent;
 
-          break;
-        }
+            break;
+          }
 
-        case 'calendar-color': {
-          calendar.color = child.textContent;
+          case 'calendar-timezone': {
+            calendar.timezone = child.textContent;
 
-          break;
-        }
+            break;
+          }
+
+          case 'calendar-color': {
+            calendar.color = child.textContent;
+
+            break;
+          }
+
+          case 'calendar-order': {
+            calendar.order = Number.parseInt(child.textContent, 10);
+
+            break;
+          }
 
-        case 'calendar-order': {
-          calendar.order = Number.parseInt(child.textContent, 10);
+          case 'supported-calendar-component-set': {
+            const comps = parseSupportedComponents(child);
+            if (comps.length > 0) {
+              calendar.supportedComponents = comps;
+            }
 
-          break;
+            break;
+          }
+          // No default
         }
-        // No default
       }
     }
 
-    // TODO: better error handling
-    if (_.isEmpty(calendar)) {
-      const err = new TypeError('Calendar update was empty');
-      err.xml = ctx.request.body;
-      throw err;
+    // Extract calendarId from URL if available
+    if (ctx.state.params && ctx.state.params.calendarId) {
+      calendar.calendarId = ctx.state.params.calendarId;
     }
 
     // TODO: we may need to implement this similar workaround

package/routes/principal/propfind.js

@@ -11,15 +11,32 @@ const commonTags = require('../../common/tags');
 module.exports = function (options) {
   const tags = commonTags(options);
   return async function (ctx) {
-    // Validate XML document before processing
-    if (!ctx.request.xml) {
-      ctx.throw(400, 'Invalid or missing XML in PROPFIND request');
+    // RFC 4918 Section 9.1 says an empty PROPFIND body
+    // MUST be treated as an allprop request, not rejected with 400
+    let children = [];
+    if (ctx.request.xml) {
+      ({ children } = xml.getWithChildren(
+        '/D:propfind/D:prop',
+        ctx.request.xml
+      ));
     }
 
-    const { children } = xml.getWithChildren(
-      '/D:propfind/D:prop',
-      ctx.request.xml
-    );
+    // If no properties requested (allprop), return a default set
+    // Each entry must include namespaceURI so getResponse() can resolve the tag handler
+    const dav = 'DAV:';
+    const cal = 'urn:ietf:params:xml:ns:caldav';
+    if (children.length === 0) {
+      children = [
+        { namespaceURI: dav, localName: 'displayname' },
+        { namespaceURI: dav, localName: 'resourcetype' },
+        { namespaceURI: dav, localName: 'current-user-principal' },
+        { namespaceURI: dav, localName: 'current-user-privilege-set' },
+        { namespaceURI: cal, localName: 'calendar-home-set' },
+        { namespaceURI: cal, localName: 'calendar-user-address-set' },
+        { namespaceURI: cal, localName: 'schedule-inbox-URL' },
+        { namespaceURI: cal, localName: 'schedule-outbox-URL' }
+      ];
+    }
 
     const actions = _.map(children, async (child) => {
       return tags.getResponse({

package/routes/principal/report.js

@@ -4,6 +4,12 @@ const winston = require('../../common/winston');
 module.exports = function (options) {
   const log = winston({ ...options, label: 'principal/report' });
   return async function (ctx) {
+    // guard against null/missing XML body
+    if (!ctx.request.xml || !ctx.request.xml.documentElement) {
+      ctx.status = 400;
+      return;
+    }
+
     const rootTag = ctx.request.xml.documentElement.localName;
     if (rootTag === 'principal-search-property-set') {
       log.debug('principal-search-property-set');

package/.commitlintrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional']
-};

package/.editorconfig

@@ -1,9 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true

package/.gitattributes

@@ -1 +0,0 @@
-* text=auto eol=lf

package/.github/workflows/ci.yml

@@ -1,24 +0,0 @@
-name: CI
-on:
-  - push
-  - pull_request
-jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os:
-          - ubuntu-latest
-        node_version:
-          - 18
-    name: Node ${{ matrix.node_version }} on ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup node
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node_version }}
-      - name: Install dependencies
-        run: npm install
-      - name: Run tests
-        run: npm run test

package/.husky/commit-msg

@@ -1,4 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-npx --no-install commitlint --edit $1

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-npx --no-install lint-staged && npm test

package/.lintstagedrc.js

@@ -1,5 +0,0 @@
-module.exports = {
-  "*.md": filenames => filenames.map(filename => `remark ${filename} -qfo`),
-  'package.json': 'fixpack',
-  '*.js': 'xo --fix'
-};

package/.prettierrc.js

@@ -1,5 +0,0 @@
-module.exports = {
-  singleQuote: true,
-  bracketSpacing: true,
-  trailingComma: 'none'
-};

package/.remarkignore

@@ -1 +0,0 @@
-test/snapshots/**/*.md

package/.remarkrc.js

@@ -1,3 +0,0 @@
-module.exports = {
-  plugins: ['preset-github']
-};

package/.xo-config.js

@@ -1,8 +0,0 @@
-module.exports = {
-  prettier: true,
-  space: true,
-  extends: ['xo-lass'],
-  rules: {
-    'no-warning-comments': 'off'
-  }
-};