@rapidmx/mapi-plugin 1.0.0-beta.10

package/dist/types/MapiSessionManager.d.ts

@@ -0,0 +1,285 @@
+import { SimpleEntity } from "@rapidrest/service-core";
+import { type HandleDataStore } from "./rop/HandleDataCache.js";
+/** A pragmatic idle-session lifetime. The spec leaves session lifetime to server policy, not a fixed wire
+ * value - a real client re-establishes (`Connect`) transparently whenever its session context has expired. */
+export declare const SESSION_TTL_SECONDS: number;
+/** The longest a session may live, however active it stays. A client simply `Connect`s again afterwards. */
+export declare const MAX_SESSION_LIFETIME_MS: number;
+/** The most sessions one user may hold at once. `Connect` past this ends that user's least recently used session (each
+ * `Execute` refreshes its session's place - see `MapiSessionManager.touch`). */
+export declare const MAX_SESSIONS_PER_USER = 20;
+/** The largest a serialized session may grow. Everything that grows with use is capped on its own (handles by their
+ * one-byte index, named properties, MIDs; write streams live outside the session); this is the backstop, and a save
+ * past it fails with `MAPI_E_TOO_BIG` rather than storing megabytes every later request has to load. */
+export declare const MAX_SESSION_BYTES: number;
+/** How long an `Execute`'s session lock lives without being renewed. A running `Execute` renews it every
+ * `SESSION_LOCK_RENEW_MS`, so only a crashed pod's lock expires. The session save is still compare-and-set, so an
+ * expired lock can't corrupt state. */
+export declare const SESSION_LOCK_TTL_MS: number;
+/** How often a running `Execute` renews its session lock and in-progress marker. */
+export declare const SESSION_LOCK_RENEW_MS: number;
+/** Tags what a ROP-assigned integer handle (the `ServerObjectHandleTable` index space) refers to.
+ * `entityUid` for a `"folder"` handle is one of `session.folderIds`' own value strings (`"virtual:<name>"` or
+ * `"folder:<uid>"`), not a bare UID - the same format throughout avoids a second parallel encoding.
+ *
+ * A `"table"` handle's `columns`/`cursor` hold `RopSetColumns`/`RopQueryRows` state. A hierarchy table carries its
+ * resolved child-folder targets in `rows`. A contents table carries no rows at all: `contentsKind` says which repo
+ * its folder's items live in and `RopQueryRows` reads just the requested window from the database (see
+ * `ContentsTable.ts`), so a large folder never lands in session state.
+ *
+ * A `"stream"` handle's `entityUid` is the `"message:<uid>"` target its content was opened from,
+ * `propertyId`/`propertyType` the `PropertyTag` `RopOpenStream` opened (this pragmatic subset only ever supports
+ * `PidTagBody`/`PtypString`, see `MessageBodyStream.ts`), and `streamPosition` how many bytes `RopReadStream` has
+ * already returned. A read stream's decoded body lives in `HandleDataCache`, not here. A write stream (opened
+ * `ReadWrite`/`Create` against a `RopCreateMessage` draft's `PidTagBody`) records the draft it belongs to in
+ * `writeTargetHandleIndex`/`writeTargetGeneration`, and how many bytes have been written in `writeSize`. The bytes
+ * themselves are chunks in the `HandleDataStore` (see `RopWriteStreamHandler`), not session state.
+ *
+ * A `"message"` handle from `RopCreateMessage` (a draft not yet `RopSaveChangesMessage`d) has `entityUid: ""`
+ * and instead carries `draftFolderUid` (the folder it will belong to) and `draftProperties` (the small,
+ * well-known set of properties this pragmatic subset's `RopSetProperties` tracks - Subject/DisplayTo/
+ * DisplayCc/DisplayBcc/an inline `PidTagBody`, each coerced to a plain string, keyed by decimal `PropertyId` -
+ * a string key because a JSON-object key is always a string regardless of how it's written). Buffers are stored
+ * as base64 and dates as ISO strings since sessions round-trip through `JSON.stringify`/`JSON.parse`.
+ *
+ * A `"fastTransfer"` handle (`RopFastTransferSourceCopyTo`/`CopyProperties`'s output handle) keeps only what is
+ * needed to rebuild its stream (`transferSourceType`, `transferColumns`/`transferExcludeIds`) plus the paging
+ * cursor `transferPosition`; the built stream itself lives in `HandleDataCache`.
+ *
+ * `generation` is a random nonce per assignment (see `assignHandle`), so data keyed by handle index can tell a handle
+ * apart from a later one that reuses the same index - including one assigned by a request whose session changes were
+ * never saved, which a per-session counter would hand out again. */
+export interface MapiObjectHandle {
+    type: "logon" | "folder" | "message" | "table" | "stream" | "fastTransfer";
+    entityUid: string;
+    generation?: string;
+    rows?: string[];
+    contentsKind?: "message" | "calendarEvent" | "contact" | "task";
+    columns?: {
+        propertyId: number;
+        propertyType: number;
+    }[];
+    cursor?: number;
+    propertyId?: number;
+    propertyType?: number;
+    streamPosition?: number;
+    draftFolderUid?: string;
+    draftProperties?: Record<string, string>;
+    writeTargetHandleIndex?: number;
+    writeTargetGeneration?: string;
+    writeSize?: number;
+    transferSourceType?: "folder" | "message";
+    transferColumns?: {
+        propertyId: number;
+        propertyType: number;
+    }[];
+    transferExcludeIds?: number[];
+    transferPosition?: number;
+    /** Set on a draft message once `RopSubmitMessage` has tried to send it, whatever the outcome. A submitted draft
+     * can't be submitted again or changed. */
+    submitted?: boolean;
+}
+/**
+ * The MAPI/HTTP `Session Context` (`[MS-OXCMAPIHTTP]` §3.1.1.1): everything a `Connect`-established session
+ * needs across subsequent `Execute` requests. Never persisted to a real database - purely an ephemeral,
+ * TTL-bound store entry (see `MapiSessionManager` below), so this deliberately extends `SimpleEntity` (just a
+ * `uid`) rather than this library's own `BaseEntity`.
+ *
+ * `createdAt` is a plain ISO-8601 string, not a `Date`, since sessions round-trip through JSON. `version` is
+ * bumped on every successful save and compared on the next one - see `MapiSessionManager.save()`.
+ */
+export declare class MapiSessionContext extends SimpleEntity {
+    mailboxUid: string;
+    userUid: string;
+    version: number;
+    handles: Record<number, MapiObjectHandle>;
+    nextHandleIndex: number;
+    createdAt: string;
+    /** This session's FID assignments for the 13 `RopLogon` special folders, keyed by FID (decimal string),
+     * valued `"virtual:<name>"` or `"folder:<uid>"` - see `RopLogonHandler`'s own doc comment. Populated by
+     * `RopLogon`, read back by a later `RopOpenFolder`. */
+    folderIds: Record<string, string>;
+    /** The reverse of `folderIds` (target -> FID) plus a monotonic counter, maintained alongside it by
+     * `FolderTarget.assignOrGetFid`/`RopLogonHandler` so "does this target already have a FID" is an O(1)
+     * lookup instead of a linear scan of `folderIds` repeated once per table row. */
+    folderTargetIds: Record<string, number>;
+    nextFolderId: number;
+    /** This session's MID assignments, keyed by MID (decimal string), valued `"message:<uid>"` - the message
+     * analog of `folderIds` above. A MID only ever comes into existence lazily, the first time a `RopQueryRows`
+     * row exposes a message's `PidTagMid` column (see `MessageTarget.assignOrGetMid`), read back by a later
+     * `RopOpenMessage`. */
+    messageIds: Record<string, string>;
+    /** The reverse of `messageIds` (target -> MID) plus a monotonic counter. */
+    messageTargetIds: Record<string, number>;
+    nextMessageId: number;
+    /** The oldest MID still mapped. Past `MAX_MESSAGE_IDS` mapped MIDs the oldest are dropped - see
+     * `MessageTarget.assignOrGetMid`. */
+    firstMessageId: number;
+    /** This session's `RopGetPropertyIdsFromNames` mapping table (`[MS-OXCPRPT]` §2.2.12), keyed by a JSON
+     * string encoding of the `{guid, kind, lid|name}` `PropertyName` the numeric ID was assigned to - see
+     * `NamedPropertyRegistry.ts`. */
+    namedProperties: Record<string, number>;
+    /** The reverse of `namedProperties` (numeric ID -> `PropertyName` JSON key) plus a monotonic counter. */
+    namedPropertyIds: Record<number, string>;
+    nextNamedPropertyId: number;
+    constructor(other: Partial<SimpleEntity> & {
+        mailboxUid: string;
+        userUid: string;
+    });
+}
+/**
+ * Stores `handle` at `index` with a fresh generation. Whatever previously held that index is released first
+ * (see `releaseHandle`), so a stream or cached data belonging to the old handle never attaches to the new one.
+ */
+export declare function assignHandle(session: MapiSessionContext, index: number, handle: MapiObjectHandle): MapiObjectHandle;
+/**
+ * Releases the handle at `index`: drops its cached data, and releases every write stream opened against it
+ * (a stream is meaningless once its draft message is gone, and would otherwise attach to whatever reuses the
+ * index next).
+ */
+export declare function releaseHandle(session: MapiSessionContext, index: number): void;
+/** The shared-store keys (FastTransfer streams, write-stream chunks) of every handle released on `session` since the
+ * last call, for the route to delete once the session's changes are saved. */
+export declare function takeReleasedHandleData(session: MapiSessionContext): string[];
+/** The outcome of `MapiSessionManager.save()`. `"conflict"` means another request saved the session first;
+ * `"missing"` that it expired or was ended; `"tooBig"` that it grew past `MAX_SESSION_BYTES` and was not saved. */
+export type SessionSaveResult = "saved" | "conflict" | "missing" | "tooBig";
+/**
+ * The storage a `MapiSessionManager` runs on: Redis when a `cache` datastore is configured, otherwise memory.
+ *
+ * A session is two entries: its JSON (`sessionKey`) and its version (`<sessionKey>.version`). A save compares the
+ * version entry only, so Redis never has to parse the session JSON.
+ */
+export interface MapiSessionStore {
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    /** Atomically records `sessionId` in the user's index (ordered by last use, starting at `createdAtMs`): drops ids
+     * whose session is gone, ends the least recently used sessions until fewer than `max` remain, then adds it. Returns
+     * the ids it ended. */
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number, ttlSeconds: number): Promise<string[]>;
+    /** `SET NX` with a TTL: `true` when the lock was free and is now held with `token`. */
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    /** Releases the lock only if it is still held with `token`. */
+    releaseLock(key: string, token: string): Promise<void>;
+    /** Extends the lock to `ttlMs` from now, only while it is still held with `token`. */
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    /** Moves `sessionId` to `score` in the user's index when it is still there. */
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+/** Creates a session at version 0. KEYS: session, version. ARGV: json, ttl. */
+export declare const CREATE_SCRIPT = "\nredis.call('SETEX', KEYS[1], ARGV[2], ARGV[1])\nredis.call('SETEX', KEYS[2], ARGV[2], '0')\nreturn 1\n";
+/** Replaces the session only when its version entry still equals the expected one, without decoding the session.
+ * KEYS: session, version. ARGV: expected version, json, ttl. Returns 1 saved, 0 on a version mismatch, -1 when gone. */
+export declare const COMPARE_AND_SET_SCRIPT = "\nlocal current = redis.call('GET', KEYS[2])\nif not current or redis.call('EXISTS', KEYS[1]) == 0 then return -1 end\nif tonumber(current) ~= tonumber(ARGV[1]) then return 0 end\nredis.call('SETEX', KEYS[1], ARGV[3], ARGV[2])\nredis.call('SETEX', KEYS[2], ARGV[3], tostring(tonumber(ARGV[1]) + 1))\nreturn 1\n";
+/** Adds a session to its user's sorted-set index in one step, so concurrent Connects can't each see room under the
+ * cap. KEYS: index. ARGV: session id, created-at score, max, index ttl, session key prefix, session key suffix. The
+ * session keys it checks and deletes are built from the ids, so they aren't declared in KEYS (fine on one Redis node,
+ * not on a cluster). Returns the ids it ended. */
+export declare const ADD_TO_USER_INDEX_SCRIPT = "\nlocal function sessionKey(id) return ARGV[5] .. id .. ARGV[6] end\nfor _, id in ipairs(redis.call('ZRANGE', KEYS[1], 0, -1)) do\n  if redis.call('EXISTS', sessionKey(id)) == 0 then redis.call('ZREM', KEYS[1], id) end\nend\nlocal ended = {}\nwhile redis.call('ZCARD', KEYS[1]) >= tonumber(ARGV[3]) do\n  local oldest = redis.call('ZRANGE', KEYS[1], 0, 0)[1]\n  redis.call('ZREM', KEYS[1], oldest)\n  redis.call('DEL', sessionKey(oldest), sessionKey(oldest) .. '.version')\n  table.insert(ended, oldest)\nend\nredis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])\nredis.call('EXPIRE', KEYS[1], ARGV[4])\nreturn ended\n";
+/** KEYS: lock. ARGV: token, ttl ms. Returns 1 when acquired. */
+export declare const ACQUIRE_LOCK_SCRIPT = "\nif redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then return 1 end\nreturn 0\n";
+/** KEYS: lock. ARGV: token. Deletes the lock only while this token still holds it. */
+export declare const RELEASE_LOCK_SCRIPT = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end\nreturn 1\n";
+/** KEYS: lock. ARGV: token, ttl ms. Returns 1 when the token still held the lock and it was extended. */
+export declare const RENEW_LOCK_SCRIPT = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('PEXPIRE', KEYS[1], ARGV[2]) return 1 end\nreturn 0\n";
+/** KEYS: user index. ARGV: score, session id. Updates the score of a member that is still present. */
+export declare const TOUCH_USER_INDEX_SCRIPT = "\nredis.call('ZADD', KEYS[1], 'XX', ARGV[1], ARGV[2])\nreturn 1\n";
+/** A `MapiSessionStore` on a node-redis client. Every read goes to Redis, never a per-process copy, so each
+ * replica sees the same session. */
+export declare class RedisMapiSessionStore implements MapiSessionStore {
+    private readonly client;
+    constructor(client: any);
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number, ttlSeconds: number): Promise<string[]>;
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string, token: string): Promise<void>;
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+/** A single-process `MapiSessionStore`. Values are stored as strings so every load hands out an independent copy,
+ * exactly like the Redis store. No method awaits between reading and writing, so each one is atomic. */
+export declare class MemoryMapiSessionStore implements MapiSessionStore {
+    private readonly entries;
+    private readonly indexes;
+    get(key: string): Promise<string | undefined>;
+    create(key: string, value: string, ttlSeconds: number): Promise<void>;
+    compareAndSet(key: string, expectedVersion: number, value: string, ttlSeconds: number): Promise<"saved" | "conflict" | "missing">;
+    delete(key: string): Promise<void>;
+    addToUserIndex(indexKey: string, sessionId: string, createdAtMs: number, max: number): Promise<string[]>;
+    acquireLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string, token: string): Promise<void>;
+    renewLock(key: string, token: string, ttlMs: number): Promise<boolean>;
+    touchUserIndex(indexKey: string, sessionId: string, score: number): Promise<void>;
+    getValue(key: string): Promise<string | undefined>;
+    putValue(key: string, value: string, ttlSeconds: number): Promise<void>;
+    private read;
+    private write;
+    private sweep;
+}
+/** The store key of a session's JSON. */
+export declare function sessionKey(sessionId: string): string;
+/**
+ * Stores/loads `MapiSessionContext`s, keyed by the opaque session id that also becomes the `MapiContext` cookie
+ * value.
+ *
+ * Every load reads the shared store (Redis when a `cache` datastore is configured). An earlier version used
+ * `RedisCache`, whose per-process copy served a session without checking Redis, so with several replicas one pod
+ * could run ROPs against handles another pod had already changed. Saves are compare-and-set on `version`: when
+ * two requests on the same session overlap, the second save reports `"conflict"` instead of overwriting the
+ * first request's handles. `Execute` also holds the session's lock (`acquireLock`) while it runs, so an overlapping
+ * request is turned away before it has any side effects, and keeps its last response (`storeResponse`) so a retry of
+ * the same request is answered again instead of being run twice.
+ */
+export declare class MapiSessionManager {
+    private redisClient?;
+    private store?;
+    /** Where handlers keep FastTransfer streams and write-stream chunks: in Redis next to the sessions when configured,
+     * so any replica can continue a transfer. */
+    handleDataStore?: HandleDataStore;
+    init(): void;
+    /** Creates a session for `userUid`, ending that user's least recently used sessions (and their stored handle data)
+     * if they already hold `MAX_SESSIONS_PER_USER`. */
+    create(mailboxUid: string, userUid: string): Promise<MapiSessionContext>;
+    /** Records that `session` was just used, so the per-user cap ends the least recently used session rather than the
+     * oldest one. */
+    touch(session: MapiSessionContext): Promise<void>;
+    /** Loads a session straight from the store. A session past `MAX_SESSION_LIFETIME_MS` is ended and treated as
+     * missing. */
+    load(sessionId: string): Promise<MapiSessionContext | undefined>;
+    /** Saves `context` only if nobody else saved it since it was loaded and it is within `MAX_SESSION_BYTES`,
+     * bumping its `version` on success. */
+    save(context: MapiSessionContext): Promise<SessionSaveResult>;
+    /** Ends a session, deleting its stored handle data too. */
+    destroy(sessionId: string): Promise<void>;
+    /** Deletes every FastTransfer stream and write-stream chunk the session stored. Best effort: they expire anyway. */
+    private deleteHandleData;
+    /** Takes the session's `Execute` lock. Returns the token to release it with, or `undefined` while another
+     * request holds it. */
+    acquireLock(sessionId: string): Promise<string | undefined>;
+    releaseLock(sessionId: string, token: string): Promise<void>;
+    /** Extends the session's lock by another `SESSION_LOCK_TTL_MS`. `false` when `token` no longer holds it. */
+    renewLock(sessionId: string, token: string): Promise<boolean>;
+    /** The response last sent on this session if it answered `requestId`; `"inProgress"` while a request with that id
+     * is still running (or ran on a pod that died less than `SESSION_LOCK_TTL_MS` ago); otherwise `undefined`. */
+    storedResponse(sessionId: string, requestId: string): Promise<Buffer | "inProgress" | undefined>;
+    /** Records that `requestId` is running on this session, for `SESSION_LOCK_TTL_MS` (renewed along with the lock). A
+     * retry of it is then answered as busy instead of running a second time. */
+    markInProgress(sessionId: string, requestId: string): Promise<void>;
+    /** Extends the in-progress marker of `requestId` by another `SESSION_LOCK_TTL_MS`, only while it is still that marker:
+     * once the request's response (or anything else) has replaced it, nothing is written. `false` when it wasn't there. */
+    renewInProgress(sessionId: string, requestId: string): Promise<boolean>;
+    /** Drops the in-progress marker of `requestId` when it is still there (the request ended without storing a
+     * response), so a retry runs. Atomic, so it never deletes a response stored meanwhile. */
+    clearInProgress(sessionId: string, requestId: string): Promise<void>;
+    /** Remembers `body` as this session's answer to `requestId`. Only the latest request is kept. */
+    storeResponse(sessionId: string, requestId: string, body: Buffer): Promise<void>;
+}

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/RopDispatcher.d.ts

