@rapidmx/activesync-plugin 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/types/EasCollectionSync.d.ts

@@ -0,0 +1,96 @@
+import type { RecoverableBaseEntity, RepoUtils } from "@rapidrest/service-core";
+import { FolderType } from "@rapidmx/restapi";
+import { type ChangeCursor } from "./EasSyncKeyUtils.js";
+import type { EasCollectionRound, EasCollectionState } from "./models/EasCollectionState.js";
+/** How far behind each cursor a round re-reads the stream for rows committed out of order by another replica. */
+export declare const DEFAULT_OVERLAP_MS = 5000;
+/** Most rows one overlap re-read returns, and most entries `recent` keeps. */
+export declare const DEFAULT_OVERLAP_LIMIT = 1000;
+/** The in-memory, mutable form of an `EasCollectionState` for one `Sync`/`GetItemEstimate` round. */
+export interface CollectionWorkingState {
+    generation: number;
+    cursor: ChangeCursor;
+    moveCursor: ChangeCursor;
+    serverIds: Set<string>;
+    echoes: Map<string, string>;
+    /** Rows the folder stream processed within the overlap window (see `EasCollectionState.recent`). `undefined` for a
+     * row written before overlap tracking existed - the rows currently in the window are then taken as reported. */
+    recent?: Map<string, string>;
+    /** See `EasCollectionState.reconcileCursor`. */
+    reconcileCursor: string;
+    /** `undefined` when the collection was started without a `FilterType`. */
+    filterType?: string;
+}
+/** One server-side change to report to the device. */
+export type CollectionCommand<T> = {
+    kind: "Add" | "Change";
+    item: T;
+} | {
+    kind: "Delete";
+    uid: string;
+};
+/** Loads the working state for the round a client's current `SyncKey` (`state.syncKey`) continues. `held` is the
+ * collection's held set (see `EasCollectionStore.loadHeldSet`); defaults to the inline `serverIds`. */
+export declare function workingStateFromRow(state: EasCollectionState, held?: Set<string>): CollectionWorkingState;
+/** Rebuilds the working state as it stood before the most recent round, for a client retrying `round.syncKey`. */
+export declare function workingStateFromRound(state: EasCollectionState, round: EasCollectionRound, held?: Set<string>): CollectionWorkingState;
+/** Deep-copies a working state so a dry run (`GetItemEstimate`) can't disturb the original. */
+export declare function cloneWorkingState(state: CollectionWorkingState): CollectionWorkingState;
+/** Records the round that turned `base` into `result` (see `EasCollectionRound`). */
+export declare function roundRecord(syncKey: string, base: CollectionWorkingState, result: CollectionWorkingState, clientIds: Map<string, string>): EasCollectionRound;
+export interface EnumerateCollectionOptions<T> {
+    repo: RepoUtils<T & RecoverableBaseEntity>;
+    folderUid: string;
+    /** The mailbox that owns the folder - items moved out of it stay within this mailbox. */
+    folderMailboxUid: string;
+    /** Most commands to report. */
+    windowSize: number;
+    /** Rows read from the out-of-folder stream per round. */
+    moveScanLimit: number;
+    /** `FilterType` window: an item the device doesn't hold yet is only added when this returns `true`. */
+    include?: (item: T) => boolean;
+    /** How far behind each cursor the streams are re-read (default `DEFAULT_OVERLAP_MS`; `0` disables). */
+    overlapMs?: number;
+    /** Most rows per overlap re-read and entries kept in `recent` (default `DEFAULT_OVERLAP_LIMIT`). */
+    overlapLimit?: number;
+    /** Held `ServerId`s checked against the store per caught-up round (`0`/absent disables the reconcile). */
+    reconcileLimit?: number;
+    now?: Date;
+}
+/**
+ * Computes one round of server-side changes for a `Sync` collection and advances `state` past them:
+ *
+ * - **Out-of-folder stream** (rows of the same mailbox in any other folder after `state.moveCursor`, live or
+ * deleted): an item the device holds has been moved out of this folder and is a `Delete`. Read before the folder
+ * rows are processed, so when an item moves between the two reads the out-of-folder row (the newer one) wins.
+ * Skipped while the device holds nothing; the cursor is then fast-forwarded to just before the round started
+ * instead, so the first real scan doesn't have to crawl the whole mailbox history.
+ * - **Folder stream** (rows of this folder after `state.cursor`): a live item the device holds is a `Change`, one
+ * it doesn't hold is an `Add` (subject to `include`), a soft-deleted item it holds is a `Delete`; a row whose
+ * `dateModified` still equals the device's own recorded write (`state.echoes`) is skipped.
+ * - **Overlap**: `dateModified` is stamped before a write commits, so with several replicas a row can become visible
+ * after a cursor has already passed its timestamp. Both streams therefore also re-read the last `overlapMs` behind
+ * their cursor. Out-of-folder rows are idempotent (an item is only deleted while held), so they're simply
+ * re-applied; folder rows are deduplicated against `state.recent` (uid -> the `dateModified` it was processed at),
+ * and only a row not recorded there at that timestamp - one that became visible late - is processed.
+ * - **Reconcile**: a hard-purged row leaves no trace in either stream. Once a round has caught up (nothing more
+ * available), up to `reconcileLimit` held ids after `state.reconcileCursor` are looked up in the folder, and each
+ * one that no longer exists there is a `Delete`; the cursor wraps around after the last held id.
+ *
+ * Both cursors only ever advance past rows actually processed - never to "now" - so nothing is skipped when the
+ * window fills up (`moreAvailable`).
+ */
+export declare function enumerateCollection<T extends RecoverableBaseEntity>(state: CollectionWorkingState, options: EnumerateCollectionOptions<T>): Promise<{
+    commands: CollectionCommand<T>[];
+    moreAvailable: boolean;
+}>;
+/** The `Class` a folder of `type` holds - for a `Sync`/`GetItemEstimate` request that omits `Class` for a collection
+ * with no remembered class. */
+export declare function classForFolderType(type: FolderType): string;
+/**
+ * Builds the `include` predicate for a collection's `FilterType`, or `undefined` for no filtering: `Email` keeps
+ * messages received within the window; `Calendar` keeps recurring events and events ending within it; `Tasks`
+ * keeps incomplete tasks for `8`. Values a class doesn't define (and no `FilterType` at all) are treated as "no
+ * filter".
+ */
+export declare function filterPredicate(collectionClass: string, filterType: string | undefined, now?: Date): ((item: any) => boolean) | undefined;

