@remit/data-ports 0.0.55 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -37,6 +37,10 @@
       "types": "./src/mutation-events.ts",
       "default": "./src/mutation-events.ts"
     },
+    "./virtual-copy": {
+      "types": "./src/virtual-copy.ts",
+      "default": "./src/virtual-copy.ts"
+    },
     "./mailbox-name": {
       "types": "./src/mailbox-name.ts",
       "default": "./src/mailbox-name.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/address.ts

@@ -95,6 +95,18 @@ export interface IAddressRepository {
 		cursor?: string;
 		limit?: number;
 	}): Promise<ResultList<AddressItem>>;
+	/**
+	 * Every address stored under the configuration, for a reader that must see
+	 * the whole set: nothing is hidden, so a row the machine marked `junkOnly`
+	 * still comes back with whatever the user decided about it. Ordered by
+	 * `addressId`, which no write moves, so a page boundary cannot skip a row
+	 * while message sync updates counts and timestamps underneath the read.
+	 */
+	listAllByAccountConfigPage(input: {
+		accountConfigId: string;
+		cursor?: string;
+		limit?: number;
+	}): Promise<ResultList<AddressItem>>;
 	createEnvelopeAddress(
 		input: CreateEnvelopeAddressInput,
 	): Promise<EnvelopeAddressItem>;

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/interfaces/outbox-message.ts

@@ -92,5 +92,15 @@ export interface IOutboxMessageRepository {
 		accountId: string,
 		options?: { limit?: number; continuationToken?: string },
 	): Promise<ResultList<OutboxMessageItem>>;
+	/**
+	 * One keyset scan over several accounts, ordered globally by createdAt then
+	 * outboxMessageId. The continuation token names a position in that single
+	 * ordering rather than one position per account, so a second page stays
+	 * coherent however the accounts' rows interleave.
+	 */
+	listByAccounts(
+		accountIds: string[],
+		options?: { limit?: number; continuationToken?: string },
+	): Promise<ResultList<OutboxMessageItem>>;
 	listQueued(accountId: string): Promise<OutboxMessageItem[]>;
 }

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

package/src/virtual-copy.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { MailboxItem } from "./types.js";
+import { isVirtualCopyMailbox } from "./virtual-copy.js";
+
+const mailbox = (fullPath: string, specialUse?: string[]): MailboxItem =>
+	({
+		mailboxId: `mbx-${fullPath}`,
+		fullPath,
+		...(specialUse ? { specialUse } : {}),
+	}) as MailboxItem;
+
+describe("which folders hold a second copy of mail that lives elsewhere", () => {
+	it("reads the special-use the server advertises", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("Everything", ["All"])), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("Pinned", ["Flagged"])), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("Urgent", ["Important"])), true);
+	});
+
+	it("falls back to the well-known path when the server advertises nothing", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("[Gmail]/All Mail")), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("[gmail]/starred")), true);
+	});
+
+	it("matches the whole path, so a folder of the user's own is real mail", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("Starred ideas")), false);
+		assert.equal(isVirtualCopyMailbox(mailbox("[Gmail]/All Mail/2024")), false);
+	});
+
+	it("reads an ordinary folder as the place mail lives", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("INBOX")), false);
+		assert.equal(isVirtualCopyMailbox(mailbox("Rubbish", ["Junk"])), false);
+	});
+});

package/src/virtual-copy.ts

@@ -0,0 +1,33 @@
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import type { MailboxItem } from "./types.js";
+
+/**
+ * Special-use folders that hold a second copy of mail already reachable through
+ * the folder it actually lives in — Gmail's All Mail, Starred and Important.
+ */
+const VIRTUAL_COPY_SPECIAL_USE: readonly string[] = [
+	MailboxSpecialUse.All,
+	MailboxSpecialUse.Flagged,
+	MailboxSpecialUse.Important,
+];
+
+/**
+ * Well-known Gmail virtual paths, for servers that do not advertise the
+ * special-use attribute. Whole path, never a prefix — a user's own
+ * `Starred ideas` folder is real mail.
+ */
+const VIRTUAL_COPY_FULL_PATHS: readonly string[] = [
+	"[gmail]/all mail",
+	"[gmail]/starred",
+	"[gmail]/important",
+];
+
+/**
+ * Whether this folder holds mail that also lives in a real folder. Such a
+ * folder is a view, not a filing location: seeing a message in it says nothing
+ * about where the message was filed, so it neither picks which duplicate a
+ * listing drops nor decides where a message lives.
+ */
+export const isVirtualCopyMailbox = (mailbox: MailboxItem): boolean =>
+	mailbox.specialUse?.some((use) => VIRTUAL_COPY_SPECIAL_USE.includes(use)) ===
+		true || VIRTUAL_COPY_FULL_PATHS.includes(mailbox.fullPath.toLowerCase());