@@ -0,0 +1,53 @@
+import type { RopContext, RopHandler } from "./rop/RopHandler.js";
+/** The most ROPs processed from one `Execute` request. A real client batches far fewer; anything past this is
+ * left unprocessed. */
+export declare const MAX_ROPS_PER_EXECUTE = 1024;
+/** The largest `RopsList` a response can carry: `RopSize` is a 16-bit count that includes its own 2 bytes. */
+export declare const MAX_ROPS_LIST_BYTES: number;
+/** `RopBufferTooSmall`'s `RopId` (`[MS-OXCROPS]` §2.2.15.1). */
+export declare const ROP_ID_BUFFER_TOO_SMALL = 255;
+/** `MAPI_E_CALL_FAILED`: a ROP failed while running (a database error, undecodable stored data, ...). */
+export declare const ERROR_CALL_FAILED = 2147500037;
+/** `MAPI_E_TOO_COMPLEX`: the ROP would have gone past this request's `ExecuteBudget`. */
+export declare const ERROR_TOO_COMPLEX = 2147746071;
+/** Thrown by `dispatchRops`, before any ROP runs, when the room for responses can't even hold a `RopBufferTooSmall`
+ * carrying the whole request. The route answers the `Execute` with `ecBufferTooSmall` ([MS-OXCRPC]). No ROP has run. */
+export declare class ExecuteBufferTooSmallError extends Error {
+    constructor();
+}
+export interface DispatchOptions {
+    /** Stop after this many ROPs. Defaults to `MAX_ROPS_PER_EXECUTE`. */
+    maxRops?: number;
+    /** The room for response ROPs, in bytes. Defaults to `MAX_ROPS_LIST_BYTES`; the route passes what the client's
+     * `MaxRopOut` leaves after the `RopSize` field and handle table. */
+    maxOutputBytes?: number;
+}
+/**
+ * Walks a decoded `RopBuffer`'s `ropsList` blob, dispatching each contained ROP - identified by its own leading
+ * `RopId` byte - to the matching registered handler in turn, collecting every response into one output buffer.
+ * Deliberately ROP-agnostic: it knows nothing about any specific ROP's own fields, only how to find the *next* one,
+ * via the handler's own advanced `reader` position once `handle()` returns - see `RopBuffer.ts`'s doc comment for
+ * why a fully generic split isn't possible for this wire format.
+ *
+ * - **Malformed requests.** An unrecognized `RopId`, or a ROP whose bytes run out or can't be sized (a
+ * `DecodeError`), throws a `DecodeError`: nothing after it can be located, so the route answers 400.
+ * - **A failing ROP.** Any other error thrown by a handler fails just that ROP: its partial output is dropped, a
+ * failure response (`RopId`, the handle index it echoes, `ReturnValue` `MAPI_E_CALL_FAILED` or, past the
+ * `ExecuteBudget`, `MAPI_E_TOO_COMPLEX`) takes its place, and the following ROPs still run. The handler has
+ * already read its whole request by the time it does work that can fail, so the next ROP is still where the
+ * reader points.
+ * - **Output space.** Room for a `RopBufferTooSmall` covering the next ROP and everything after it (3 bytes plus
+ * those request bytes) is always kept free. `context.ropOutputRemaining` tells each handler the room left *after*
+ * that reserve (computed from where the reader stands, so once a handler has read its request it excludes the
+ * handler's own bytes). A response that doesn't leave the reserve is replaced by `RopBufferTooSmall` (`SizeNeeded`
+ * plus the unprocessed request bytes, from this ROP on, for the client to resend) and processing stops; that always
+ * fits, because the reserve for this ROP was kept by the one before it. Handlers that change state by how much they
+ * return (`RopQueryRows`, `RopReadStream`, `RopFastTransferSourceGetBuffer`) size their response to the room, so they
+ * are never replaced after moving a cursor. Only when the request as a whole can't be covered by a
+ * `RopBufferTooSmall` is `ExecuteBufferTooSmallError` thrown, before anything runs, and the route answers the
+ * `Execute` with `ecBufferTooSmall` ([MS-OXCRPC]). So a failed `Execute` never follows state already changed and
+ * saved, which a retry would skip past.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare function dispatchRops(ropsList: Buffer, handlers: Map<number, RopHandler>, context: RopContext, options?: DispatchOptions): Promise<Buffer>;

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

@@ -0,0 +1,14 @@
+import { BufferReader } from "./BufferCursor.js";
+import { type RecurrenceRule } from "@rapidmx/restapi";
+/**
+ * Encodes `rule` (plus the occurrence's own `startDate`/`endDate`, needed for phase/time-of-day derivation)
+ * into an `AppointmentRecurrencePattern` blob, ready to be written as the raw content of a `PtypBinary`
+ * `PidLidAppointmentRecur` property value.
+ */
+export declare function encodeAppointmentRecurrence(rule: RecurrenceRule, startDate: Date, endDate: Date): Buffer;
+/**
+ * Decodes an `AppointmentRecurrencePattern` blob (read from `reader`'s current position) back into a
+ * `RecurrenceRule`. Throws a clear error for any pattern this pragmatic subset can't represent (see this
+ * file's own doc comment) rather than silently dropping data.
+ */
+export declare function decodeAppointmentRecurrence(reader: BufferReader): RecurrenceRule;

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

