@remit/calendar-service 0.0.3 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/calendar-service",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
   "type": "module",
   "main": "src/index.ts",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./memory-store": {
+      "types": "./src/memory-store.ts",
+      "default": "./src/memory-store.ts"
     }
   },
   "scripts": {

package/src/feed.test.ts

@@ -0,0 +1,286 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	CalendarCollectionItem,
+	CalendarObjectItem,
+} from "@remit/data-ports";
+import {
+	buildCalendarFeed,
+	CALENDAR_FEED_TOKEN_BYTES,
+	calendarFeedIsUnchanged,
+	calendarFeedIsUnmodifiedSince,
+	calendarFeedPath,
+	hashCalendarFeedToken,
+	isCalendarFeedToken,
+	mintCalendarFeedToken,
+	readCalendarFeedToken,
+	redactCalendarFeedPath,
+} from "./feed.js";
+import { AMSTERDAM_VTIMEZONE, ical, singleEvent } from "./fixtures.js";
+
+const collection = (
+	overrides: Partial<CalendarCollectionItem> = {},
+): CalendarCollectionItem =>
+	({
+		calendarId: "cal-1",
+		accountConfigId: "acc-1",
+		urlSegment: "work",
+		displayName: "Work",
+		color: "Cal1",
+		componentSet: "VeventOnly",
+		source: "UserCreated",
+		timezone: "",
+		syncSequence: 3,
+		createdAt: 1_700_000_000_000,
+		updatedAt: 1_700_000_000_000,
+		...overrides,
+	}) as CalendarCollectionItem;
+
+const object = (
+	resourceName: string,
+	icalData: string,
+	updatedAt = 1_700_000_100_000,
+): CalendarObjectItem =>
+	({
+		calendarObjectId: `obj-${resourceName}`,
+		calendarId: "cal-1",
+		resourceName,
+		icalData,
+		updatedAt,
+	}) as CalendarObjectItem;
+
+describe("a feed token", () => {
+	it("is base64url over the declared number of random bytes", () => {
+		const minted = mintCalendarFeedToken();
+
+		assert.equal(
+			Buffer.from(minted.token, "base64url").length,
+			CALENDAR_FEED_TOKEN_BYTES,
+		);
+		assert.ok(isCalendarFeedToken(minted.token));
+		assert.equal(minted.tokenHash, hashCalendarFeedToken(minted.token));
+		assert.equal(minted.tokenHash.length, 64);
+		assert.equal(
+			minted.tokenHash.includes(minted.token),
+			false,
+			"the stored value is a digest, not the secret",
+		);
+	});
+
+	it("is never the same twice", () => {
+		const minted = new Set(
+			Array.from({ length: 64 }, () => mintCalendarFeedToken().token),
+		);
+
+		assert.equal(minted.size, 64);
+	});
+
+	it("refuses anything that is not the shape of one", () => {
+		for (const candidate of [
+			"",
+			"short",
+			"a".repeat(42),
+			"a".repeat(44),
+			`${"a".repeat(42)}/`,
+			`${"a".repeat(42)}.`,
+			"../../etc/passwd",
+		]) {
+			assert.equal(isCalendarFeedToken(candidate), false, candidate);
+		}
+	});
+});
+
+describe("a feed address", () => {
+	it("reads back the token it was written from", () => {
+		const minted = mintCalendarFeedToken();
+
+		assert.equal(
+			readCalendarFeedToken(calendarFeedPath(minted.token)),
+			minted.token,
+		);
+	});
+
+	it("is not a feed address without the path and the suffix", () => {
+		assert.equal(readCalendarFeedToken("/feeds/calendar/abc"), null);
+		assert.equal(readCalendarFeedToken("/calendars/abc.ics"), null);
+		assert.equal(readCalendarFeedToken("/feeds/calendar/a/b.ics"), null);
+	});
+});
+
+describe("the calendar a feed serves", () => {
+	it("names itself from the collection and terminates its last line", () => {
+		const feed = buildCalendarFeed(collection({ displayName: "Team" }), [
+			object(
+				"a.ics",
+				singleEvent("SUMMARY:Stand-up", "DTSTART:20260907T090000Z"),
+			),
+		]);
+
+		assert.match(feed.icalData, /^BEGIN:VCALENDAR\r\n/);
+		assert.match(feed.icalData, /X-WR-CALNAME:Team\r\n/);
+		assert.match(feed.icalData, /END:VCALENDAR\r\n$/);
+		assert.match(feed.icalData, /SUMMARY:Stand-up/);
+	});
+
+	it("carries the collection's zone so a client reads floating times the same way", () => {
+		const feed = buildCalendarFeed(
+			collection({ timezone: "Europe/Amsterdam" }),
+			[],
+		);
+
+		assert.match(feed.icalData, /X-WR-TIMEZONE:Europe\/Amsterdam\r\n/);
+	});
+
+	it("keeps the rule rather than the occurrences it would produce", () => {
+		const feed = buildCalendarFeed(collection(), [
+			object(
+				"a.ics",
+				singleEvent(
+					"SUMMARY:Weekly",
+					"DTSTART:20260907T090000Z",
+					"RRULE:FREQ=WEEKLY;COUNT=5",
+				),
+			),
+		]);
+
+		assert.equal(feed.icalData.match(/BEGIN:VEVENT/g)?.length, 1);
+		assert.match(feed.icalData, /RRULE:FREQ=WEEKLY;COUNT=5/);
+	});
+
+	it("carries one copy of a VTIMEZONE two resources both declare", () => {
+		const withZone = (uid: string) =>
+			ical(
+				"BEGIN:VCALENDAR",
+				"VERSION:2.0",
+				"PRODID:-//Remit//Calendar Tests//EN",
+				...AMSTERDAM_VTIMEZONE,
+				"BEGIN:VEVENT",
+				`UID:${uid}`,
+				"DTSTAMP:20260801T090000Z",
+				"DTSTART;TZID=Europe/Amsterdam:20260907T090000",
+				"END:VEVENT",
+				"END:VCALENDAR",
+			);
+
+		const feed = buildCalendarFeed(collection(), [
+			object("a.ics", withZone("a@example.com")),
+			object("b.ics", withZone("b@example.com")),
+		]);
+
+		assert.equal(feed.icalData.match(/BEGIN:VTIMEZONE/g)?.length, 1);
+		assert.equal(feed.icalData.match(/BEGIN:VEVENT/g)?.length, 2);
+	});
+
+	it("declares one VERSION however many resources it gathered", () => {
+		const feed = buildCalendarFeed(collection(), [
+			object("a.ics", singleEvent("DTSTART:20260907T090000Z")),
+			object("b.ics", singleEvent("DTSTART:20260908T090000Z")),
+		]);
+
+		assert.equal(feed.icalData.match(/^VERSION:/gm)?.length, 1);
+		assert.equal(feed.icalData.match(/^PRODID:/gm)?.length, 1);
+	});
+
+	it("moves its tag when the bytes change and holds it when they do not", () => {
+		const one = object("a.ics", singleEvent("DTSTART:20260907T090000Z"));
+		const two = object("b.ics", singleEvent("DTSTART:20260908T090000Z"));
+
+		const first = buildCalendarFeed(collection(), [one]);
+		const again = buildCalendarFeed(collection(), [one]);
+		const grown = buildCalendarFeed(collection(), [one, two]);
+		const renamed = buildCalendarFeed(collection({ displayName: "Team" }), [
+			one,
+		]);
+
+		assert.equal(again.etag, first.etag);
+		assert.notEqual(grown.etag, first.etag);
+		assert.notEqual(renamed.etag, first.etag);
+	});
+
+	it("carries no modification time of its own", () => {
+		// The newest surviving event is not when the calendar last changed: a
+		// delete removes the newest one and leaves every survivor older than the
+		// change. The collection's own timestamp is what the feed serves, and it
+		// belongs to the store rather than to these bytes (issue #1067).
+		const feed = buildCalendarFeed(collection({ updatedAt: 500 }), [
+			object("a.ics", singleEvent("DTSTART:20260907T090000Z"), 900),
+		]);
+
+		assert.deepEqual(Object.keys(feed).sort(), ["etag", "icalData"]);
+	});
+});
+
+describe("a conditional poll", () => {
+	it("is unchanged for the tag it holds, quoted, weak or in a list", () => {
+		for (const header of ['"abc"', "abc", 'W/"abc"', '"other", "abc"', "*"]) {
+			assert.ok(calendarFeedIsUnchanged(header, "abc"), String(header));
+		}
+	});
+
+	it("is changed with no header, an empty one, or somebody else's tag", () => {
+		for (const header of [undefined, "", '"other"', 'W/"other"']) {
+			assert.equal(
+				calendarFeedIsUnchanged(header, "abc"),
+				false,
+				String(header),
+			);
+		}
+	});
+});
+
+describe("a feed path in a log line", () => {
+	it("keeps the route and drops the token", () => {
+		const minted = mintCalendarFeedToken();
+
+		const redacted = redactCalendarFeedPath(calendarFeedPath(minted.token));
+
+		assert.equal(redacted.includes(minted.token), false);
+		assert.equal(redacted, "/feeds/calendar/<redacted>.ics");
+	});
+
+	it("leaves a path that carries no token alone", () => {
+		for (const path of [
+			"/calendars/abc",
+			"/feeds/calendar/no-suffix",
+			"/health",
+		]) {
+			assert.equal(redactCalendarFeedPath(path), path, path);
+		}
+	});
+});
+
+describe("a poll carrying a date", () => {
+	const lastModified = Date.UTC(2026, 8, 7, 9, 0, 0);
+
+	it("is unmodified for the second it was last written in", () => {
+		// Last-Modified went out truncated to the second, so the value that comes
+		// back is 750ms behind the stored timestamp and still means "the copy I
+		// have is the one you served".
+		assert.ok(
+			calendarFeedIsUnmodifiedSince(
+				new Date(lastModified).toUTCString(),
+				lastModified + 750,
+			),
+		);
+	});
+
+	it("is modified once the calendar moves into a later second", () => {
+		assert.equal(
+			calendarFeedIsUnmodifiedSince(
+				new Date(lastModified).toUTCString(),
+				lastModified + 1000,
+			),
+			false,
+		);
+	});
+
+	it("is not a condition when the date is absent or unreadable", () => {
+		for (const header of [undefined, "", "whenever"]) {
+			assert.equal(
+				calendarFeedIsUnmodifiedSince(header, lastModified),
+				false,
+				String(header),
+			);
+		}
+	});
+});