package/dist/types/EasCommandHandler.d.ts

@@ -1,5 +1,5 @@
 import type { JWTUser } from "@rapidrest/core";
-import type { HttpRequest, RepoUtils } from "@rapidrest/service-core";
+import type { HttpRequest, HttpResponse, RepoUtils } from "@rapidrest/service-core";
 import type { WbxmlElement } from "./codec/WbxmlElement.js";
 import type { DeviceSyncState } from "./models/DeviceSyncState.js";
 /**
@@ -18,9 +18,9 @@ export interface EasCommandContext {
     readonly deviceId: string;
     /** The client-supplied `?DeviceType=` query value (e.g. `iPhone`, `Android`). */
     readonly deviceType: string;
-    /** The client-supplied `?PolicyKey=` query value, if present - the provisioning policy key the device is
-     * currently operating under. Not yet validated against `deviceSyncState.policyKey` here (deferred to
-     * `ProvisionCommand`'s own implementation); handlers that care should compare it themselves for now. */
+    /** The policy key the device presented (`X-MS-PolicyKey` header, else the `?PolicyKey=` query value). For every
+     * command except `Provision`/`Settings`, `BaseEasRoute` has already refused the request unless this equals the
+     * stored `deviceSyncState.policyKey`. */
     readonly policyKey?: string;
     /** This device's persisted sync/provisioning state, looked up (or newly created) by `BaseEasRoute` before
      * dispatch. Handlers read/write cursor and provisioning fields on this directly. */
@@ -41,6 +41,9 @@ export interface EasCommandContext {
     /** The raw underlying HTTP request, for the rare handler that needs something this context doesn't
      * already surface (e.g. a header). */
     readonly req: HttpRequest;
+    /** The underlying HTTP response, when dispatched over HTTP - `PingCommand` registers `onFinish()` on it so a
+     * long-poll stops waiting as soon as the client disconnects. Optional so isolated handler tests can omit it. */
+    readonly res?: HttpResponse;
 }
 /**
  * One EAS protocol command (`Provision`, `FolderSync`, `Sync`, ...). `BaseEasRoute` builds one instance of

package/dist/types/EasSyncKeyUtils.d.ts

@@ -1,14 +1,38 @@
-import type { RecoverableBaseEntity, RepoUtils } from "@rapidrest/service-core";
+import { type RecoverableBaseEntity, type RepoUtils } from "@rapidrest/service-core";
 import type { DeviceSyncState } from "./models/DeviceSyncState.js";
+/**
+ * A position in a `(dateModified, uid)`-ordered change stream. `dateModified` alone is not a total order - several
+ * rows can share one timestamp (a bulk update inside one millisecond) - so a cursor that only remembered the
+ * timestamp would either re-send or skip the rows sharing the page boundary's timestamp. `uid` breaks the tie;
+ * `""` means "before every row at `date`".
+ */
+export interface ChangeCursor {
+    date: Date;
+    uid: string;
+}
+/** Whether `uid` can be listed in an `in(...)` query operand as itself: no comma (the operand separator), no parentheses
+ * or other punctuation, and not one of the literals the query parser substitutes (`me`, `null`). */
+export declare function isListableUid(uid: string): boolean;
+/** The cursor that precedes every row ever written. */
+export declare function epochCursor(): ChangeCursor;
+/** Orders two `(date, uid)` positions: negative when `a` sorts before `b`, positive when after, `0` when equal. */
+export declare function compareCursor(a: ChangeCursor, b: ChangeCursor): number;
+/** The cursor position of `row`. */
+export declare function cursorOf(row: {
+    dateModified: Date | string;
+    uid: string;
+}): ChangeCursor;
 /**
  * A parsed EAS `SyncKey`. The wire value is opaque to the client per spec, so this library encodes it as
- * `"<generation>:<watermarkIso>"` (e.g. `"3:2026-09-04T12:00:00.000Z"`) - a monotonic generation counter (bumped
- * once per successful sync round, satisfying the spec's "the server MUST return a different SyncKey every
- * time" requirement) paired with the `dateModified` watermark that generation was issued at.
+ * `"<generation>:<watermarkIso>"`, optionally followed by `"#<uid>"` when the cursor has a tie-breaking uid (e.g.
+ * `"3:2026-09-04T12:00:00.000Z#6f1c..."`) - a monotonic generation counter (bumped once per successful sync round,
+ * satisfying the spec's "the server MUST return a different SyncKey every time" requirement) paired with the
+ * `(dateModified, uid)` cursor that generation was issued at.
  */
 export interface SyncKey {
     generation: number;
     watermark: Date;
+    uid?: string;
 }
 /** Formats a `SyncKey` back into its wire string form. */
 export declare function formatSyncKey(key: SyncKey): string;
