@rapidmx/mapi-plugin 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/types/codec/PropertyValue.d.ts

@@ -50,6 +50,16 @@ export type PropertyValueData = number | bigint | boolean | string | Buffer | Da
  * the low half. On the wire (little-endian), that means `PropertyType` is read/written first.
  */
 export declare function readPropertyTag(reader: BufferReader): PropertyTag;
+/** The most `PropertyTag`s accepted in one request's tag array (`RopSetColumns`, `RopGetPropertiesSpecific`,
+ * the FastTransfer source ROPs, NSPI `Columns`). Every tag multiplies the per-row resolution work and, for
+ * `RopSetColumns`, the stored session state; a real client asks for far fewer. */
+export declare const MAX_PROPERTY_TAG_COUNT = 256;
+/**
+ * Reads `count` consecutive `PropertyTag`s. When `count` exceeds `MAX_PROPERTY_TAG_COUNT`, the tags' bytes are
+ * skipped (still bounds-checked, so a count larger than the buffer throws) and `undefined` is returned, leaving
+ * the reader positioned after the array so the caller can send an error response and keep parsing later ROPs.
+ */
+export declare function readPropertyTagArray(reader: BufferReader, count: number): PropertyTag[] | undefined;
 export declare function writePropertyTag(writer: BufferWriter, tag: PropertyTag): void;
 /** `TypedPropertyValue` structure (`[MS-OXCDATA]` §2.11.4): `PropertyType` (2 bytes) followed by the value
  * itself, encoded per `readPropertyValue`/`writePropertyValue` below. */

package/dist/types/codec/RopBuffer.d.ts

@@ -21,5 +21,12 @@ export interface RopBuffer {
      * ROPs within `ropsList` reference them by index. */
     handleTable: number[];
 }
+/** The largest `ServerObjectHandleTable` accepted. Every ROP addresses a handle by a one-byte index, so a table
+ * with more than 255 entries can't be referenced anyway; a larger one is only a way to make the server allocate
+ * and echo back an oversized array. */
+export declare const MAX_HANDLE_TABLE_ENTRIES = 255;
 export declare function encodeRopBuffer(buf: RopBuffer): Buffer;
+/** Throws a `RangeError` for a malformed buffer: a `RopSize` smaller than its own field or larger than the
+ * buffer, a handle table that isn't a whole number of 4-byte entries, or one with more than
+ * `MAX_HANDLE_TABLE_ENTRIES` entries. */
 export declare function decodeRopBuffer(buffer: Buffer): RopBuffer;

package/dist/types/mongo/MapiEmsmdbRouteMongo.d.ts

@@ -15,5 +15,6 @@ export declare class MapiEmsmdbRouteMongo extends BaseMapiEmsmdbRoute<MailboxMon
     protected contactClass: any;
     protected taskClass: any;
     protected labelClass: any;
+    protected auditLogClass: any;
     protected ropHandlerClasses: any[];
 }

package/dist/types/nspi/NspiGetMatchesHandler.d.ts

@@ -1,4 +1,6 @@
 import type { HttpRequest, HttpResponse, RepoUtils } from "@rapidrest/service-core";
+/** The most rows one `GetMatches` lookup asks the repo for per query - `RepoUtils.find()`'s own page cap. */
+export declare const MAX_MATCH_ROWS = 1000;
 /**
  * `GetMatches` request type (`[MS-OXCMAPIHTTP]` §2.2.5.5, backed by `[MS-OXNSPI]`'s own `NspiGetMatches`
  * method): searches the GAL (this library's `Contact` records, the same source of truth EAS's own `Search`

package/dist/types/rop/AddressList.d.ts

@@ -0,0 +1,48 @@
+import type { RopContext } from "./RopHandler.js";
+/** Splits a `PidTagDisplayTo`/`Cc`/`Bcc`-style string on the semicolons Outlook separates recipients with,
+ * trimming and dropping empty entries. Commas are not separators: a resolved recipient's display name commonly
+ * contains one (`Doe, Jane <jane@example.com>`). */
+export declare function splitAddressList(value: string | undefined): string[];
+/** `true` for a plain SMTP address (see `PLAIN_EMAIL_ADDRESS`) no longer than RFC 5321's 254 characters. These
+ * strings reach MIME headers, the SMTP envelope and iCalendar `mailto:` lines, where a CR/LF would inject content. */
+export declare function isPlainEmailAddress(value: string): boolean;
+/** One entry of a display string: an address with an optional display name, a display name alone (`address`
+ * undefined, still to be resolved), or something that can't be used (`invalid`). */
+export interface RecipientEntry {
+    name: string;
+    address?: string;
+    invalid?: boolean;
+}
+/**
+ * Parses one `;`-separated entry with nodemailer's `addressparser`: `jane@example.com`, `Jane <jane@example.com>`,
+ * `"Doe, Jane" <jane@example.com>` or a bare display name `Jane Doe`. An entry holding several addresses yields one
+ * recipient each. Any address that isn't a plain SMTP address marks the entry invalid.
+ */
+export declare function parseRecipientEntry(entry: string): RecipientEntry[];
+/** Every entry of a `PidTagDisplayTo`/`Cc`/`Bcc`-style string - see `parseRecipientEntry`. */
+export declare function parseRecipientList(value: string | undefined): RecipientEntry[];
+/** The plain addresses in a `PidTagDisplayTo`/`Cc`/`Bcc`-style string, including those written as
+ * `Name <address>`, skipping display names without an address and anything invalid. */
+export declare function parseAddressList(value: string | undefined): string[];
+/** A recipient ready to send to. */
+export interface ResolvedRecipient {
+    name: string;
+    address: string;
+}
+/** The outcome of `resolveRecipientList`: the usable recipients, and the entries that were display names with no
+ * single matching contact (`unresolved`) or not usable at all (`invalid`). */
+export interface RecipientResolution {
+    recipients: ResolvedRecipient[];
+    unresolved: string[];
+    invalid: string[];
+}
+/** The most recipients (To, Cc and Bcc together) one submitted message or meeting may have - the same limit
+ * `@rapidmx/activesync`'s `ComposeMailCommand` enforces (`MAX_COMPOSE_RECIPIENTS`). */
+export declare const MAX_RECIPIENTS_PER_MESSAGE = 500;
+/**
+ * Resolves a display string into addresses. An entry carrying an address is used as is; a bare display name (Outlook
+ * writes names, not addresses, into `PidTagDisplayTo` once it has resolved a recipient against an address book) is
+ * looked up among the caller's own contacts by exact display name and used when exactly one contact matches, with
+ * that contact's first valid email address.
+ */
+export declare function resolveRecipientList(value: string | undefined, context: Pick<RopContext, "mailboxUid" | "contactRepo">): Promise<RecipientResolution>;

