@rapidmx/mapi-plugin 1.0.0-beta.3

package/dist/types/BaseMapiEmsmdbRoute.d.ts

@@ -0,0 +1,82 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { Mailbox } from "@rapidmx/restapi";
+/**
+ * Abstract base for the single fixed EMSMDB endpoint (`POST /mapi/emsmdb` by `[MS-OXCMAPIHTTP]` convention,
+ * though the concrete path is left to the consuming application to mount via `@Route(...)` - see
+ * `BaseEasRoute.ts` for the identical undecorated-base-class pattern this follows). Like EAS, MAPI/HTTP
+ * multiplexes several request types against one URL - here via the `X-RequestType` **header**
+ * (`Connect`/`Execute`/`Disconnect`/`NotificationWait`) rather than a query parameter - so there is exactly
+ * one `@Post()` method, not one per request type.
+ *
+ * **Auth**: `@Auth(["jwt"])` - unchanged from every other route in this app. Real, modern Exchange Server's
+ * own MAPI virtual directory genuinely supports `OAuth` as a configured `IISAuthenticationMethods` value
+ * alongside `NTLM`/`Negotiate`, so Bearer-token auth on this exact endpoint is real current Exchange
+ * behavior, not a deviation this library invents - see the architecture plan's "Auth" section.
+ *
+ * **Connect/Disconnect are complete**: `Connect` establishes a real `MapiSessionContext` (via
+ * `MapiSessionManager`) and sets the two spec-fixed session cookies (`MapiContext`/`MapiSequence`);
+ * `Disconnect` releases the session. **`Execute` dispatches real ROPs** (starting with `RopLogon`/`RopRelease`
+ * - build-order step 4) via `RopDispatcher`, using whichever `RopHandler`s `ropHandlerClasses` registers;
+ * an unrecognized `RopId` simply stops processing (see `RopDispatcher`'s own doc comment for why), the same
+ * "real, functional, no commands implemented yet" stance `BaseEasRoute`'s own skeleton step took for its
+ * empty `commandHandlerClasses` before `ProvisionCommand` landed - here scoped per-ROP instead of per-request.
+ *
+ * **Always non-chunked**: every response here uses `Content-Length` (via `res.status(200).send(buffer)`),
+ * never `Transfer-Encoding: chunked` - both are equally spec-valid per `[MS-OXCMAPIHTTP]`'s own "Common
+ * Response Format", and skipping the `PROCESSING`/`PENDING`/`DONE` keep-alive meta-tag streaming matches
+ * every other route in this library's own response idiom. See the architecture plan's "Protocol facts"
+ * section for the full reasoning and its documented limitation.
+ *
+ * `mailboxClass`/`folderClass` are supplied by the Mongo/SQL concrete subclasses, following the exact
+ * one-line-per-backend pattern used throughout this library's other routes/jobs. `folderRepo` is built once
+ * here (not per-handler, unlike EAS's per-command repo pattern) and threaded through `RopContext` to every
+ * `RopHandler` - see `RopHandler.ts`'s own doc comment for why.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class BaseMapiEmsmdbRoute<M extends Mailbox> {
+    protected abstract mailboxClass: any;
+    protected abstract folderClass: any;
+    protected abstract messageClass: any;
+    protected abstract calendarEventClass: any;
+    protected abstract contactClass: any;
+    protected abstract taskClass: any;
+    protected abstract labelClass: any;
+    /** ROP handler classes to instantiate (one each) in `@Init`, keyed by their own `ropId`. Empty until a
+     * concrete `RopHandler` lands - every ROP is then simply left unprocessed (see `RopDispatcher`'s own doc
+     * comment), the correct, honest behavior for a transport skeleton with no ROPs implemented yet. */
+    protected ropHandlerClasses: any[];
+    private _objectFactory?;
+    private mailboxRepo?;
+    private folderRepo?;
+    private messageRepo?;
+    private calendarEventRepo?;
+    private contactRepo?;
+    private taskRepo?;
+    private labelRepo?;
+    private sessionManager?;
+    private readonly ropHandlers;
+    private blobStore?;
+    private scanPipeline?;
+    private mailTransport?;
+    private logger;
+    init(): Promise<void>;
+    dispatch(req: HttpRequest, res: HttpResponse, user?: JWTUser): Promise<void>;
+    /**
+     * `Connect` establishes a new Session Context - never trusts the request body's own `UserDn` field for
+     * mailbox identity (the same "never a client-supplied mailbox, always resolved from the authenticated
+     * JWT" principle `BaseEasRoute`/`BaseSearchRoute` already apply via `resolveCallerMailboxUid`) - so the
+     * request body is never decoded at all here.
+     */
+    private handleConnect;
+    /**
+     * `Execute` decodes the outer envelope (`Flags`/`RopBufferSize`/`RopBuffer`/...) and the inner ROP buffer
+     * framing (`RopBuffer.ts`), dispatches every contained ROP via `RopDispatcher`, and re-encodes the
+     * collected responses - preserving the incoming `handleTable` unchanged (this pragmatic subset never
+     * allocates/frees table-wide handle slots at the framing level; individual `RopHandler`s manage their own
+     * entries within `session.handles` instead).
+     */
+    private handleExecute;
+    private handleDisconnect;
+}

