@sockethub/platform-caldav 1.0.0-alpha.9 → 1.0.0-beta.1

package/README.md

@@ -1,14 +1,20 @@
 # `@sockethub/platform-caldav`
 
 Sockethub platform for discovering CalDAV calendars and reading, creating,
-updating, and deleting events (`VEVENT`) and tasks (`VTODO`).
+updating, and deleting events (`VEVENT`) and tasks (`VTODO`). It can also read
+published iCalendar (`.ics`) feeds, such as holiday calendars or read-only
+subscription links, without a CalDAV account.
 
 Requests accept only public HTTPS services by default. Administrators can opt
 in to HTTP with `packageConfig.allowInsecureHttp` and private-network targets
 with `packageConfig.allowPrivateAddresses`; these are server settings and
-cannot be enabled by a connected client. Credentials and OAuth tokens are sent
-only to the configured origin. Every calendar and item target is checked
-against the authenticated account before it is used.
+cannot be enabled by a connected client. Address checks use the shared
+outbound URL guard, including IPv6 embeddings of private ranges and the
+local-use NAT64 prefix `64:ff9b:1::/48`. See
+[Outbound URL guard](../../docs/configuration.md#outbound-url-guard).
+Credentials and OAuth tokens are sent only to the configured origin. Every
+calendar and item target is checked against the authenticated account before
+it is used.
 
 ## Authentication
 
@@ -63,6 +69,8 @@ never forwarded to another origin.
 - `fetch`: discover calendars and their event/task support.
 - `query`: read items from one discovered calendar, optionally filtering by
   component type or UTC date range.
+- `read`: list the items in a published `.ics` feed without credentials,
+  with the same optional filters as `query`.
 - `create`: create an event or task with collision protection.
 - `update`: replace an item only when its ETag still matches.
 - `delete`: delete an item only when its ETag still matches.
@@ -113,6 +121,44 @@ Each returned item contains its resource `id`, `uid`, `etag`, and
 `updateSupported`. Keep the ETag for later update or delete requests. Use date
 ranges for large calendars; responses larger than 10 MiB are rejected.
 
+### Read a published iCalendar feed
+
+Many calendars are shared as a read-only `.ics` link (often shown as a
+`webcal://` URL). The `read` action fetches such a feed and returns its
+events and tasks as a collection. It needs no credentials and no `fetch`
+step; `webcal:` links are fetched over HTTPS.
+
+```json
+{
+  "type": "read",
+  "actor": { "id": "caldav:alice", "type": "person" },
+  "target": {
+    "id": "https://example.org/holidays/2026.ics",
+    "type": "feed"
+  },
+  "object": {
+    "type": "event",
+    "startTime": "2026-08-01T00:00:00Z",
+    "endTime": "2026-09-01T00:00:00Z"
+  }
+}
+```
+
+The collection `summary` is the feed's `X-WR-CALNAME` when present. Items use
+the same shape as `query` results, with `updateSupported` always `false` and
+no `etag`; each item's `id` is the feed URL plus a fragment derived from its
+UID, so it is unique within the feed but cannot be used for `update` or
+`delete`. The optional `object` filters by component type and overlap with a
+UTC date range, following the CalDAV time-range rules. Recurring items are not
+expanded: a recurring event is returned once, with its `recurrence` rule,
+whenever the rule can still produce an occurrence inside the range, and
+rescheduled occurrences appear as additional items. Components the platform
+cannot represent (for example an event without a summary) are skipped and
+logged rather than failing the whole feed. An all-day event without an end
+lasts one day when matching a range. Feeds larger than 10 MiB are rejected,
+and the same HTTPS and private-address policies apply as for CalDAV servers,
+including on every redirect.
+
 ### Create an event
 
 ```json
@@ -233,6 +279,7 @@ administrator must explicitly enable `allowPrivateAddresses` or
 | Calendar listing | Supported | Discovers accessible calendars in the user's calendar home and their advertised `VEVENT`/`VTODO` component support. |
 | Events and tasks | Supported | Reads and writes `VEVENT` and `VTODO`. `VJOURNAL` and other component types are not supported. |
 | Calendar queries | Supported | Supports component and UTC time-range filters. Without a range, a query returns a calendar snapshot. |
+| Published iCalendar feeds | Read-only | Reads `.ics` and `webcal://` subscription links without credentials, with component and time-range filters. Recurrences are not expanded. |
 | Conditional create, update, and delete | Supported | Uses ETags with `If-None-Match` and `If-Match` to prevent accidental overwrites. |
 | Recurrence | Partially supported | Common recurrence rules are parsed and generated. Resources with recurrence exceptions, exclusion dates, or multiple primary components are readable but rejected for update when rewriting could lose data. |
 | Scheduling data | Partially supported | Organizer and attendee properties are represented, but CalDAV scheduling inbox/outbox delivery, invitation responses, and server-side email are not implemented. |
@@ -251,4 +298,5 @@ Stable errors include `caldav:authentication-failed`,
 `caldav:unsupported-authentication`,
 `caldav:connection-failed`, `caldav:invalid-calendar`,
 `caldav:invalid-resource`, `caldav:unsupported-component`,
-`caldav:conflict`, and `caldav:not-found`.
+`caldav:conflict`, `caldav:not-found`, `caldav:invalid-feed`, and
+`caldav:feed-failed`.

package/dist/ics.d.ts

@@ -0,0 +1,25 @@
+import type { CalendarItem, QueryInput } from "./types.js";
+export interface ICalendarFeed {
+    name?: string;
+    items: CalendarItem[];
+    skipped: number;
+}
+/**
+ * Whether an item overlaps the requested time range, following the CalDAV
+ * time-range rules: an item matches when it starts before the range ends and
+ * ends after the range starts (a zero-length item matches when it starts at
+ * or after the range start). Recurring items are never expanded: they match
+ * while the rule can still produce an occurrence inside the range: a bounded
+ * rule (UNTIL or COUNT) stops matching once its last possible occurrence,
+ * including the master duration, has ended. Items without any time match
+ * only when no range is given. An all-day event with no end lasts one day
+ * (RFC 5545 section 3.6.1).
+ */
+export declare function matchesRange(item: CalendarItem, query: QueryInput): boolean;
+/**
+ * Parse every event and task in a published iCalendar file (an `.ics`
+ * subscription) into the item model used by CalDAV queries. Components the
+ * parser cannot represent are counted in `skipped` rather than failing the
+ * whole feed, since subscriptions are read-only and often third-party.
+ */
+export declare function parseICalendarFeed(body: string, sourceUrl: string, query?: QueryInput): ICalendarFeed;

package/dist/index.d.ts

@@ -1,19 +1,47 @@
 import type { ActivityStream, PlatformCallback, PlatformInterface, PlatformSchemaStruct, PlatformSession, StatelessPlatformConfig } from "@sockethub/schemas";
+import { type Agent } from "undici";
 import type { CalDavCredentials } from "./types.js";
+/**
+ * `fetch` that honours an undici `dispatcher`. Defaults to undici's own
+ * `fetch` so the request and the guarded dispatcher come from the same build.
+ */
+type FeedFetch = (url: URL, init: RequestInit & {
+    dispatcher?: Agent;
+}) => Promise<Response>;
 export declare function assertCalendarResource(calendarId: string, resourceId: string): void;
 export default class CalDav implements PlatformInterface {
     private readonly log;
+    private readonly fetchImpl;
+    private feedDispatcher?;
     config: StatelessPlatformConfig;
-    constructor(session: PlatformSession);
+    constructor(session: PlatformSession, fetchImpl?: FeedFetch);
     get schema(): PlatformSchemaStruct;
     isInitialized(): boolean;
     cleanup(done: PlatformCallback): void;
     fetch(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
+    /**
+     * Read a published iCalendar (`.ics`) file such as a holiday calendar or a
+     * read-only subscription link. No CalDAV account is involved, so this
+     * action takes no credentials; `webcal:` links are fetched over HTTPS.
+     */
+    read(job: ActivityStream, done: PlatformCallback): void;
     create(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
     query(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
     update(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
     delete(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
     private client;
+    /**
+     * The SSRF-guarded dispatcher for feed reads, created once per instance
+     * (its policy comes from packageConfig, fixed before the first job) so
+     * connections are pooled across reads.
+     */
+    private dispatcher;
+    /**
+     * Fetch a feed, following redirects by hand so every hop is re-checked
+     * against the scheme policy; the guarded dispatcher only vets addresses.
+     */
+    private fetchFeed;
+    private feedUrl;
     private calendar;
     private assertResource;
     private mutationResponse;