package/dist/types/rop/CalendarEventTarget.d.ts

@@ -1,5 +1,7 @@
 import type { RepoUtils } from "@rapidrest/service-core";
 import { Attendee, BusyStatus, RecurrenceRule } from "@rapidmx/restapi";
+import type { ExecuteBudget } from "./ExecuteBudget.js";
+import { type RepoSort } from "./RepoPaging.js";
 /**
  * The `RopGetContentsTable`/`RopOpenMessage` analog of `MessageTarget.ts`, for a `Folder` of type `CALENDAR`:
  * resolves a `"calendarEvent:<uid>"` row/handle target into the display data a calendar-item row or an opened
@@ -24,6 +26,8 @@ export interface CalendarEventTargetInfo {
  * vanished (soft-deleted or otherwise) - the same "don't fail the whole ROP over one stale row" principle
  * `MessageTarget.resolveMessageInfo`/`FolderTarget.resolveFolderInfo` already apply. */
 export declare function resolveCalendarEventInfo(target: string, calendarEventRepo: RepoUtils<any>): Promise<CalendarEventTargetInfo>;
-/** Resolves the calendar events directly in `folderUid`, as `"calendarEvent:<uid>"` target strings, for
- * `RopGetContentsTable` against a `CALENDAR`-type folder. */
-export declare function resolveFolderCalendarEvents(folderUid: string, calendarEventRepo: RepoUtils<any>): Promise<string[]>;
+/** The order a calendar folder's events are listed in: latest start first, ties broken by `uid`. */
+export declare const CALENDAR_EVENT_SORT: RepoSort;
+/** Resolves the calendar events directly in `folderUid`, latest first and capped at `MAX_COLLECTION_ROWS`, as
+ * `"calendarEvent:<uid>"` target strings. */
+export declare function resolveFolderCalendarEvents(folderUid: string, calendarEventRepo: RepoUtils<any>, budget?: ExecuteBudget): Promise<string[]>;

package/dist/types/rop/ContactTarget.d.ts

@@ -1,4 +1,5 @@
 import type { RepoUtils } from "@rapidrest/service-core";
+import type { RepoSort } from "./RepoPaging.js";
 /**
  * The `RopGetContentsTable`/`RopOpenMessage` analog of `MessageTarget.ts`, for a `Folder` of type `CONTACTS`:
  * resolves a `"contact:<uid>"` row/handle target into the display data a contact-item row or an opened
@@ -24,6 +25,5 @@ export interface ContactTargetInfo {
  * (soft-deleted or otherwise) - the same "don't fail the whole ROP over one stale row" principle
  * `MessageTarget.resolveMessageInfo`/`CalendarEventTarget.resolveCalendarEventInfo` already apply. */
 export declare function resolveContactInfo(target: string, contactRepo: RepoUtils<any>): Promise<ContactTargetInfo>;
-/** Resolves the contacts directly in `folderUid`, as `"contact:<uid>"` target strings, for
- * `RopGetContentsTable` against a `CONTACTS`-type folder. */
-export declare function resolveFolderContacts(folderUid: string, contactRepo: RepoUtils<any>): Promise<string[]>;
+/** The order a `CONTACTS` folder's contents table lists contacts in (see `ContentsTable.ts`). */
+export declare const CONTACT_SORT: RepoSort;

package/dist/types/rop/ContentsTable.d.ts

@@ -0,0 +1,16 @@
+import type { MapiObjectHandle } from "../MapiSessionManager.js";
+import type { RopContext } from "./RopHandler.js";
+export type ContentsKind = NonNullable<MapiObjectHandle["contentsKind"]>;
+/** Which repo a folder's items live in, decided by the folder's own `type`: a `Contact`/`Task`/`CalendarEvent` is
+ * its own entity, never a `Message` row. */
+export declare function resolveContentsKind(folderUid: string, context: RopContext): Promise<ContentsKind>;
+/**
+ * The `"<kind>:<uid>"` row targets at positions `[start, start + count)` of a contents table (a `"folder:<uid>"`
+ * table with `contentsKind` set), read straight from the database in a fixed, stable order. A context without the
+ * matching optional repo yields no rows.
+ *
+ * Reading a window per `RopQueryRows` instead of snapshotting every row at `RopGetContentsTable` time keeps session
+ * state small and makes no folder too large to page through. The trade-off is that a message added or removed
+ * between two `RopQueryRows` calls can shift the rows that follow.
+ */
+export declare function resolveContentsWindow(context: RopContext, table: MapiObjectHandle, start: number, count: number): Promise<string[]>;

package/dist/types/rop/ExecuteBudget.d.ts