package/dist/types/BaseMapiNspiRoute.d.ts

@@ -0,0 +1,38 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { Mailbox } from "@rapidmx/restapi";
+/**
+ * Abstract base for the single fixed NSPI endpoint (`POST /mapi/nspi` by `[MS-OXCMAPIHTTP]` convention, though
+ * the concrete path is left to the consuming application to mount via `@Route(...)`, the identical
+ * undecorated-base-class pattern `BaseMapiEmsmdbRoute`/`BaseEasRoute` already establish). Dispatches on the
+ * `X-RequestType` header, the same multiplexing mechanism EMSMDB uses - but unlike EMSMDB, there is no ROP
+ * buffer framing here: each `X-RequestType` value (`Bind`/`Unbind`/`GetMatches`) is its own flat, self-
+ * contained request/response body (`[MS-OXCMAPIHTTP]` §2.2.5), so this route dispatches directly to a small
+ * handler function per operation instead of decoding a multiplexed stream.
+ *
+ * **Pragmatic subset scope**: only `Bind`/`Unbind`/`GetMatches` are implemented - real NSPI's other dozen-plus
+ * request types (`QueryRows`, `ResolveNames`, `GetProps`, `ModProps`, ...) are genuine full address-book/
+ * directory-replication operations this deployment's own minimal GAL-lookup use case doesn't need; an
+ * unrecognized `X-RequestType` gets a `501`, the same "recognized-but-deferred vs malformed" distinction
+ * `BaseMapiEmsmdbRoute`'s own `NotificationWait` case already draws. See `NspiBindHandler.ts`'s own doc comment
+ * for why no real NSPI session state is created or tracked between calls.
+ *
+ * **Auth**: `@Auth(["jwt"])`, unchanged from every other route in this app - the same reasoning
+ * `BaseMapiEmsmdbRoute`'s own doc comment already gives for why Bearer-token auth on an address-book endpoint
+ * is real, current Exchange behavior, not a deviation this library invents.
+ *
+ * `mailboxClass`/`contactClass` are supplied by the Mongo/SQL concrete subclasses. GAL search itself (see
+ * `NspiGetMatchesHandler.ts`) uses `RepoUtils`'s `regex(...)` operator, which compiles identically on both
+ * backends - no per-backend hook needed here.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class BaseMapiNspiRoute<M extends Mailbox> {
+    protected abstract mailboxClass: any;
+    protected abstract contactClass: any;
+    private _objectFactory?;
+    private mailboxRepo?;
+    private contactRepo?;
+    init(): Promise<void>;
+    dispatch(req: HttpRequest, res: HttpResponse, user?: JWTUser): Promise<void>;
+}

package/dist/types/MapiSessionManager.d.ts

@@ -0,0 +1,130 @@
+import { SimpleEntity } from "@rapidrest/service-core";
+/** 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 `rows`/`columns`/`cursor` hold `RopGetHierarchyTable`/`RopSetColumns`/`RopQueryRows`
+ * state for that specific table instance: `rows` is the resolved, order-fixed list of entity targets (same
+ * `"virtual:<name>"`/`"folder:<uid>"` format) this table enumerates, `columns` the `RopSetColumns`-configured
+ * property list, `cursor` how many rows `RopQueryRows` has already returned. 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-mode stream) or `writeTargetHandleIndex`/`writeBufferBase64` the accumulated write state (a write-mode
+ * stream opened `ReadWrite`/`Create` against a `RopCreateMessage` draft's `PidTagBody` - see
+ * `RopOpenStreamHandler`'s own doc comment).
+ *
+ * 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). `writeBufferBase64`
+ * stores accumulated `RopWriteStream` bytes as base64 rather than a raw `Buffer` for the same reason `Date`
+ * fields elsewhere in this class are stored as ISO strings: `RedisCache`'s Redis-backed path round-trips
+ * everything through `JSON.stringify`/`JSON.parse`, which cannot represent a `Buffer` (or a `bigint`, which is
+ * why no property value is ever stored in its native decoded MAPI type here) losslessly.
+ *
+ * A `"fastTransfer"` handle (`RopFastTransferSourceCopyTo`/`CopyProperties`'s output handle) carries the
+ * entire pre-built FastTransfer stream eagerly (`transferBufferBase64`, same base64-for-`RedisCache` reasoning
+ * as `writeBufferBase64`) - this pragmatic subset builds the whole stream up front rather than truly
+ * incrementally, since a real client only ever pages it out via `RopFastTransferSourceGetBuffer`'s own
+ * `transferPosition` cursor into that already-complete buffer, see `FastTransferStream.ts`'s own doc comment. */
+export interface MapiObjectHandle {
+    type: "logon" | "folder" | "message" | "table" | "stream" | "fastTransfer";
+    entityUid: string;
+    rows?: string[];
+    columns?: {
+        propertyId: number;
+        propertyType: number;
+    }[];
+    cursor?: number;
+    propertyId?: number;
+    propertyType?: number;
+    streamPosition?: number;
+    draftFolderUid?: string;
+    draftProperties?: Record<string, string>;
+    writeTargetHandleIndex?: number;
+    writeBufferBase64?: string;
+    transferBufferBase64?: string;
+    transferPosition?: number;
+}
+/**
+ * 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 cache entry (see `MapiSessionManager` below), so this deliberately extends `SimpleEntity` (just a
+ * `uid`) rather than this library's own `BaseEntity`, which would add ACL/soft-delete/optimistic-locking
+ * machinery this object has no use for.
+ *
+ * `createdAt` is a plain ISO-8601 string, not a `Date` - `RedisCache`'s Redis-backed path round-trips values
+ * through `JSON.stringify`/`JSON.parse`, which silently turns a `Date` into a string on the way out without
+ * reviving it back to a `Date` on the way in; storing it as a string from the start keeps the shape identical
+ * whether a session happens to be served from the in-memory or the Redis-backed path.
+ */
+export declare class MapiSessionContext extends SimpleEntity {
+    mailboxUid: string;
+    userUid: string;
+    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 - see `assignOrGetFid`'s own
+     * doc comment for why the scan this replaces was a genuine (not just theoretical) quadratic cost across a
+     * session's lifetime. Small and purely additive to session state (one more string-keyed map of numbers,
+     * the same order of magnitude as `folderIds` itself), unlike caching whole resolved rows would be. */
+    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. Unlike `folderIds` (pre-populated by `RopLogon`), 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 - the message analog of
+     * `folderTargetIds`/`nextFolderId` above, for the identical O(1)-lookup reason. */
+    messageTargetIds: Record<string, number>;
+    nextMessageId: 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`'s own doc comment for why a JSON string (rather than a delimiter-joined one)
+     * is the safest key shape here. A real client resolves every named property (almost every Calendar-specific
+     * one - `PidLidAppointmentStartWhole`, `PidLidBusyStatus`, `PidLidAppointmentRecur`, ...) through this table
+     * once per session before ever setting/reading it via `RopSetProperties`/`RopGetPropertiesSpecific`. */
+    namedProperties: Record<string, number>;
+    /** The reverse of `namedProperties` (numeric ID -> `PropertyName` JSON key) plus a monotonic counter -
+     * `NamedPropertyRegistry.ts`'s own doc comment covers why both the O(n) forward scan this replaces and the
+     * `Math.max(...spread)` id-allocation it used are real problems, not just theoretical ones, at real
+     * mailbox/session scale. */
+    namedPropertyIds: Record<number, string>;
+    nextNamedPropertyId: number;
+    /** `mailboxUid`/`userUid` are always known at construction time (the only call site is
+     * `MapiSessionManager.create()`, which resolves both up front) - required here rather than optional with
+     * a same-value fallback, which would just be dead code no real caller ever takes the other branch of. */
+    constructor(other: Partial<SimpleEntity> & {
+        mailboxUid: string;
+        userUid: string;
+    });
+}
+/**
+ * Stores/loads `MapiSessionContext`s, keyed by the opaque session id that also becomes the `MapiContext`
+ * cookie value. Reuses `@rapidrest/service-core`'s existing generic `RedisCache<T>` (Redis-backed when a
+ * `cache` datastore is configured, transparent in-memory fallback otherwise) rather than either a bespoke
+ * Redis client (unlike `PingCommand`'s own throwaway pub/sub client - fine for ephemeral fan-out, not a good
+ * fit for stateful session data) or the framework's generic cookie/session middleware (built for a whole-app
+ * `req.session` object, not this protocol's specific handle-table shape). `RedisCache` needs no real
+ * persisted entity - only a class with a `.name` for its Redis key prefix - so a purely ephemeral,
+ * never-persisted class like `MapiSessionContext` is a perfectly valid `type` for it.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MapiSessionManager {
+    private _objectFactory?;
+    private cache?;
+    init(): Promise<void>;
+    create(mailboxUid: string, userUid: string): Promise<MapiSessionContext>;
+    load(sessionId: string): Promise<MapiSessionContext | undefined>;
+    save(context: MapiSessionContext): Promise<void>;
+    destroy(sessionId: string): Promise<void>;
+}

package/dist/types/RopDispatcher.d.ts

@@ -0,0 +1,17 @@
+import type { RopContext, RopHandler } from "./rop/RopHandler.js";
+/**
+ * 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.
+ *
+ * An unrecognized `RopId` stops processing immediately: the bytes belonging to that ROP (and everything after
+ * it) can't be skipped without knowing that ROP's own layout, so there is no safe way to resync and continue.
+ * This is an inherent constraint of the wire format, not a design choice this library is choosing not to
+ * handle - a real client only ever sends ROPs the server has already told it (via its supported-command
+ * surface) that it understands.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare function dispatchRops(ropsList: Buffer, handlers: Map<number, RopHandler>, context: RopContext): 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,78 @@
+/**
+ * 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
+ */
+export declare class BufferReader {
+    private readonly buffer;
+    private offset;
+    constructor(buffer: Buffer, offset?: number);
+    get position(): number;
+    get remaining(): number;
+    hasMore(): boolean;
+    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;
+    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,11 @@
+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 was
+ * built from - unwrapping the `VCALID` form (see this file's own doc comment) when `Data` carries the
+ * `"vCal-Uid"` marker, falling back to treating `Data` as bare `OutlookID` bytes otherwise. 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;

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,77 @@
+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;
+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,25 @@
+/**
+ * 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[];
+}
+export declare function encodeRopBuffer(buf: RopBuffer): Buffer;
+export declare function decodeRopBuffer(buffer: Buffer): RopBuffer;

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

@@ -0,0 +1,17 @@
+import type { BufferReader, BufferWriter } from "./BufferCursor.js";
+/**
+ * `TypedString` (`[MS-OXCDATA]` §2.11.7): a leading `StringType` byte followed by an optional string in the
+ * format that byte names - used by `RopOpenMessage`'s success response (`SubjectPrefix`/`NormalizedSubject`).
+ * `writeTypedString` never produces the "reduced Unicode" (`0x03`) form - that's purely a wire-size
+ * optimization real Exchange applies when every character happens to fit in one byte, not something a peer is
+ * ever required to send, so this codec always writes plain UTF-16LE (`0x04`) for non-empty strings. `undefined`
+ * writes as "no string" (`0x00`), matching a field the spec allows to be entirely absent (e.g. no subject
+ * prefix at all, as opposed to an empty one).
+ */
+export declare function writeTypedString(writer: BufferWriter, value: string | undefined): void;
+/** Reads a `TypedString`, supporting every `StringType` value a peer could legally send (`0x00`-`0x04`) even
+ * though `writeTypedString` only ever produces `0x00`/`0x01`/`0x04` itself - this side of the codec is only
+ * ever exercised in this library's own round-trip tests, since a real MAPI/HTTP client never sends a
+ * `TypedString` value to the server. Returns `undefined` for `StringType = 0x00` ("no string"), matching
+ * `writeTypedString`'s own `undefined` input. */
+export declare function readTypedString(reader: BufferReader): string | undefined;

package/dist/types/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MAPI-over-HTTP protocol compatibility (Phase 3 of this library's roadmap): a hand-built ROP (Remote
+ * Operation) codec and buffer-framing layer (`[MS-OXCROPS]`), JWT-secured EMSMDB transport (`BaseMapiEmsmdbRoute`,
+ * reusing the framework's existing `@Auth(["jwt"])` strategy - no MAPI-specific auth code of its own), and a
+ * minimal NSPI address-book endpoint (`BaseMapiNspiRoute`) for GAL "search as you type" lookups.
+ *
+ * This module exports only the backend-agnostic surface: the wire-format codecs, the abstract route base
+ * classes, `MapiSessionManager`, the ROP dispatcher, and every ROP/NSPI handler class (each takes a generic
+ * `RopContext`/repo argument, not a concrete entity class, so none of them are backend-specific). The concrete
+ * Mongo/SQL classes a deployment actually instantiates (`MapiEmsmdbRouteMongo`/`SQL`,
+ * `MapiNspiRouteMongo`/`SQL`) are exported from this package's `./mongo`/`./sql` subpaths instead, alongside
+ * every other entity/route/job this library defines - see `src/eas/index.ts`'s identical doc comment for the
+ * same convention.
+ *
+ * A deployment mounts both MAPI endpoints with a trivial one-line subclass each, the same pattern
+ * `src/eas/index.ts`'s doc comment describes for `BaseEasRoute`:
+ * ```ts
+ * import { MapiEmsmdbRouteMongo, MapiNspiRouteMongo } from "@rapidrest/mail/mongo";
+ * import { RouteDecorators } from "@rapidrest/service-core";
+ * const { Route } = RouteDecorators;
+ *
+ * @Route("/mapi/emsmdb")
+ * export class MyMapiEmsmdbRoute extends MapiEmsmdbRouteMongo {}
+ *
+ * @Route("/mapi/nspi")
+ * export class MyMapiNspiRoute extends MapiNspiRouteMongo {}
+ * ```
+ * Real Outlook desktop locates both URLs via `@rapidrest/mail/autodiscover`'s Outlook/EXCH response
+ * (`BaseAutodiscoverRoute`'s `mapiUrl` property) - see that module's own doc comment.
+ *
+ * **Documented gaps in this pragmatic subset** (see the architecture plan's "MAPI over HTTP (Phase 3)" section
+ * for the full reasoning behind each):
+ * - Incremental sync (`RopFastTransferSourceCopyTo`/`CopyProperties`/`GetBuffer`) always builds a full,
+ *   non-differential dump, not real IDSET-based ICS (`[MS-OXCFXICS]`) - a real client still works correctly
+ *   against this, just less efficiently than byte-perfect ICS.
+ * - Calendar/meetings: no counter-proposals, meeting-forwarding, delegate scheduling, or resource-booking
+ *   auto-accept; no DST-aware timezones (fixed-offset approximation only); no recurrence exceptions/modified
+ *   instances; no Hijri/`MonthEnd` recurrence patterns.
+ * - No `RopModifyRecipients` - attendees/recipients are always added via the same `PidTagDisplayTo`/`Cc`
+ *   pragmatic path used for ordinary mail.
+ * - No public-folder support, no delegate/shared-mailbox access, no rules/permissions/search-folder ROPs, no
+ *   client-certificate enrollment.
+ * - Calendar named properties (location/recurrence/timezone/etc.) are excluded from FastTransfer streams -
+ *   only the columns in `FastTransferStream.ts`'s `DEFAULT_*_COLUMNS` tables are included.
+ * - NSPI is limited to `Bind`/`Unbind`/`GetMatches` only - no row/name lookups beyond a single content-
+ *   restriction search, no directory replication.
+ */
+export * from "./codec/BufferCursor.js";
+export * from "./codec/MapiGuid.js";
+export * from "./codec/TypedString.js";
+export * from "./codec/PropertyValue.js";
+export * from "./codec/RopBuffer.js";
+export * from "./codec/AppointmentRecurrence.js";
+export * from "./codec/MapiTimeZone.js";
+export * from "./codec/GlobalObjectId.js";
+export * from "./RopDispatcher.js";
+export * from "./MapiSessionManager.js";
+export * from "./BaseMapiEmsmdbRoute.js";
+export * from "./BaseMapiNspiRoute.js";
+export * from "./rop/RopHandler.js";
+export * from "./rop/FolderTarget.js";
+export * from "./rop/MessageTarget.js";
+export * from "./rop/CalendarEventTarget.js";
+export * from "./rop/MessageBodyStream.js";
+export * from "./rop/PropertyResolvers.js";
+export * from "./rop/NamedPropertyRegistry.js";
+export * from "./rop/CalendarNamedProperties.js";
+export * from "./rop/FastTransferStream.js";
+export * from "./rop/MeetingMessageClassHandler.js";
+export * from "./rop/RopLogonHandler.js";
+export * from "./rop/RopReleaseHandler.js";
+export * from "./rop/RopOpenFolderHandler.js";
+export * from "./rop/RopGetHierarchyTableHandler.js";
+export * from "./rop/RopSetColumnsHandler.js";
+export * from "./rop/RopQueryRowsHandler.js";
+export * from "./rop/RopGetContentsTableHandler.js";
+export * from "./rop/RopOpenMessageHandler.js";
+export * from "./rop/RopGetPropertiesSpecificHandler.js";
+export * from "./rop/RopOpenStreamHandler.js";
+export * from "./rop/RopReadStreamHandler.js";
+export * from "./rop/RopCreateMessageHandler.js";
+export * from "./rop/RopSetPropertiesHandler.js";
+export * from "./rop/RopWriteStreamHandler.js";
+export * from "./rop/RopSaveChangesMessageHandler.js";
+export * from "./rop/RopSubmitMessageHandler.js";
+export * from "./rop/RopGetPropertyIdsFromNamesHandler.js";
+export * from "./rop/RopDeleteMessagesHandler.js";
+export * from "./rop/RopDeleteFolderHandler.js";
+export * from "./rop/RopFastTransferSourceCopyToHandler.js";
+export * from "./rop/RopFastTransferSourceCopyPropertiesHandler.js";
+export * from "./rop/RopFastTransferSourceGetBufferHandler.js";
+export * from "./nspi/NspiCodec.js";
+export * from "./nspi/NspiBindHandler.js";
+export * from "./nspi/NspiGetMatchesHandler.js";

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

@@ -0,0 +1,19 @@
+import { MailboxMongo } from "@rapidmx/restapi/mongo";
+import { BaseMapiEmsmdbRoute } from "../BaseMapiEmsmdbRoute.js";
+/**
+ * Mongo-backed concrete `BaseMapiEmsmdbRoute`, mounted at `/mapi/emsmdb`. Exported from this plugin's
+ * `./mongo` entry point, so the server host mounts it without a wrapper class of its
+ * own.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class MapiEmsmdbRouteMongo extends BaseMapiEmsmdbRoute<MailboxMongo> {
+    protected mailboxClass: any;
+    protected folderClass: any;
+    protected messageClass: any;
+    protected calendarEventClass: any;
+    protected contactClass: any;
+    protected taskClass: any;
+    protected labelClass: any;
+    protected ropHandlerClasses: any[];
+}