package/src/feed.ts

@@ -0,0 +1,182 @@
+import { createHash, randomBytes } from "node:crypto";
+import type {
+	CalendarCollectionItem,
+	CalendarObjectItem,
+} from "@remit/data-ports";
+import ICAL from "ical.js";
+import { CALENDAR_PRODID } from "./build.js";
+import { computeEtag } from "./etag.js";
+import { serializeCalendar } from "./parse.js";
+
+/** Random bytes behind a feed token (issue #1067). */
+export const CALENDAR_FEED_TOKEN_BYTES = 32;
+
+/** Where a feed lives, as the one place the shape of that path is written. */
+export const CALENDAR_FEED_PATH_PREFIX = "/feeds/calendar/";
+export const CALENDAR_FEED_PATH_SUFFIX = ".ics";
+
+/** base64url over `CALENDAR_FEED_TOKEN_BYTES`, so the length is fixed. */
+const TOKEN_LENGTH = Math.ceil((CALENDAR_FEED_TOKEN_BYTES * 4) / 3);
+const TOKEN_SHAPE = new RegExp(`^[A-Za-z0-9_-]{${TOKEN_LENGTH}}$`);
+
+/** A minted feed address: the secret, handed out once, and what is stored. */
+export interface CalendarFeedSecret {
+	token: string;
+	tokenHash: string;
+}
+
+export const hashCalendarFeedToken = (token: string): string =>
+	createHash("sha256").update(token, "utf8").digest("hex");
+
+/**
+ * A fresh feed token and the hash that will stand in for it.
+ *
+ * 32 random bytes rather than a stretched password: nothing about this value is
+ * user-chosen, so there is no dictionary to search and a slow hash would only
+ * tax every poll of every subscribed client.
+ */
+export const mintCalendarFeedToken = (): CalendarFeedSecret => {
+	const token = randomBytes(CALENDAR_FEED_TOKEN_BYTES).toString("base64url");
+	return { token, tokenHash: hashCalendarFeedToken(token) };
+};
+
+/**
+ * Whether a path segment can be a feed token at all.
+ *
+ * Checked before anything is hashed or read, so a request carrying a megabyte
+ * of path or a `../` never reaches the store. A refusal here is the same 404 a
+ * revoked token gets — the caller learns nothing from the difference.
+ */
+export const isCalendarFeedToken = (token: string): boolean =>
+	TOKEN_SHAPE.test(token);
+
+export const calendarFeedPath = (token: string): string =>
+	`${CALENDAR_FEED_PATH_PREFIX}${token}${CALENDAR_FEED_PATH_SUFFIX}`;
+
+/**
+ * The token a request path carries, or `null` when the path is not a feed
+ * address. One segment only: a slash inside it would name a different route.
+ */
+export const readCalendarFeedToken = (path: string): string | null => {
+	if (!path.startsWith(CALENDAR_FEED_PATH_PREFIX)) return null;
+	if (!path.endsWith(CALENDAR_FEED_PATH_SUFFIX)) return null;
+	const token = path.slice(
+		CALENDAR_FEED_PATH_PREFIX.length,
+		-CALENDAR_FEED_PATH_SUFFIX.length,
+	);
+	if (token.includes("/")) return null;
+	return token;
+};
+
+/**
+ * The feed path with its token taken out, for a log line or a metric label.
+ *
+ * The token is the whole credential, so a path that carries one is not a field
+ * that can be recorded. Redacted rather than dropped: which route was served is
+ * what an operator reads a log for, and a blank path loses that too.
+ */
+export const redactCalendarFeedPath = (path: string): string =>
+	readCalendarFeedToken(path) === null
+		? path
+		: `${CALENDAR_FEED_PATH_PREFIX}<redacted>${CALENDAR_FEED_PATH_SUFFIX}`;
+
+/** The bytes a feed serves, and what a conditional request needs to skip them. */
+export interface CalendarFeed {
+	icalData: string;
+	etag: string;
+}
+
+/**
+ * One VCALENDAR carrying every event in a collection.
+ *
+ * The stored components are copied across as they are: a recurring event
+ * travels as its master plus its RRULE, never as an expansion, because a
+ * subscriber renders occurrences itself and expects to keep doing so past any
+ * horizon this server would have chosen. VTIMEZONE definitions come along for
+ * the same reason — without them a client reads a TZID it cannot resolve.
+ *
+ * `X-WR-CALNAME` is a property of the calendar, not of the response: Apple
+ * Calendar, Google Calendar and Thunderbird all name a subscription from it.
+ */
+export const buildCalendarFeed = (
+	collection: CalendarCollectionItem,
+	objects: readonly CalendarObjectItem[],
+): CalendarFeed => {
+	const feed = new ICAL.Component("vcalendar");
+	feed.updatePropertyWithValue("prodid", CALENDAR_PRODID);
+	feed.updatePropertyWithValue("version", "2.0");
+	feed.updatePropertyWithValue("calscale", "GREGORIAN");
+	feed.updatePropertyWithValue("x-wr-calname", collection.displayName);
+	if (collection.timezone !== "") {
+		feed.updatePropertyWithValue("x-wr-timezone", collection.timezone);
+	}
+
+	const zonesSeen = new Set<string>();
+	for (const object of objects) {
+		const stored = new ICAL.Component(ICAL.parse(object.icalData));
+		// A copy of the list, not the list: adding a component reparents it,
+		// which splices it out of the array `getAllSubcomponents` handed back and
+		// would drop whatever followed it.
+		for (const child of [...stored.getAllSubcomponents()]) {
+			if (child.name === "vtimezone") {
+				const tzid = child.getFirstPropertyValue("tzid");
+				const key = typeof tzid === "string" ? tzid : "";
+				if (zonesSeen.has(key)) continue;
+				zonesSeen.add(key);
+			}
+			feed.addSubcomponent(child);
+		}
+	}
+
+	// ical.js leaves the last content line unterminated. Every line in an
+	// iCalendar stream ends with CRLF (RFC 5545 3.1), END:VCALENDAR included.
+	const serialized = serializeCalendar(feed);
+	const icalData = serialized.endsWith("\r\n")
+		? serialized
+		: `${serialized}\r\n`;
+	return { icalData, etag: computeEtag(icalData) };
+};
+
+/**
+ * Whether an `If-None-Match` covers the tag the feed would serve.
+ *
+ * Accepts the weak form and `*`, and reads the header as the list RFC 9110
+ * 13.1.2 says it is — a subscriber that has polled through a proxy may get its
+ * own tag back with a `W/` on it, and answering 200 to that resends the whole
+ * calendar for nothing.
+ */
+export const calendarFeedIsUnchanged = (
+	ifNoneMatch: string | undefined,
+	etag: string,
+): boolean => {
+	if (ifNoneMatch === undefined || ifNoneMatch === "") return false;
+	if (ifNoneMatch.trim() === "*") return true;
+	return ifNoneMatch
+		.split(",")
+		.map((candidate) =>
+			candidate.trim().replace(/^W\//, "").replace(/^"|"$/g, ""),
+		)
+		.includes(etag);
+};
+
+/**
+ * Whether the calendar has stood still since the date an `If-Modified-Since`
+ * carries.
+ *
+ * Compared at whole seconds, which is the resolution an HTTP-date has: a
+ * `Last-Modified` served from a millisecond timestamp is rounded down on the
+ * way out, and comparing the unrounded value against what comes back declares
+ * every calendar modified within the second it was last written.
+ *
+ * An unreadable date is not a condition (RFC 9110 13.1.3) — the full calendar
+ * is served rather than a 304 nobody asked for.
+ */
+export const calendarFeedIsUnmodifiedSince = (
+	ifModifiedSince: string | undefined,
+	lastModifiedAt: number,
+): boolean => {
+	if (ifModifiedSince === undefined || ifModifiedSince === "") return false;
+	const since = Date.parse(ifModifiedSince);
+	if (Number.isNaN(since)) return false;
+	return Math.floor(lastModifiedAt / 1000) * 1000 <= since;
+};

package/src/index.ts

@@ -27,6 +27,22 @@ export {
 	expandCalendar,
 	expandCalendarWindow,
 } from "./expand.js";
+export {
+	buildCalendarFeed,
+	CALENDAR_FEED_PATH_PREFIX,
+	CALENDAR_FEED_PATH_SUFFIX,
+	CALENDAR_FEED_TOKEN_BYTES,
+	type CalendarFeed,
+	type CalendarFeedSecret,
+	calendarFeedIsUnchanged,
+	calendarFeedIsUnmodifiedSince,
+	calendarFeedPath,
+	hashCalendarFeedToken,
+	isCalendarFeedToken,
+	mintCalendarFeedToken,
+	readCalendarFeedToken,
+	redactCalendarFeedPath,
+} from "./feed.js";
 export {
 	type ParsedCalendar,
 	parseCalendar,

package/src/memory-store.ts

@@ -1,21 +1,26 @@
 import type {
 	CalendarCollectionItem,
 	CalendarEventIndexItem,
+	CalendarFeedTokenItem,
 	CalendarObjectItem,
 	CalendarOccurrenceInput,
 	CalendarSuggestionItem,
 	CreateCalendarCollectionInput,
 	ICalendarCollectionRepository,
 	ICalendarEventIndexRepository,
+	ICalendarFeedTokenRepository,
 	ICalendarObjectRepository,
 	ICalendarSuggestionRepository,
 	ICalendarUnitOfWork,
+	PutCalendarFeedTokenInput,
 	PutCalendarObjectInput as PutCalendarObjectRow,
 	PutCalendarSuggestionInput,
 	SettleCalendarSuggestionInput,
 	UpdateCalendarCollectionInput,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import {
+	deriveCalendarFeedTokenId,
 	deriveCalendarId,
 	deriveCalendarObjectId,
 	deriveCalendarSuggestionId,
@@ -23,7 +28,11 @@ import {
 } from "@remit/data-ports/id";
 import { CalendarSuggestionState } from "@remit/domain-enums";
 
-export class MissingRow extends Error {}
+// The class the port's conformance suite requires a repository to throw for an
+// absent row, so a caller that branches on it — the calendar feed answers 404 to
+// a token whose collection is gone — behaves the same against this double as
+// against a real one.
+export class MissingRow extends NotFoundError {}
 
 /**
  * A pass-through unit of work over plain maps — the shape the port documents
@@ -37,6 +46,7 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 	readonly objects = new Map<string, CalendarObjectItem>();
 	readonly occurrences = new Map<string, CalendarEventIndexItem[]>();
 	readonly suggestions = new Map<string, CalendarSuggestionItem>();
+	readonly feedTokens = new Map<string, CalendarFeedTokenItem>();
 
 	private readonly collectionRepo: ICalendarCollectionRepository = {
 		create: async (input: CreateCalendarCollectionInput) => {
@@ -101,6 +111,7 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 			const bumped = {
 				...collection,
 				syncSequence: collection.syncSequence + 1,
+				updatedAt: Date.now(),
 			};
 			this.collections.set(calendarId, bumped);
 			return bumped.syncSequence;
@@ -281,6 +292,40 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 		},
 	};
 
+	private readonly feedTokenRepo: ICalendarFeedTokenRepository = {
+		put: async (input: PutCalendarFeedTokenInput) => {
+			const feedTokenId = deriveCalendarFeedTokenId(input.calendarId);
+			const now = Date.now();
+			const existing = this.feedTokens.get(feedTokenId);
+			const token: CalendarFeedTokenItem = {
+				feedTokenId,
+				accountConfigId: input.accountConfigId,
+				calendarId: input.calendarId,
+				tokenHash: input.tokenHash,
+				createdAt: existing?.createdAt ?? now,
+				rotatedAt: existing ? now : 0,
+				updatedAt: now,
+			};
+			this.feedTokens.set(feedTokenId, token);
+			return token;
+		},
+		findByCalendar: async (accountConfigId: string, calendarId: string) => {
+			const token = this.feedTokens.get(deriveCalendarFeedTokenId(calendarId));
+			if (!token || token.accountConfigId !== accountConfigId) return null;
+			return token;
+		},
+		findByTokenHash: async (tokenHash: string) =>
+			[...this.feedTokens.values()].find(
+				(token) => token.tokenHash === tokenHash,
+			) ?? null,
+		delete: async (accountConfigId: string, calendarId: string) => {
+			const feedTokenId = deriveCalendarFeedTokenId(calendarId);
+			const token = this.feedTokens.get(feedTokenId);
+			if (!token || token.accountConfigId !== accountConfigId) return;
+			this.feedTokens.delete(feedTokenId);
+		},
+	};
+
 	get calendarSuggestion(): ICalendarSuggestionRepository {
 		return this.suggestionRepo;
 	}
@@ -291,6 +336,7 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 			calendarObject: ICalendarObjectRepository;
 			calendarEventIndex: ICalendarEventIndexRepository;
 			calendarSuggestion: ICalendarSuggestionRepository;
+			calendarFeedToken: ICalendarFeedTokenRepository;
 		}) => Promise<T>,
 	): Promise<T> {
 		return fn({
@@ -298,6 +344,7 @@ export class MemoryCalendarStore implements ICalendarUnitOfWork {
 			calendarObject: this.objectRepo,
 			calendarEventIndex: this.eventIndexRepo,
 			calendarSuggestion: this.suggestionRepo,
+			calendarFeedToken: this.feedTokenRepo,
 		});
 	}
 }