@@ -0,0 +1,92 @@
+/**
+ * A small positional cursor over a `Buffer`, shared by every MAPI codec in this package (`MapiGuid`,
+ * `PropertyValue`, `RopBuffer`, and every individual ROP handler's own request/response encoding). Unlike
+ * WBXML's self-describing tag stream, MAPI's wire structures are fixed/variable-length binary records with no
+ * generic "read until end tag" mechanism, so every codec needs the same little-endian primitive reads/writes
+ * with automatic offset advancement - reimplementing that per file would be pure repetition across the dozens
+ * of ROP handlers this phase's plan calls for, unlike EAS's WBXML codec, which only needed one such reader.
+ *
+ * Underlying `Buffer` methods already bounds-check and throw `RangeError` on overflow/truncation for every
+ * fixed-width primitive read - a malformed or truncated ROP buffer legitimately failing loudly is the correct
+ * behavior, not something to swallow here. `readBytes`/`readNullTerminatedUtf16LE`/`readNullTerminatedString8`
+ * are the three exceptions: `Buffer.subarray` silently clamps instead of throwing, and a null-terminated scan
+ * has no fixed width to bounds-check against `Buffer` methods at all, so those three enforce the same
+ * "malformed/truncated input throws" contract explicitly below instead of relying on it happening for free.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+/**
+ * A request that can't be decoded: truncated, or carrying a value (such as an unknown property type) whose wire
+ * size can't be determined. `RopDispatcher` answers the whole `Execute` with a 400 for one of these, since the bytes
+ * of every later ROP can no longer be located.
+ */
+export declare class DecodeError extends RangeError {
+    constructor(message: string);
+}
+export declare class BufferReader {
+    private readonly buffer;
+    private offset;
+    constructor(buffer: Buffer, offset?: number);
+    get position(): number;
+    get remaining(): number;
+    hasMore(): boolean;
+    /** Moves to `position` (backwards or forwards). Throws a `RangeError` for a position outside the buffer. */
+    seek(position: number): void;
+    readUInt8(): number;
+    readInt16LE(): number;
+    readUInt16LE(): number;
+    readInt32LE(): number;
+    readUInt32LE(): number;
+    readFloatLE(): number;
+    readDoubleLE(): number;
+    readBigInt64LE(): bigint;
+    readBigUInt64LE(): bigint;
+    /** Unlike every fixed-width `readXxxLE` above, `Buffer.prototype.subarray` never throws - an out-of-range
+     * `length` (negative, or reaching past the buffer's end) silently clamps instead, which would otherwise let
+     * a malformed/truncated ROP buffer produce garbage-but-not-erroring reads (a negative `length` even rewinds
+     * `offset` backwards) instead of failing loudly the way this class's own doc comment promises. Explicitly
+     * bounds-checked here for that reason. */
+    readBytes(length: number): Buffer;
+    /** Reads a UTF-16LE string up to (and consuming) its terminating `0x0000` code unit - `PtypString`'s wire
+     * encoding. Scans on 2-byte boundaries, since a null code unit's low/high byte pair can't be mistaken for
+     * one half of a non-null UTF-16 code unit at an odd offset the way a naive single-byte scan could.
+     *
+     * Throws if no terminator is found before running out of buffer, rather than silently returning whatever
+     * content preceded the truncation and leaving `offset` past the buffer's actual end - a truncated/malformed
+     * string is exactly the kind of input this class's own doc comment says should fail loudly. This also
+     * closes a real DoS: `PropertyValue.ts`'s `readCountedArray` loops a client-controlled element count with
+     * no independent cap, trusting each element's own reader to terminate the loop early against a too-small
+     * buffer the way every fixed-width reader already does - without this, `PtypMultipleString`'s
+     * `readNullTerminatedUtf16LE` calls kept silently returning `""` past the buffer's end forever instead. */
+    readNullTerminatedUtf16LE(): string;
+    /** Reads a single-byte-terminated 8-bit string (`PtypString8`'s wire encoding). Multibyte string content
+     * itself is treated as UTF-8, a pragmatic choice documented in `PropertyValue.ts` rather than the
+     * "externally specified encoding" the spec leaves open-ended.
+     *
+     * Throws if no terminator is found before running out of buffer - see `readNullTerminatedUtf16LE`'s own
+     * doc comment for why (identical reasoning, including the `readCountedArray` DoS this closes). */
+    readNullTerminatedString8(): string;
+}
+/** The write-side counterpart to `BufferReader`, accumulating chunks and concatenating once via `toBuffer()` -
+ * the same "array of pieces, `Buffer.concat` once at the end" idiom `WbxmlEncoder` already uses for its own
+ * byte-array accumulator, adapted for multi-byte little-endian fields instead of single bytes. */
+export declare class BufferWriter {
+    private readonly chunks;
+    private byteLength;
+    /** The number of bytes written so far. */
+    get length(): number;
+    private push;
+    writeUInt8(value: number): this;
+    writeInt16LE(value: number): this;
+    writeUInt16LE(value: number): this;
+    writeInt32LE(value: number): this;
+    writeUInt32LE(value: number): this;
+    writeFloatLE(value: number): this;
+    writeDoubleLE(value: number): this;
+    writeBigInt64LE(value: bigint): this;
+    writeBigUInt64LE(value: bigint): this;
+    writeBytes(value: Buffer): this;
+    writeNullTerminatedUtf16LE(value: string): this;
+    writeNullTerminatedString8(value: string): this;
+    toBuffer(): Buffer;
+}

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