@@ -0,0 +1,48 @@
+/** The most rows (items or folders) whose properties one `Execute` resolves, across all of its ROPs. */
+export declare const MAX_ROWS_RESOLVED_PER_EXECUTE = 20000;
+/** The most bytes one `Execute` builds or parses (FastTransfer streams and message bodies), across all of its ROPs. */
+export declare const MAX_BYTES_BUILT_PER_EXECUTE: number;
+/** The most database queries (paged reads, table lookups, deletes) one `Execute` runs through the budgeted paths. */
+export declare const MAX_QUERIES_PER_EXECUTE = 20000;
+/** The most rows one `Execute` reads back from paged queries (folder lists, folder walks, item lists). */
+export declare const MAX_ROWS_FETCHED_PER_EXECUTE = 100000;
+/** The most `RopSubmitMessage`s one `Execute` runs. Each one can relay mail, so a request can't repeat it 1024 times. */
+export declare const MAX_SUBMITS_PER_EXECUTE = 16;
+/** Thrown when an `Execute` has used up its `ExecuteBudget`. The ROP that hit it fails; see `RopDispatcher`. */
+export declare class WorkBudgetExceededError extends Error {
+    constructor(what: string);
+}
+/**
+ * The work one `Execute` may do. Limits on ROP count and per-ROP sizes alone still let one request chain many
+ * expensive ROPs (a dozen 10000-row FastTransfer dumps, the same large body parsed by several streams, or a thousand
+ * hierarchy tables or folder walks), so rows resolved, bytes built, queries run, rows fetched and submits are counted
+ * across the whole request. Every charge happens before the work it pays for. Also dedupes message body parses within
+ * the request (`bodies`).
+ */
+export declare class ExecuteBudget {
+    rowsRemaining: number;
+    bytesRemaining: number;
+    queriesRemaining: number;
+    fetchedRowsRemaining: number;
+    submitsRemaining: number;
+    /** Message uid -> its decoded body, so opening the same body twice in one request parses it once. */
+    readonly bodies: Map<string, Promise<Buffer<ArrayBufferLike>>>;
+    constructor(maxRows?: number, maxBytes?: number, limits?: {
+        maxQueries?: number;
+        maxFetchedRows?: number;
+        maxSubmits?: number;
+    });
+    /** Uses `count` rows of the budget, throwing `WorkBudgetExceededError` once it is exhausted. */
+    chargeRows(count?: number): void;
+    /** Uses `count` bytes of the budget, throwing `WorkBudgetExceededError` once it is exhausted. */
+    chargeBytes(count: number): void;
+    /** Throws `WorkBudgetExceededError` when no bytes are left, so work that can't be sized up front (fetching a blob)
+     * isn't started at all. */
+    assertBytesLeft(): void;
+    /** Uses `count` queries of the budget. Called before running them. */
+    chargeQueries(count?: number): void;
+    /** Uses `count` fetched rows of the budget. */
+    chargeFetchedRows(count: number): void;
+    /** Uses one submit of the budget. */
+    chargeSubmit(): void;
+}

package/dist/types/rop/FastTransferStream.d.ts

@@ -1,18 +1,57 @@
 import { PropertyType } from "../codec/PropertyValue.js";
-import type { MapiObjectHandle } from "../MapiSessionManager.js";
-import type { RopContext } from "./RopHandler.js";
+import { type MapiObjectHandle } from "../MapiSessionManager.js";
+import { type RopContext } from "./RopHandler.js";
 interface PropertyColumn {
     propertyId: number;
     propertyType: PropertyType;
 }
+/** The largest FastTransfer stream built for one handle; a larger source fails with `MAPI_E_TOO_BIG`. */
+export declare const MAX_FAST_TRANSFER_BYTES: number;
+/** How long a built stream is kept for paging out. A client pages a stream out right after opening it; one that
+ * leaves it longer than this has to open the transfer again. */
+export declare const FAST_TRANSFER_TTL_SECONDS: number;
+/** Thrown while building a stream that has grown past its byte limit. */
+export declare class FastTransferTooBigError extends Error {
+    constructor();
+}
 /**
  * Builds the complete FastTransfer stream for `handle` (a `"folder"` or `"message"` Server object). `columns`,
  * when given (a `RopFastTransferSourceCopyProperties` explicit include list), replaces every default column set
  * uniformly at both folder- and message-level; `excludePropertyIds` (a `RopFastTransferSourceCopyTo` exclude
  * list) is only ever applied to this pragmatic subset's own default columns, per the same reasoning.
+ *
+ * The size is checked after every item, so a huge folder stops being built as soon as it passes `maxBytes`
+ * (`FastTransferTooBigError`) instead of being fully built first. Every item resolved and the finished stream's bytes
+ * count against the request's `ExecuteBudget` when there is one.
  */
 export declare function buildFastTransferStream(handle: MapiObjectHandle, context: RopContext, options?: {
     columns?: PropertyColumn[];
     excludePropertyIds?: ReadonlySet<number>;
+    maxBytes?: number;
 }): Promise<Buffer>;
+/** Why `loadFastTransferBuffer` has no stream: `"tooBig"` when a rebuild passed `MAX_FAST_TRANSFER_BYTES`, `"lost"`
+ * when the stored stream is gone part-way through paging. */
+export type FastTransferLoadFailure = "tooBig" | "lost";
+/**
+ * The built stream for the `"fastTransfer"` handle at `handleIndex`, from the shared `HandleDataStore` (Redis when
+ * configured, so any replica can page it out).
+ *
+ * When the stream is gone (expired, evicted, or built by a replica without shared storage), it is rebuilt only if
+ * nothing has been paged out yet. Part-way through, a rebuild could differ from what the client already has (items
+ * added or changed since), and continuing at the old offset would hand it bytes from a different stream, so that
+ * case reports `"lost"` and the client restarts the transfer. A rebuild is held to `MAX_FAST_TRANSFER_BYTES` like
+ * the original build, and storing it to the session's and user's handle data quota (`handleDataOwners`); either
+ * failing reports `"tooBig"`.
+ */
+export declare function loadFastTransferBuffer(context: RopContext, handleIndex: number, transfer: MapiObjectHandle): Promise<Buffer | FastTransferLoadFailure>;
+/**
+ * Shared by `RopFastTransferSourceCopyTo`/`CopyProperties`: builds the stream for `source`, and on success stores a
+ * `"fastTransfer"` handle at `outputHandleIndex` with the stream in the `HandleDataStore`. Returns `false`, storing
+ * nothing, when the stream exceeds `MAX_FAST_TRANSFER_BYTES` or the session's or user's handle data quota
+ * (`handleDataOwners`) has no room for it.
+ */
+export declare function openFastTransferHandle(context: RopContext, outputHandleIndex: number, source: MapiObjectHandle, options: {
+    columns?: PropertyColumn[];
+    excludePropertyIds?: number[];
+}): Promise<boolean>;
 export {};

