calendar-plugin/requirements/caldav.md

# CalDAV Requirements

## Purpose
Define requirements for exposing the plugin calendar through a CalDAV endpoint with read/write behavior and standards-compatible resource representations.

## Standards and RFC
CalDAV behavior must be standards-compatible with:

- RFC 4791: Calendaring Extensions to WebDAV (CalDAV)
- RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
- RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- RFC 6578: Collection Synchronization for WebDAV (sync report)
- RFC 7232: HTTP conditional requests (ETag/If-Match semantics)

If additional CalDAV/WebDAV extensions are used, they must be documented and not break baseline client interoperability.

## Timezone Assumption
Unless explicitly overridden by a future requirement, all plugin dates and times are assumed to be in the `Europe/London` timezone.

## Scope
This document covers:

- CalDAV endpoint structure and resources
- Required WebDAV/CalDAV operations
- Mapping between plugin data and CalDAV/iCalendar resources
- Concurrency, sync, and error behavior

## Normative Boundaries
To avoid ambiguity across requirement documents:

- Exact CalDAV URI layout, method matrix, and DAV property/report behavior are defined in `requirements/caldav_endpoints.md`.
- Authentication and authorization policy is defined in `requirements/authentication.md` and `requirements/authorization.md`.
- Error response normalization is defined in `requirements/error_model.md`.
- Recurrence exception semantics are defined in `requirements/recurrence_exceptions.md`.
- Concrete persistence schema is defined in `requirements/data_schema.md`.

## Endpoint and Resource Model
The plugin must expose a CalDAV hierarchy with authenticated user principals and calendar collections.

Minimum resource model:

- Principal resource per authenticated CalDAV user
- Shared calendar home set
- Single shared `public` calendar collection
- Event resources as `text/calendar` (`VEVENT`-based `.ics` objects) within collections

URI requirements:

- Resource URIs must be stable for the lifetime of each object.
- Event resource URI should be derived from a stable internal event identifier.
- Recurrence exceptions must remain part of the same logical series and not create split series artifacts.

## Authentication and Authorization
- CalDAV access must require HTTPS and authenticated credentials.
- Authorization must enforce account approval state (`pending_approval` vs `active`).
- Unverified or non-approved users must be denied authentication/authorization.
- `active` users are write-enabled for the shared calendar.
- All authenticated users access the same shared calendar collection.

## Required CalDAV/WebDAV Operations
The endpoint must support these operations at minimum.

### Discovery and Collection Introspection
- `OPTIONS`: advertise DAV capabilities, including CalDAV support.
- `PROPFIND`:
  - discover principals, calendar home sets, and calendar collections
  - retrieve core properties (display name, resource type, ctag/sync metadata where available)

### Read and Query
- `REPORT` (`calendar-query`): return events in collection, including time-range filtering.
- `REPORT` (`calendar-multiget`): fetch specific event resources by href.
- `GET`: retrieve individual event resource (`text/calendar`).
- `GET` on CalDAV collection resources should return `200` (empty body acceptable) for client availability probes.

### Create and Update
- `PUT`: create new event resource or replace an existing event resource.
- `PUT` updates must preserve recurrence/exception semantics from iCalendar input.
- CalDAV clients (including Thunderbird) must be able to read current event privacy and update it on edit (for example via `CLASS`).
- Write operations must require approved authenticated access.

### Delete
- `DELETE`: remove event resource when permitted.
- Deleting a single occurrence of a recurring event must be represented as a recurrence exception in the series (`EXDATE` and/or `RECURRENCE-ID` override pattern), not by splitting into multiple independent series.

### Concurrency and Sync
- `ETag` must be emitted for event resources.
- `If-Match`/`If-None-Match` preconditions must be honored for safe updates/creates.
- `REPORT` (`sync-collection`) should be supported for incremental sync tokens.
- Sync token invalidation/rotation behavior must be deterministic and documented.
- `sync-collection` no-change requests (client token equals current token) should return an empty change set (`207` with no changed/deleted `response` entries).
- `sync-collection` should prefer stable incremental behavior over historical replay; unchanged resyncs must not emit large historical tombstone sets.

## iCalendar Representation Requirements
CalDAV event payloads must be standards-compatible `VCALENDAR` with `VEVENT` components.

Minimum mapping expectations:

