@rapidmx/mapi-plugin 1.0.0-beta.3

package/dist/lib/codec/AppointmentRecurrence.js

@@ -0,0 +1,314 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { BufferWriter } from "./BufferCursor.js";
+import { RecurrenceFrequency } from "@rapidmx/restapi";
+/**
+ * Encodes/decodes `CalendarEvent.recurrenceRule` to/from the binary blob carried by `PidLidAppointmentRecur`
+ * (`[MS-OXOCAL]` §2.2.1.44: the outer `AppointmentRecurrencePattern` structure, §2.2.1.44.5, wrapping an inner
+ * `RecurrencePattern`, §2.2.1.44.1). Every field layout/size below was confirmed against those spec pages
+ * directly, not assumed.
+ *
+ * **Pragmatic scope, matching the same limits `CalendarSyncAdapter` (EAS) already carries**:
+ * - Only `RecurFrequency` Daily/Weekly/Monthly/Yearly and `PatternType` Day/Week/Month are produced or
+ * accepted - `MonthNth`/`MonthEnd`/Hijri patterns have no representation in `RecurrenceRule` (no ordinal-
+ * weekday field) and decoding one throws a clear, documented error rather than silently guessing.
+ * - `DeletedInstanceCount`/`ModifiedInstanceCount` (recurrence exceptions) and the outer structure's
+ * `ExceptionCount` are always written as `0`; decoding a nonzero value throws, since `RecurrenceRule` has no
+ * field to hold per-instance exceptions.
+ * - A `YEARLY` rule with `interval > 1` ("every N years", N>1) is encoded as `RecurFrequency=Monthly` with
+ * `Period=12*N`, per the spec's own stated rule that "a yearly recurrence pattern is just a monthly pattern
+ * that occurs every 12 months" (a plain `RecurFrequency=Yearly` value's `Period` MUST be exactly 12).
+ * **This is a one-way, documented round-trip asymmetry**: decoding that same blob back yields
+ * `{freq: MONTHLY, interval: 12*N}`, not the original `{freq: YEARLY, interval: N}` - the two are
+ * indistinguishable on the wire once encoded, the same ambiguity a real Exchange server itself has no way
+ * around either.
+ * - `StartTimeOffset`/`EndTimeOffset` (the outer structure) are derived from `startDate`/`endDate`'s own
+ * time-of-day only (`hours*60+minutes`), not carried through decode - the real start/end instant of any
+ * given occurrence comes from `PidLidAppointmentStartWhole`/`EndWhole`, not from this blob.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+/** `RecurFrequency` (`[MS-OXOCAL]` §2.2.1.44.1). */
+var RecurFrequencyWire;
+(function (RecurFrequencyWire) {
+    RecurFrequencyWire[RecurFrequencyWire["Daily"] = 8202] = "Daily";
+    RecurFrequencyWire[RecurFrequencyWire["Weekly"] = 8203] = "Weekly";
+    RecurFrequencyWire[RecurFrequencyWire["Monthly"] = 8204] = "Monthly";
+    RecurFrequencyWire[RecurFrequencyWire["Yearly"] = 8205] = "Yearly";
+})(RecurFrequencyWire || (RecurFrequencyWire = {}));
+/** `PatternType` (`[MS-OXOCAL]` §2.2.1.44.1) - only the 3 values this codec produces/accepts. */
+var PatternTypeWire;
+(function (PatternTypeWire) {
+    PatternTypeWire[PatternTypeWire["Day"] = 0] = "Day";
+    PatternTypeWire[PatternTypeWire["Week"] = 1] = "Week";
+    PatternTypeWire[PatternTypeWire["Month"] = 2] = "Month";
+})(PatternTypeWire || (PatternTypeWire = {}));
+/** `EndType` (`[MS-OXOCAL]` §2.2.1.44.1). */
+var EndTypeWire;
+(function (EndTypeWire) {
+    EndTypeWire[EndTypeWire["AfterDate"] = 8225] = "AfterDate";
+    EndTypeWire[EndTypeWire["AfterN"] = 8226] = "AfterN";
+    EndTypeWire[EndTypeWire["Never"] = 8227] = "Never";
+})(EndTypeWire || (EndTypeWire = {}));
+/** Sentinel `EndDate` value (`[MS-OXOCAL]` §2.2.1.44.1) meaning "never-ending". */
+const NEVER_END_DATE = 0x5ae980df;
+const MINUTES_PER_DAY = 1440;
+const MINUTES_PER_WEEK = 10080;
+/** `RecurrencePattern.CalendarType` `Default` value (Gregorian) - the only calendar type this codec supports. */
+const CALENDAR_TYPE_DEFAULT = 0x0000;
+/** `RecurrencePattern.FirstDOW` `Sunday` value - this codec always encodes with a Sunday week start, since
+ * `RecurrenceRule` has no field of its own to source a different one from. */
+const FIRST_DOW_SUNDAY = 0x00000000;
+/** `RecurrencePattern`'s `DayOfWeekMask` bits (`[MS-OXOCAL]` §2.2.1.44.1) - confirmed identical to
+ * `CalendarSyncAdapter`'s own `DAY_OF_WEEK_BITS` table for MS-ASCAL's `DayOfWeek` field, reused here under the
+ * same RFC 5545 two-letter day codes `RecurrenceRule.byDay` uses. */
+const DAY_OF_WEEK_BITS = { SU: 1, MO: 2, TU: 4, WE: 8, TH: 16, FR: 32, SA: 64 };
+const DAY_OF_WEEK_CODE_BY_BIT = [
+    ["SU", 1],
+    ["MO", 2],
+    ["TU", 4],
+    ["WE", 8],
+    ["TH", 16],
+    ["FR", 32],
+    ["SA", 64],
+];
+/** Minutes-since-1601-01-01T00:00:00Z epoch, as a JS `Date`-compatible millisecond timestamp - every date field
+ * in `RecurrencePattern` uses this epoch/unit, distinct from `PropertyValue.ts`'s `FILETIME` epoch (which is
+ * also 1601-based, but in 100-ns units, not minutes). */
+const EPOCH_1601_MS = Date.UTC(1601, 0, 1);
+function dateToMinutesSince1601(date) {
+    return Math.round((date.getTime() - EPOCH_1601_MS) / 60000);
+}
+function minutesSince1601ToDate(minutes) {
+    return new Date(EPOCH_1601_MS + minutes * 60000);
+}
+function utcMidnight(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+}
+/** Calendar months elapsed between 1601-01-01 and the first day of the month containing `date`. */
+function monthsElapsedSince1601(date) {
+    return (date.getUTCFullYear() - 1601) * 12 + date.getUTCMonth();
+}
+function dayOfWeekMaskFromByDay(byDay, fallbackDate) {
+    if (byDay && byDay.length > 0) {
+        return byDay.reduce((mask, day) => mask | (DAY_OF_WEEK_BITS[day] ?? 0), 0);
+    }
+    return DAY_OF_WEEK_CODE_BY_BIT[fallbackDate.getUTCDay()][1];
+}
+function byDayFromMask(mask) {
+    return DAY_OF_WEEK_CODE_BY_BIT.filter(([, bit]) => (mask & bit) !== 0).map(([code]) => code);
+}
+/**
+ * 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 function encodeAppointmentRecurrence(rule, startDate, endDate) {
+    let recurFrequency;
+    let patternType;
+    let period;
+    let patternSpecific;
+    let firstDateTime;
+    switch (rule.freq) {
+        case RecurrenceFrequency.DAILY: {
+            recurFrequency = RecurFrequencyWire.Daily;
+            patternType = PatternTypeWire.Day;
+            period = rule.interval * MINUTES_PER_DAY;
+            patternSpecific = Buffer.alloc(0);
+            firstDateTime = dateToMinutesSince1601(utcMidnight(startDate)) % period;
+            break;
+        }
+        case RecurrenceFrequency.WEEKLY: {
+            recurFrequency = RecurFrequencyWire.Weekly;
+            patternType = PatternTypeWire.Week;
+            period = rule.interval;
+            const mask = dayOfWeekMaskFromByDay(rule.byDay, startDate);
+            patternSpecific = new BufferWriter().writeUInt32LE(mask).toBuffer();
+            const midnight = utcMidnight(startDate);
+            const weekStart = new Date(midnight.getTime() - midnight.getUTCDay() * MINUTES_PER_DAY * 60000);
+            firstDateTime = dateToMinutesSince1601(weekStart) % (period * MINUTES_PER_WEEK);
+            break;
+        }
+        case RecurrenceFrequency.MONTHLY: {
+            recurFrequency = RecurFrequencyWire.Monthly;
+            patternType = PatternTypeWire.Month;
+            period = rule.interval;
+            const day = rule.byMonthDay?.[0] ?? startDate.getUTCDate();
+            patternSpecific = new BufferWriter().writeUInt32LE(day).toBuffer();
+            const monthsElapsed = monthsElapsedSince1601(startDate);
+            const refMonthIndex = monthsElapsed % period;
+            firstDateTime = dateToMinutesSince1601(new Date(Date.UTC(1601, refMonthIndex, 1)));
+            break;
+        }
+        case RecurrenceFrequency.YEARLY: {
+            patternType = PatternTypeWire.Month;
+            if (rule.interval <= 1) {
+                recurFrequency = RecurFrequencyWire.Yearly;
+                period = 12;
+            }
+            else {
+                recurFrequency = RecurFrequencyWire.Monthly;
+                period = 12 * rule.interval;
+            }
+            const day = rule.byMonthDay?.[0] ?? startDate.getUTCDate();
+            patternSpecific = new BufferWriter().writeUInt32LE(day).toBuffer();
+            const monthsElapsed = monthsElapsedSince1601(startDate);
+            const refMonthIndex = monthsElapsed % period;
+            firstDateTime = dateToMinutesSince1601(new Date(Date.UTC(1601, refMonthIndex, 1)));
+            break;
+        }
+        default:
+            throw new Error(`AppointmentRecurrence: unsupported RecurrenceFrequency ${rule.freq}`);
+    }
+    let endType;
+    let occurrenceCount = 0;
+    let endDateMinutes;
+    if (rule.until) {
+        endType = EndTypeWire.AfterDate;
+        endDateMinutes = dateToMinutesSince1601(utcMidnight(rule.until));
+    }
+    else if (rule.count != null) {
+        endType = EndTypeWire.AfterN;
+        occurrenceCount = rule.count;
+        endDateMinutes = NEVER_END_DATE;
+    }
+    else {
+        endType = EndTypeWire.Never;
+        endDateMinutes = NEVER_END_DATE;
+    }
+    const writer = new BufferWriter();
+    // RecurrencePattern (MS-OXOCAL §2.2.1.44.1)
+    writer.writeUInt16LE(0x3004); // ReaderVersion
+    writer.writeUInt16LE(0x3004); // WriterVersion
+    writer.writeUInt16LE(recurFrequency);
+    writer.writeUInt16LE(patternType);
+    writer.writeUInt16LE(CALENDAR_TYPE_DEFAULT);
+    writer.writeUInt32LE(firstDateTime);
+    writer.writeUInt32LE(period);
+    writer.writeUInt32LE(0); // SlidingFlag
+    writer.writeBytes(patternSpecific);
+    writer.writeUInt32LE(endType);
+    writer.writeUInt32LE(occurrenceCount);
+    writer.writeUInt32LE(FIRST_DOW_SUNDAY);
+    writer.writeUInt32LE(0); // DeletedInstanceCount
+    writer.writeUInt32LE(0); // ModifiedInstanceCount
+    writer.writeUInt32LE(dateToMinutesSince1601(utcMidnight(startDate))); // StartDate
+    writer.writeUInt32LE(endDateMinutes); // EndDate
+    // AppointmentRecurrencePattern's own wrapper fields (MS-OXOCAL §2.2.1.44.5)
+    writer.writeUInt32LE(0x00003006); // ReaderVersion2
+    writer.writeUInt32LE(0x00003009); // WriterVersion2
+    writer.writeUInt32LE(startDate.getUTCHours() * 60 + startDate.getUTCMinutes()); // StartTimeOffset
+    writer.writeUInt32LE(endDate.getUTCHours() * 60 + endDate.getUTCMinutes()); // EndTimeOffset
+    writer.writeUInt16LE(0); // ExceptionCount
+    writer.writeUInt32LE(0); // ReservedBlock1Size
+    writer.writeUInt32LE(0); // ReservedBlock2Size
+    return writer.toBuffer();
+}
+/**
+ * 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 function decodeAppointmentRecurrence(reader) {
+    reader.readUInt16LE(); // ReaderVersion
+    reader.readUInt16LE(); // WriterVersion
+    const recurFrequency = reader.readUInt16LE();
+    const patternType = reader.readUInt16LE();
+    reader.readUInt16LE(); // CalendarType
+    const firstDateTime = reader.readUInt32LE();
+    const period = reader.readUInt32LE();
+    reader.readUInt32LE(); // SlidingFlag
+    let freq;
+    let interval;
+    let byDay;
+    let byMonthDay;
+    let byMonth;
+    switch (recurFrequency) {
+        case RecurFrequencyWire.Daily:
+            if (patternType !== PatternTypeWire.Day) {
+                throw new Error(`AppointmentRecurrence: unsupported PatternType 0x${patternType.toString(16)} for Daily`);
+            }
+            freq = RecurrenceFrequency.DAILY;
+            interval = period / MINUTES_PER_DAY;
+            break;
+        case RecurFrequencyWire.Weekly: {
+            if (patternType !== PatternTypeWire.Week) {
+                throw new Error(`AppointmentRecurrence: unsupported PatternType 0x${patternType.toString(16)} for Weekly`);
+            }
+            const mask = reader.readUInt32LE();
+            freq = RecurrenceFrequency.WEEKLY;
+            interval = period;
+            byDay = byDayFromMask(mask);
+            break;
+        }
+        case RecurFrequencyWire.Monthly: {
+            if (patternType !== PatternTypeWire.Month) {
+                throw new Error(`AppointmentRecurrence: unsupported PatternType 0x${patternType.toString(16)} for Monthly`);
+            }
+            const day = reader.readUInt32LE();
+            freq = RecurrenceFrequency.MONTHLY;
+            interval = period;
+            byMonthDay = [day];
+            break;
+        }
+        case RecurFrequencyWire.Yearly: {
+            if (patternType !== PatternTypeWire.Month) {
+                throw new Error(`AppointmentRecurrence: unsupported PatternType 0x${patternType.toString(16)} for Yearly`);
+            }
+            const day = reader.readUInt32LE();
+            freq = RecurrenceFrequency.YEARLY;
+            interval = 1;
+            byMonthDay = [day];
+            byMonth = [minutesSince1601ToDate(firstDateTime).getUTCMonth() + 1];
+            break;
+        }
+        default:
+            throw new Error(`AppointmentRecurrence: unsupported RecurFrequency 0x${recurFrequency.toString(16)}`);
+    }
+    const endType = reader.readUInt32LE();
+    const occurrenceCount = reader.readUInt32LE();
+    reader.readUInt32LE(); // FirstDOW
+    const deletedInstanceCount = reader.readUInt32LE();
+    if (deletedInstanceCount > 0) {
+        throw new Error("AppointmentRecurrence: recurrence exceptions (DeletedInstanceCount > 0) are not supported");
+    }
+    const modifiedInstanceCount = reader.readUInt32LE();
+    if (modifiedInstanceCount > 0) {
+        throw new Error("AppointmentRecurrence: recurrence exceptions (ModifiedInstanceCount > 0) are not supported");
+    }
+    reader.readUInt32LE(); // StartDate
+    const endDateMinutes = reader.readUInt32LE();
+    let until;
+    let count;
+    if (endType === EndTypeWire.AfterDate) {
+        until = minutesSince1601ToDate(endDateMinutes);
+    }
+    else if (endType === EndTypeWire.AfterN) {
+        count = occurrenceCount;
+    }
+    reader.readUInt32LE(); // ReaderVersion2
+    reader.readUInt32LE(); // WriterVersion2
+    reader.readUInt32LE(); // StartTimeOffset
+    reader.readUInt32LE(); // EndTimeOffset
+    const exceptionCount = reader.readUInt16LE();
+    if (exceptionCount > 0) {
+        throw new Error("AppointmentRecurrence: exceptions (ExceptionCount > 0) are not supported");
+    }
+    const reservedBlock1Size = reader.readUInt32LE();
+    reader.readBytes(reservedBlock1Size);
+    const reservedBlock2Size = reader.readUInt32LE();
+    reader.readBytes(reservedBlock2Size);
+    return {
+        freq,
+        interval,
+        ...(byDay ? { byDay } : {}),
+        ...(byMonthDay ? { byMonthDay } : {}),
+        ...(byMonth ? { byMonth } : {}),
+        ...(until ? { until } : {}),
+        ...(count != null ? { count } : {}),
+        exceptions: [],
+    };
+}
+//# sourceMappingURL=AppointmentRecurrence.js.map

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

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

package/dist/lib/codec/BufferCursor.js

@@ -0,0 +1,213 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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
+ */
+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;
+    }
+    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 = [];
+    }
+    writeUInt8(value) {
+        const buf = Buffer.alloc(1);
+        buf.writeUInt8(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeInt16LE(value) {
+        const buf = Buffer.alloc(2);
+        buf.writeInt16LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeUInt16LE(value) {
+        const buf = Buffer.alloc(2);
+        buf.writeUInt16LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeInt32LE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeInt32LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeUInt32LE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeUInt32LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeFloatLE(value) {
+        const buf = Buffer.alloc(4);
+        buf.writeFloatLE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeDoubleLE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeDoubleLE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeBigInt64LE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeBigInt64LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeBigUInt64LE(value) {
+        const buf = Buffer.alloc(8);
+        buf.writeBigUInt64LE(value, 0);
+        this.chunks.push(buf);
+        return this;
+    }
+    writeBytes(value) {
+        this.chunks.push(value);
+        return this;
+    }
+    writeNullTerminatedUtf16LE(value) {
+        this.chunks.push(Buffer.from(value, "utf16le"), Buffer.from([0x00, 0x00]));
+        return this;
+    }
+    writeNullTerminatedString8(value) {
+        this.chunks.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,92 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 treating `Data` as bare bytes only when the `vCal-Uid` marker isn't present, i.e. an
+ * `OutlookID` - a native-Exchange-generated `GlobalObjectId` this server's own SMTP-based invite flow never
+ * produces, but decoded for completeness). `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` (the `PidLidExceptionReplaceTime` fields, used only when a
+ * `GlobalObjectId` identifies a single modified occurrence of a recurring series) are always encoded as `0`
+ * ("not an exception") and not decoded - recurrence exceptions are a documented gap elsewhere in this pragmatic
+ * subset (see `AppointmentRecurrence.ts`'s own doc comment), so there is nothing to source a real value from.
+ * `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 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 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.readUInt8(); // YH
+    reader.readUInt8(); // YL
+    reader.readUInt8(); // M
+    reader.readUInt8(); // D
+    reader.readBigUInt64LE(); // CreationTime - not needed to recover icalUid
+    reader.readBytes(8); // X
+    const size = reader.readUInt32LE();
+    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 data.toString("utf-8");
+}
+//# sourceMappingURL=GlobalObjectId.js.map