@rapidmx/mapi-plugin 1.0.0-beta.10

package/dist/lib/codec/BufferCursor.js

@@ -0,0 +1,242 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * 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 class DecodeError extends RangeError {
+    constructor(message) {
+        super(message);
+        this.name = "DecodeError";
+    }
+}
+export class BufferReader {
+    constructor(buffer, offset = 0) {
+        this.buffer = buffer;
+        this.offset = offset;
+    }
+    get position() {
+        return this.offset;
+    }
+    get remaining() {
+        return this.buffer.length - this.offset;
+    }
+    hasMore() {
+        return this.offset < this.buffer.length;
+    }
+    /** Moves to `position` (backwards or forwards). Throws a `RangeError` for a position outside the buffer. */
+    seek(position) {
+        if (position < 0 || position > this.buffer.length) {
+            throw new RangeError(`BufferReader.seek(${position}): out of range (buffer length ${this.buffer.length}).`);
+        }
+        this.offset = position;
+    }
+    readUInt8() {
+        const value = this.buffer.readUInt8(this.offset);
+        this.offset += 1;
+        return value;
+    }
+    readInt16LE() {
+        const value = this.buffer.readInt16LE(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    readUInt16LE() {
+        const value = this.buffer.readUInt16LE(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    readInt32LE() {
+        const value = this.buffer.readInt32LE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    readUInt32LE() {
+        const value = this.buffer.readUInt32LE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    readFloatLE() {
+        const value = this.buffer.readFloatLE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    readDoubleLE() {
+        const value = this.buffer.readDoubleLE(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    readBigInt64LE() {
+        const value = this.buffer.readBigInt64LE(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    readBigUInt64LE() {
+        const value = this.buffer.readBigUInt64LE(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    /** 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) {
+        if (length < 0 || this.offset + length > this.buffer.length) {
+            throw new RangeError(`BufferReader.readBytes(${length}): out of range at offset ${this.offset} (buffer length ${this.buffer.length}).`);
+        }
+        const value = this.buffer.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return value;
+    }
+    /** 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() {
+        let end = this.offset;
+        while (end + 1 < this.buffer.length && !(this.buffer[end] === 0 && this.buffer[end + 1] === 0)) {
+            end += 2;
+        }
+        if (end + 1 >= this.buffer.length) {
+            throw new RangeError("BufferReader.readNullTerminatedUtf16LE(): no null terminator found before the end of the buffer.");
+        }
+        const value = this.buffer.toString("utf16le", this.offset, end);
+        this.offset = end + 2;
+        return value;
+    }
+    /** 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() {
+        let end = this.offset;
+        while (end < this.buffer.length && this.buffer[end] !== 0) {
+            end += 1;
+        }
+        if (end >= this.buffer.length) {
+            throw new RangeError("BufferReader.readNullTerminatedString8(): no null terminator found before the end of the buffer.");
+        }
+        const value = this.buffer.toString("utf-8", this.offset, end);
+        this.offset = end + 1;
+        return value;
+    }
+}
+/** 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 class BufferWriter {
+    constructor() {
+        this.chunks = [];
+        this.byteLength = 0;
+    }
+    /** The number of bytes written so far. */
+    get length() {
+        return this.byteLength;
+    }
+    push(...buffers) {
+        for (const buffer of buffers) {
+            this.chunks.push(buffer);
+            this.byteLength += buffer.length;
+        }
+    }
+    writeUInt8(value) {
+        const buf = Buffer.alloc(1);
+        buf.writeUInt8(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeInt16LE(value) {
+        const buf = Buffer.alloc(2);
+        buf.writeInt16LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeUInt16LE(value) {
+        const buf = Buffer.alloc(2);
+        buf.writeUInt16LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeInt32LE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeInt32LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeUInt32LE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeUInt32LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeFloatLE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeFloatLE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeDoubleLE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeDoubleLE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeBigInt64LE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeBigInt64LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeBigUInt64LE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeBigUInt64LE(value, 0);
+        this.push(buf);
+        return this;
+    }
+    writeBytes(value) {
+        this.push(value);
+        return this;
+    }
+    writeNullTerminatedUtf16LE(value) {
+        this.push(Buffer.from(value, "utf16le"), Buffer.from([0x00, 0x00]));
+        return this;
+    }
+    writeNullTerminatedString8(value) {
+        this.push(Buffer.from(value, "utf-8"), Buffer.from([0x00]));
+        return this;
+    }
+    toBuffer() {
+        return Buffer.concat(this.chunks);
+    }
+}
+//# sourceMappingURL=BufferCursor.js.map

package/dist/lib/codec/BufferCursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BufferCursor.js","sourceRoot":"","sources":["../../../src/codec/BufferCursor.ts"],"names":[],"mappings":"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"}

package/dist/lib/codec/GlobalObjectId.js

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { BufferWriter } from "./BufferCursor.js";
+import { dateToFiletime } from "./PropertyValue.js";
+/**
+ * Encodes/decodes `CalendarEvent.icalUid` to/from the `GlobalObjectId` BLOB carried by `PidLidGlobalObjectId`
+ * (`[MS-OXOCAL]` §2.2.1.27, confirmed field-by-field this session): `ByteArrayID(16, a fixed spec constant)
+ * +YH(1)+YL(1)+M(1)+D(1)+CreationTime(8,FILETIME)+X(8,reserved,zero)+Size(4)+Data(variable, Size bytes)` - 40
+ * fixed header bytes followed by `Data`.
+ *
+ * **This server never actually embeds a `GlobalObjectId` in the invites it sends** - `RopSubmitMessageHandler
+ * .submitAppointment()`'s invite is a plain RFC 5546 `METHOD:REQUEST` iCalendar attachment relayed over SMTP,
+ * not a native MAPI Store object a real client reads `PidLidGlobalObjectId` off of directly; that iCalendar
+ * only ever carries a plain `UID:` line. A real Outlook client receiving it therefore always *synthesizes* its
+ * own `PidLidGlobalObjectId` from that bare iCalendar UID, using the `VCALID` form both `[MS-ASEMAIL]` §2.2.2.37
+ * and the equivalent `[MS-OXCICAL]` UID-conversion algorithm document: `Data` = the 8-byte ASCII marker
+ * `"vCal-Uid"`, then a 4-byte version (`01 00 00 00`), then the UID's own bytes, then one trailing `NUL` -
+ * **not** the bare UID bytes this codec originally assumed. `decodeGlobalObjectId` recognizes and unwraps this
+ * form (falling back to the hex form below only when the `vCal-Uid` marker isn't present, i.e. an
+ * `OutlookID` - a native-Exchange-generated `GlobalObjectId`, decoded to the hex form `[MS-OXCICAL]` gives its
+ * iCalendar UID). `encodeGlobalObjectId` now builds the same `VCALID` shape, both so
+ * a round trip through this codec models the real wire form and because `MeetingMessageClassHandler.test.ts`'s
+ * own test doubles need a realistic fixture to encode.
+ *
+ * **Pragmatic scope**: `YH`/`YL`/`M`/`D` (set when a `GlobalObjectId` identifies a single occurrence of a recurring
+ * series) are always encoded as `0` ("not an exception"); `globalObjectIdInstanceDate` reads them from a client's
+ * meeting response.
+ * `PidLidCleanGlobalObjectId` (the sibling property real Outlook also sets, identical structure but with
+ * `YH`/`YL`/`M`/`D` always zeroed) is therefore byte-identical to this codec's own output and needs no separate
+ * implementation - the same value serves both properties.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+/** `ByteArrayID` (`[MS-OXOCAL]` §2.2.1.27): a fixed 16-byte constant identifying this BLOB as a `GlobalObjectId`
+ * - the spec's own exact required byte sequence, not invented. */
+const BYTE_ARRAY_ID = Buffer.from([0x04, 0x00, 0x00, 0x00, 0x82, 0x00, 0xe0, 0x00, 0x74, 0xc5, 0xb7, 0x10, 0x1a, 0x82, 0xe0, 0x08]);
+/** `VCALID`'s own fixed 8-byte ASCII marker (`[MS-ASEMAIL]` §2.2.2.37's `VCALSTRING`) identifying `Data` as a
+ * `"vCal-Uid"`-wrapped UID rather than a native `OutlookID`'s raw bytes. */
+const VCAL_MARKER = Buffer.from("vCal-Uid", "ascii");
+/** `VCALID`'s own fixed 4-byte `VERSION` field - always this exact literal byte sequence, not a real version
+ * negotiated at runtime. */
+const VCAL_VERSION = Buffer.from([0x01, 0x00, 0x00, 0x00]);
+/** A `VCALID`'s minimum possible `Data` length: `VCAL_MARKER` (8) + `VCAL_VERSION` (4) + a zero-length UID (0)
+ * + the trailing `NUL` (1). */
+const VCAL_MIN_DATA_LENGTH = VCAL_MARKER.length + VCAL_VERSION.length + 1;
+/** 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 function encodeGlobalObjectId(icalUid, at) {
+    const data = Buffer.concat([VCAL_MARKER, VCAL_VERSION, Buffer.from(icalUid, "utf-8"), Buffer.from([0x00])]);
+    const writer = new BufferWriter();
+    writer.writeBytes(BYTE_ARRAY_ID);
+    writer.writeUInt8(0); // YH - not an exception, see class doc comment
+    writer.writeUInt8(0); // YL
+    writer.writeUInt8(0); // M
+    writer.writeUInt8(0); // D
+    writer.writeBigUInt64LE(dateToFiletime(at)); // CreationTime
+    writer.writeBytes(Buffer.alloc(8)); // X - reserved, MUST be zero
+    writer.writeUInt32LE(data.length); // Size
+    writer.writeBytes(data);
+    return writer.toBuffer();
+}
+/** 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 function decodeGlobalObjectId(reader) {
+    const byteArrayId = reader.readBytes(16);
+    if (!byteArrayId.equals(BYTE_ARRAY_ID)) {
+        throw new Error("GlobalObjectId: ByteArrayID did not match the required [MS-OXOCAL] constant.");
+    }
+    reader.readBytes(4); // YH/YL/M/D
+    const creationTimeAndReserved = reader.readBytes(16); // CreationTime + X
+    const sizeBytes = reader.readBytes(4);
+    const size = sizeBytes.readUInt32LE(0);
+    const data = reader.readBytes(size);
+    const isVCalId = size >= VCAL_MIN_DATA_LENGTH && data.subarray(0, 8).equals(VCAL_MARKER) && data.subarray(8, 12).equals(VCAL_VERSION);
+    if (isVCalId) {
+        // Strip the marker+version prefix and the trailing NUL, per [MS-ASEMAIL]'s own UID-length formula
+        // (BYTECOUNT minus the marker minus the version minus 1 byte for the NUL).
+        return data.subarray(12, data.length - 1).toString("utf-8");
+    }
+    return Buffer.concat([byteArrayId, Buffer.alloc(4), creationTimeAndReserved, sizeBytes, data]).toString("hex").toUpperCase();
+}
+/** 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 function globalObjectIdInstanceDate(globalObjectId) {
+    const year = (globalObjectId[16] << 8) | globalObjectId[17];
+    if (year === 0) {
+        return undefined;
+    }
+    return `${String(year).padStart(4, "0")}-${String(globalObjectId[18]).padStart(2, "0")}-${String(globalObjectId[19]).padStart(2, "0")}`;
+}
+//# sourceMappingURL=GlobalObjectId.js.map

package/dist/lib/codec/GlobalObjectId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalObjectId.js","sourceRoot":"","sources":["../../../src/codec/GlobalObjectId.ts"],"names":[],"mappings":"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"}

package/dist/lib/codec/MapiGuid.js

@@ -0,0 +1,41 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { BufferWriter } from "./BufferCursor.js";
+/**
+ * Encodes/decodes the 16-byte binary GUID layout `[MS-DTYP]`'s `GUID` structure defines and every MAPI wire
+ * structure that embeds a GUID (EntryIDs, `PidTagStoreRecordKey`, `PtypGuid` property values, property set
+ * IDs) uses: `Data1`/`Data2`/`Data3` in little-endian order, followed by `Data4`'s 8 bytes unchanged (the same
+ * order they appear in a standard textual GUID's last two hyphen-separated groups). This is distinct from a
+ * plain RFC 4122 UUID's all-big-endian textual byte order, so a generic UUID library's byte form can't be
+ * reused directly - hand-built here, same "no library, build the wire format precisely" precedent as the
+ * WBXML codec and the Autodiscover XML helpers.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+const GUID_STRING_PATTERN = /^([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})$/i;
+/** Encodes a standard hyphenated GUID/UUID string into its 16-byte MS wire form. */
+export function encodeGuid(guid) {
+    const match = GUID_STRING_PATTERN.exec(guid);
+    if (!match) {
+        throw new Error(`Invalid GUID string: ${guid}`);
+    }
+    const [, data1, data2, data3, data4a, data4b] = match;
+    const writer = new BufferWriter();
+    writer.writeUInt32LE(parseInt(data1, 16));
+    writer.writeUInt16LE(parseInt(data2, 16));
+    writer.writeUInt16LE(parseInt(data3, 16));
+    writer.writeBytes(Buffer.from(data4a + data4b, "hex"));
+    return writer.toBuffer();
+}
+/** Decodes a 16-byte MS wire-form GUID (read from `reader`'s current position) into a standard hyphenated
+ * GUID/UUID string. */
+export function decodeGuid(reader) {
+    const data1 = reader.readUInt32LE().toString(16).padStart(8, "0");
+    const data2 = reader.readUInt16LE().toString(16).padStart(4, "0");
+    const data3 = reader.readUInt16LE().toString(16).padStart(4, "0");
+    const data4 = reader.readBytes(8).toString("hex");
+    return `${data1}-${data2}-${data3}-${data4.slice(0, 4)}-${data4.slice(4)}`;
+}
+//# sourceMappingURL=MapiGuid.js.map

package/dist/lib/codec/MapiGuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapiGuid.js","sourceRoot":"","sources":["../../../src/codec/MapiGuid.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAgB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GAAG,2EAA2E,CAAC;AAExG,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAC,IAAY;IACnC,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IAEtD,MAAM,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;IAClC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAED;uBACuB;AACvB,MAAM,UAAU,UAAU,CAAC,MAAoB;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/E,CAAC"}

package/dist/lib/codec/MapiTimeZone.js

@@ -0,0 +1,126 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { BufferWriter } from "./BufferCursor.js";
+/**
+ * Encodes/decodes `CalendarEvent.timezone` (a plain IANA zone identifier) to/from `PidLidTimeZoneStruct`'s
+ * `TimeZoneStruct` BLOB (`[MS-OXOCAL]` §2.2.1.39, confirmed field-by-field this session, including a real
+ * worked example: `lBias(4,LONG)+lStandardBias(4,LONG)+lDaylightBias(4,LONG)+wStandardYear(2,WORD)+
+ * stStandardDate(16,SYSTEMTIME)+wDaylightYear(2,WORD)+stDaylightDate(16,SYSTEMTIME)` = 48 bytes total, all
+ * little-endian. `SYSTEMTIME` (`[MS-DTYP]`) is 8 `WORD` fields (`wYear`/`wMonth`/`wDayOfWeek`/`wDay`/`wHour`/
+ * `wMinute`/`wSecond`/`wMilliseconds`), 16 bytes.
+ *
+ * This is deliberately the older, simpler `TimeZoneStruct` - not the newer `TimeZoneDefinition`/
+ * `PidLidAppointmentTimeZoneDefinitionStartDisplay`, which additionally encodes named DST transition rules.
+ *
+ * **Pragmatic scope, matching the same limits `CalendarSyncAdapter` (EAS) already carries for timezones**:
+ * - `"UTC"` encodes as an all-zero struct (no bias, no DST) - the spec-legitimate representation of "no offset,
+ * no DST".
+ * - Any other IANA zone is approximated as a **fixed-offset** zone: `lBias` is derived from that zone's actual
+ * UTC offset at the given reference instant (via `Intl`), with `lStandardBias`/`lDaylightBias` always `0` and
+ * both `SYSTEMTIME` transition dates all-zero (`wMonth=0`, the spec's own documented way to say "this zone
+ * does not observe daylight saving time"). **This is wrong across a real DST boundary** for a zone that
+ * actually observes DST - a real client will show the correct offset only for occurrences near the reference
+ * instant used at encode time, not a spec violation but a real, documented fidelity gap.
+ * - Decoding a struct back into an IANA identifier is fundamentally lossy (a bias alone doesn't identify a
+ * unique zone name) - this codec resolves a whole-hour offset to a synthetic-but-valid `Etc/GMT±N` IANA identifier
+ * (note the IANA `Etc/GMT` area's own sign convention is POSIX-inverted from common usage: `Etc/GMT+8` means UTC-8,
+ * not UTC+8). A half-hour/quarter-hour offset keeps its minutes: it maps to a real DST-less zone with that offset
+ * (e.g. `Asia/Kolkata`, `Asia/Kathmandu`) or otherwise to a fixed-offset identifier like `"-03:30"`. An offset
+ * outside UTC-12..UTC+14 decodes as `"UTC"`.
+ * - Encoding a zone `Intl` doesn't recognize falls back to UTC instead of throwing.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+const SYSTEMTIME_FIELD_COUNT = 8;
+function writeZeroTransitionBlock(writer) {
+    writer.writeUInt16LE(0); // wStandardYear / wDaylightYear
+    for (let i = 0; i < SYSTEMTIME_FIELD_COUNT; i++) {
+        writer.writeUInt16LE(0);
+    }
+}
+function skipTransitionBlock(reader) {
+    reader.readUInt16LE(); // wStandardYear / wDaylightYear
+    for (let i = 0; i < SYSTEMTIME_FIELD_COUNT; i++) {
+        reader.readUInt16LE();
+    }
+}
+/** The zone's UTC offset in minutes at instant `at` (standard convention: local minus UTC, e.g. `-480` for
+ * `America/Los_Angeles` in winter), read via `Intl`'s `shortOffset` formatting rather than hand-rolling a
+ * zone database. Throws the same way `Intl.DateTimeFormat` itself does for an unrecognized zone identifier. */
+function utcOffsetMinutes(timezone, at) {
+    const formatter = new Intl.DateTimeFormat("en-US", { timeZone: timezone, timeZoneName: "shortOffset" });
+    // `formatToParts` always includes a "timeZoneName" part when `timeZoneName` is requested in the
+    // formatter's own options, so the non-null assertion below reflects a real `Intl` guarantee, not an
+    // unverified assumption.
+    const tzName = formatter.formatToParts(at).find((part) => part.type === "timeZoneName").value;
+    const match = /^GMT([+-])(\d+)(?::(\d+))?$/.exec(tzName);
+    if (!match) {
+        return 0; // Bare "GMT", i.e. UTC itself.
+    }
+    const sign = match[1] === "-" ? -1 : 1;
+    const hours = parseInt(match[2], 10);
+    const minutes = match[3] ? parseInt(match[3], 10) : 0;
+    return sign * (hours * 60 + minutes);
+}
+/** 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 function encodeTimeZoneStruct(timezone, at) {
+    const writer = new BufferWriter();
+    let bias = 0;
+    try {
+        bias = timezone === "UTC" ? 0 : -utcOffsetMinutes(timezone, at);
+    }
+    catch {
+        // An identifier Intl doesn't recognize (e.g. stored by another client) is sent as UTC rather than failing
+        // the whole property read.
+        bias = 0;
+    }
+    writer.writeInt32LE(bias); // lBias
+    writer.writeInt32LE(0); // lStandardBias - no DST modeled
+    writer.writeInt32LE(0); // lDaylightBias - no DST modeled
+    writeZeroTransitionBlock(writer); // wStandardYear + stStandardDate
+    writeZeroTransitionBlock(writer); // wDaylightYear + stDaylightDate
+    return writer.toBuffer();
+}
+/** 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 function decodeTimeZoneStruct(reader) {
+    const bias = reader.readInt32LE();
+    reader.readInt32LE(); // lStandardBias - not reconstructable into a real DST rule, ignored
+    reader.readInt32LE(); // lDaylightBias - ditto
+    skipTransitionBlock(reader); // wStandardYear + stStandardDate
+    skipTransitionBlock(reader); // wDaylightYear + stDaylightDate
+    const offsetMinutes = -bias;
+    // No real zone is further than UTC-12/UTC+14; anything else is garbage and treated as UTC.
+    if (offsetMinutes === 0 || offsetMinutes < -12 * 60 || offsetMinutes > 14 * 60) {
+        return "UTC";
+    }
+    if (offsetMinutes % 60 === 0) {
+        const hours = offsetMinutes / 60;
+        return `Etc/GMT${hours < 0 ? "+" : "-"}${Math.abs(hours)}`;
+    }
+    return FRACTIONAL_OFFSET_ZONES[offsetMinutes] ?? formatFixedOffset(offsetMinutes);
+}
+/** Real zones with a non-whole-hour offset and no daylight saving, so the zone matches a DST-less
+ * `TimeZoneStruct` all year. */
+const FRACTIONAL_OFFSET_ZONES = {
+    [-570]: "Pacific/Marquesas",
+    210: "Asia/Tehran",
+    270: "Asia/Kabul",
+    330: "Asia/Kolkata",
+    345: "Asia/Kathmandu",
+    390: "Asia/Yangon",
+    525: "Australia/Eucla",
+    570: "Australia/Darwin",
+};
+/** A fixed-offset identifier such as `"-03:30"`, which `Intl.DateTimeFormat` accepts as a `timeZone`. Used for a
+ * minute-precision offset with no matching DST-less zone, instead of rounding it to a whole hour. */
+function formatFixedOffset(offsetMinutes) {
+    const magnitude = Math.abs(offsetMinutes);
+    const hours = String(Math.floor(magnitude / 60)).padStart(2, "0");
+    const minutes = String(magnitude % 60).padStart(2, "0");
+    return `${offsetMinutes < 0 ? "-" : "+"}${hours}:${minutes}`;
+}
+//# sourceMappingURL=MapiTimeZone.js.map

package/dist/lib/codec/MapiTimeZone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapiTimeZone.js","sourceRoot":"","sources":["../../../src/codec/MapiTimeZone.ts"],"names":[],"mappings":"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"}