- Internal stable event id -> `UID`
- Title -> `SUMMARY`
- Description -> `DESCRIPTION`
- Location -> `LOCATION`
- Category -> `CATEGORIES`
- Start/end -> `DTSTART` / `DTEND`
- Last modification timestamp -> `DTSTAMP` (and `LAST-MODIFIED` when available)
- Recurrence rules -> `RRULE`
- Recurrence exceptions -> `EXDATE` and/or additional `VEVENT` with matching `UID` plus `RECURRENCE-ID`
- Parsing must correctly handle quoted property parameters containing `:` (for example `DESCRIPTION;ALTREP="data:text/html,..."`) so field values are not polluted by parameter content.

Privacy visibility mapping:

- Event visibility must round-trip through CalDAV/iCalendar semantics (for example `CLASS:PUBLIC` and `CLASS:PRIVATE` where supported).
- Authenticated CalDAV users must receive full event content for both public and private events.
- CalDAV feeds are not subject to the public redaction model used by anonymous web/ICS surfaces.

Recurrence behavior:

- Series-level recurrence remains a single logical event sequence keyed by `UID`.
- Exception instances must be represented as exceptions to that `UID`, not a new split sequence.
- Sequence/version metadata should be updated on write operations so clients detect changes.
- Monthly ordinal rules must round-trip accurately, including `BYDAY=2SA`-style forms and `BYSETPOS=-1` (`last` weekday in month).

## Plugin Data Mapping Requirements
Plugin persistence must represent CalDAV resources in a way that supports idempotent read/write sync.

Required persisted mapping fields (direct columns or normalized equivalents):

- Internal event id
- CalDAV resource path/name
- `UID`
- Current `ETag`
- Calendar collection id
- Last-modified-by user id (nullable for system/import operations)
- Serialized recurrence rule data
- Recurrence exception records (date-only exceptions and/or overridden instances)
- Created/updated timestamps

Behavior requirements:

- Importing/updating from CalDAV must map to existing records by stable identifiers (`UID` + resource identity rules).
- Duplicate creation from repeated client retries must be prevented.
- Data model must preserve enough metadata to regenerate standards-compliant responses.

## Error Handling Requirements
- Malformed iCalendar payloads must return appropriate client error responses.
- Authorization failures must return appropriate auth status without leaking sensitive details.
- Write precondition failures (etag mismatch) must return precondition errors and no partial write.
- Server errors must be logged with enough detail for troubleshooting.

## Security and Privacy
- Transport must be TLS-only for credentials and calendar data.
- Sensitive tokens/credentials must not be logged in plaintext.
- Responses must not leak admin-only or internal plugin metadata.

## Interoperability Targets
The implementation should interoperate with common CalDAV clients, including:

- Apple Calendar
- Thunderbird
- DAVx5-class clients

Client-specific workarounds, if required, must be documented.

## Majority-Client Compatibility Strategy
There is no single guaranteed feature set that satisfies every CalDAV client implementation, but interoperability for the majority can be managed by combining:

- strict baseline standards compliance (RFC 4791 + RFC 4918 + RFC 5545)
- a stable compatibility profile for discovery/auth/report/write behavior
- continuous regression tests against representative client patterns

The project must maintain a compatibility profile with three levels:

- Level A (required for release): standards-critical discovery/auth/read
  - `401` with `WWW-Authenticate` on unauthenticated CalDAV access
  - principal discovery (`current-user-principal`)
  - principal `calendar-home-set`
  - discoverable calendar collection with `<C:calendar/>`
  - `REPORT` support for `calendar-query` and `calendar-multiget`
- Level B (required for release): practical write/sync interoperability
  - `PUT`/`DELETE` with stable ETag behavior
  - recurrence + exception round-trip fidelity
  - sync collection stability for incremental updates
- Level C (best effort): client-specific ergonomics/extensions
  - optional properties beyond baseline RFC surface
  - minor behavior adjustments for specific client quirks that do not break A/B

Release gating must include at least:

- `fixture-tests/fixture_caldav_client_compat_smoke.sh` (legacy local discovery/auth compatibility; retained for archival comparison)
- existing fixture smoke + security smoke suites
- at least one real-client manual smoke (for example Thunderbird or Apple Calendar) for release candidates

## Verification Requirements
Acceptance should verify:

- Principal and calendar discovery works via `OPTIONS` and `PROPFIND`.
- Calendar query and multiget reports return correct data for time-range and href selection.
- `GET`, `PUT`, and `DELETE` behaviors match access level permissions.
- ETag and conditional writes prevent lost updates.
- Sync collection reports provide incremental changes.
- Recurring-event single-occurrence delete results in exception representation, not sequence split.
- Returned iCalendar validates against RFC 5545 expectations and is accepted by target clients.
- Privacy values round-trip through CalDAV edit flows (including Thunderbird) without losing event detail fidelity.