caldav-adapter 4.3.1 → 5.0.0

package/.commitlintrc.js

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

package/.editorconfig

@@ -0,0 +1,9 @@
+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

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

package/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+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@v3
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node_version }}
+      - name: Install dependencies
+        run: npm install
+      - name: Run tests
+        run: npm run test

package/.husky/commit-msg

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

package/.husky/pre-commit

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

package/.lintstagedrc.js

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

package/.prettierrc.js

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

package/.remarkignore

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

package/.remarkrc.js

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

package/.xo-config.js

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sanders DeNardi <sedenardi@gmail.com> (http://www.sandersdenardi.com/) and Forward Email LLC <support@forwardemail.net> (https://forwardemail.net)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,263 +1,49 @@
-# caldav-adapter
+# [**caldav-adapter**](https://github.com/forwardemail/caldav-adapter)
 
-Middleware to handle CalDAV requests to node web server. Works with
+[![build status](https://github.com/forwardemail/caldav-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/forwardemail/caldav-adapter/actions/workflows/ci.yml)
+[![code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
+[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![made with lass](https://img.shields.io/badge/made_with-lass-95CC28.svg)](https://lass.js.org)
+[![license](https://img.shields.io/github/license/forwardemail/caldav-adapter.svg)](LICENSE)
 
-* Node v8 or higher
-* Koa v2 or higher
+> CalDAV server for Node.js and Koa.  Modernized and maintained for [Forward Email](https://forwardemail.net).
 
-This middleware will intercept any requests to the `caldavRoot` URL, authenticate using Basic Authentication, and exposes the following URLs and methods:
 
-* Principal Methods: `OPTIONS`, `PROPFIND`
-* Calendar Home Methods: `OPTIONS`, `PROPFIND`
-* Calendar Methods: `OPTIONS`, `PROPFIND`, `REPORT`, `GET`, `PUT` & `DELETE` (if calendar is not read-only)
+## Table of Contents
 
-The following CalDAV functionality is supported:
+* [Usage](#usage)
+* [Install](#install)
+* [Contributors](#contributors)
+* [License](#license)
 
-* Creating, updating, deleting one-off (non-recurring) events
-* Creating, updating, deleting recurring events (with limited `RRULE` support, see schema)
-* Read-only calendars, read-only or read/write events on each calendar
-
-This module is written in Typescript, and contains exported types for all the definitions mentioned below.
-
-## Installation
-
-```
-npm i caldav-adapter
-```
 
 ## Usage
 
-```js
-const Koa = require('koa');
-const app = new Koa();
-
-const caldav = require('caldav-adapter');
-app.use(adapter.koa({
-  authenticate: async ({ username, password }) => {
-    if (password === 'pass') {
-      return {
-        principalId: username,
-        principalName: username.toUpperCase()
-      };
-    }
-  },
-  authRealm: config.authRealm,
-  caldavRoot: 'caldav',
-  proId: { company: 'TestCompany', product: 'Calendar', language: 'EN' },
-  logEnabled: true,
-  logLevel: 'debug',
-  data: {
-    getCalendar: data.getCalendar,
-    getCalendarsForPrincipal: data.getCalendarsForPrincipal,
-    getEventsForCalendar: data.getEventsForCalendar,
-    getEventsByDate: data.getEventsByDate,
-    getEvent: data.getEvent,
-    createEvent: data.createEvent,
-    updateEvent: data.updateEvent,
-    deleteEvent: data.deleteEvent
-  }
-}));
-```
-
-### authenticate(options)
-
-* `options`: object Parameters which might have the following properties:
-  * `username`: string
-  * `password`: string
-* returns: Promise<object> Promise which resolves to the user object, which is passed to all `data.*` functions on each request.
-
-### authRealm
-
-* required: string Realm for Basic Authentication.
-
-### caldavRoot
-
-* optional: string Root URL for CalDAV server (default `/`)
-
-### proId
-
-* required: string Product Identifier passed to [ical-generator](https://github.com/sebbo2002/ical-generator#prodidstringobject-prodid)
-
-### logEnabled
-
-* optional: boolean Enables stdout logging via Winston (default `false`)
-
-### logLevel
-
-* optional: string Log level used by Winston (default `debug`)
-
-### data.getCalendar(options)
-
-* `options` Parameters which might have the following properties:
-  * `calendarId`: string
-  * `principalId`: string
-  * `user`: object
-* returns: Promise<[calendar](#calendar-model)> Promise which resolves to the requested calendar.
-
-### data.getCalendarsForPrincipal(options)
-
-* `options` Parameters which might have the following properties:
-  * `principalId`: string
-  * `user`: object
-* returns: Promise<[calendar](#calendar-model)[]> Promise which resolves to an array of the principal's calendars.
-
-### data.getEventsForCalendar(options)
+Please refer to the Forward Email implementation at <https://github.com/forwardemail/forwardemail.net> for usage insight.
 
-* `options` Parameters which might have the following properties:
-  * `calendarId`: string
-  * `principalId`: string
-  * `fullData`: boolean Clients will oftentimes request all events for a calendar to check the events' `etag` (lastModifiedOn) field to see whether they need updating. Since this can be an expensive operation for some fields (like description), this will be true if the client is requesting the full `calendar-data`.
-  * `user`: object
-* returns: Promise<[event](#event-model)[]> Promise which resolves to an array of the calendar's events.
 
-### data.getEventsByDate(options)
+## Install
 
-* `options` Parameters which might have the following properties:
-  * `calendarId`: string
-  * `principalId`: string
-  * `start` string> ISO date string
-  * `end` string> ISO date string
-  * `fullData`: object
-  * `user`: object
-* returns: Promise<[event](#event-model)[]> Promise which resolves to an array of the calendars' events between the given dates.
+[npm][]:
 
-### data.getEvent(options)
-
-* `options` Parameters which might have the following properties:
-  * `eventId`: string
-  * `calendarId`: string
-  * `principalId`: string
-  * `fullData`: object
-  * `user`: object
-* returns: Promise<[event](#event-model)> Promise which resolves to an event.
-
-### data.createEvent(options)
-
-* `options` Parameters which might have the following properties:
-  * `event`: [event](#event-model)
-  * `calendarId`: string
-  * `principalId`: string
-  * `user`: object
-* returns: Promise<[event](#event-model)> Promise which resolves to the created event.
-
-### data.deleteEvent(options)
-
-* `options` Parameters which might have the following properties:
-  * `eventId`: string
-  * `calendarId`: string
-  * `principalId`: string
-  * `user`: object
-* returns: Promise<`void`> Promise which resolves to the deleted event.
-
-### data.updateEvent(options)
-
-* `options` Parameters which might have the following properties:
-  * `event`: [event](#event-model)
-  * `calendarId`: string
-  * `principalId`: string
-  * `user`: object
-* returns: Promise<[event](#event-model)> Promise which resolves to the updated event.
-
-## Models
-
-### calendar model
-
-* `order`, `color` are unused for now
-
-```json
-{
-  "calendarId": "exampleCal1",
-  "ownerId": "user@ex.co",
-  "calendarName": "Example Calendar 1",
-  "timeZone": "America/New_York",
-  "order": 1,
-  "readOnly": true,
-  "color": "#FD8208",
-  "syncToken": "https://example.com/ns/sync-token/1",
-  "createdOn": "20180802T152540Z"
-}
+```sh
+npm install caldav-adapter
 ```
 
-### event model
 
-* dates can be anything the `moment` constructor can handle (Date or moment objects, ISO string, etc.)
-* `ical` field is only returned from the middleware, it's unused in responses
-* `recurring` only supports the `freq`, `until`, and `exdate` fields
-* `recurrences` is an optional array of recurrence exceptions
+## Contributors
 
-```json
-{
-      "eventId": "30946424-40f4-47e2-80b1-006fdebbeb25",
-      "calendarId": "exampleCal2",
-      "summary": "Testing Event 6",
-      "location": "Location 6",
-      "description": "Recurring event on Friday, 4-6pm",
-      "startDate": "20190111T210000Z",
-      "endDate": "20190111T230000Z",
-      "timeZone": "America/New_York",
-      "createdOn": "20190226T203808Z",
-      "lastModifiedOn": "20190226T211704Z",
-      "ical": "BEGIN:VCALENDAR...",
-      "recurring": {
-        "freq": "WEEKLY",
-        "until": "20190211T170000Z",
-        "exdate": [
-          "20190301T210000Z",
-          "20190315T200000Z",
-          "20190308T210000Z"
-        ],
-        "recurrences": [
-          {
-            "recurrenceId": "20190322T200000Z",
-            "summary": "Testing Event 6",
-            "location": "Location 6",
-            "description": "Recurring event on Friday, 4-6pm",
-            "startDate": "20190322T140000Z",
-            "endDate": "20190322T160000Z",
-            "timeZone": "America/New_York",
-            "createdOn": "20190226T203808Z",
-            "lastModifiedOn": "20190226T202744Z"
-          }
-        ]
-      }
-    }
-```
+| Name                | Website                          |
+| ------------------- | -------------------------------- |
+| **Sanders DeNardi** | <http://www.sandersdenardi.com/> |
+| **Forward Email**   | <https://forwardemail.net>       |
 
-## Examples
 
-Please see `exampe/server.js` for example middleware implementation, as well as `example/data.js` for `data.*` method examples.
-
-If you run the server without changing any of the configuration options, you can connect to it via iPhone or MacOS with the following server details:
-
-* Server: https://localhost:3001/caldav/p/user@ex.co
-* User Name: user@ex.co
-* Password: pass
-
-**NOTE**: You will need to install a self-signed HTTPS certificate on your local machine to connect directly to `localhost`. Otherwise you can use `ngrok` or a similar service to create a secure connection to a server on your local machine.
-
-## Tested Clients
-
-* MacOS 10.14
-  * Calendar.app
-  * Mozilla Thunderbird
-* iOS 12
-  * Calendar.app
-  * Google Calendar
-
-## Next
-
-* Android tests
-
-## Future
-
-* Adding tests (integration tests with a dummy CalDAV client)
-* Add scheduling support (inbox/outbox calendars, defined in the [RFC here](https://tools.ietf.org/html/rfc6638)
-* Add support for Express and other frameworks
+## License
 
-## Contributing
+[MIT](LICENSE) © Sanders DeNardi and Forward Email LLC
 
-Pull requests are more than welcome! Please follow existing naming and style conventions, and correct any linting errors before submitting code.
 
-## License
+##
 
-MIT
+[npm]: https://www.npmjs.com

package/common/parse-body.js

@@ -0,0 +1,16 @@
+const ical = require('node-ical');
+const raw = require('raw-body');
+const { DOMParser } = require('@xmldom/xmldom');
+
+module.exports = async function (ctx) {
+  ctx.request.body = await raw(ctx.req, {
+    encoding: true,
+    limit: '1mb' // Practical
+  });
+
+  if (ctx.request.type.includes('xml')) {
+    ctx.request.xml = new DOMParser().parseFromString(ctx.request.body);
+  } else if (ctx.request.type === 'text/calendar') {
+    ctx.request.ical = await ical.async.parseICS(ctx.request.body);
+  }
+};

package/common/response.js

@@ -0,0 +1,51 @@
+const setAllowHeader = function (ctx, methods = []) {
+  ctx.set('Allow', methods.join(', '));
+};
+
+const setDAVHeader = function (ctx) {
+  ctx.set(
+    'DAV',
+    [
+      '1',
+      // '2',
+      '3',
+      // 'extended-mkcol',
+      'calendar-access',
+      'calendar-schedule'
+      // 'calendar-auto-schedule',
+      /* https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-proxy.txt */
+      // 'calendar-proxy',
+      // 'calendarserver-sharing',
+      // 'calendarserver-subscribed',
+      // 'access-control',
+      /* https://tools.ietf.org/html/rfc3744#section-9.4 */
+      // 'calendarserver-principal-property-search'
+    ].join(', ')
+  );
+};
+
+const setXMLHeader = function (ctx) {
+  ctx.set('Content-Type', 'application/xml; charset="utf-8"');
+};
+
+module.exports = {};
+
+/* https://tools.ietf.org/html/rfc4791#section-5.1.1 */
+module.exports.setOptions = function (ctx, methods = []) {
+  ctx.status = 200;
+  setAllowHeader(ctx, methods);
+  setDAVHeader(ctx);
+  ctx.body = '';
+};
+
+/* https://tools.ietf.org/html/rfc4791#section-7.8.1 */
+module.exports.setMultistatusResponse = function (ctx) {
+  ctx.status = 207;
+  setDAVHeader(ctx);
+  setXMLHeader(ctx);
+};
+
+module.exports.setMissingMethod = function (ctx) {
+  ctx.status = 404;
+  ctx.set('Content-Type', 'text/html; charset="utf-8"');
+};