@@ -0,0 +1,15 @@
+import { BufferReader } from "./BufferCursor.js";
+/** Encodes `icalUid` into a `GlobalObjectId` BLOB in the `VCALID` form a real client synthesizes from a plain
+ * iCalendar UID (see this file's own doc comment for why that's the form that matters here), using `at` as the
+ * `CreationTime`. */
+export declare function encodeGlobalObjectId(icalUid: string, at: Date): Buffer;
+/** Decodes a `GlobalObjectId` BLOB (read from `reader`'s current position) back into the `icalUid` it stands for.
+ * A `VCALID` (see this file's own doc comment) yields the UID it wraps. Anything else is a native `OutlookID`,
+ * whose `Data` is binary, not text: per `[MS-OXCICAL]`'s UID conversion, the iCalendar UID of such an object is the
+ * uppercase hex of the whole `GlobalObjectId` with the instance date (`YH`/`YL`/`M`/`D`, bytes 16-19) zeroed, so
+ * that is what is returned (compare it case-insensitively). Throws if `ByteArrayID` doesn't match the spec's own
+ * fixed constant - a real, spec-mandated identity check, not an invented restriction. */
+export declare function decodeGlobalObjectId(reader: BufferReader): string;
+/** The `YYYY-MM-DD` occurrence date a `GlobalObjectId` names (`YH`/`YL`/`M`/`D`), or `undefined` when it names the
+ * whole series (a zero year). `globalObjectId` must already have decoded successfully. */
+export declare function globalObjectIdInstanceDate(globalObjectId: Buffer): string | undefined;

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

