@remit/data-ports 0.0.55 → 0.0.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/conformance/calendar-collection.ts

@@ -204,6 +204,26 @@ export function calendarCollectionRepositoryConformance(
 			assert.equal(reread.syncSequence, 5);
 		});
 
+		// Every write and every delete of an object in the collection goes through
+		// this bump, which makes the collection the one timestamp that only moves
+		// forward — the calendar feed serves it as Last-Modified, and a validator
+		// that moved backwards on a delete would tell a subscriber its stale copy
+		// is still good.
+		test("bumpSyncSequence carries the collection's modification time forward", async () => {
+			const accountConfigId = harness.makeId();
+			const calendar = await repo.create({
+				accountConfigId,
+				urlSegment: "touched",
+				displayName: "Touched",
+			});
+
+			await repo.bumpSyncSequence(accountConfigId, calendar.calendarId);
+			const bumped = await repo.get(accountConfigId, calendar.calendarId);
+
+			assert.ok(bumped.updatedAt >= calendar.updatedAt);
+			assert.equal(bumped.createdAt, calendar.createdAt);
+		});
+
 		test("bumpSyncSequence throws a not-found error for a missing collection", async () => {
 			await assert.rejects(
 				repo.bumpSyncSequence(harness.makeId(), harness.makeId()),

package/src/conformance/calendar-feed-token.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { deriveCalendarFeedTokenId } from "../id.js";
+import type { ICalendarFeedTokenRepository } from "../interfaces/calendar-feed-token.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+const hashOf = (label: string): string => label.padEnd(64, "0");
+
+export function calendarFeedTokenRepositoryConformance(
+	harness: RepositoryConformanceHarness<ICalendarFeedTokenRepository>,
+): void {
+	describe("ICalendarFeedTokenRepository conformance", () => {
+		let repo: ICalendarFeedTokenRepository;
+
+		before(async () => {
+			repo = await harness.createRepository();
+		});
+
+		after(() => harness.teardown());
+
+		test("put derives the id from the calendar and starts unrotated", async () => {
+			const accountConfigId = harness.makeId();
+			const calendarId = harness.makeId();
+
+			const minted = await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("a"),
+			});
+
+			assert.equal(minted.feedTokenId, deriveCalendarFeedTokenId(calendarId));
+			assert.equal(minted.calendarId, calendarId);
+			assert.equal(minted.tokenHash, hashOf("a"));
+			assert.equal(minted.rotatedAt, 0);
+			assert.ok(minted.createdAt > 0);
+		});
+
+		test("a second put rotates the one address rather than adding another", async () => {
+			const accountConfigId = harness.makeId();
+			const calendarId = harness.makeId();
+
+			const minted = await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("b"),
+			});
+			const rotated = await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("c"),
+			});
+
+			assert.equal(rotated.feedTokenId, minted.feedTokenId);
+			assert.equal(rotated.tokenHash, hashOf("c"));
+			assert.equal(
+				rotated.createdAt,
+				minted.createdAt,
+				"the feed is the same feed under a new secret",
+			);
+			assert.ok(
+				rotated.rotatedAt > 0,
+				"a replacement is distinguishable from a first mint",
+			);
+			assert.equal(
+				await repo.findByTokenHash(hashOf("b")),
+				null,
+				"the address that was rotated away no longer resolves",
+			);
+			assert.equal(
+				(await repo.findByTokenHash(hashOf("c")))?.calendarId,
+				calendarId,
+			);
+		});
+
+		test("findByCalendar answers only for the account config that owns it", async () => {
+			const accountConfigId = harness.makeId();
+			const stranger = harness.makeId();
+			const calendarId = harness.makeId();
+			await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("d"),
+			});
+
+			assert.equal(
+				(await repo.findByCalendar(accountConfigId, calendarId))?.tokenHash,
+				hashOf("d"),
+			);
+			assert.equal(await repo.findByCalendar(stranger, calendarId), null);
+			assert.equal(
+				await repo.findByCalendar(accountConfigId, harness.makeId()),
+				null,
+			);
+		});
+
+		test("findByTokenHash is unscoped, and names the owner it found", async () => {
+			const accountConfigId = harness.makeId();
+			const calendarId = harness.makeId();
+			await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("e"),
+			});
+
+			const found = await repo.findByTokenHash(hashOf("e"));
+
+			assert.equal(found?.accountConfigId, accountConfigId);
+			assert.equal(found?.calendarId, calendarId);
+			assert.equal(await repo.findByTokenHash(hashOf("nothing")), null);
+		});
+
+		test("delete stops the address resolving", async () => {
+			const accountConfigId = harness.makeId();
+			const calendarId = harness.makeId();
+			await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("f"),
+			});
+
+			await repo.delete(accountConfigId, calendarId);
+
+			assert.equal(await repo.findByTokenHash(hashOf("f")), null);
+			assert.equal(
+				await repo.findByCalendar(accountConfigId, calendarId),
+				null,
+			);
+		});
+
+		test("delete leaves another account config's address alone", async () => {
+			const accountConfigId = harness.makeId();
+			const stranger = harness.makeId();
+			const calendarId = harness.makeId();
+			await repo.put({
+				accountConfigId,
+				calendarId,
+				tokenHash: hashOf("g"),
+			});
+
+			await repo.delete(stranger, calendarId);
+
+			assert.equal(
+				(await repo.findByTokenHash(hashOf("g")))?.calendarId,
+				calendarId,
+			);
+		});
+	});
+}

