@blamejs/core 0.11.33 → 0.11.35

package/CHANGELOG.md

@@ -8,6 +8,12 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.35 (2026-05-21) — **`b.calendar` VTODO ↔ JSCalendar Task (RFC 8984 §6).** Closes the v0.11.31 deferral. `b.calendar.fromIcal` now recognises VTODO components and maps them to JSCalendar Task objects per RFC 8984 §6. `b.calendar.toIcal` emits a VTODO envelope (with DUE / STATUS / PERCENT-COMPLETE / COMPLETED iCalendar properties) when the input `@type` is `Task`. `b.calendar.validate` picks up Task-specific shape rules: `due` as LocalDateTime, `estimatedDuration` as PnYnMnDTnHnMnS, `progress` from the RFC 8984 §6.4.3 vocabulary (`needs-action` | `in-process` | `completed` | `cancelled` | `failed`), `percentComplete` ∈ [0..100], `progressUpdated` as UTCDateTime. A VCALENDAR carrying both VEVENT and VTODO components now returns an array of mixed `Event` + `Task` shapes. **Added:** *`b.calendar.fromIcal` maps VTODO → JSCalendar Task* — VTODO components in the VCALENDAR are mapped to `@type: "Task"` objects with the same `uid` / `updated` / `title` / `description` / `start` / `timeZone` / `locations` / `recurrenceRules` slots Event uses, plus the Task-specific fields: `due` (DUE → LocalDateTime), `estimatedDuration` (DURATION), `progress` (STATUS lowercased), `percentComplete` (PERCENT-COMPLETE 0..100), `progressUpdated` (COMPLETED → UTCDateTime). UTC DUE values map to `timeZone: "Etc/UTC"` the same way DTSTART does. · *`b.calendar.toIcal` emits VTODO when `@type === "Task"`* — The envelope is `BEGIN:VTODO` / `END:VTODO` instead of `BEGIN:VEVENT`. Task-specific properties round-trip: `DUE` (with `;TZID=` parameter or `Z` suffix or floating local time per the same RFC 8984 §1.4.4 timeZone mapping as DTSTART), `STATUS` (uppercased), `PERCENT-COMPLETE`, `COMPLETED` (UTC). `estimatedDuration` maps to `DURATION` (RFC 5545 doesn't distinguish Event vs Task duration on the wire). · *`b.calendar.validate` learns Task-specific shape rules (RFC 8984 §6.4)* — `due` must be a LocalDateTime, `estimatedDuration` must match the same PnYnMnDTnHnMnS Duration grammar Event uses, `progress` must be in the `JSCAL_TASK_PROGRESS` catalogue (also exposed as a new top-level export), `percentComplete` must be a finite number in 0..100, `progressUpdated` must be a UTCDateTime. Structured `CalendarError` codes: `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-percent`, `calendar/bad-progress-updated`. · *Mixed-component VCALENDAR returns an array of Event + Task shapes* — When a VCALENDAR contains both VEVENT and VTODO children, `fromIcal` returns an Array — events first, tasks second, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`calendar/no-vevent` error code renamed to `calendar/no-component`* — The refusal that fires when a VCALENDAR has no parseable child component now uses the more accurate `calendar/no-component` code (since VTODO is also valid). Operators that grep on the prior `calendar/no-vevent` code need to update the match; the human-facing error message also updates. **References:** [RFC 8984 §6 (JSCalendar Task)](https://www.rfc-editor.org/rfc/rfc8984.html#section-6) · [RFC 5545 §3.6.2 (iCalendar VTODO component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2) · [RFC 5545 §3.8.2.3 (DUE date-time)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.2.3) · [RFC 5545 §3.8.1.11 (STATUS — needs-action/in-process/completed/cancelled)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11)
+
+- v0.11.34 (2026-05-21) — **JMAP WebSocket transport (RFC 8887) on `b.mail.server.jmap`.** Closes the v0.11.29 deferral. The JMAP listener now exposes `webSocketHandler(req, socket, head)` — a turnkey RFC 8887 transport built on the framework's `b.websocket.handleUpgrade`. Clients connect with the `jmap` subprotocol; bidirectional JSON frames carry `{ "@type": "Request" }` / `{ "@type": "WebSocketPushEnable" }` / `{ "@type": "WebSocketPushDisable" }` from the client, and `{ "@type": "Response" }` / `{ "@type": "StateChange" }` / `{ "@type": "RequestError" }` from the server. `Request` frames flow through the same `dispatch(actor, request)` path the HTTP `apiHandler` uses; `WebSocketPushEnable` hooks the operator's `mailStore.subscribePush(actor, types, emitFn)` and converts backend StateChange events into outbound WebSocket frames.
+
+The session resource picks up `webSocketUrl` so clients discover the endpoint via the same JMAP session-discovery flow they use for `apiUrl` / `eventSourceUrl` / `uploadUrl` / `downloadUrl`. permessage-deflate is OFF by default — same CRIME-class compression-oracle threat model as the v0.11.28 IMAP COMPRESS=DEFLATE intentional skip — operators opt in via `opts.webSocketPermessageDeflate`. **Added:** *`webSocketHandler(req, socket, head)` on the listener handle* — Mount on the operator's HTTP server's `'upgrade'` event. Auth is delegated to the surrounding HTTP middleware (the handler expects `req.user` / `req.actor` to be populated by upstream auth); unauthenticated requests write `HTTP/1.1 401 Unauthorized` to the raw socket per the WebSocket spec's pre-handshake error shape. RFC 8887 §3.1 requires the `jmap` subprotocol; the handler refuses the upgrade with close-code 1002 if `Sec-WebSocket-Protocol: jmap` is missing. · *Bidirectional JSON-framed transport* — Client → server `@type`: `Request` (same body as HTTP POST — `{ using, methodCalls, createdIds? }`), `WebSocketPushEnable` (`{ dataTypes?, pushState? }`), `WebSocketPushDisable`. Server → client `@type`: `Response` (`{ requestId, methodResponses, sessionState, createdIds }`), `StateChange` (`{ changed, pushed? }`), `RequestError` (`{ requestId, type, description }`). Unknown `@type` frames trigger a `RequestError` rather than tearing down the channel. · *Push integration shares the operator hook with EventSource* — `WebSocketPushEnable` forwards `(actor, dataTypes, emitFn)` to `mailStore.subscribePush` — the same backend hook the EventSource handler (v0.11.29) consumes. Operators wire push once and both transports surface the same `StateChange` events. Per-connection `WebSocketPushDisable` calls the unsubscribe function the backend returned from `subscribePush`. Connection close cleans up implicitly. · *Session resource carries `webSocketUrl`* — The session JSON now includes `webSocketUrl: opts.webSocketUrl || "/jmap/ws"` per RFC 8887 §3. Operators discoverable-by-default — clients using a stock JMAP library find the WS endpoint via the session resource the same way they find `apiUrl` today. **Security:** *Binary frames refused* — JMAP is JSON-only over WebSocket. Binary frames trigger a `RequestError` with `type: "notJSON"`; the connection stays open so the next text frame can be valid. Prevents a misbehaving client from sneaking opaque bytes past the JSON parser. · *JSON parse routed through `b.safeJson.parse`* — WebSocket text frames are parsed through `b.safeJson.parse` with the per-connection `maxBytes` cap (default 10 MiB; operator-tunable via `opts.webSocketMaxMessageBytes`). Catches CVE-2020-7660-class prototype-pollution payloads + adversarial-depth JSON before they reach the JMAP method dispatcher. · *permessage-deflate OFF by default (CRIME-class threat)* — RFC 7692 permessage-deflate enables compression-oracle attacks (CVE-2012-4929 CRIME class) when the operator pipes JSON containing both attacker-controlled and confidential data through the same connection. Default is OFF; operators with explicit threat-model justification opt in via `opts.webSocketPermessageDeflate = true`. Mirrors the v0.11.28 IMAP COMPRESS=DEFLATE intentional refusal. · *Subprotocol negotiation refuses non-`jmap` clients* — If the client's `Sec-WebSocket-Protocol` header doesn't include `jmap`, the listener refuses the upgrade with close-code 1002 (protocol error). RFC 8887 §3.1 — the JMAP-WS connection is identified by the subprotocol; refusing here prevents the connection from being misinterpreted as a generic WebSocket channel by middleware downstream. **References:** [RFC 8887 (JMAP over WebSocket)](https://www.rfc-editor.org/rfc/rfc8887.html) · [RFC 8620 (JMAP Core)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 6455 (The WebSocket Protocol)](https://www.rfc-editor.org/rfc/rfc6455.html) · [RFC 7692 (Compression Extensions for WebSocket — NOT enabled)](https://www.rfc-editor.org/rfc/rfc7692.html) · [CVE-2012-4929 (CRIME — compression-oracle attack on TLS)](https://nvd.nist.gov/vuln/detail/CVE-2012-4929)
+
 - v0.11.33 (2026-05-21) — **IMAP QRESYNC (RFC 7162 §3.2) — VANISHED responses + SELECT delta on `b.mail.server.imap`.** Closes the v0.11.27 deferral. The IMAP listener now advertises QRESYNC in CAPABILITY, accepts `ENABLE QRESYNC` (which implicitly engages CONDSTORE per §3.2.5), and parses the `(QRESYNC (<uidvalidity> <modseq> [<knownUids>] [<knownSequenceMatchData>]))` parameter list on SELECT / EXAMINE. When the client's UIDVALIDITY matches the backend's, the listener emits a single `* VANISHED (EARLIER) <uid-set>` listing UIDs the server expunged since the client's snapshot — operators implement the actual delta computation via `mailStore.selectFolder(actor, mailbox, { qresync }) → { ..., vanishedEarlier }`. Stale-UIDVALIDITY clients fall through to a full re-SELECT. **Added:** *CAPABILITY advertises `QRESYNC`* — Sits next to the existing `CONDSTORE` advertisement. Both extensions are server-advertised; clients ENABLE before relying on the responses. RFC 7162 §3.2.5 — QRESYNC implies CONDSTORE. · *`ENABLE QRESYNC` engages both flags* — The handler flips `state.enabledQResync = true` AND `state.enabledCondStore = true` and emits `* ENABLED QRESYNC` + `OK ENABLE completed`. Already-engaged QRESYNC re-issues skip the advertisement line (only newly-engaged extensions appear). · *`SELECT mailbox (QRESYNC (<uidvalidity> <modseq> [<knownUids>] [<knownSeq>]))`* — The QRESYNC parameter list is stripped from the SELECT args before the mailbox-name validator runs and forwarded to `mailStore.selectFolder` as `opts.qresync = { uidvalidity, modseq, knownUids, knownSeq }`. Backends compute the delta and return `vanishedEarlier` (sequence-set string) in the existing select-info object. Non-finite uidvalidity / modseq values refuse with `BAD SELECT QRESYNC params must be (<uidvalidity> <modseq> ...) numerics` before the backend call. · *Implicit CONDSTORE+QRESYNC engagement on parameterised SELECT* — Per RFC 7162 §3.2.4, a client that issues `SELECT INBOX (QRESYNC (...))` without a prior `ENABLE QRESYNC` flips both flags implicitly for the session. Subsequent FETCH responses include `MODSEQ (<n>)` just as they would after explicit ENABLE. · *`* VANISHED (EARLIER) <uid-set>` emission* — The listener emits a single VANISHED untagged response between `HIGHESTMODSEQ` and the tagged OK when (a) the client supplied a QRESYNC parameter, (b) the client's UIDVALIDITY matches the backend's, AND (c) the backend supplied a non-empty `vanishedEarlier`. Mismatched UIDVALIDITY suppresses the VANISHED line so the client correctly falls through to a full re-sync (RFC 7162 §3.2.5). **Security:** *QRESYNC parameter parse is bounded* — The regex anchors on `\(\s*QRESYNC\s*\(\s*([^)]+)\)` — `[^)]*` not `.*` — so a malformed parameter list cannot consume the entire SELECT args. Both `uidvalidity` and `modseq` parse strictly as `\d+` via `parseInt(...)` + `isFinite` check; non-numeric values refuse before the backend dispatch. · *VANISHED suppressed on UIDVALIDITY mismatch* — RFC 7162 §3.2.5 — when the client's `uidvalidity` does NOT match the server's current value, the mailbox has been reset (e.g., recreated under the same name) and the client's UID cache is invalid. The listener intentionally drops the VANISHED line so the client forces a fresh full-sync instead of acting on a delta that references a different message set. **References:** [RFC 7162 §3.2 (QRESYNC — Quick Mailbox Resynchronization)](https://www.rfc-editor.org/rfc/rfc7162.html) · [RFC 9051 (IMAP4rev2)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 5161 (IMAP ENABLE Extension)](https://www.rfc-editor.org/rfc/rfc5161.html)
 
 - v0.11.32 (2026-05-21) — **`b.mail.crypto.pgp.encrypt` / `.decrypt` / `.wkd` promoted to stable — WKD IDN-homograph defense.** The PGP encrypt / decrypt / Web Key Directory (WKD) primitives that shipped under `b.mail.crypto.pgp.experimental.*` at v0.10.16 are promoted to top-level stable. `b.mail.crypto.pgp.encrypt` / `b.mail.crypto.pgp.decrypt` / `b.mail.crypto.pgp.wkd.fetch` / `b.mail.crypto.pgp.wkd.computeUrl` are now the canonical paths; the v0.10.16 `experimental` aliases continue to work so existing operator code keeps importing through the old path until they migrate at their own pace. WKD picks up a hard IDN-homograph refusal at `wkd.computeUrl` — Cyrillic / Greek / full-width / Han confusable domain characters refuse with `mail-crypto/pgp/bad-domain` before any HTTP fetch runs. Operators with internationalised domains MUST Punycode-encode upstream (RFC 3492 `xn--` form). **Added:** *Top-level `b.mail.crypto.pgp.encrypt` / `.decrypt` / `.wkd.{fetch,computeUrl}`* — Same function bodies that shipped under `b.mail.crypto.pgp.experimental.*` at v0.10.16 are now exported at the top of the namespace. The framework-private envelope (BJ-PGP-PQ magic + version) is unchanged; the IANA-pending RFC 9580bis ML-KEM PKESK codepoints will land as an alternate-encoding option in a follow-up slice. The `experimental` alias keeps the v0.10.16 import paths working — operator migration is opt-in. `b.mail.crypto.pgp.encrypt === b.mail.crypto.pgp.experimental.encrypt` (same reference) so a feature-detection test like `typeof b.mail.crypto.pgp.encrypt === 'function'` is the new operator-facing pattern. **Security:** *WKD IDN-homograph refusal at `wkd.computeUrl`* — `wkd.computeUrl(email)` now refuses any domain containing characters outside the LDH+dot ASCII subset (RFC 952 / RFC 1123 §2). The threat model: Cyrillic `а` (U+0430), Greek `ο` (U+03BF), full-width `Ａ` (U+FF21), and Han homographs visually impersonate Latin letters in `paypa1.com` / `gοogle.com` style phishing host strings; a naive `toLowerCase` + concat into the WKD URL would route the key fetch to the attacker's domain. Operators with legitimate internationalised domains MUST Punycode-encode upstream (the `xn--` form is plain ASCII LDH and passes). The framework's `b.httpClient` already refuses non-ASCII hostnames at the SSRF guard layer; this primitive surfaces the same refusal at the WKD entry point so the error surface is consistent. · *RFC 5321 + RFC 1035 length caps* — Email length capped at 320 octets (RFC 5321 §4.5.3.1 maximum). Domain length capped at 253 octets (RFC 1035 §2.3.4). Empty labels (`bad..example.com`), leading-dot, and trailing-dot domains refuse before any URL construction. Adversarial-length inputs cannot reach the tokenizer / hasher path. **References:** [draft-koch-openpgp-webkey-service (Web Key Directory)](https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/) · [RFC 9580 (OpenPGP)](https://www.rfc-editor.org/rfc/rfc9580.html) · [RFC 3492 (Punycode — IDNA `xn--` form)](https://www.rfc-editor.org/rfc/rfc3492.html) · [RFC 5891 (IDNA 2008)](https://www.rfc-editor.org/rfc/rfc5891.html) · [RFC 5321 §4.5.3.1 (SMTP — local-part + domain octet maximums)](https://www.rfc-editor.org/rfc/rfc5321.html) · [RFC 1035 §2.3.4 (domain label length)](https://www.rfc-editor.org/rfc/rfc1035.html) · [Unicode TR 39 (Security Mechanisms — confusable identifiers)](https://www.unicode.org/reports/tr39/)

package/lib/calendar.js

@@ -61,6 +61,18 @@ var JSCAL_ALERT_ACTIONS = Object.freeze({
   display: 1, email: 1,
 });
 
+// RFC 8984 §6.4.3 — Task progress vocabulary. Mirrors RFC 5545 STATUS
+// values for VTODO (`NEEDS-ACTION` / `IN-PROCESS` / `COMPLETED` /
+// `CANCELLED`); JSCalendar lower-cases them. `failed` is NOT included
+// — RFC 5545 STATUS does not define a `FAILED` value, so the iCal
+// round-trip path could not safely emit it (strict consumers refuse
+// the unknown STATUS token). Operators with a "failed" semantic
+// model it via `progress: "cancelled"` + a vendor-namespaced
+// extension property instead.
+var JSCAL_TASK_PROGRESS = Object.freeze({
+  "needs-action": 1, "in-process": 1, "completed": 1, "cancelled": 1,
+});
+
 // Recurrence-expansion caps. Mirror b.safeIcal's RRULE limits so the
 // expand path can't outpace what the parser already permitted.
 var MAX_EXPAND_INSTANCES = 4096;                                                                       // allow:raw-byte-literal — instance count cap, not bytes
@@ -120,6 +132,44 @@ function validate(jsCal) {
         "b.calendar.validate: Event.duration MUST be an RFC 8601 PnYnMnDTnHnMnS Duration");
     }
   }
+  if (t === JSCAL_TYPES.Task) {
+    if (jsCal.start !== undefined && (typeof jsCal.start !== "string" || !_isLocalDateTime(jsCal.start))) {
+      throw new CalendarError("calendar/bad-start",
+        "b.calendar.validate: Task.start MUST be a LocalDateTime (RFC 8984 §6.4)");
+    }
+    if (jsCal.due !== undefined && (typeof jsCal.due !== "string" || !_isLocalDateTime(jsCal.due))) {
+      throw new CalendarError("calendar/bad-due",
+        "b.calendar.validate: Task.due MUST be a LocalDateTime (RFC 8984 §6.4.4)");
+    }
+    if (jsCal.estimatedDuration !== undefined &&
+        (typeof jsCal.estimatedDuration !== "string" || !_isDuration(jsCal.estimatedDuration))) {
+      throw new CalendarError("calendar/bad-duration",
+        "b.calendar.validate: Task.estimatedDuration MUST be an RFC 8601 PnYnMnDTnHnMnS Duration");
+    }
+    if (jsCal.progress !== undefined &&
+        !Object.prototype.hasOwnProperty.call(JSCAL_TASK_PROGRESS, jsCal.progress)) {
+      throw new CalendarError("calendar/bad-progress",
+        "b.calendar.validate: Task.progress MUST be one of " +
+        Object.keys(JSCAL_TASK_PROGRESS).join(" | ") + " (RFC 8984 §6.4.3)");
+    }
+    if (jsCal.percentComplete !== undefined) {
+      // RFC 8984 §6.4.4 specifies `UnsignedInt` (integer). RFC 5545
+      // §3.8.1.16 PERCENT-COMPLETE is also integer-typed. A float
+      // would emit as `PERCENT-COMPLETE:12.5` which strict parsers
+      // refuse.
+      if (typeof jsCal.percentComplete !== "number" || !isFinite(jsCal.percentComplete) ||
+          !Number.isInteger(jsCal.percentComplete) ||
+          jsCal.percentComplete < 0 || jsCal.percentComplete > 100) {                                  // allow:raw-byte-literal — RFC 8984 §6 percent range
+        throw new CalendarError("calendar/bad-percent",
+          "b.calendar.validate: Task.percentComplete MUST be an integer in 0..100 (RFC 8984 §6.4.4 UnsignedInt)");
+      }
+    }
+    if (jsCal.progressUpdated !== undefined &&
+        (typeof jsCal.progressUpdated !== "string" || !_isUtcDateTime(jsCal.progressUpdated))) {
+      throw new CalendarError("calendar/bad-progress-updated",
+        "b.calendar.validate: Task.progressUpdated MUST be a UTCDateTime");
+    }
+  }
   if (jsCal.recurrenceRules !== undefined) {
     if (!Array.isArray(jsCal.recurrenceRules)) {
       throw new CalendarError("calendar/bad-recurrence",
@@ -185,11 +235,13 @@ function validate(jsCal) {
 function fromIcal(text, opts) {
   var ast = safeIcal.parse(text, opts || {});
   var events = (ast && ast.vcalendar && ast.vcalendar.vevent) || [];
-  if (events.length === 0) {
-    throw new CalendarError("calendar/no-vevent",
-      "b.calendar.fromIcal: VCALENDAR has no VEVENT components");
+  var todos  = (ast && ast.vcalendar && ast.vcalendar.vtodo)  || [];
+  if (events.length === 0 && todos.length === 0) {
+    throw new CalendarError("calendar/no-component",
+      "b.calendar.fromIcal: VCALENDAR has no VEVENT or VTODO components");
   }
-  var converted = events.map(_veventToJsCalEvent);
+  var converted = events.map(_veventToJsCalEvent)
+    .concat(todos.map(_vtodoToJsCalTask));
   return converted.length === 1 ? converted[0] : converted;
 }
 
@@ -220,11 +272,16 @@ function fromIcal(text, opts) {
 function toIcal(jsCal, opts) {
   validate(jsCal);
   var prodid = (opts && opts.prodid) || "-//blamejs//Calendar//EN";
+  // RFC 8984 §6 — JSCalendar Task maps to RFC 5545 §3.6.2 VTODO; Event
+  // maps to VEVENT. The wrapper + most properties are identical; the
+  // wrapping component tag + Task-specific fields (DUE / STATUS /
+  // PERCENT-COMPLETE / COMPLETED) diverge.
+  var component = jsCal["@type"] === "Task" ? "VTODO" : "VEVENT";
   var lines = [
     "BEGIN:VCALENDAR",
     "VERSION:2.0",
     "PRODID:" + prodid,
-    "BEGIN:VEVENT",
+    "BEGIN:" + component,
     "UID:" + _foldLine(jsCal.uid),
     "DTSTAMP:" + _utcDateTimeToIcal(jsCal.updated),
   ];
@@ -244,7 +301,35 @@ function toIcal(jsCal, opts) {
       lines.push("DTSTART:" + dtStartIcal);
     }
   }
-  if (jsCal.duration) lines.push("DURATION:" + jsCal.duration);
+  // RFC 5545 §3.8.2.3 — DUE is Task-only; same TZID/UTC handling as DTSTART.
+  if (component === "VTODO" && jsCal.due) {
+    var dueIcal = _localDateTimeToIcal(jsCal.due);
+    if (jsCal.timeZone === "Etc/UTC" || jsCal.timeZone === "UTC") {
+      lines.push("DUE:" + dueIcal + "Z");
+    } else if (jsCal.timeZone) {
+      lines.push("DUE;TZID=" + jsCal.timeZone + ":" + dueIcal);
+    } else {
+      lines.push("DUE:" + dueIcal);
+    }
+  }
+  // RFC 8984 §6 — Task carries `estimatedDuration` (RFC 5545 DURATION).
+  // Event uses `duration`. Both map to the same iCalendar property.
+  var icalDuration = component === "VTODO"
+    ? (jsCal.estimatedDuration || jsCal.duration)
+    : jsCal.duration;
+  if (icalDuration) lines.push("DURATION:" + icalDuration);
+  // RFC 5545 §3.8.1.11 STATUS — Task progress maps directly; the four
+  // RFC 8984 §6.4.3 progress values (`needs-action` / `in-process` /
+  // `completed` / `cancelled`) are the same wire strings.
+  if (component === "VTODO" && jsCal.progress) {
+    lines.push("STATUS:" + String(jsCal.progress).toUpperCase());
+  }
+  if (component === "VTODO" && typeof jsCal.percentComplete === "number") {
+    lines.push("PERCENT-COMPLETE:" + jsCal.percentComplete);
+  }
+  if (component === "VTODO" && jsCal.progressUpdated) {
+    lines.push("COMPLETED:" + _utcDateTimeToIcal(jsCal.progressUpdated));
+  }
   if (Array.isArray(jsCal.locations) || (jsCal.locations && typeof jsCal.locations === "object")) {
     var locValues = Array.isArray(jsCal.locations) ? jsCal.locations : Object.values(jsCal.locations);
     for (var li = 0; li < locValues.length; li += 1) {
@@ -259,7 +344,7 @@ function toIcal(jsCal, opts) {
       lines.push("RRULE:" + _recurrenceRuleToIcal(jsCal.recurrenceRules[rri]));
     }
   }
-  lines.push("END:VEVENT", "END:VCALENDAR");
+  lines.push("END:" + component, "END:VCALENDAR");
   return lines.join("\r\n") + "\r\n";
 }
 
@@ -432,6 +517,64 @@ function _veventToJsCalEvent(ve) {
   return jsCal;
 }
 
+// RFC 8984 §6 — JSCalendar Task. The VTODO mapping is structurally
+// similar to VEVENT but adds Task-specific properties:
+//   DUE       → due (LocalDateTime)
+//   STATUS    → progress ("needs-action"|"in-process"|"completed"|"cancelled")
+//   PERCENT-COMPLETE → percentComplete (0..100)
+//   COMPLETED → progressUpdated (UTCDateTime)
+function _vtodoToJsCalTask(vt) {
+  var props = (vt && vt.properties) || {};
+  var jsCal = {
+    "@type":  "Task",
+    uid:      _firstValue(props.UID) || "",
+    updated:  _icalDateTimeToUtc(_firstValue(props.DTSTAMP) || ""),
+  };
+  var summary = _firstValue(props.SUMMARY);
+  if (summary) jsCal.title = _unescapeText(summary);
+  var description = _firstValue(props.DESCRIPTION);
+  if (description) jsCal.description = _unescapeText(description);
+  var dtstart = _firstValue(props.DTSTART);
+  if (dtstart) jsCal.start = _icalDateTimeToLocal(dtstart);
+  var due = _firstValue(props.DUE);
+  if (due) jsCal.due = _icalDateTimeToLocal(due);
+  var duration = _firstValue(props.DURATION);
+  if (duration) jsCal.estimatedDuration = duration;
+  var tzid = _firstParamValue(props.DTSTART, "TZID") ||
+             _firstParamValue(props.DUE, "TZID");
+  if (tzid) {
+    jsCal.timeZone = tzid;
+  } else if ((typeof dtstart === "string" && /Z$/.test(dtstart)) ||
+             (typeof due === "string" && /Z$/.test(due))) {
+    jsCal.timeZone = "Etc/UTC";
+  }
+  var status = _firstValue(props.STATUS);
+  if (status) {
+    var statusLower = String(status).toLowerCase();
+    var statusMap = {
+      "needs-action": "needs-action",
+      "in-process":   "in-process",
+      "completed":    "completed",
+      "cancelled":    "cancelled",
+    };
+    if (statusMap[statusLower]) jsCal.progress = statusMap[statusLower];
+  }
+  var percent = _firstValue(props["PERCENT-COMPLETE"]);
+  if (percent !== null && percent !== undefined) {
+    var pn = parseInt(percent, 10);
+    if (isFinite(pn) && pn >= 0 && pn <= 100) jsCal.percentComplete = pn;                              // allow:raw-byte-literal — RFC 8984 §6 percent range
+  }
+  var completed = _firstValue(props.COMPLETED);
+  if (completed) jsCal.progressUpdated = _icalDateTimeToUtc(completed);
+  var location = _firstValue(props.LOCATION);
+  if (location) {
+    jsCal.locations = { L1: { "@type": "Location", name: _unescapeText(location) } };
+  }
+  var rrule2 = _firstValue(props.RRULE);
+  if (rrule2) jsCal.recurrenceRules = [_icalRruleToJscal(rrule2)];
+  return jsCal;
+}
+
 function _firstValue(prop) {
   if (!prop) return null;
   if (Array.isArray(prop)) {
@@ -576,6 +719,7 @@ module.exports = {
   JSCAL_TYPES:            JSCAL_TYPES,
   JSCAL_FREQUENCIES:      JSCAL_FREQUENCIES,
   JSCAL_ALERT_ACTIONS:    JSCAL_ALERT_ACTIONS,
+  JSCAL_TASK_PROGRESS:    JSCAL_TASK_PROGRESS,
   MAX_EXPAND_INSTANCES:   MAX_EXPAND_INSTANCES,
   MAX_EXPAND_SPAN_MS:     MAX_EXPAND_SPAN_MS,
 };

package/lib/mail-server-jmap.js

@@ -122,6 +122,7 @@ var C = require("./constants");
 var bCrypto = require("./crypto");
 var safeJson = require("./safe-json");
 var safeBuffer = require("./safe-buffer");
+var websocket = require("./websocket");
 var validateOpts = require("./validate-opts");
 var guardJmap = require("./guard-jmap");
 var mailServerRegistry = require("./mail-server-registry");
@@ -476,8 +477,21 @@ function create(opts) {
     Promise.resolve().then(function () { return opts.accountsFor(actor); })
       .then(function (accountInfo) {
         var info = accountInfo || { primaryAccounts: {}, accounts: {} };
+        // RFC 8887 §3 — advertise the WebSocket transport in the
+        // capabilities object so RFC-compliant clients discover the
+        // endpoint via the canonical session-discovery flow rather
+        // than depending on the top-level `webSocketUrl` alias.
+        var defaultCaps = { "urn:ietf:params:jmap:core": {} };
+        var hasOperatorWsCap = Object.prototype.hasOwnProperty.call(
+          serverCapabilities, "urn:ietf:params:jmap:websocket");
+        if (!hasOperatorWsCap) {
+          defaultCaps["urn:ietf:params:jmap:websocket"] = {
+            url:          opts.webSocketUrl || "/jmap/ws",
+            supportsPush: true,
+          };
+        }
         var session = {
-          capabilities: Object.assign({}, { "urn:ietf:params:jmap:core": {} }, serverCapabilities),
+          capabilities: Object.assign({}, defaultCaps, serverCapabilities),
           accounts:     info.accounts || {},
           primaryAccounts: info.primaryAccounts || {},
           username:     actor.username || actor.id || "unknown",
@@ -485,6 +499,13 @@ function create(opts) {
           downloadUrl:  opts.downloadUrl  || "/jmap/download/{accountId}/{blobId}/{name}?accept={type}",
           uploadUrl:    opts.uploadUrl    || "/jmap/upload/{accountId}",
           eventSourceUrl: opts.eventSourceUrl || "/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}",
+          // RFC 8887 §3 — `webSocketUrl` advertises the JMAP WS
+          // endpoint. Operator overrides via opts.webSocketUrl; default
+          // mounts at `/jmap/ws`.
+          urlEndpointResolution: serverCapabilities["urn:ietf:params:jmap:websocket"]
+            ? { useEndpoint: opts.webSocketUrl || "/jmap/ws", urlPrefix: "" }
+            : undefined,
+          webSocketUrl:   opts.webSocketUrl || "/jmap/ws",
           state:        sessionState,
         };
         res.statusCode = 200;
@@ -971,6 +992,204 @@ function create(opts) {
       });
   }
 
+  // RFC 8887 — JMAP over WebSocket. The session-resource's `webSocketUrl`
+  // points at this handler. Client opens a WS connection with the `jmap`
+  // subprotocol; bidirectional JSON frames carry `{ "@type": "Request" }`
+  // / `{ "@type": "WebSocketPushEnable" }` / `{ "@type":
+  // "WebSocketPushDisable" }` from the client, and `{ "@type":
+  // "Response" }` / `{ "@type": "StateChange" }` / `{ "@type":
+  // "RequestError" }` from the server.
+  function webSocketHandler(req, socket, head) {
+    var actor = req.user || (req.actor || null);
+    if (!actor) {
+      try { socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n"); socket.destroy(); }
+      catch (_e) { /* silent-catch: socket already torn down */ }
+      return null;
+    }
+    var conn = websocket.handleUpgrade(req, socket, head, {
+      subprotocols:    ["jmap"],
+      origins:         opts.webSocketOrigins || null,
+      maxMessageBytes: opts.webSocketMaxMessageBytes || (10 * 1024 * 1024),                            // allow:raw-byte-literal — 10 MiB JMAP WS message cap
+      // permessage-deflate is off by default — same CRIME-class threat
+      // model as the IMAP COMPRESS=DEFLATE intentional skip in v0.11.28.
+      // Operators opt in via opts.webSocketPermessageDeflate.
+      permessageDeflate: opts.webSocketPermessageDeflate === true,
+    });
+    if (!conn) return null;
+    // RFC 8887 §3.1 — server MUST select `jmap` if offered. Refuse the
+    // connection cleanly if subprotocol negotiation came back null.
+    if (conn.subprotocol !== "jmap") {
+      try { conn.close(1002, "RFC 8887 requires Sec-WebSocket-Protocol: jmap"); }                      // allow:raw-byte-literal — RFC 6455 protocol-error close code
+      catch (_e) { /* silent-catch: closed */ }
+      return null;
+    }
+
+    var pushUnsubscribe = null;
+    var pushEnabled = false;
+    var pushSetupPromise = null;
+    var connClosed = false;
+
+    function _sendJson(obj) {
+      try { conn.send(JSON.stringify(obj)); }
+      catch (_e) { /* silent-catch: socket already torn down */ }
+    }
+
+    function _sendRequestError(requestId, type, description) {
+      _sendJson({
+        "@type":       "RequestError",
+        requestId:     requestId || null,
+        type:          type,
+        description:   description,
+      });
+    }
+
+    conn.on("message", function (data, isBinary) {
+      if (isBinary) {
+        _sendRequestError(null,
+          "urn:ietf:params:jmap:error:notJSON",
+          "WebSocket frame must be a JSON text frame (RFC 8887 §4)");
+        return;
+      }
+      var text = data.toString("utf8");
+      if (text.length > (opts.webSocketMaxMessageBytes || (10 * 1024 * 1024))) {                       // allow:raw-byte-literal — mirrors handleUpgrade cap
+        _sendRequestError(null,
+          "urn:ietf:params:jmap:error:limit",
+          "WebSocket message exceeds maxSizeRequest");
+        return;
+      }
+      var parsed;
+      try { parsed = safeJson.parse(text, { maxBytes: opts.webSocketMaxMessageBytes || (10 * 1024 * 1024) }); } // allow:raw-byte-literal — mirrors handleUpgrade cap
+      catch (_e) {
+        _sendRequestError(null,
+          "urn:ietf:params:jmap:error:notJSON",
+          "WebSocket frame is not valid JSON");
+        return;
+      }
+      var type = parsed && parsed["@type"];
+      var requestId = parsed && parsed.id;
+
+      if (type === "Request") {
+        // RFC 8887 §4 — `Request` carries the same body as the HTTP
+        // POST: `{ using, methodCalls, createdIds? }`. Dispatch
+        // through the existing dispatch path; response is wrapped in
+        // `{ "@type": "Response", requestId, methodResponses, createdIds? }`.
+        // EXCEPT when dispatch returns a refusal shape — request-
+        // level validation failure (`{ type, description,
+        // methodResponses: [] }`) — those MUST surface as
+        // `{ "@type": "RequestError" }` so the client can distinguish
+        // an invalid request from a valid empty-result Response.
+        Promise.resolve()
+          .then(function () { return dispatch(actor, parsed); })
+          .then(function (rv) {
+            if (rv && typeof rv.type === "string" && typeof rv.description === "string") {
+              _sendRequestError(requestId, rv.type, rv.description);
+              return;
+            }
+            _sendJson({
+              "@type":         "Response",
+              requestId:       requestId,
+              methodResponses: rv.methodResponses,
+              sessionState:    rv.sessionState,
+              createdIds:      rv.createdIds,
+            });
+          })
+          .catch(function (err) {
+            _sendRequestError(requestId,
+              (err && err.code) || "urn:ietf:params:jmap:error:serverFail",
+              (err && err.message) || "Dispatch failed");
+          });
+        return;
+      }
+
+      if (type === "WebSocketPushEnable") {
+        if (typeof opts.mailStore.subscribePush !== "function") {
+          _sendRequestError(null,
+            "urn:ietf:params:jmap:error:serverUnavailable",
+            "Push subscribe backend not configured (mailStore.subscribePush)");
+          return;
+        }
+        // RFC 8887 §5 — duplicate enable is a no-op. Also refuse
+        // mid-subscription concurrency: if a previous PushEnable hasn't
+        // resolved yet, the second is treated as no-op. Without this
+        // gate a fast-firing enable/disable/enable sequence could
+        // leak duplicate backend subscriptions OR end up with an
+        // un-unsubscribed handle when connection closes.
+        if (pushEnabled) return;
+        // SYNC flip: gate concurrent PushEnable calls before the
+        // async subscribePush resolves. PushDisable / close that
+        // arrive in the gap see pushEnabled=true + a pending
+        // pushSetupPromise; the setup promise's `then` handles the
+        // late-cleanup case via the connClosed flag.
+        pushEnabled = true;
+        var dataTypes = Array.isArray(parsed.dataTypes) && parsed.dataTypes.length > 0
+          ? parsed.dataTypes : null;
+        pushSetupPromise = Promise.resolve()
+          .then(function () {
+            return opts.mailStore.subscribePush(actor, dataTypes, function (event) {
+              if (!event || connClosed) return;
+              if (event.kind === "StateChange") {
+                _sendJson({
+                  "@type":  "StateChange",
+                  changed:  event.changed || {},
+                  pushed:   event.pushed,
+                });
+              }
+            });
+          })
+          .then(function (unsub) {
+            pushUnsubscribe = typeof unsub === "function" ? unsub : null;
+            // Late cleanup: if Disable / close arrived in the setup
+            // gap, run the unsubscribe immediately.
+            if ((connClosed || !pushEnabled) && typeof pushUnsubscribe === "function") {
+              try { pushUnsubscribe(); }
+              catch (_e) { /* silent-catch: drop-silent — unsubscribe is best-effort */ }
+              pushUnsubscribe = null;
+            }
+          })
+          .catch(function (err) {
+            // Setup failed — roll back the sync flip so a retry can
+            // succeed, and surface the error to the operator client.
+            pushEnabled = false;
+            _sendRequestError(null,
+              "urn:ietf:params:jmap:error:serverFail",
+              (err && err.message) || "subscribePush threw");
+          });
+        return;
+      }
+
+      if (type === "WebSocketPushDisable") {
+        // Mark disabled first so an in-flight subscribePush sees
+        // pushEnabled=false in its late-cleanup branch.
+        pushEnabled = false;
+        if (typeof pushUnsubscribe === "function") {
+          try { pushUnsubscribe(); }
+          catch (_e) { /* silent-catch: drop-silent — unsubscribe is best-effort */ }
+        }
+        pushUnsubscribe = null;
+        return;
+      }
+
+      _sendRequestError(requestId,
+        "urn:ietf:params:jmap:error:unknownDataType",
+        "Unknown WebSocket frame @type '" + type + "' (RFC 8887 §4)");
+    });
+
+    conn.on("close", function () {
+      // SYNC flip — an in-flight subscribePush.then() observes
+      // connClosed=true and runs the late-cleanup unsubscribe path.
+      connClosed = true;
+      pushEnabled = false;
+      if (typeof pushUnsubscribe === "function") {
+        try { pushUnsubscribe(); }
+        catch (_e) { /* silent-catch: drop-silent */ }
+      }
+      pushUnsubscribe = null;
+    });
+    void pushSetupPromise;
+
+    return conn;
+  }
+
   function discoveryHandler(req, res) {
     // RFC 8620 §2.2 — well-known endpoint redirects (or directly returns)
     // the session URL. We redirect to /jmap/session per the most common
@@ -990,6 +1209,7 @@ function create(opts) {
     eventSourceHandler:   eventSourceHandler,
     uploadHandler:        uploadHandler,
     downloadHandler:      downloadHandler,
+    webSocketHandler:     webSocketHandler,
     MailServerJmapError:  MailServerJmapError,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.33",
+  "version": "0.11.35",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:10fe079a-bfcc-4ffe-84e1-55a6b5b11ccf",
+  "serialNumber": "urn:uuid:ce80c06c-78db-449e-871f-1b1da1e018c7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T18:47:05.672Z",
+    "timestamp": "2026-05-21T20:42:06.128Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.33",
+      "bom-ref": "@blamejs/core@0.11.35",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.33",
+      "version": "0.11.35",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.33",
+      "purl": "pkg:npm/%40blamejs/core@0.11.35",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.33",
+      "ref": "@blamejs/core@0.11.35",
       "dependsOn": []
     }
   ]