@@ -26,7 +50,7 @@ export type SyncKeyResolution = {
 };
 /**
  * Resolves an incoming client `SyncKey` string against the value this library itself previously issued and
- * stored (`storedValue`, e.g. `DeviceSyncState.folderSyncKeys[folderUid]`) — deliberately a plain string
+ * stored (`storedValue`, e.g. `DeviceSyncState.folderSyncKeys["$foldersync"]`) — deliberately a plain string
  * equality check, not a re-parse-and-compare of the client's value, so a client that echoes back anything
  * other than the exact opaque string it was handed is treated as `"invalid"` even if it happens to parse.
  *
@@ -40,50 +64,57 @@ export type SyncKeyResolution = {
 export declare function resolveSyncKey(clientValue: string | undefined, storedValue: string | undefined): SyncKeyResolution;
 /**
  * Applies `patch` to `deviceSyncState` and persists it - the one correct way any EAS command handler (or
- * `BaseEasRoute` itself) should ever write to a `DeviceSyncState`, replacing the inline
- * `deviceSyncStateRepo.update(...)` calls `ProvisionCommand`/`FolderSyncCommand`/`SyncCommand` used to each
- * repeat individually.
+ * `BaseEasRoute` itself) should ever write to a `DeviceSyncState`.
+ *
+ * `RepoUtils.update()` does **not** mutate the `existing` object passed to it - it only returns a freshly-fetched
+ * instance reflecting the write - so the returned row (including its bumped `version`) is copied back onto
+ * `deviceSyncState`, keeping a second write later in the same request from being built off a stale version.
+ *
+ * **Concurrent requests**: one device routinely has several requests in flight at once (a long-poll `Ping`
+ * alongside a `Sync`, or two `Sync`s for different folders), and the row's optimistic lock covers the whole row.
+ * Losing that race used to surface as a 409 *after* the command's side effects had already happened. Instead, a
+ * version conflict re-reads the row, re-applies the patch on top of the fresh copy and retries (bounded). Pass
+ * `patch` as a function when it derives from the row's current content (e.g. updating one entry of the
+ * `folderSyncKeys` map) so the retry merges into what the other request wrote rather than overwriting it.
+ */
+export declare function persistDeviceSyncState(deviceSyncState: DeviceSyncState, deviceSyncStateRepo: RepoUtils<any>, patch: Record<string, unknown> | ((current: DeviceSyncState) => Record<string, unknown>)): Promise<void>;
+/**
+ * Reads up to `limit` rows matching `criteria` that sort strictly after `cursor` in `(dateModified, uid)` order,
+ * live and soft-deleted rows merged into one stream. `more` is `true` when rows beyond the returned page exist.
  *
- * This exists because `RepoUtils.update()` does **not** mutate the `existing` object passed to it - confirmed
- * by reading its implementation directly - it only returns a freshly-fetched instance reflecting the write,
- * leaving the caller's in-memory copy (including its optimistic-concurrency `version`) stale. A single write
- * per request is harmless (nothing re-reads the stale copy), but a *second* write to the same `deviceSyncState`
- * later in the same request - e.g. `BaseEasRoute.dispatch()`'s own trailing `lastSyncAt` update, or a second
- * collection's SyncKey in a multi-collection `Sync` - would build its own patch's `version` off that stale
- * value. `RepoUtils.update()` filters its underlying write by exactly that `version`, so the write silently
- * matches zero rows instead of throwing - a silent no-op, not a visible error. Copying `update()`'s own
- * returned result back onto `deviceSyncState` (last line below) keeps every field, including `version`, current
- * for whatever writes this same request still has left to make.
+ * `RepoUtils.find()` excludes soft-deleted rows unless the query names `deleted` explicitly, so the two halves are
+ * separate queries (the second with a literal `deleted: true`), each over-fetched by one and merged. `limit`/`sort`
+ * are baked into the query object as well as the options - the SQL query builder only reads the former.
  */