@@ -0,0 +1,6 @@
+import { BufferReader } from "./BufferCursor.js";
+/** Encodes a standard hyphenated GUID/UUID string into its 16-byte MS wire form. */
+export declare function encodeGuid(guid: string): Buffer;
+/** Decodes a 16-byte MS wire-form GUID (read from `reader`'s current position) into a standard hyphenated
+ * GUID/UUID string. */
+export declare function decodeGuid(reader: BufferReader): string;

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

@@ -0,0 +1,7 @@
+import { BufferReader } from "./BufferCursor.js";
+/** Encodes `timezone` (an IANA identifier, or `"UTC"`) into a 48-byte `TimeZoneStruct` BLOB, using `at` as the
+ * reference instant for resolving a non-UTC zone's current fixed offset. */
+export declare function encodeTimeZoneStruct(timezone: string, at: Date): Buffer;
+/** Decodes a `TimeZoneStruct` BLOB (read from `reader`'s current position) into an approximate IANA zone
+ * identifier - see this file's own doc comment for the lossy `Etc/GMT±N` fallback's exact rounding rules. */
+export declare function decodeTimeZoneStruct(reader: BufferReader): string;

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

@@ -0,0 +1,87 @@
+import { BufferReader, BufferWriter } from "./BufferCursor.js";
+/**
+ * The property-value system every meaningful ROP depends on (`RopGetPropertiesSpecific`/`RopSetProperties`,
+ * table row data in `RopQueryRows`, ...), per `[MS-OXCDATA]` §2.11. Only the property types this phase's
+ * planned ROP handlers actually need are implemented (`readPropertyValue`/`writePropertyValue` throw a clear
+ * error for anything else) - add more as a real handler needs them, not speculatively.
+ *
+ * Numeric values and member names (`Ptyp*`) are exactly as published in `[MS-OXCDATA]`'s "Property Data
+ * Types" table - the full `Ptyp`-prefixed spec names are used rather than shorter aliases (`String`,
+ * `Boolean`, ...) both for fidelity to the spec and because those shorter names collide with this project's
+ * lint config's `id-denylist` rule (which exists to stop primitive-wrapper-like names shadowing globals).
+ */
+export declare enum PropertyType {
+    PtypNull = 1,
+    PtypInteger16 = 2,
+    PtypInteger32 = 3,
+    PtypFloating32 = 4,
+    PtypFloating64 = 5,
+    PtypBoolean = 11,
+    PtypInteger64 = 20,
+    PtypString8 = 30,
+    PtypString = 31,
+    PtypTime = 64,
+    PtypGuid = 72,
+    PtypBinary = 258,
+    PtypMultipleInteger32 = 4099,
+    PtypMultipleString8 = 4126,
+    PtypMultipleString = 4127,
+    PtypMultipleBinary = 4354
+}
+export interface PropertyTag {
+    propertyId: number;
+    propertyType: PropertyType;
+}
+export interface TypedPropertyValue {
+    propertyType: PropertyType;
+    value: PropertyValueData;
+}
+export interface TaggedPropertyValue {
+    propertyId: number;
+    propertyType: PropertyType;
+    value: PropertyValueData;
+}
+export type PropertyValueData = number | bigint | boolean | string | Buffer | Date | string[] | number[] | Buffer[];
+/**
+ * `PropertyTag` structure (`[MS-OXCDATA]` §2.9): a 4-byte value with **`PropertyType` in the low-order 16
+ * bits and `PropertyId` in the high-order 16 bits** - confirmed against the spec's own bit-range description
+ * and cross-checked against the well-known real property-tag constant `PR_SUBJECT = 0x0037001F` (`PidTagSubject`
+ * = property ID `0x0037`, `PtypString` = type `0x001F`), which only decodes correctly with `PropertyType` as
+ * 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. */
+export declare function readTypedPropertyValue(reader: BufferReader): TypedPropertyValue;
+export declare function writeTypedPropertyValue(writer: BufferWriter, typed: TypedPropertyValue): void;
+/** `TaggedPropertyValue` structure (`[MS-OXCDATA]` §2.11.4, confirmed via `RopSetProperties`'s own request-buffer
+ * page): a full `PropertyTag` (4 bytes - `PropertyId` **and** `PropertyType`, unlike `TypedPropertyValue`'s bare
+ * `PropertyType`) followed by the value itself. Used where a property's identity can't be inferred from
+ * context (e.g. `RopSetProperties`, which sets an arbitrary, client-chosen set of properties in one call). */
+export declare function readTaggedPropertyValue(reader: BufferReader): TaggedPropertyValue;
+export declare function writeTaggedPropertyValue(writer: BufferWriter, tagged: TaggedPropertyValue): void;
+/**
+ * Reads a bare `PropertyValue` (`[MS-OXCDATA]` §2.11.2) of the given, already-known `type`. `PtypBinary`'s
+ * length prefix is 16 bits and every `PtypMultiple*`'s value count is 32 bits wide, per the spec's explicit
+ * "in the context of ROP buffers" sizing rule - the only context every planned caller of this function
+ * operates in (the wider 32-bit `PtypBinary` count only applies to extended rules / a specific MAPI/HTTP
+ * structure this library doesn't implement).
+ */
+export declare function readPropertyValue(reader: BufferReader, type: PropertyType): PropertyValueData;
+export declare function writePropertyValue(writer: BufferWriter, type: PropertyType, value: PropertyValueData): void;
+/** Converts a `PtypTime` value (100-ns intervals since 1601-01-01) into a JS `Date`. Sub-millisecond
+ * precision is truncated - `Date` has no finer resolution, a real, bounded, documented gap. */
+export declare function filetimeToDate(filetime: bigint): Date;
+/** Converts a JS `Date` into a `PtypTime` value (100-ns intervals since 1601-01-01). */
+export declare function dateToFiletime(date: Date): bigint;

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

