@blamejs/core 0.11.34 → 0.11.35

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.34",
+  "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:ae6b3d2c-59a3-48d1-ade0-1b48f59dfdef",
+  "serialNumber": "urn:uuid:ce80c06c-78db-449e-871f-1b1da1e018c7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T19:31:15.355Z",
+    "timestamp": "2026-05-21T20:42:06.128Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.34",
+      "bom-ref": "@blamejs/core@0.11.35",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.34",
+      "version": "0.11.35",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.34",
+      "purl": "pkg:npm/%40blamejs/core@0.11.35",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.34",
+      "ref": "@blamejs/core@0.11.35",
       "dependsOn": []
     }
   ]