-export declare function persistDeviceSyncState(deviceSyncState: DeviceSyncState, deviceSyncStateRepo: RepoUtils<any>, patch: Record<string, unknown>): Promise<void>;
-/** One page of enumerated changes for a `RecoverableBaseEntity` collection scoped by a single field (e.g.
- * `folderUid` for `Message`/`CalendarEvent`/.../`mailboxUid` for `Folder`), since the last sync at `watermark`. */
+export declare function scanAfter<T extends RecoverableBaseEntity>(repo: RepoUtils<T>, criteria: Record<string, unknown>, cursor: ChangeCursor, limit: number): Promise<{
+    rows: T[];
+    more: boolean;
+}>;
+/**
+ * Reads the rows matching `criteria` at or before `cursor` whose `dateModified` lies within `windowMs` of it - the
+ * part of the stream a cursor has already passed but where a row committed out of order (another replica stamped
+ * `dateModified` before this one read past it, but committed after) can still appear. At most `limit` rows, the
+ * newest ones, returned in ascending `(dateModified, uid)` order; live and soft-deleted rows merged as `scanAfter`
+ * does. Returns nothing for the epoch cursor (nothing has been passed yet).
+ */
+export declare function scanOverlap<T extends RecoverableBaseEntity>(repo: RepoUtils<T>, criteria: Record<string, unknown>, cursor: ChangeCursor, windowMs: number, limit: number): Promise<T[]>;
+/** One page of enumerated changes for a `RecoverableBaseEntity` collection scoped by a single field. */
 export interface ChangeSet<T extends RecoverableBaseEntity> {
     adds: T[];
     changes: T[];
     deletes: T[];
-    /** The new watermark to persist as this generation's cursor - the latest `dateModified` actually included
-     * in this page, never simply "now" (which would silently skip any row modified after this page was read
-     * but before the caller finishes processing it). Equal to the input `watermark` when nothing changed. */
-    newWatermark: Date;
-    /** `true` when more changed rows exist beyond `windowSize` - the caller should set the response's
-     * `MoreAvailable` flag so the client immediately re-syncs for the rest, rather than waiting a full poll
-     * interval. */
+    /** The cursor to persist for the next round - the last row actually included in this page, never simply
+     * "now" (which would silently skip any row modified after this page was read). Equal to the input cursor when
+     * nothing changed. */
+    cursor: ChangeCursor;
+    /** `true` when more changed rows exist beyond `windowSize`. */
     moreAvailable: boolean;
 }
 /**
- * Enumerates `Add`/`Change`/`Delete`s for one scoped collection since `watermark`, for `FolderSyncCommand` and
- * (eventually) `SyncCommand`'s shared cursor mechanism. Requires `T` to be `RecoverableBaseEntity` (soft
- * delete) — see `RecoverableRepoUtils`'s own doc comment for why a plain hard-deleted entity can't support
- * this at all (nothing left to enumerate once a row is actually gone).
- *
- * `RepoUtils.find()` does **not** support an `includeDeleted` option - confirmed by reading its source: unlike
- * `count()`/`findOne()`, it never strips `ModelUtils.buildSearchQuery()`'s default `deleted: false` exclusion
- * back out. Rather than the (harmless-looking but silently no-op) `includeDeleted: true` this function used to
- * pass, deleted rows are fetched via a **second** `find()` call with an explicit, literal `deleted: true` in
- * the query object itself - `buildSearchQuery()`'s exclusion only applies when the caller's query has no
- * `"deleted"` key at all, so supplying one directly (rather than relying on an option `find()` doesn't honor)
- * reliably selects exactly the soft-deleted rows instead. The two result sets are then merged and re-windowed
- * together so `windowSize`/`MoreAvailable` still describe the combined stream, not each half independently.
+ * Enumerates `Add`/`Change`/`Delete`s for one scoped collection after `cursor` - used by `FolderSyncCommand`
+ * (scoped by `mailboxUid` over `Folder`). `Sync` item collections use `EasCollectionSync` instead, which tracks the
+ * exact set of items each device holds; the folder hierarchy is small and always fully re-sent on `SyncKey 0`, so
+ * a creation-time rule is enough here: a row created after the cursor can't be on the device yet, so a live one is
+ * an `Add` (never an `Update` for a `ServerId` the device has never seen) and a deleted one is not reported at all.
  */
-export declare function computeChanges<T extends RecoverableBaseEntity>(repo: RepoUtils<T>, scopeField: string, scopeUid: string, watermark: Date, windowSize: number): Promise<ChangeSet<T>>;
+export declare function computeChanges<T extends RecoverableBaseEntity>(repo: RepoUtils<T>, scopeField: string, scopeUid: string, cursor: ChangeCursor, windowSize: number): Promise<ChangeSet<T>>;

package/dist/types/MessageMoveRules.d.ts