@@ -0,0 +1,32 @@
+/**
+ * The outer `ROP input/output buffer` framing (`[MS-OXCROPS]` §2.2.1): `RopSize` (2 bytes, the size of
+ * itself plus `RopsList`) + `RopsList` (variable) + `ServerObjectHandleTable` (the remaining bytes, each a
+ * 32-bit Server object handle referenced by index from within the ROPs).
+ *
+ * Deliberately **ROP-agnostic**: `RopsList` is a concatenated sequence of individual ROP request/response
+ * buffers with no per-ROP length prefix (unlike WBXML's tag-based self-description) - each ROP's own byte
+ * layout is bespoke and keyed by its leading `RopId` byte, so splitting `RopsList` into individual ROPs
+ * requires ROP-specific decode logic this generic framing codec can't provide. A `RopDispatcher` (a later
+ * build step, once real `RopHandler`s exist) walks `ropsList` with a `BufferReader`, reading each ROP's
+ * `RopId` and delegating to the matching handler, which itself knows how many bytes its own ROP consumes -
+ * exactly the same "handler owns its own wire format" division of responsibility `EasCommandHandler` already
+ * uses for EAS commands.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export interface RopBuffer {
+    /** Raw bytes of the concatenated ROP request/response entries (`RopsList`). */
+    ropsList: Buffer;
+    /** The `ServerObjectHandleTable` array - one 32-bit handle per referenced Server object, in the order
+     * 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;