package/src/conformance/index.ts

@@ -1,5 +1,6 @@
 export { calendarCollectionRepositoryConformance } from "./calendar-collection.js";
 export { calendarEventIndexRepositoryConformance } from "./calendar-event-index.js";
+export { calendarFeedTokenRepositoryConformance } from "./calendar-feed-token.js";
 export { calendarObjectRepositoryConformance } from "./calendar-object.js";
 export { calendarSuggestionRepositoryConformance } from "./calendar-suggestion.js";
 export type { RepositoryConformanceHarness } from "./harness.js";

package/src/id.ts

@@ -47,6 +47,15 @@ export const deriveCalendarId = (
 		REMIT_NAMESPACE,
 	);
 
+/**
+ * Identity of a calendar's feed address (issue #1067). Derived from the
+ * collection, so one calendar holds one active token by construction: rotating
+ * rewrites the row it already has instead of leaving a second live address
+ * nobody can see to revoke.
+ */
+export const deriveCalendarFeedTokenId = (calendarId: string): string =>
+	base36uuidv5(`calendarfeedtoken:${calendarId}`, REMIT_NAMESPACE);
+
 /**
  * Identity of a calendar resource (issue #15). Derived from its collection and
  * its resource name — the last path segment of the resource's URL — so a

package/src/index.ts

@@ -6,6 +6,7 @@ export type { IAccountSettingRepository } from "./interfaces/account-setting.js"
 export type { IAddressRepository } from "./interfaces/address.js";
 export type { ICalendarCollectionRepository } from "./interfaces/calendar-collection.js";
 export type { ICalendarEventIndexRepository } from "./interfaces/calendar-event-index.js";
+export type { ICalendarFeedTokenRepository } from "./interfaces/calendar-feed-token.js";
 export type { ICalendarObjectRepository } from "./interfaces/calendar-object.js";
 export type {
 	ICalendarSuggestionRepository,
@@ -75,6 +76,7 @@ export type {
 	BodyPartUpsertInput,
 	CalendarCollectionItem,
 	CalendarEventIndexItem,
+	CalendarFeedTokenItem,
 	CalendarObjectItem,
 	CalendarOccurrenceInput,
 	CalendarSuggestionItem,
@@ -122,6 +124,7 @@ export type {
 	OrganizeJobRequestItem,
 	OutboxAttachmentItem,
 	OutboxMessageItem,
+	PutCalendarFeedTokenInput,
 	PutCalendarObjectInput,
 	PutCalendarSuggestionInput,
 	PutMessageFlagPushInput,

package/src/interfaces/calendar-feed-token.ts

@@ -0,0 +1,38 @@
+import type {
+	CalendarFeedTokenItem,
+	PutCalendarFeedTokenInput,
+} from "../types.js";
+
+export interface ICalendarFeedTokenRepository {
+	/**
+	 * Mints the calendar's feed address, or replaces the token it already has.
+	 *
+	 * One statement, and an upsert on the derived `feedTokenId`: a calendar holds
+	 * exactly one active address, so there is no state in which a revoked token
+	 * still resolves alongside its replacement. `createdAt` survives a
+	 * replacement — the feed is the same feed under a new secret — and
+	 * `rotatedAt` is stamped only when a row was already there, so a caller can
+	 * tell a fresh address from a rotated one without a prior read.
+	 */
+	put(input: PutCalendarFeedTokenInput): Promise<CalendarFeedTokenItem>;
+	/**
+	 * The address a calendar holds, or `null` when it has none. Scoped by account
+	 * config: a management read is always somebody's, and an unscoped one would
+	 * answer for a calendar the caller does not own.
+	 */
+	findByCalendar(
+		accountConfigId: string,
+		calendarId: string,
+	): Promise<CalendarFeedTokenItem | null>;
+	/**
+	 * The row a token hash names, or `null` when nothing answers to it.
+	 *
+	 * Deliberately unscoped, and the only read that is: a subscriber arrives with
+	 * no session at all, so the hash is the whole lookup key and the row it finds
+	 * is what names the owner. The caller still compares the stored hash against
+	 * the presented one before serving anything.
+	 */
+	findByTokenHash(tokenHash: string): Promise<CalendarFeedTokenItem | null>;
+	/** Revokes the calendar's address. Every subscribed client stops resolving. */
+	delete(accountConfigId: string, calendarId: string): Promise<void>;
+}