@@ -0,0 +1,45 @@
+import { FolderType, type Message } from "@rapidmx/restapi";
+/** Whether a send of `message` is in flight: its `scheduledSendLeaseExpiresAt` (set when `send()` or `ScheduledSendJob`
+ * claims it for relay) is still in the future. restapi refuses to move or delete such a message (409,
+ * `assertNotInFlight()`): a moved or soft-deleted message could miss its relay marker and be sent a second time. */
+export declare function hasLiveSendLease(message: Message): boolean;
+/** The outcome of `planMessageMove()`: refused (with why), or allowed with extra fields the move's update must carry. */
+export type MessageMovePlan = {
+    allowed: false;
+    reason: "destination" | "sent" | "inFlight";
+} | {
+    allowed: true;
+    patch: Record<string, unknown>;
+};
+/**
+ * Decides whether an ActiveSync client may move `message` from a folder of `sourceType` into one of `destinationType`,
+ * matching restapi's own REST rules for a non-trusted caller (`BaseMessageRoute.prepareScheduledSendUpdate()`), plus
+ * one of this plugin's own:
+ * - **Into Outbox** is always refused (`"destination"`): only a send puts a message there, after checking its sender -
+ * `ScheduledSendJob` relays whatever it finds in Outbox.
+ * - **Into Drafts** is refused unless the message already is in Drafts, or is taken back out of Outbox to cancel its send
+ * (`"destination"`): a draft's body can be rewritten over ActiveSync (`EmailSyncAdapter.fromApplicationData`), so moving a
+ * received, sent or held message into Drafts, editing it and moving it back would forge its content under its original
+ * sender and dates. Out of Outbox only for what a send queued: a delivered message (`scanResultUid`) a mail filter rule
+ * filed into Outbox is refused, as restapi refuses it with 403.
+ * - **A send in flight** (`hasLiveSendLease()` - claimed for relay by `send()` or `ScheduledSendJob`) can't be moved
+ * anywhere (`"inFlight"`), as restapi's `assertNotInFlight()` refuses with 409: moving it back to Drafts would let it be
+ * sent again while the first relay still runs. Once the lease has lapsed, it can move. Deletes check the same.
+ * - **Out of Outbox** cancels the scheduled send: the plan clears `scheduledSendTime`, the job's retry state and its
+ * lease (`scheduledSendAttempts`/`scheduledSendError`/`scheduledSendLeaseExpiresAt`, only where the stored row has them -
+ * the SQL model of restapi 0.9.0 has no such columns). A message the job already relayed (`scheduledSendRelayedAt`, whose
+ * filing is still pending) is refused (`"sent"`).
+ */
+export declare function planMessageMove(message: Message, sourceType: FolderType | undefined, destinationType: FolderType | undefined): MessageMovePlan;
+/**
+ * Whether `message`, filed in a folder of `folderType`, is a genuine draft whose content an ActiveSync client may
+ * rewrite: it lives in Drafts and carries none of the marks a delivery or a send leaves (`SENT_OR_DELIVERED_MARKERS`).
+ * Moves into Drafts are refused over ActiveSync (`planMessageMove()`), but a message can still reach Drafts other ways
+ * (restapi's REST moves out of Outbox, a mail filter, an import), so a delivered or sent message found there is not
+ * treated as a draft.
+ *
+ * `sentDate` can't be the marker: every message has one, and a draft gets it when it is created. **Residual**: a
+ * plain-text, unencrypted sent copy with no receipt request carries none of these marks; restapi keeps it out of
+ * Drafts (non-trusted moves into Drafts only from Drafts or Outbox, and only a send from Drafts queues into Outbox).
+ */
+export declare function isGenuineDraft(message: Message, folderType: FolderType | undefined): boolean;

package/dist/types/MimeHeaderUtils.d.ts

@@ -0,0 +1,73 @@
+/** The raw (unfolded, trimmed) values of a message's top-level `From` and `Sender` headers. */
+export interface OriginatorHeaders {
+    from: string[];
+    sender: string[];
+}
+/**
+ * Every top-level `From` and `Sender` header value of `raw`, found exactly the way `checkOriginatorHeaders()` finds
+ * them: header names case-insensitive, whitespace before the colon allowed (the obsolete `From :` form), folded
+ * values unfolded, and a bare CR treated as a line break.
+ */
+export declare function extractOriginatorHeaders(raw: Buffer): OriginatorHeaders;
+/**
+ * Whether any display name, group name or comment in one `From`/`Sender` header value contains an address-like `@`
+ * (RFC 2047 encoded words decoded, look-alike `@` characters included): `"ceo@example.com" <me@example.com>` shows
+ * the reader an address the sender doesn't own, though its real address is fine.
+ */
+export declare function hasAddressLikeDisplayName(value: string): boolean;
+/** Options for `checkOriginatorHeaders()`. */
+export interface OriginatorHeaderCheckOptions {
+    /**
+     * Also refuse a `From`/`Sender` whose display name, group name or comment contains an address
+     * (`hasAddressLikeDisplayName()`). Every path that sends a user-composed message as one of a mailbox's addresses
+     * should set it - the REST send path and `ScheduledSendJob` do, and so should protocol plugins (ActiveSync, MAPI).
+     */
+    rejectAddressLikeDisplayNames?: boolean;
+}
+/**
+ * Refuses a raw RFC 5322 message whose originator headers name anyone other than an allowed sender. Every `From`
+ * and `Sender` header in the top-level header block is checked - header names case-insensitively (including the
+ * obsolete `From :` form with whitespace before the colon), folded values unfolded, and a bare CR treated as a line
+ * break too, so a header can't be hidden from this scan behind a line ending another parser would honor. Returns a
+ * refusal reason, or `undefined` if the message passes. Fails closed on:
+ * - no `From` header, more than one `From` header, or more than one `Sender` header;
+ * - a `From`/`Sender` value that yields no address at all (e.g. only an empty group);
+ * - any parsed entry without an address (a malformed list, e.g. an unquoted display name containing a comma);
+ * - any parsed address - group members included - that `isAllowed` rejects;
+ * - any addr-spec-looking token outside quoted strings/comments that `isAllowed` rejects - covers the tolerant
+ * parser recovering `<me@example.com> <other@example.com>` as one mailbox with the second as its "display name";
+ * - with `options.rejectAddressLikeDisplayNames`, any display name, group name or comment containing an address.
+ *
+ * Quoted display names and RFC 2047 encoded words are never treated as addresses. `isAllowed` receives each address
+ * exactly as parsed; normalize (e.g. lowercase) inside it.
+ */
+export declare function checkOriginatorHeaders(raw: Buffer, isAllowed: (address: string) => boolean, options?: OriginatorHeaderCheckOptions): string | undefined;
+/** Whether `address` is exactly one plain address (`local@domain`, nothing around it), at most 320 characters - safe to
+ * hand to a composer as one recipient, e.g. a meeting attendee or organizer. */
+export declare function isPlainAddress(address: unknown): address is string;
+/**
+ * `name` as a display name that's safe to put in front of one of our own addresses in a `From` (or an iCalendar `CN`)
+ * this server composes: trimmed, or `undefined` - so the caller omits the name - when it isn't a string, is blank,
+ * contains a line break or other control character, or shows an address-like `@` (look-alikes and RFC 2047 encoded
+ * words included, the same rule as `hasAddressLikeDisplayName()`). A display name like `ceo@example.com` in front of a
+ * real address shows the reader an address the sender doesn't own.
+ */
+export declare function safeDisplayName(name: unknown): string | undefined;
+/**
+ * The ActiveSync compose sender check: restapi's `checkOriginatorHeaders()` with `rejectAddressLikeDisplayNames`, plus
+ * two plugin-side refusals restapi doesn't make. Returns a refusal reason, or `undefined` if the message passes.
+ * - **Relaxed for the sender's own address**: a display name or comment that shows an address is still accepted when
+ * every address it shows is one of the mailbox's own (`"me@example.com" <me@example.com>`) - see
+ * `displayTextShowsOnlyAllowedAddresses()`. Any other address, or a look-alike `@`, is refused as restapi refuses it.
+ * - **A `From`/`Sender` field restapi's lexer can't see** - the tolerant `lexHeaderFields()` counts more of them (e.g.
+ * a leading space on the first line, or a form feed before the colon, both of which mailsplit still reads as `From`).
+ * - **An empty group** (`victims:;, me@example.com`) - it contributes no address, only text of the sender's choice
+ * shown beside the real address, and RFC 5322 doesn't allow groups in `From`/`Sender` at all.
+ */
+export declare function checkComposedOriginators(raw: Buffer, isAllowed: (address: string) => boolean): string | undefined;
+/**
+ * Returns a copy of `raw` with every top-level header field named `name` (case-insensitive, whitespace before the
+ * colon allowed, including its folded continuation lines) removed, found with `lexHeaderFields()` - so a field
+ * written `Bcc :` is removed too. Only the header block is touched; every other byte is copied verbatim.
+ */
+export declare function stripHeader(raw: Buffer, name: string): Buffer;