package/dist/types/rop/FolderTarget.d.ts

@@ -1,6 +1,7 @@
 import type { RepoUtils } from "@rapidrest/service-core";
 import { Folder } from "@rapidmx/restapi";
 import type { MapiSessionContext } from "../MapiSessionManager.js";
+import type { ExecuteBudget } from "./ExecuteBudget.js";
 export interface FolderTargetInfo {
     displayName: string;
     unreadCount: number;
@@ -19,7 +20,7 @@ export interface FolderResolutionCache {
 /** Resolves a target string into the display data a folder-table row needs. A `"folder:<uid>"` target whose
  * `Folder` has since been deleted (soft-deleted or otherwise vanished) degrades to empty-looking values rather
  * than throwing - the row simply won't be interesting to a client, not a reason to fail the whole ROP. */
-export declare function resolveFolderInfo(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache): Promise<FolderTargetInfo>;
+export declare function resolveFolderInfo(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache, budget?: ExecuteBudget): Promise<FolderTargetInfo>;
 /**
  * Resolves the direct children of `target`, as an array of the same target-string format, for
  * `RopGetHierarchyTable`. Only `"virtual:root"`/`"virtual:ipmSubtree"` (this mailbox's top-level real
@@ -44,7 +45,7 @@ export declare function resolveFolderInfo(mailboxUid: string, target: string, fo
  * that batch so the full list is fetched at most once per batch instead of once per row - see
  * `FolderResolutionCache`'s own doc comment for why this isn't session state.
  */
-export declare function resolveFolderChildren(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache): Promise<string[]>;
+export declare function resolveFolderChildren(mailboxUid: string, target: string, folderRepo: RepoUtils<any>, cache?: FolderResolutionCache, budget?: ExecuteBudget): Promise<string[]>;
 /**
  * Returns `target`'s existing FID if `RopLogon` or an earlier `RopGetHierarchyTable` row already assigned
  * one, otherwise assigns and remembers the next free small integer FID. This is what lets a client

package/dist/types/rop/HandleDataCache.d.ts

@@ -0,0 +1,145 @@
+/** How long an entry lives without being read - the same idle lifetime as a session. */
+export declare const HANDLE_DATA_TTL_MS: number;
+/** The most bytes this process keeps across all entries before evicting the least recently used ones. */
+export declare const HANDLE_DATA_MAX_BYTES: number;
+/**
+ * A process-local, byte-bounded LRU with TTL for large per-handle data: an opened stream's decoded message body
+ * and a FastTransfer handle's built stream. Keeping these out of the session JSON means an `Execute` doesn't
+ * re-serialize megabytes to Redis, and a `RopReadStream` doesn't re-fetch and re-parse the whole MIME message
+ * for every chunk.
+ *
+ * It is only a cache. Every caller can rebuild an entry from the handle's own (small) session state, so a miss
+ * (another replica served the previous request, eviction, TTL) costs one rebuild, never wrong data. Keys carry
+ * the handle's generation (see `assignHandle`), so a reused handle index never picks up a previous handle's data.
+ */
+export declare class HandleDataCache {
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly entries;
+    private totalBytes;
+    constructor(maxBytes?: number, ttlMs?: number);
+    get(key: string): Buffer | undefined;
+    /** Stores `value` under `key`. A value larger than the whole budget isn't cached at all. */
+    set(key: string, value: Buffer): void;
+    /** The size of the live entry at `key`, without refreshing it or changing its recency. */
+    sizeOf(key: string): number | undefined;
+    delete(key: string): void;
+    /** The bytes currently held, for tests and diagnostics. */
+    get size(): number;
+}
+/** The process-wide instance every handler shares. */
+export declare const handleDataCache: HandleDataCache;
+/** The cache key for the handle at `handleIndex`, as of its current generation. A generation is a random nonce
+ * (see `assignHandle`), so a key is never reused, not even by a request whose session changes were never saved. */
+export declare function handleDataKey(sessionUid: string, handleIndex: number, generation: string | undefined): string;
+/** The `HandleDataStore` key of the write stream at `handleIndex`. */
+export declare function writeStreamKey(sessionUid: string, handleIndex: number, generation: string | undefined): string;
+/** The most bytes of FastTransfer streams and write-stream chunks one session keeps stored at once. */
+export declare const MAX_HANDLE_DATA_BYTES_PER_SESSION: number;
+/** The most bytes of FastTransfer streams and write-stream chunks one user keeps stored at once, across all of their
+ * sessions. */
+export declare const MAX_HANDLE_DATA_BYTES_PER_USER: number;
+/** How long an owner index outlives its last write: a session's longest lifetime. */
+export declare const HANDLE_DATA_INDEX_TTL_SECONDS: number;
+/** The most chunks one write stream keeps. Each `RopWriteStream` stores one chunk, so this bounds the hash a stream
+ * builds up (and the work `readChunks` does) however small the writes are. */
+export declare const MAX_CHUNKS_PER_STREAM = 8192;
+/** How often, at most, an owner index that is over its quota is recounted from its members. Between recounts a write is
+ * checked against the index's running total alone, so a client hammering a full quota can't make every write walk
+ * every member. */
+export declare const OWNER_RECOUNT_INTERVAL_MS = 1000;
+/** An index that stored data is counted against: the keys it holds and the most bytes they may add up to. */
+export interface HandleDataOwner {
+    index: string;
+    maxBytes: number;
+}
+/** The index of everything a session stores, used for its quota and to delete it all when the session ends. */
+export declare function sessionHandleDataIndex(sessionUid: string): string;
+/** The quota owners a write by `sessionUid` (belonging to `userUid`) counts against. */
+export declare function handleDataOwners(sessionUid: string, userUid: string): HandleDataOwner[];
+/**
+ * Where per-handle data that has to outlive one `Execute` lives: a built FastTransfer stream, and the chunks a write
+ * stream has accumulated. With Redis (`RedisHandleDataStore`) every replica sees the same data, so a client can page
+ * a stream out or finish writing a body through any pod. Without it (`MemoryHandleDataStore`) the data is only in
+ * this process.
+ *
+ * **Quotas.** A write given `owners` is recorded in each owner's index and refused (`false`, nothing stored) when it
+ * would take any owner past its `maxBytes`. Sizes are raw (unencoded) bytes. Every write costs O(1) per owner: each
+ * index keeps a running total, and a chunked stream keeps its own size (the end of its furthest chunk), so neither the
+ * stream's chunks nor the index's members are walked. A delete given the same `owners` takes the key's bytes off their
+ * totals. Data that disappears otherwise (TTL, eviction, `deleteOwnedBy` of another index, a delete without owners)
+ * keeps counting until a write that the total would refuse recounts the index from its live members, at most once per
+ * `OWNER_RECOUNT_INTERVAL_MS` per index. Totals only ever over-count, never under-count.
+ */
+export interface HandleDataStore {
+    get(key: string): Promise<Buffer | undefined>;
+    /** Stores `value` at `key`. `false` when an owner's quota refused it. */
+    set(key: string, value: Buffer, ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    /** Stores `data` as the chunk starting at byte `offset` of the stream at `key`. Writing the same offset again
+     * replaces the chunk, so a retried write never duplicates bytes or charges the quota twice. `false` when an owner's
+     * quota refused it, or the stream already has `MAX_CHUNKS_PER_STREAM` chunks and this is a new one. */
+    putChunk(key: string, offset: number, data: Buffer, ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    /** The first `size` bytes of the stream at `key`, assembled from its chunks, or `undefined` when a chunk is
+     * missing (expired or evicted) and the stream can't be reassembled exactly. */
+    readChunks(key: string, size: number): Promise<Buffer | undefined>;
+    /** Deletes the value or chunked stream at `key`, taking it off the totals of `owners`. */
+    delete(key: string, owners?: HandleDataOwner[]): Promise<void>;
+    /** Deletes everything recorded in the owner index `index`, and the index itself. */
+    deleteOwnedBy(index: string): Promise<void>;
+}
+/** A `HandleDataStore` in this process only, on a `HandleDataCache` (so it is byte-bounded and can evict). */
+export declare class MemoryHandleDataStore implements HandleDataStore {
+    private readonly cache;
+    private readonly indexes;
+    private readonly streams;
+    constructor(cache?: HandleDataCache);
+    get(key: string): Promise<Buffer | undefined>;
+    set(key: string, value: Buffer, _ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    putChunk(key: string, offset: number, data: Buffer, _ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    readChunks(key: string, size: number): Promise<Buffer | undefined>;
+    delete(key: string, owners?: HandleDataOwner[]): Promise<void>;
+    deleteOwnedBy(index: string): Promise<void>;
+    /** `true` while `key` still holds a value or its stream's first chunk (a stream missing that can't be read). */
+    private exists;
+    /** Records `key` at `bytes` in every owner index, unless that would take one past its quota. */
+    private admit;
+    /** `true` when `key` at `bytes` keeps `index` within `maxBytes`, recounting an index that looks full (rate limited). */
+    private fits;
+}
+/** Stores a value within its owners' quotas. KEYS: data key, then each owner index. ARGV: data key prefix, member name,
+ * index ttl, recount interval ms, base64 value, ttl, raw bytes, then each owner's max bytes. Returns 1 stored, 0 refused. */
+export declare const SET_WITH_QUOTA_SCRIPT = "\nlocal function recount(index, prefix, indexTtl)\n  local total = 0\n  local members = redis.call('ZRANGE', index, 0, -1, 'WITHSCORES')\n  for j = 1, #members, 2 do\n    if redis.call('EXISTS', prefix .. members[j]) == 0 then\n      redis.call('ZREM', index, members[j])\n    else\n      total = total + tonumber(members[j + 1])\n    end\n  end\n  redis.call('SET', index .. '.total', tostring(total), 'EX', indexTtl)\n  return total\nend\nlocal function admits(index, member, bytes, maxBytes, prefix, recountMs, indexTtl)\n  local stored = redis.call('GET', index .. '.total')\n  local fresh = not stored\n  local total = stored and tonumber(stored) or recount(index, prefix, indexTtl)\n  local old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  if total - old + bytes <= maxBytes then return true end\n  if fresh or not redis.call('SET', index .. '.recount', '1', 'PX', recountMs, 'NX') then return false end\n  total = recount(index, prefix, indexTtl)\n  old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  return total - old + bytes <= maxBytes\nend\nlocal function record(index, member, bytes, indexTtl)\n  local old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  redis.call('ZADD', index, tostring(bytes), member)\n  redis.call('INCRBY', index .. '.total', tostring(bytes - old))\n  redis.call('EXPIRE', index, indexTtl)\n  redis.call('EXPIRE', index .. '.total', indexTtl)\nend\n\nlocal bytes = tonumber(ARGV[7])\nfor i = 2, #KEYS do\n  if not admits(KEYS[i], ARGV[2], bytes, tonumber(ARGV[i + 6]), ARGV[1], ARGV[4], ARGV[3]) then return 0 end\nend\nredis.call('SETEX', KEYS[1], ARGV[6], ARGV[5])\nfor i = 2, #KEYS do record(KEYS[i], ARGV[2], bytes, ARGV[3]) end\nreturn 1\n";
+/** Stores one write-stream chunk within its owners' quotas, in O(1): the hash keeps its size (the end of its furthest
+ * chunk) in the `size` field, and that size is what the owners are charged, so a chunk rewritten at the same offset
+ * isn't charged twice. KEYS: hash key, then each owner index. ARGV: data key prefix, member name, index ttl, recount
+ * interval ms, unpadded base64url chunk, ttl, raw chunk bytes, hash field (offset), max chunks, then each owner's max
+ * bytes. Returns 1 stored, 0 refused (quota, or a new chunk past the max chunks). */
+export declare const PUT_CHUNK_WITH_QUOTA_SCRIPT = "\nlocal function recount(index, prefix, indexTtl)\n  local total = 0\n  local members = redis.call('ZRANGE', index, 0, -1, 'WITHSCORES')\n  for j = 1, #members, 2 do\n    if redis.call('EXISTS', prefix .. members[j]) == 0 then\n      redis.call('ZREM', index, members[j])\n    else\n      total = total + tonumber(members[j + 1])\n    end\n  end\n  redis.call('SET', index .. '.total', tostring(total), 'EX', indexTtl)\n  return total\nend\nlocal function admits(index, member, bytes, maxBytes, prefix, recountMs, indexTtl)\n  local stored = redis.call('GET', index .. '.total')\n  local fresh = not stored\n  local total = stored and tonumber(stored) or recount(index, prefix, indexTtl)\n  local old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  if total - old + bytes <= maxBytes then return true end\n  if fresh or not redis.call('SET', index .. '.recount', '1', 'PX', recountMs, 'NX') then return false end\n  total = recount(index, prefix, indexTtl)\n  old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  return total - old + bytes <= maxBytes\nend\nlocal function record(index, member, bytes, indexTtl)\n  local old = tonumber(redis.call('ZSCORE', index, member) or 0)\n  redis.call('ZADD', index, tostring(bytes), member)\n  redis.call('INCRBY', index .. '.total', tostring(bytes - old))\n  redis.call('EXPIRE', index, indexTtl)\n  redis.call('EXPIRE', index .. '.total', indexTtl)\nend\n\nlocal field = ARGV[8]\nif redis.call('HEXISTS', KEYS[1], field) == 0 and redis.call('HLEN', KEYS[1]) > tonumber(ARGV[9]) then return 0 end\nlocal size = math.max(tonumber(redis.call('HGET', KEYS[1], 'size') or 0), tonumber(field) + tonumber(ARGV[7]))\nfor i = 2, #KEYS do\n  if not admits(KEYS[i], ARGV[2], size, tonumber(ARGV[i + 8]), ARGV[1], ARGV[4], ARGV[3]) then return 0 end\nend\nredis.call('HSET', KEYS[1], field, ARGV[5], 'size', tostring(size))\nredis.call('EXPIRE', KEYS[1], ARGV[6])\nfor i = 2, #KEYS do record(KEYS[i], ARGV[2], size, ARGV[3]) end\nreturn 1\n";
+/** Deletes one data key and takes it off its owners' totals. KEYS: data key, then each owner index. ARGV: member name. */
+export declare const DELETE_WITH_OWNERS_SCRIPT = "\nredis.call('DEL', KEYS[1])\nfor i = 2, #KEYS do\n  local old = redis.call('ZSCORE', KEYS[i], ARGV[1])\n  if old then\n    redis.call('ZREM', KEYS[i], ARGV[1])\n    if redis.call('EXISTS', KEYS[i] .. '.total') == 1 then redis.call('INCRBY', KEYS[i] .. '.total', tostring(-tonumber(old))) end\n  end\nend\nreturn 1\n";
+/** Deletes every key an owner index names, then the index with its total and recount marker. KEYS: index. ARGV: data key
+ * prefix. Returns the members (unprefixed keys) it deleted, so the caller can drop its local copies too. */
+export declare const DELETE_OWNED_SCRIPT = "\nlocal members = redis.call('ZRANGE', KEYS[1], 0, -1)\nfor _, member in ipairs(members) do\n  redis.call('DEL', ARGV[1] .. member)\nend\nredis.call('DEL', KEYS[1], KEYS[1] .. '.total', KEYS[1] .. '.recount')\nreturn members\n";
+/** The prefix of every handle data key in Redis. */
+export declare const HANDLE_DATA_PREFIX = "mapi.handle.";
+/**
+ * A `HandleDataStore` on a node-redis client, with this process's `HandleDataCache` in front for reads. Values are
+ * stored base64-encoded (a plain string works with any client configuration); a write stream is a hash of
+ * `offset -> chunk` plus its `size`. Owner indexes are sorted sets (`mapi.handle-owner.<index>`) of key -> raw bytes, with
+ * a running total beside each (see `OWNER_INDEX_LUA`).
+ */
+export declare class RedisHandleDataStore implements HandleDataStore {
+    private readonly client;
+    private readonly local;
+    constructor(client: any, local?: HandleDataCache);
+    get(key: string): Promise<Buffer | undefined>;
+    set(key: string, value: Buffer, ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    putChunk(key: string, offset: number, data: Buffer, ttlSeconds: number, owners?: HandleDataOwner[]): Promise<boolean>;
+    readChunks(key: string, size: number): Promise<Buffer | undefined>;
+    delete(key: string, owners?: HandleDataOwner[]): Promise<void>;
+    deleteOwnedBy(index: string): Promise<void>;
+}
+/** The Redis key of an owner index. */
+export declare function ownerKey(index: string): string;
+/** The store used when a `RopContext` doesn't carry one (unit tests, or a route built without a session manager). */
+export declare const defaultHandleDataStore: HandleDataStore;

package/dist/types/rop/MeetingMessageClassHandler.d.ts

@@ -1,36 +1,30 @@
 import type { RopContext } from "./RopHandler.js";
 /**
  * Handles a submitted `"IPM.Schedule.Meeting.Resp.{Pos,Neg,Tent}"` message - an attendee's own response to a
- * meeting invite this server previously sent (`RopSubmitMessageHandler.submitAppointment`). Delegated to from
- * `RopSubmitMessageHandler` for that message-class prefix, instead of the ordinary mail or Appointment paths.
+ * meeting invite. Delegated to from `RopSubmitMessageHandler` for that message-class prefix, instead of the ordinary
+ * mail or Appointment paths. Returns the ROP's `ReturnValue`.
  *
- * Correlates the response back to the original `CalendarEvent` via `PidLidGlobalObjectId` (echoed by a real
- * client from the invite it's responding to - see `GlobalObjectId.ts`'s own doc comment for why this requires
- * no separate correlation table) and updates the caller's own `Attendee.responseStatus` in place, reusing the
- * exact same matching-by-mailbox-address logic `MeetingResponseCommand` (EAS's own `MeetingResponse` handler)
- * already implements - this is a from-scratch reimplementation of that small algorithm rather than a
- * cross-import, since EAS and MAPI are independent protocol verticals in this codebase with no dependency
- * between them.
+ * Mirrors restapi's `BaseCalendarEventRoute.respond()`. It correlates the response via `PidLidGlobalObjectId`
+ * (echoed by a real client from the invite it's responding to - see `GlobalObjectId.ts`) to **the caller's own
+ * copy** of the meeting: the query is scoped to the caller's `mailboxUid`, which is the access check. The
+ * organizer's copy (in another mailbox) is never touched here; the organizer's server applies the iTIP `REPLY` sent
+ * below, exactly as for a REST response. A native Outlook `GlobalObjectId` decodes to the uppercase hex form of its
+ * iCalendar UID, which is matched in either case.
  *
- * Every failure mode here (no `PidLidGlobalObjectId` set, no matching `CalendarEvent`, no resolvable mailbox,
- * caller isn't actually an attendee, unrecognized message-class suffix) is a silent no-op rather than an error
- * response - the same "don't fail the whole ROP over a stale/unresolvable reference" principle this pragmatic
- * subset applies throughout (e.g. `MessageTarget.resolveMessageInfo`'s own doc comment). A response that can't
- * be correlated or applied is simply dropped, not a reason to reject the client's `RopSubmitMessage` call.
+ * **One occurrence of a recurring meeting** (the `GlobalObjectId`'s instance date is set): the caller's exception
+ * copy for that date is used when there is one, comparing dates in the event's own time zone. Without one, the
+ * series is left alone - responding to one occurrence must not change or delete every other occurrence. Declining
+ * adds the occurrence to the caller's series `recurrenceRule.exceptions` (so it leaves their calendar); accepting or
+ * tentatively accepting changes nothing locally. Either way the `REPLY` names just that occurrence (`RECURRENCE-ID`).
  *
- * **The one query in this package that isn't `mailboxUid`-scoped, and why that's unavoidable here**: unlike
- * every other `ignoreACL: true` repo call in this codebase (all transitively scoped to the caller's own
- * mailbox via a session FID/MID registry that itself only ever gets populated from mailbox-scoped queries),
- * `calendarEventRepo.find({ icalUid })` below deliberately searches *every* mailbox on this server - the
- * `CalendarEvent` being responded to belongs to the meeting's *organizer*, who is very often a different
- * mailbox than the attendee submitting this response, and the caller's own session has no way to know which
- * mailbox that is. Safety instead comes from two independent properties: `icalUid` is a server-generated
- * `crypto.randomUUID()` (see `RopSaveChangesMessageHandler.saveAppointment`), for all practical purposes
- * globally unique, so this can't be used to enumerate or collide with another organizer's events; and the
- * actual authorization gate is the attendee-membership check a few lines down (`callerAddresses.has(...)`),
- * derived entirely from *this* caller's own resolved mailbox record, not from anything the client supplied -
- * a crafted `PidLidGlobalObjectId` can at best name a real `icalUid` it doesn't already know the value of
- * (astronomically unlikely against a random UUID) and still can't mutate an event unless the caller's own
- * mailbox is genuinely a listed attendee on it.
+ * **The whole meeting** (no instance date, or a copy that doesn't recur): the caller's `Attendee.responseStatus` is
+ * recorded; declining soft-deletes the caller's copy instead. Declining an occurrence through its exception copy also
+ * adds that occurrence to the series' exceptions, so the series doesn't show it again. Every update is versioned
+ * (`asEntity`), so a concurrent change fails the response instead of being overwritten.
+ *
+ * The `REPLY` (restapi's own `buildEventIcs`) goes out through `sendOrThrow`, so a transport that rejects it is
+ * reported as `MAPI_E_CALL_FAILED` instead of success; the response itself stays recorded. An organizer or attendee
+ * address that isn't a plain SMTP address is not mailed at all. A response that can't be matched to a meeting the
+ * caller attends is an error (`MAPI_E_NOT_FOUND`/`MAPI_E_INVALID_PARAMETER`), not a silent success.
  */
-export declare function submitMeetingResponse(messageClass: string, draftProperties: Record<string, string>, context: RopContext): Promise<void>;
+export declare function submitMeetingResponse(messageClass: string, draftProperties: Record<string, string>, context: RopContext): Promise<number>;

package/dist/types/rop/MessageBodyStream.d.ts

@@ -1,5 +1,8 @@
 import type { RepoUtils } from "@rapidrest/service-core";
 import { type BlobStore } from "@rapidmx/restapi";
+import type { MapiObjectHandle } from "../MapiSessionManager.js";
+import type { ExecuteBudget } from "./ExecuteBudget.js";
+import type { RopContext } from "./RopHandler.js";
 /** `PidTagBody` (`[MS-OXPROPS]`): property ID `0x1000`, `PtypString`. The only streamable property this
  * pragmatic subset supports via `RopOpenStream`/`RopReadStream` - `PidTagHtml`/`PidTagRtfCompressed` are a
  * documented gap (see `RopOpenStreamHandler`'s own doc comment). */
@@ -16,11 +19,17 @@ export declare const PID_TAG_BODY = 4096;
  * `sanitizedHtmlBlobKey` - `PidTagBody` is specifically the plain-text body per `[MS-OXPROPS]`, unlike EAS's
  * `Body` element, which can carry either format tagged by its own `Type` field.
  *
- * Recomputed on every call rather than cached anywhere (including on the `"stream"` handle itself) -
- * `MapiSessionContext` is serialized through `RedisCache`'s JSON round trip for multi-instance deployments, so
- * a raw `Buffer` stored there wouldn't survive it (the same class of gap this codebase already documented for
- * `Date` fields, see `MapiSessionContext`'s own doc comment). A documented, pragmatic trade-off: a large body
- * read across several `RopReadStream` calls re-parses the MIME source each time rather than once - correct,
- * not byte-perfect-efficient.
+ * Does no caching itself - `loadStreamBody` below is what the stream ROPs call. With a `budget`, nothing is fetched
+ * once its bytes are used up, and the raw message's size is charged before it is parsed.
  */
-export declare function resolveMessageBodyBytes(target: string, messageRepo: RepoUtils<any>, blobStore: BlobStore): Promise<Buffer>;
+export declare function resolveMessageBodyBytes(target: string, messageRepo: RepoUtils<any>, blobStore: BlobStore, budget?: ExecuteBudget): Promise<Buffer>;
+/**
+ * The body bytes for the read stream at `handleIndex`. Parsed once and kept in `HandleDataCache` (outside the
+ * session JSON) for the life of the handle, so reading a large body in many `RopReadStream` chunks costs one
+ * fetch and one MIME parse instead of one per chunk. A cache miss (eviction, or a request served by another
+ * replica) just resolves the body again: a stored message's body never changes, so the bytes are the same.
+ *
+ * Within one `Execute`, streams opened on the same message share a single parse (`ExecuteBudget.bodies`), and each
+ * parse's bytes count against the request's byte budget.
+ */
+export declare function loadStreamBody(context: RopContext, handleIndex: number, stream: MapiObjectHandle): Promise<Buffer>;

package/dist/types/rop/MessageTarget.d.ts

@@ -1,5 +1,7 @@
 import type { RepoUtils } from "@rapidrest/service-core";
 import type { MapiSessionContext } from "../MapiSessionManager.js";
+import type { ExecuteBudget } from "./ExecuteBudget.js";
+import { type RepoSort } from "./RepoPaging.js";
 /**
  * The `RopGetContentsTable` analog of `FolderTarget.ts`: resolves a `"message:<uid>"` row target (see
  * `RopGetContentsTableHandler`'s own doc comment for why contents-table rows use this prefix instead of
@@ -19,9 +21,11 @@ export interface MessageTargetInfo {
  * (soft-deleted or otherwise), the same "don't fail the whole ROP over one stale row" principle
  * `FolderTarget.resolveFolderInfo` already applies. */
 export declare function resolveMessageInfo(target: string, messageRepo: RepoUtils<any>): Promise<MessageTargetInfo>;
-/** Resolves the messages directly in `folderUid`, as `"message:<uid>"` target strings, for
- * `RopGetContentsTable`. */
-export declare function resolveFolderMessages(folderUid: string, messageRepo: RepoUtils<any>): Promise<string[]>;
+/** The order a folder's messages are listed in: newest first, ties broken by `uid` so paging is stable. */
+export declare const MESSAGE_SORT: RepoSort;
+/** Resolves the messages directly in `folderUid`, newest first and capped at `MAX_COLLECTION_ROWS`, as
+ * `"message:<uid>"` target strings. */
+export declare function resolveFolderMessages(folderUid: string, messageRepo: RepoUtils<any>, budget?: ExecuteBudget): Promise<string[]>;
 /**
  * Returns `target`'s existing MID if an earlier `RopQueryRows` row already assigned one, otherwise assigns and
  * remembers the next free small integer MID. The exact `FolderTarget.assignOrGetFid` pattern, adapted for
@@ -36,3 +40,6 @@ export declare function resolveFolderMessages(folderUid: string, messageRepo: Re
  * that pages through many messages.
  */
 export declare function assignOrGetMid(session: MapiSessionContext, target: string): number;
+/** The most MIDs one session keeps mapped. A session paging through a very large mailbox would otherwise grow its
+ * MID maps - saved with the session on every `Execute` - without bound. */
+export declare const MAX_MESSAGE_IDS = 20000;

package/dist/types/rop/NamedPropertyRegistry.d.ts

@@ -11,6 +11,10 @@ export interface PropertyName {
     lid?: number;
     name?: string;
 }
+/** The most distinct named properties one session registers. The registry is saved with the session on every
+ * `Execute`, and a name can be up to 255 bytes, so letting a client fill the whole `0x8000`-`0xFFFF` ID space
+ * would make every request carry megabytes of session state. Real clients register a few hundred at most. */
+export declare const MAX_NAMED_PROPERTIES_PER_SESSION = 4096;
 /**
  * Returns `propertyName`'s existing numeric property ID if an earlier `RopGetPropertyIdsFromNames` call in
  * this session already assigned one, otherwise assigns and remembers the next free ID starting at
@@ -28,8 +32,8 @@ export interface PropertyName {
  * lifetime, so a linear scan repeated once per property per row is quadratic over a session that resolves many
  * named properties.
  *
- * Once `nextNamedPropertyId` would exceed `LAST_NAMED_PROPERTY_ID` (32,768 distinct names already registered
- * this session - the entire `0x8000`-`0xFFFF` numeric ID space this pragmatic subset has to hand out), a *new*
+ * Once `nextNamedPropertyId` would exceed `LAST_NAMED_PROPERTY_ID` (`MAX_NAMED_PROPERTIES_PER_SESSION` distinct
+ * names already registered this session), a *new*
  * name can no longer be assigned a real ID; this returns `0x0000` for it instead of throwing, the exact value
  * `[MS-OXCPRPT]`'s own `RopGetPropertyIdsFromNames` processing rules already use for "this `PropertyName`
  * could not be resolved" (the same value this pragmatic subset already produces for a `Kind = 0xFF` entry) -

package/dist/types/rop/PropertyResolvers.d.ts

@@ -57,4 +57,4 @@ export interface ResolutionCache extends FolderResolutionCache {
 export declare function resolvePropertyValues(target: string, columns: {
     propertyId: number;
     propertyType: PropertyType;
-}[], context: Pick<RopContext, "mailboxUid" | "session" | "folderRepo" | "messageRepo" | "calendarEventRepo" | "mailboxRepo" | "contactRepo" | "taskRepo" | "labelRepo">, cache?: ResolutionCache): Promise<PropertyValueData[]>;
+}[], context: Pick<RopContext, "mailboxUid" | "session" | "folderRepo" | "messageRepo" | "calendarEventRepo" | "mailboxRepo" | "contactRepo" | "taskRepo" | "labelRepo" | "budget">, cache?: ResolutionCache): Promise<PropertyValueData[]>;