package/src/interfaces/calendar-unit-of-work.ts

@@ -1,5 +1,6 @@
 import type { ICalendarCollectionRepository } from "./calendar-collection.js";
 import type { ICalendarEventIndexRepository } from "./calendar-event-index.js";
+import type { ICalendarFeedTokenRepository } from "./calendar-feed-token.js";
 import type { ICalendarObjectRepository } from "./calendar-object.js";
 import type { ICalendarSuggestionRepository } from "./calendar-suggestion.js";
 
@@ -18,6 +19,13 @@ export interface CalendarUnitOfWorkRepositories {
 	 * with no event behind it, is a state nothing later can repair.
 	 */
 	calendarSuggestion: ICalendarSuggestionRepository;
+	/**
+	 * Present so removing a calendar takes its feed address with it (issue
+	 * #1067). A token row outliving its collection is a credential pointing at
+	 * nothing — it answers 404, but nobody can see it to revoke it, and a later
+	 * calendar under the same derived id would inherit it.
+	 */
+	calendarFeedToken: ICalendarFeedTokenRepository;
 }
 
 /**

package/src/interfaces/outbox-attachment.ts

@@ -52,13 +52,12 @@ export interface IOutboxAttachmentRepository {
 	 * from these rows and the receiving server rejects it.
 	 *
 	 * A count-then-insert only satisfies that under serializable isolation or an
-	 * external lock. **The drizzle/SQLite implementation gets it from neither the
-	 * schema nor the isolation level:** `runInTransaction` issues a SAVEPOINT,
-	 * which begins a DEFERRED transaction, and what actually orders concurrent
-	 * reservations is the module-level write queue in `tx.ts` — correct on a
-	 * single-process deployment, which is what that backend is. Two writer
-	 * processes against one SQLite file would fail loud
-	 * (`SQLITE_BUSY_SNAPSHOT`), not silently over-admit.
+	 * external lock. **The drizzle/SQLite implementation gets it from the lock,
+	 * not from the schema or the isolation level:** `runInTransaction` opens a
+	 * unit with `BEGIN IMMEDIATE`, so it holds the file's write lock from before
+	 * its first read, and the module-level write queue in `tx.ts` orders the
+	 * units inside one process. Two writer processes against one SQLite file are
+	 * ordered by that lock rather than over-admitting.
 	 *
 	 * **An adapter without serializable isolation must not do a
 	 * read-then-write.** On DynamoDB in particular, a Query followed by a

package/src/types.ts

@@ -8,6 +8,7 @@ import type {
 	BodyPartStorageSchema,
 	CalendarCollectionSchema,
 	CalendarEventIndexSchema,
+	CalendarFeedTokenSchema,
 	CalendarObjectSchema,
 	CalendarSuggestionSchema,
 	ConfigImportSchema,
@@ -584,6 +585,16 @@ export type UpdateCalendarCollectionInput = Partial<
 	Pick<CalendarCollectionItem, "displayName" | "color" | "timezone">
 >;
 
+export type CalendarFeedTokenItem = z.infer<typeof CalendarFeedTokenSchema>;
+
+// `feedTokenId` is derived from `calendarId`, which is what makes one active
+// token per calendar structural rather than enforced. `rotatedAt` is the
+// repository's to stamp: only it can tell a mint from a replacement.
+export type PutCalendarFeedTokenInput = Omit<
+	CalendarFeedTokenItem,
+	"feedTokenId" | "rotatedAt" | "createdAt" | "updatedAt"
+>;
+
 /**
  * A whole calendar resource. Every projected column is supplied together with
  * the `icalData` it was projected from — the repository never derives one from