package/dist/types/RegexPatternUtils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mirrors `@rapidrest/service-core`'s private `ModelUtils.MAX_PATTERN_LENGTH`: a `regex(...)` query operand
+ * longer than this is rejected as a potential ReDoS pattern with `INVALID_REQUEST`. The check runs against the
+ * operand AFTER escaping, so a raw client term well under the limit can still exceed it once each regex
+ * metacharacter doubles in length.
+ */
+export declare const MAX_REGEX_PATTERN_LENGTH = 100;
+/**
+ * Escapes `value` for a literal-substring `regex(...)` match, truncating the raw term (never mid-escape or
+ * mid-code-point) so the escaped result always fits `MAX_REGEX_PATTERN_LENGTH`. Matching on a prefix of an
+ * over-long search term still yields a superset of the full term's matches, which is a far better outcome than
+ * the whole command failing.
+ */
+export declare function boundedEscapedPattern(value: string, maxLength?: number): string;

package/dist/types/RestapiCompat.d.ts

@@ -0,0 +1,24 @@
+import { type RepoUtils } from "@rapidrest/service-core";
+/**
+ * Inline copies of small restapi helpers that the `@rapidmx/restapi` 0.9.0 this plugin builds against doesn't export
+ * yet. Each matches restapi's source exactly - replace the copy with restapi's export once the dependency is bumped.
+ */
+/** The longest value `boundIndexedValue()` stores verbatim (restapi `util/ConversationUtils.ts`). */
+export declare const MAX_INDEXED_VALUE_LENGTH: number;
+/**
+ * Returns `value` unchanged when it's at most `MAX_INDEXED_VALUE_LENGTH` characters, otherwise
+ * `sha256:<64 hex digits>` of its UTF-8 bytes - how restapi stores indexed identifiers from untrusted mail/calendar
+ * data (`Message.messageId`, `Message.conversationId`, `CalendarEvent.icalUid`). Idempotent, so a lookup value passed
+ * through it matches the stored one. Copy of restapi's `boundIndexedValue()` (`util/ConversationUtils.ts`).
+ */
+export declare function boundIndexedValue<T extends string | null | undefined>(value: T): T;
+/**
+ * `row` as an instance of `repo`'s model class, for use as the `existing` argument of `RepoUtils.update()`.
+ *
+ * `update()` only enforces its optimistic lock (a version mismatch -> 409, a version-filtered write, and the
+ * `version`/`dateModified` bump) when `existing instanceof BaseEntity`. The Mongo backend's `find()`/`findOne()` return
+ * plain documents, so passing one straight through silently turns a version-checked write into an unconditional
+ * overwrite that other devices' change streams never see. SQL reads already return entity instances, which pass
+ * through as-is. Copy of restapi's `asEntity()` (`util/EntityUtils.ts`).
+ */
+export declare function asEntity<T>(repo: RepoUtils<any>, row: T): T;

package/dist/types/adapters/CalendarSyncAdapter.d.ts

@@ -1,6 +1,10 @@
 import { type WbxmlElement } from "../codec/WbxmlElement.js";
 import type { EasCollectionSyncAdapter } from "./EasCollectionSyncAdapter.js";
-import { type CalendarEvent } from "@rapidmx/restapi";
+import { type CalendarEvent, type Mailbox } from "@rapidmx/restapi";
+/** Most attendees one event may carry from a device - restapi's `MAX_EVENT_ATTENDEES` (REST calendar writes) and
+ * `MeetingSchedulingJob`'s default `max_attendees`, and the MAPI plugin's cap. The job mails every attendee, so an
+ * unbounded list would make one Sync item a bulk mailing. */
+export declare const MAX_CALENDAR_ATTENDEES = 500;
 /**
  * Maps `CalendarEvent` to/from the EAS `Sync` `Calendar` collection class (MS-ASCAL).
  *
@@ -13,9 +17,8 @@ import { type CalendarEvent } from "@rapidmx/restapi";
  * its own to source a real value from.
  * - Recurrence patterns keyed by an ordinal weekday (MS-ASCAL `Type` 3/6, e.g. "the 2nd Tuesday of the month")
  * are not emitted - see `RECURRENCE_TYPE_CODES`'s own doc comment.
- * - Recurrence exceptions (individually modified/cancelled occurrences of a recurring series) are not synced -
- * deferred, matching this library's "pragmatic subset" precedent elsewhere (e.g. `FolderSyncCommand`'s SyncKey
- * replay-protection gap).
+ * - Recurrence exceptions (individually modified/cancelled occurrences of a recurring series) are not synced to the
+ * device; a device `Change` of the recurrence keeps the series' existing exceptions rather than wiping them.
  *
  * @author Jean-Philippe Steinmetz
  */
@@ -24,23 +27,40 @@ export declare class CalendarSyncAdapter implements EasCollectionSyncAdapter<Cal
     toApplicationData(event: CalendarEvent): WbxmlElement;
     private recurrenceElement;
     /**
-     * Reverse of `toApplicationData`. `timezone`/`status`/`sequence`/`icalUid` have no wire representation at
-     * all (see this class's own "pragmatic subset" doc comment for `timezone`; the other three are purely
-     * server-managed identifiers/state a client was never sent in the first place) and are never included in
-     * the returned partial - `newEntityDefaults()` below supplies `icalUid`/`sequence` for a brand new event
-     * (`status`/`timezone` are left at the model's own constructor defaults), and `applyChange` leaves all four
-     * untouched by construction (merging onto `existing`).
+     * Reverse of `toApplicationData`. `timezone`/`status`/`icalUid` have no wire representation at all and are
+     * never included in the returned partial - `newEntityDefaults()` supplies `icalUid`/`sequence` for a brand new
+     * event, and a `Change` merges onto `existing`.
      *
-     * `OrganizerEmail` is required for a new event (there is nowhere else to default it from - this adapter
-     * has no mailbox context of its own) - a real calendar client always sends it regardless, since it already
-     * knows its own account's address. Omitting it on an `Add` throws, which `SyncCommand.applyAdd` turns into
-     * Status `6` ("client has sent a malformed or invalid item"), the spec's own designated code for exactly
-     * this case.
+     * **Organizer** (`mailbox` = the caller's own mailbox, supplied by `SyncCommand`): a device can only create an
+     * event organized by itself - on an `Add`, an `OrganizerEmail` that isn't one of the mailbox's own addresses (or
+     * a missing one) is replaced by the mailbox's primary address, since the organizer is who iTIP invitations are
+     * sent as. The organizer's display name is always the mailbox's own (`MimeHeaderUtils.safeDisplayName()`: omitted
+     * when it looks like an address or has a line break) - never the device's `OrganizerName`, which invitations would
+     * otherwise show as the sender's name (e.g. `payroll@corp.com`). On a `Change` the organizer is never reassigned (an
+     * attendee's copy of someone else's meeting keeps its real organizer). Without a `mailbox` (direct use),
+     * `OrganizerEmail` must be one plain address (`isPlainAddress()`) and `OrganizerName` is kept only when it passes the
+     * same rule.
      *
-     * `Attendees`/`Recurrence` are ghosted as a whole element, like `ContactsSyncAdapter`'s arrays: present at
-     * all -> rebuilt entirely from what's there; absent -> left untouched on a `Change`.
+     * **Attendees** match restapi's REST calendar validation (`BaseCalendarEventRoute.assertParticipants()`, 400 there):
+     * each `Email` must be one plain address (`MimeHeaderUtils.isPlainAddress()`, so not a list like `a@x, b@y`), and at
+     * most `MAX_CALENDAR_ATTENDEES` are accepted - refused, never truncated. As in restapi, on a `Change` only a changed
+     * list is checked: a device re-sending exactly the addresses the event already has (e.g. an attendee copy filed with
+     * a larger or odder list) still saves. A `Name` is kept only when `safeDisplayName()` allows it. A refusal throws,
+     * which `SyncCommand` reports as Status 6.
+     *
+     * **Change merging** (`existing` given): `Attendees`/`Recurrence` are ghosted as a whole element - present ->
+     * rebuilt from what's there, absent -> untouched - but a rebuilt attendee the event already had keeps the fields
+     * the device didn't send (`AttendeeStatus`/`AttendeeType`/`Name`, and `isOrganizer`), and a rebuilt recurrence
+     * keeps the series' existing exceptions (cancelled occurrences have no wire representation here). A change to the
+     * time, location, attendees or recurrence bumps `sequence`, as `BaseCalendarEventRoute.update` does, so updated
+     * invitations go out - but only on the organizer's copy: when `mailbox` (the item's owner on a `Change`) isn't
+     * the organizer, `sequence` is left alone and `inviteSequenceSent` is kept equal to it, so an attendee editing
+     * their own copy never makes `MeetingSchedulingJob` send invitations as the organizer.
      */
-    fromApplicationData(el: WbxmlElement): Partial<CalendarEvent>;
+    fromApplicationData(el: WbxmlElement, existing?: CalendarEvent, mailbox?: Mailbox): Partial<CalendarEvent>;
+    /** Stamps `cancelNoticeSentAt` on an attendee's copy of a meeting before it is deleted, so the deletion is never
+     * taken as the organizer cancelling the meeting (see `EasCollectionSyncAdapter.beforeDelete`). */
+    beforeDelete(existing: CalendarEvent, mailbox: Mailbox): Partial<CalendarEvent> | undefined;
     /** `icalUid`/`sequence` have no wire representation on `Add` (see `fromApplicationData`'s own doc comment)
      * - without this, every Sync-created event would fall back to `CalendarEventMongo`/`CalendarEventSQL`'s own
      * constructor default of `icalUid: ""`, violating RFC 5545's uniqueness expectation for `UID`. Mirrors
@@ -50,3 +70,12 @@ export declare class CalendarSyncAdapter implements EasCollectionSyncAdapter<Cal
     private attendeeFromElement;
     private recurrenceRuleFromElement;
 }
+/** The calendar day (1-31) and month (1-12) `date` falls on in IANA `timezone`, falling back to UTC for a zone
+ * `Intl` doesn't recognize. */
+export declare function localDayAndMonth(date: Date, timezone: string): {
+    day: number;
+    month: number;
+};
+/** `true` when `event`'s organizer is one of `mailbox`'s own addresses - the organizer's copy of a meeting, as opposed
+ * to an attendee's copy of someone else's. An event without an organizer address counts as the mailbox's own. */
+export declare function isOrganizedBy(event: CalendarEvent, mailbox: Mailbox): boolean;

package/dist/types/adapters/EasCollectionSyncAdapter.d.ts

@@ -23,6 +23,10 @@ export interface EasCollectionSyncAdapter<T extends RecoverableBaseEntity> {
      * rendering `Categories`; every other adapter today returns a plain `WbxmlElement`, which callers `await`
      * through unchanged (the same optional-async shape `fromApplicationData` already established below). */
     toApplicationData(item: T): WbxmlElement | Promise<WbxmlElement>;
+    /** Optional bulk form of `toApplicationData`, returning one element per item in the same order. Implemented
+     * where rendering needs a lookup that is far cheaper done once for a whole page (`EmailSyncAdapter`'s
+     * `Label` resolution); callers fall back to per-item `toApplicationData` when absent. */
+    toApplicationDataBatch?(items: T[]): Promise<WbxmlElement[]>;
     /**
      * Parses one client-originated `Add`/`Change` command's `<ApplicationData>` element (`el`) into a partial
      * entity update. Only fields actually present in `el` are included in the result - an omitted field means
@@ -37,9 +41,21 @@ export interface EasCollectionSyncAdapter<T extends RecoverableBaseEntity> {
      * @param el The command's `<ApplicationData>` element.
      * @param existing The item being changed, for a `Change` command; `undefined` for `Add`. Adapters that
      * need to know the item's current field values to correctly interpret a partial update - `EmailSyncAdapter`
-     * uses this to reuse an existing Draft's `bodyBlobKey` on `Change` rather than minting a new one.
+     * uses this to refuse a `Body` change on anything but a Draft, and to carry over unchanged MIME headers.
+     * @param mailbox For an `Add`, the caller's own mailbox - `CalendarSyncAdapter` uses it so a device can never
+     * make someone else the organizer of an event it creates. For a `Change`, the mailbox that owns the item (the
+     * synced folder's mailbox) - `CalendarSyncAdapter` uses it to tell the organizer's copy of a meeting from an
+     * attendee's copy.
      */
-    fromApplicationData?(el: WbxmlElement, existing?: T): Partial<T> | Promise<Partial<T>>;
+    fromApplicationData?(el: WbxmlElement, existing?: T, mailbox?: Mailbox): Partial<T> | Promise<Partial<T>>;
+    /**
+     * Fields to stamp on an item just before a client-originated `Delete` removes it, or `undefined` for none.
+     * `CalendarSyncAdapter` marks an attendee's copy of a meeting as already cancelled, so deleting your own copy
+     * never makes restapi's `MeetingSchedulingJob` mail a cancellation to everyone on the organizer's behalf.
+     *
+     * @param mailbox The mailbox that owns the item.
+     */
+    beforeDelete?(existing: T, mailbox: Mailbox): Partial<T> | undefined;
     /**
      * Supplies default field values for a brand-new entity created via a client-originated `Add`, applied
      * *before* `fromApplicationData`'s own partial is merged on top (so anything the client actually sent