@blamejs/core 0.11.36 → 0.11.38

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.38 (2026-05-21) — **`b.mail.server.jmap.emailSubmissionSetHandler` — reference JMAP EmailSubmission/set composing `b.mail.send.deliver`.** Reference implementation of JMAP `EmailSubmission/set` (RFC 8621 §7.5) that composes `b.mail.send.deliver` (v0.11.24). Operators wire it as a method handler on `b.mail.server.jmap.create({ methods: ... })`. The handler walks `args.create`, validates each EmailSubmission's shape against the RFC 8621 §7.5 vocabulary (`identityId` / `emailId` / `envelope.mailFrom.email` / `envelope.rcptTo[]`), looks up the referenced Email blob via an operator-supplied `lookupEmail(emailId, accountId, actor)`, hands the RFC 822 body to `deliver(envelope)`, and maps the result into JMAP `deliveryStatus` (`recipient → { smtpReply, delivered, displayed }` per RFC 8621 §7.4). Closes the v0.11.24 deferral on a reference JMAP→deliver bridge. **Added:** *`b.mail.server.jmap.emailSubmissionSetHandler(opts)` factory* — Returns an async `(actor, args, ctx) → result` function suitable for the `opts.methods` map on `b.mail.server.jmap.create`. Required opts: `deliver` (a `b.mail.send.deliver` instance), `lookupEmail` (async `(emailId, accountId, actor) → Buffer|null`), `identities` (sync `(accountId) → Array<{ id, email }>`). Optional: `onCreated(subId, submission, accountId)` for persistence, `onDestroyed(subId, accountId)`, `onCancel(subId, accountId) → boolean` for undo support, `maxRecipients` (default 1000). · *Full RFC 8621 §7.5 error vocabulary* — Refusals map to the spec's typed `notCreated` shape with JMAP-namespaced types: `identityNotFound` (unknown identityId), `emailNotFound` (lookupEmail returned null), `forbiddenMailFrom` (envelope.mailFrom doesn't match identity.email), `invalidRecipients` (malformed envelope.rcptTo[i].email), `noRecipients` (empty rcptTo), `tooManyRecipients` (exceeds maxRecipients), `invalidProperties` (missing required keys). Per RFC 8621 §3.6.2, only `undoStatus` is honored in `args.update`; non-canceled values + non-undoStatus keys return `invalidProperties`. · *Delivery-result → JMAP deliveryStatus mapping* — `b.mail.send.deliver`'s `{ delivered, deferred, failed }` outcomes translate into the per-recipient JMAP deliveryStatus shape: `delivered` → `{ smtpReply, delivered: "yes" }`; `deferred` → `{ smtpReply, delivered: "queued" }`; `failed` → `{ smtpReply, delivered: "no" }`. `displayed` is `unknown` until a downstream MDN (RFC 9007) reports otherwise — operators with MDN ingest update via `EmailSubmission/set`'s update branch. · *Undo via `onCancel` hook* — `args.update[subId] = { undoStatus: "canceled" }` invokes `opts.onCancel(subId, accountId) → boolean`. Operators backing the JMAP server with a deferred-send queue (e.g. `b.outbox`) return true when the cancel succeeded; the handler refuses with `cannotUnsend` when `onCancel` isn't configured (operator hasn't wired a queue-based send model). · *Audit event on every set* — Emits `mail.jmap.emailsubmission.set` with `{ accountId, created, notCreated, updated, notUpdated, destroyed, notDestroyed }` counts. The metadata never carries recipient email addresses or RFC 822 body bytes — those stay in the operator's deliver primitive's per-host audit stream. **Security:** *Identity binding refuses spoofed `envelope.mailFrom`* — RFC 8621 §7.5.1.2 — every create gates `envelope.mailFrom.email` against the identity record's `email` field. The reference handler refuses with `forbiddenMailFrom` when they differ. Operators wiring a delegation model populate the identity's `mayDelegate` / per-domain authorized-senders list and supply the corresponding `identities(accountId)` lookup; the reference handler treats the lookup output as the trust source. · *Recipient count cap matches `b.mail.send.deliver`* — Default `maxRecipients = 1000` aligns with `b.mail.send.deliver`'s recipient-fan-out cap; operators reduce it for tighter postures (e.g. 50 for transactional-mail accounts) without weakening the deliver primitive's own gate. **Detectors:** *Two new KNOWN_CLUSTERS family-subset entries* — The new handler's opts-walk shingle structurally resembles `lib/importmap-integrity.js:build` (SRI module-map walk) and `lib/middleware/security-headers.js:create` (header-map walk). Added explanatory family-subset entries documenting why each primitive's per-entry body validates a distinct spec vocabulary (W3C Importmap-Integrity vs RFC 8621 §7.5 EmailSubmission vs HTTP header-value sanitisation) so the dup detector can't surface the false-positive again. **References:** [RFC 8621 §7 (JMAP EmailSubmission)](https://www.rfc-editor.org/rfc/rfc8621.html#section-7) · [RFC 8621 §7.5 (EmailSubmission/set)](https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5) · [RFC 8621 §7.4 (deliveryStatus shape)](https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4) · [RFC 8620 §3.6.1 (JMAP error vocabulary)](https://www.rfc-editor.org/rfc/rfc8620.html#section-3.6.1)
+
+- v0.11.37 (2026-05-21) — **`b.calendar` VJOURNAL ↔ JSCalendar Note (RFC 5545 §3.6.3).** Closes the v0.11.31 deferral on VJOURNAL. `b.calendar.fromIcal` now recognises VJOURNAL components and maps them to JSCalendar-shaped Note objects (`@type: "Note"`). `b.calendar.toIcal` emits a VJOURNAL envelope when the input `@type` is `Note`. `b.calendar.validate` adds Note-specific shape rules: optional `start` LocalDateTime, no `duration` / `due` / `progress` / `percentComplete` / `progressUpdated` (those are Event / Task-only properties), optional `status` from the RFC 5545 §3.8.1.11 VJOURNAL vocabulary (`draft` | `final` | `cancelled`). VJOURNAL is the only iCalendar component that may carry multiple DESCRIPTION properties — Note preserves operator-visible boundaries by joining them with a blank-line separator. A VCALENDAR carrying VEVENT + VTODO + VJOURNAL children now returns a mixed `Event` + `Task` + `Note` array. **Added:** *`b.calendar.fromIcal` maps VJOURNAL → JSCalendar Note* — VJOURNAL components in the VCALENDAR map to `@type: "Note"` objects with `uid` / `updated` / `title` (SUMMARY) / `description` (DESCRIPTION) / `start` (DTSTART → LocalDateTime, optional) / `timeZone` / `status` (lower-cased STATUS) / `locations` / `recurrenceRules`. UTC DTSTART maps to `timeZone: "Etc/UTC"` the same way DTSTART does for Event. · *`b.calendar.toIcal` emits VJOURNAL when `@type === "Note"`* — The envelope is `BEGIN:VJOURNAL` / `END:VJOURNAL` instead of `BEGIN:VEVENT` or `BEGIN:VTODO`. Note's `status` round-trips uppercased per RFC 5545 §3.8.1.11. Note does NOT emit DURATION / DUE / PERCENT-COMPLETE / COMPLETED on the wire (those properties are forbidden on VJOURNAL per RFC 5545 §3.6.3 grammar). · *`b.calendar.validate` learns Note-specific shape rules (RFC 5545 §3.6.3)* — Note's `start` must be a LocalDateTime when present. Setting `duration`, `due`, `progress`, `percentComplete`, or `progressUpdated` on a Note is refused (those are Event / Task-only properties). `status` must be in the `JSCAL_NOTE_STATUS` catalogue (`draft` | `final` | `cancelled` — different from the Task progress vocabulary). Structured `CalendarError` codes: `calendar/bad-note-status` plus reuse of `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-duration`, `calendar/bad-percent`, `calendar/bad-progress-updated` for the forbidden-property refusals. · *Multiple DESCRIPTION properties preserved* — VJOURNAL is the only iCalendar component permitted to carry multiple DESCRIPTION properties (one per discrete journal entry). `fromIcal` joins them into a single Note.description with `\n\n` between entries, preserving the operator-visible boundary. Single-DESCRIPTION VJOURNALs map to the literal string with no join. · *Mixed-component VCALENDAR returns array of Event + Task + Note shapes* — A VCALENDAR carrying VEVENT + VTODO + VJOURNAL children now returns an Array — events first, tasks second, journals third, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`JSCAL_TYPES.Note` and `JSCAL_NOTE_STATUS` exports* — `b.calendar.JSCAL_TYPES.Note === "Note"` (the discriminator string). `b.calendar.JSCAL_NOTE_STATUS` exposes the `draft` / `final` / `cancelled` vocabulary as a frozen object for operator-side enum lookups. **Changed:** *JSCalendar `Note` is a blamejs-recognised extension* — RFC 8984 §1.2 only enumerates `Event`, `Task`, and `Group` as discriminator values. `Note` is not formally an RFC 8984 type — blamejs adopts it as a recognised extension shape for VJOURNAL round-trip interop. Operators interoperating with strict RFC 8984 consumers should map Note → Group + a vendor-namespaced property before exchange. **References:** [RFC 5545 §3.6.3 (iCalendar VJOURNAL component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.3) · [RFC 5545 §3.8.1.11 (STATUS — DRAFT/FINAL/CANCELLED on VJOURNAL)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11) · [RFC 8984 §1.2 (JSCalendar @type discriminator)](https://www.rfc-editor.org/rfc/rfc8984.html#section-1.2)
+
 - v0.11.36 (2026-05-21) — **`b.calendar.expandRecurrence` picks up BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND filters (RFC 5545 §3.3.10).** Closes the v0.11.31 deferral on the time-of-day and year-relative BY* filters. `expandRecurrence` now honours `byWeekNo` (ISO 8601 1..53 with negative-from-end semantics), `byYearDay` (1..366 with negative-from-end), `byHour` (0..23), `byMinute` (0..59), and `bySecond` (0..60 — covers POSIX leap-second representation). The expansion still operates as a per-step filter (stepping at the rule's FREQ, then dropping candidates that fail the BY* predicates) — BYSETPOS remains deferred-with-condition because it requires expanding ALL candidates within a FREQ interval and picking the Nth, which is a structural restructure of the expand loop. Operators with `last weekday of month`-style needs continue to see the same defer note from v0.11.31. **Added:** *`byWeekNo` filter — ISO 8601 week numbers* — `recurrenceRules[i].byWeekNo: [1, 53, -1]` filters candidates to the named ISO 8601 weeks. Negative values count from the end of the year (`-1` = last ISO week, which may be week 52 or week 53 depending on the year). The ISO week-of-year calculation matches the canonical algorithm — week 1 is the week containing the first Thursday of the year. · *`byYearDay` filter — day-of-year (1..366 / -1..-366)* — `recurrenceRules[i].byYearDay: [1, 366, -1]` filters by ordinal day-of-year. Negative values count from the end of the year, accounting for leap-year length (366 vs 365). With a `frequency: "daily"` rule + `byYearDay: [1]` the expander emits Jan 1 of each year. · *`byHour` / `byMinute` / `bySecond` time-of-day filters* — `byHour: [9, 17]` filters candidates by UTC hour-of-day (0..23). `byMinute: [0, 30]` (0..59). `bySecond: [0, 30, 60]` (0..60 — the leap-second representation in POSIX time). Most useful with sub-day frequencies — `frequency: "hourly"` + `byHour: [9, 17]` emits twice-daily at 9am and 5pm. · *Negative BY* semantics per RFC 5545 §3.3.10* — `byWeekNo: [-1]` matches the last ISO week of the year (computed via the Dec-28 anchor — Dec 28 always falls in the last ISO week). `byYearDay: [-1]` matches the last day of the year (uses the Gregorian leap-year rule to determine whether 365 or 366 is the correct ordinal). Both negative-value paths covered by tests. **Security:** *Same step-budget cap from v0.11.31 applies* — Sparse BY* filters (e.g. `byYearDay: [1]` with `frequency: "daily"` — only 1 in 365 candidates matches) still loop within the `MAX_EXPAND_INSTANCES * 366` step budget; the 10-year `MAX_EXPAND_SPAN_MS` window cap also applies. Operators can't construct a BY*-filter that loops past the bounded budget. · *Integer-range validation on every BY* value* — `byWeekNo` rejects values outside ±53. `byYearDay` rejects outside ±366. `byHour` 0..23. `byMinute` 0..59. `bySecond` 0..60. Adversarial-shape values silently drop from the set (no error — the rule continues with the surviving values per RFC 5545's tolerant grammar). **References:** [RFC 5545 §3.3.10 (RRULE — BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.3.10) · [RFC 8984 §4.3.2 (JSCalendar RecurrenceRule)](https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.2) · [ISO 8601 (Week numbering)](https://www.iso.org/iso-8601-date-and-time-format.html)
 
 - 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)

package/lib/calendar.js

@@ -42,6 +42,14 @@ var CalendarError = defineClass("CalendarError", { alwaysPermanent: true });
 var JSCAL_TYPES = Object.freeze({
   Event:        "Event",
   Task:         "Task",
+  // Note maps RFC 5545 §3.6.3 VJOURNAL — a dated, free-form journal
+  // entry with no duration / progress / due semantics. Not formally
+  // defined as an @type in RFC 8984 §1.2 (which only enumerates
+  // Event + Task + Group); blamejs adopts `Note` as a recognised
+  // extension shape for VJOURNAL round-trip interop with iCalendar
+  // sources. Operators interoperating with strict RFC 8984 consumers
+  // should map Note → Group or Note → custom-@type before exchange.
+  Note:         "Note",
   Group:        "Group",
   Participant:  "Participant",
   Location:     "Location",
@@ -73,6 +81,15 @@ var JSCAL_TASK_PROGRESS = Object.freeze({
   "needs-action": 1, "in-process": 1, "completed": 1, "cancelled": 1,
 });
 
+// RFC 5545 §3.8.1.11 STATUS for VJOURNAL — Note carries DRAFT / FINAL
+// / CANCELLED. JSCalendar lower-cases them on import/export. Note's
+// `status` is OPTIONAL; absence on the wire maps to `status`
+// unset (rather than defaulting to "draft" — operator intent is
+// ambiguous when STATUS is omitted, per RFC 5545 grammar).
+var JSCAL_NOTE_STATUS = Object.freeze({
+  "draft": 1, "final": 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
@@ -106,9 +123,9 @@ function validate(jsCal) {
       "b.calendar.validate: input must be a JSCalendar object");
   }
   var t = jsCal["@type"];
-  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task) {
+  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task && t !== JSCAL_TYPES.Note) {
     throw new CalendarError("calendar/bad-type",
-      "b.calendar.validate: @type must be 'Event' or 'Task' (got " + JSON.stringify(t) + ")");
+      "b.calendar.validate: @type must be 'Event' or 'Task' or 'Note' (got " + JSON.stringify(t) + ")");
   }
   if (typeof jsCal.uid !== "string" || jsCal.uid.length === 0) {
     throw new CalendarError("calendar/no-uid",
@@ -170,6 +187,43 @@ function validate(jsCal) {
         "b.calendar.validate: Task.progressUpdated MUST be a UTCDateTime");
     }
   }
+  if (t === JSCAL_TYPES.Note) {
+    // Note (VJOURNAL) — dated free-form journal entry. RFC 5545
+    // §3.6.3 permits an optional DTSTART (date or date-time) and
+    // SUMMARY / DESCRIPTION; STATUS values are limited to DRAFT /
+    // FINAL / CANCELLED. There is no DUE / DURATION / COMPLETED /
+    // PERCENT-COMPLETE on VJOURNAL.
+    if (jsCal.start !== undefined && (typeof jsCal.start !== "string" || !_isLocalDateTime(jsCal.start))) {
+      throw new CalendarError("calendar/bad-start",
+        "b.calendar.validate: Note.start MUST be a LocalDateTime (RFC 5545 §3.6.3)");
+    }
+    if (jsCal.duration !== undefined) {
+      throw new CalendarError("calendar/bad-duration",
+        "b.calendar.validate: Note.duration MUST NOT be set (RFC 5545 §3.6.3 VJOURNAL has no DURATION)");
+    }
+    if (jsCal.due !== undefined) {
+      throw new CalendarError("calendar/bad-due",
+        "b.calendar.validate: Note.due MUST NOT be set (DUE is a VTODO-only property)");
+    }
+    if (jsCal.progress !== undefined) {
+      throw new CalendarError("calendar/bad-progress",
+        "b.calendar.validate: Note.progress MUST NOT be set (progress is a Task-only property)");
+    }
+    if (jsCal.percentComplete !== undefined) {
+      throw new CalendarError("calendar/bad-percent",
+        "b.calendar.validate: Note.percentComplete MUST NOT be set (percentComplete is a Task-only property)");
+    }
+    if (jsCal.progressUpdated !== undefined) {
+      throw new CalendarError("calendar/bad-progress-updated",
+        "b.calendar.validate: Note.progressUpdated MUST NOT be set (progressUpdated is a Task-only property)");
+    }
+    if (jsCal.status !== undefined &&
+        !Object.prototype.hasOwnProperty.call(JSCAL_NOTE_STATUS, jsCal.status)) {
+      throw new CalendarError("calendar/bad-note-status",
+        "b.calendar.validate: Note.status MUST be one of " +
+        Object.keys(JSCAL_NOTE_STATUS).join(" | ") + " (RFC 5545 §3.8.1.11 VJOURNAL STATUS)");
+    }
+  }
   if (jsCal.recurrenceRules !== undefined) {
     if (!Array.isArray(jsCal.recurrenceRules)) {
       throw new CalendarError("calendar/bad-recurrence",
@@ -234,14 +288,16 @@ function validate(jsCal) {
  */
 function fromIcal(text, opts) {
   var ast = safeIcal.parse(text, opts || {});
-  var events = (ast && ast.vcalendar && ast.vcalendar.vevent) || [];
-  var todos  = (ast && ast.vcalendar && ast.vcalendar.vtodo)  || [];
-  if (events.length === 0 && todos.length === 0) {
+  var events   = (ast && ast.vcalendar && ast.vcalendar.vevent)   || [];
+  var todos    = (ast && ast.vcalendar && ast.vcalendar.vtodo)    || [];
+  var journals = (ast && ast.vcalendar && ast.vcalendar.vjournal) || [];
+  if (events.length === 0 && todos.length === 0 && journals.length === 0) {
     throw new CalendarError("calendar/no-component",
-      "b.calendar.fromIcal: VCALENDAR has no VEVENT or VTODO components");
+      "b.calendar.fromIcal: VCALENDAR has no VEVENT, VTODO or VJOURNAL components");
   }
   var converted = events.map(_veventToJsCalEvent)
-    .concat(todos.map(_vtodoToJsCalTask));
+    .concat(todos.map(_vtodoToJsCalTask))
+    .concat(journals.map(_vjournalToJsCalNote));
   return converted.length === 1 ? converted[0] : converted;
 }
 
@@ -276,7 +332,9 @@ function toIcal(jsCal, opts) {
   // 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 component = jsCal["@type"] === "Task"
+    ? "VTODO"
+    : jsCal["@type"] === "Note" ? "VJOURNAL" : "VEVENT";
   var lines = [
     "BEGIN:VCALENDAR",
     "VERSION:2.0",
@@ -324,6 +382,11 @@ function toIcal(jsCal, opts) {
   if (component === "VTODO" && jsCal.progress) {
     lines.push("STATUS:" + String(jsCal.progress).toUpperCase());
   }
+  // RFC 5545 §3.8.1.11 — VJOURNAL STATUS values are DRAFT / FINAL /
+  // CANCELLED. JSCalendar Note carries them lower-cased; emit upper.
+  if (component === "VJOURNAL" && jsCal.status) {
+    lines.push("STATUS:" + String(jsCal.status).toUpperCase());
+  }
   if (component === "VTODO" && typeof jsCal.percentComplete === "number") {
     lines.push("PERCENT-COMPLETE:" + jsCal.percentComplete);
   }
@@ -664,6 +727,72 @@ function _vtodoToJsCalTask(vt) {
   return jsCal;
 }
 
+// RFC 5545 §3.6.3 — VJOURNAL maps to a JSCalendar-shaped Note. The
+// VJOURNAL grammar permits MULTIPLE DESCRIPTION properties (the only
+// iCalendar component that does); blamejs joins them with a single
+// blank line to preserve operator-visible separators. STATUS is
+// limited to DRAFT / FINAL / CANCELLED (different from VTODO's
+// vocabulary), with no DUE / DURATION / PERCENT-COMPLETE / COMPLETED.
+function _vjournalToJsCalNote(vj) {
+  var props = (vj && vj.properties) || {};
+  var jsCal = {
+    "@type":  "Note",
+    uid:      _firstValue(props.UID) || "",
+    updated:  _icalDateTimeToUtc(_firstValue(props.DTSTAMP) || ""),
+  };
+  var summary = _firstValue(props.SUMMARY);
+  if (summary) jsCal.title = _unescapeText(summary);
+  // RFC 5545 §3.6.3 — VJOURNAL is the only component that may carry
+  // multiple DESCRIPTION properties (one per discrete journal entry).
+  // Concatenate them with a blank-line separator so downstream
+  // consumers see the operator-visible boundaries.
+  var descriptions = _allValues(props.DESCRIPTION);
+  if (descriptions.length === 1) {
+    jsCal.description = _unescapeText(descriptions[0]);
+  } else if (descriptions.length > 1) {
+    var parts = [];
+    for (var di = 0; di < descriptions.length; di += 1) {
+      parts.push(_unescapeText(descriptions[di]));
+    }
+    jsCal.description = parts.join("\n\n");
+  }
+  var dtstart = _firstValue(props.DTSTART);
+  if (dtstart) jsCal.start = _icalDateTimeToLocal(dtstart);
+  var tzid = _firstParamValue(props.DTSTART, "TZID");
+  if (tzid) {
+    jsCal.timeZone = tzid;
+  } else if (typeof dtstart === "string" && /Z$/.test(dtstart)) {
+    jsCal.timeZone = "Etc/UTC";
+  }
+  var status = _firstValue(props.STATUS);
+  if (status) {
+    var statusLower = String(status).toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(JSCAL_NOTE_STATUS, statusLower)) {
+      jsCal.status = statusLower;
+    }
+  }
+  var location = _firstValue(props.LOCATION);
+  if (location) {
+    jsCal.locations = { L1: { "@type": "Location", name: _unescapeText(location) } };
+  }
+  var rrule3 = _firstValue(props.RRULE);
+  if (rrule3) jsCal.recurrenceRules = [_icalRruleToJscal(rrule3)];
+  return jsCal;
+}
+
+function _allValues(prop) {
+  if (!prop) return [];
+  if (Array.isArray(prop)) {
+    var out = [];
+    for (var i = 0; i < prop.length; i += 1) {
+      var item = prop[i];
+      if (item && item.value !== undefined) out.push(item.value);
+    }
+    return out;
+  }
+  return prop.value !== undefined ? [prop.value] : [];
+}
+
 function _firstValue(prop) {
   if (!prop) return null;
   if (Array.isArray(prop)) {
@@ -809,6 +938,7 @@ module.exports = {
   JSCAL_FREQUENCIES:      JSCAL_FREQUENCIES,
   JSCAL_ALERT_ACTIONS:    JSCAL_ALERT_ACTIONS,
   JSCAL_TASK_PROGRESS:    JSCAL_TASK_PROGRESS,
+  JSCAL_NOTE_STATUS:      JSCAL_NOTE_STATUS,
   MAX_EXPAND_INSTANCES:   MAX_EXPAND_INSTANCES,
   MAX_EXPAND_SPAN_MS:     MAX_EXPAND_SPAN_MS,
 };

package/lib/mail-server-jmap.js

@@ -1214,7 +1214,352 @@ function create(opts) {
   };
 }
 
+/**
+ * @primitive b.mail.server.jmap.emailSubmissionSetHandler
+ * @signature b.mail.server.jmap.emailSubmissionSetHandler(opts)
+ * @since     0.11.38
+ * @status    stable
+ * @related   b.mail.server.jmap.create
+ * @compliance gdpr, soc2
+ *
+ * Reference implementation of JMAP `EmailSubmission/set` (RFC 8621 §7.5)
+ * that composes `b.mail.send.deliver`. Returns an async method-handler
+ * suitable for plumbing into `b.mail.server.jmap.create({ methods: ... })`.
+ *
+ * The handler:
+ *
+ *   1. Walks `args.create` per RFC 8621 §7.5. For each EmailSubmission:
+ *      - Refuses `identityId` not registered in `opts.identities(accountId)`.
+ *      - Refuses `emailId` absent — calls `opts.lookupEmail(emailId,
+ *        accountId, actor)` to fetch the RFC 822 blob (refuses
+ *        `emailNotFound` when null).
+ *      - Refuses missing or oversize `envelope.rcptTo` (max 1000 per
+ *        the same recipient cap `b.mail.send.deliver` enforces).
+ *      - Validates `envelope.mailFrom.email` matches the identity's
+ *        authorized addresses (`forbiddenMailFrom` per RFC 8621
+ *        §7.5.1.2 when not).
+ *   2. Hands the RFC 822 blob to the supplied `opts.deliver(envelope)`
+ *      (a `b.mail.send.deliver.create()` instance).
+ *   3. Maps `deliver`'s `{ delivered, deferred, failed }` result into
+ *      JMAP `deliveryStatus` (`recipient → { smtpReply, delivered,
+ *      displayed }` per RFC 8621 §7.4).
+ *   4. Calls `opts.onCreated(subId, submission, accountId)` so the
+ *      operator can persist the EmailSubmission record (state survives
+ *      across JMAP requests via `EmailSubmission/get`).
+ *
+ * `args.destroy` removes EmailSubmission records via
+ * `opts.onDestroyed(subId, accountId)` — the delivery itself cannot
+ * be unsent at this point; `destroy` only removes the JMAP-visible
+ * record.
+ *
+ * `args.update` is honored only for the `undoStatus: "canceled"`
+ * transition per RFC 8621 §7.5.2 (operators with a queue-based
+ * deferred-send model wire `opts.onCancel(subId, accountId)`; the
+ * reference handler refuses with `cannotUnsend` when no `onCancel`
+ * is configured).
+ *
+ * @opts
+ *   deliver:        async function (envelope),    // b.mail.send.deliver instance (REQUIRED)
+ *   lookupEmail:    async function (emailId, accountId, actor) → Buffer|null,  (REQUIRED)
+ *   identities:     function (accountId) → [ { id, email, mayDelegate } ], (REQUIRED)
+ *   onCreated:      async function (subId, submission, accountId), (optional)
+ *   onDestroyed:    async function (subId, accountId),             (optional)
+ *   onCancel:       async function (subId, accountId) → boolean,   (optional — undo support)
+ *   maxRecipients:  number,                                       // default 1000
+ *
+ * @example
+ *   var deliver = b.mail.send.deliver({ hostname: "mta.example.com" });
+ *   var emailSubSet = b.mail.server.jmap.emailSubmissionSetHandler({
+ *     deliver:     deliver,
+ *     lookupEmail: async function (emailId, accountId) {
+ *       return mailStore.fetchBlob(accountId, emailId);
+ *     },
+ *     identities:  function (accountId) {
+ *       return [{ id: "I1", email: "ops@example.com" }];
+ *     },
+ *     onCreated:   async function (id, sub, accountId) { return; },
+ *   });
+ *
+ *   var jmap = b.mail.server.jmap.create({
+ *     mailStore:   store,
+ *     accountsFor: async function () { return { primaryAccounts: {}, accounts: {} }; },
+ *     methods:     { "EmailSubmission/set": emailSubSet },
+ *   });
+ */
+function emailSubmissionSetHandler(opts) {
+  validateOpts.requireObject(opts, "mail.server.jmap.emailSubmissionSetHandler",
+    MailServerJmapError, "mail-server-jmap/bad-opts");
+  if (typeof opts.deliver !== "function") {
+    throw new MailServerJmapError("mail-server-jmap/no-deliver",
+      "emailSubmissionSetHandler: opts.deliver async function is required " +
+      "(compose b.mail.send.deliver.create({ ... }))");
+  }
+  if (typeof opts.lookupEmail !== "function") {
+    throw new MailServerJmapError("mail-server-jmap/no-lookup-email",
+      "emailSubmissionSetHandler: opts.lookupEmail(emailId, accountId, actor) async function is required");
+  }
+  if (typeof opts.identities !== "function") {
+    throw new MailServerJmapError("mail-server-jmap/no-identities",
+      "emailSubmissionSetHandler: opts.identities(accountId) function is required (returns Array<{id,email}>)");
+  }
+  var maxRecipients = opts.maxRecipients || 1000;                                                       // allow:raw-byte-literal — recipient cap mirrors b.mail.send.deliver
+  if (typeof maxRecipients !== "number" || !isFinite(maxRecipients) || maxRecipients < 1) {
+    throw new MailServerJmapError("mail-server-jmap/bad-max-recipients",
+      "emailSubmissionSetHandler: opts.maxRecipients MUST be a positive integer");
+  }
+
+  return async function emailSubmissionSet(actor, args, _ctx) {
+    if (!args || typeof args !== "object" || typeof args.accountId !== "string") {
+      throw new MailServerJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "EmailSubmission/set: accountId is required");
+    }
+    var accountId = args.accountId;
+    var created     = {};
+    var notCreated  = {};
+    var updated     = {};
+    var notUpdated  = {};
+    var destroyed   = [];
+    var notDestroyed = {};
+
+    // ---- create branch (RFC 8621 §7.5.1) ----------------------------------
+    if (args.create && typeof args.create === "object" && !Array.isArray(args.create)) {
+      var createKeys = Object.keys(args.create);
+      for (var ci = 0; ci < createKeys.length; ci += 1) {
+        var clientId = createKeys[ci];
+        var sub = args.create[clientId];
+        try {
+          var result = await _processCreate(actor, accountId, sub);
+          created[clientId] = result;
+          if (typeof opts.onCreated === "function") {
+            try { await opts.onCreated(result.id, result, accountId); }
+            catch (_e) { /* drop-silent — persistence is operator side-effect */ }
+          }
+        } catch (err) {
+          notCreated[clientId] = _jmapErrorShape(err);
+        }
+      }
+    }
+
+    // ---- update branch (RFC 8621 §7.5.2 — undoStatus="canceled" only) -----
+    if (args.update && typeof args.update === "object" && !Array.isArray(args.update)) {
+      var updateKeys = Object.keys(args.update);
+      for (var ui = 0; ui < updateKeys.length; ui += 1) {
+        var subId = updateKeys[ui];
+        var patch = args.update[subId];
+        if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+          notUpdated[subId] = { type: "invalidPatch", description: "patch must be an object" };
+          continue;
+        }
+        var patchKeys = Object.keys(patch);
+        // RFC 8621 §7.5.2 — only `undoStatus` is mutable post-create.
+        var nonUndo = patchKeys.filter(function (k) { return k !== "undoStatus"; });
+        if (nonUndo.length > 0) {
+          notUpdated[subId] = {
+            type:        "invalidProperties",
+            properties:  nonUndo,
+            description: "only undoStatus may be updated on an EmailSubmission",
+          };
+          continue;
+        }
+        if (patch.undoStatus !== "canceled") {
+          notUpdated[subId] = {
+            type:        "invalidProperties",
+            properties:  ["undoStatus"],
+            description: "only undoStatus='canceled' is honored",
+          };
+          continue;
+        }
+        if (typeof opts.onCancel !== "function") {
+          notUpdated[subId] = {
+            type: "cannotUnsend",
+            description: "undo not supported (opts.onCancel was not configured)",
+          };
+          continue;
+        }
+        try {
+          var ok = await opts.onCancel(subId, accountId);
+          if (ok) updated[subId] = null;
+          else notUpdated[subId] = { type: "cannotUnsend" };
+        } catch (err) {
+          notUpdated[subId] = _jmapErrorShape(err);
+        }
+      }
+    }
+
+    // ---- destroy branch (RFC 8621 §7.5.3) ---------------------------------
+    if (Array.isArray(args.destroy)) {
+      for (var di = 0; di < args.destroy.length; di += 1) {
+        var destroyId = args.destroy[di];
+        if (typeof destroyId !== "string" || destroyId.length === 0) {
+          notDestroyed[String(destroyId)] = { type: "invalidArguments" };
+          continue;
+        }
+        if (typeof opts.onDestroyed === "function") {
+          try {
+            await opts.onDestroyed(destroyId, accountId);
+            destroyed.push(destroyId);
+          } catch (err) {
+            notDestroyed[destroyId] = _jmapErrorShape(err);
+          }
+        } else {
+          // No persistence wired — accept the destroy as a noop so the
+          // operator's clients can clean up client-side state.
+          destroyed.push(destroyId);
+        }
+      }
+    }
+
+    _emit("mail.jmap.emailsubmission.set", {
+      accountId:   accountId,
+      created:     Object.keys(created).length,
+      notCreated:  Object.keys(notCreated).length,
+      updated:     Object.keys(updated).length,
+      notUpdated:  Object.keys(notUpdated).length,
+      destroyed:   destroyed.length,
+      notDestroyed: Object.keys(notDestroyed).length,
+    });
+
+    return {
+      accountId:    accountId,
+      oldState:     args.ifInState || null,
+      newState:     bCrypto.generateToken(16),                                                          // allow:raw-byte-literal — opaque state token length
+      created:      Object.keys(created).length     > 0 ? created     : null,
+      notCreated:   Object.keys(notCreated).length  > 0 ? notCreated  : null,
+      updated:      Object.keys(updated).length     > 0 ? updated     : null,
+      notUpdated:   Object.keys(notUpdated).length  > 0 ? notUpdated  : null,
+      destroyed:    destroyed.length                > 0 ? destroyed   : null,
+      notDestroyed: Object.keys(notDestroyed).length > 0 ? notDestroyed : null,
+    };
+  };
+
+  // -------- per-create processing -------------------------------------------
+  async function _processCreate(actor, accountId, sub) {
+    if (!sub || typeof sub !== "object" || Array.isArray(sub)) {
+      throw _err("invalidArguments", "EmailSubmission must be an object");
+    }
+    if (typeof sub.identityId !== "string" || sub.identityId.length === 0) {
+      throw _err("invalidProperties", "identityId is required", ["identityId"]);
+    }
+    if (typeof sub.emailId !== "string" || sub.emailId.length === 0) {
+      throw _err("invalidProperties", "emailId is required", ["emailId"]);
+    }
+    if (!sub.envelope || typeof sub.envelope !== "object" || Array.isArray(sub.envelope)) {
+      throw _err("invalidProperties", "envelope is required", ["envelope"]);
+    }
+    var mailFrom = sub.envelope.mailFrom;
+    if (!mailFrom || typeof mailFrom !== "object" || typeof mailFrom.email !== "string") {
+      throw _err("invalidProperties", "envelope.mailFrom.email is required", ["envelope/mailFrom"]);
+    }
+    if (!Array.isArray(sub.envelope.rcptTo) || sub.envelope.rcptTo.length === 0) {
+      throw _err("noRecipients", "envelope.rcptTo must contain at least one Address");
+    }
+    if (sub.envelope.rcptTo.length > maxRecipients) {
+      throw _err("tooManyRecipients", "rcptTo exceeds " + maxRecipients);
+    }
+    var rcptEmails = [];
+    for (var ri = 0; ri < sub.envelope.rcptTo.length; ri += 1) {
+      var r = sub.envelope.rcptTo[ri];
+      if (!r || typeof r.email !== "string" || r.email.indexOf("@") <= 0) {
+        throw _err("invalidRecipients", "envelope.rcptTo[" + ri + "].email malformed");
+      }
+      rcptEmails.push(r.email);
+    }
+
+    // Identity gate (RFC 8621 §7.5.1.2 forbiddenMailFrom / §7.5.1.3 identityNotFound).
+    var identList = opts.identities(accountId) || [];
+    var identity = null;
+    for (var ii = 0; ii < identList.length; ii += 1) {
+      if (identList[ii].id === sub.identityId) { identity = identList[ii]; break; }
+    }
+    if (!identity) {
+      throw _err("identityNotFound", "no identity " + sub.identityId + " for account " + accountId);
+    }
+    if (identity.email && identity.email !== mailFrom.email) {
+      throw _err("forbiddenMailFrom",
+        "envelope.mailFrom.email does not match identity " + identity.id);
+    }
+
+    // Blob lookup (RFC 8621 §7.5.1.4 emailNotFound).
+    var rfc822 = await opts.lookupEmail(sub.emailId, accountId, actor);
+    if (rfc822 == null) {
+      throw _err("emailNotFound", "emailId " + sub.emailId + " not found");
+    }
+
+    // Hand to b.mail.send.deliver.
+    var deliverResult = await opts.deliver({
+      from:   mailFrom.email,
+      to:     rcptEmails,
+      rfc822: rfc822,
+    });
+
+    // Map deliver result → JMAP deliveryStatus (RFC 8621 §7.4).
+    var deliveryStatus = Object.create(null);
+    var delivered = deliverResult && deliverResult.delivered  ? deliverResult.delivered : [];
+    var deferred  = deliverResult && deliverResult.deferred   ? deliverResult.deferred  : [];
+    var failed    = deliverResult && deliverResult.failed     ? deliverResult.failed    : [];
+    for (var ddi = 0; ddi < delivered.length; ddi += 1) {
+      deliveryStatus[delivered[ddi].recipient] = {
+        smtpReply: delivered[ddi].smtpReply || "250 Accepted",
+        delivered: "yes",
+        displayed: "unknown",
+      };
+    }
+    for (var dfi = 0; dfi < deferred.length; dfi += 1) {
+      deliveryStatus[deferred[dfi].recipient] = {
+        smtpReply: deferred[dfi].smtpReply || "451 Temporary failure",
+        delivered: "queued",
+        displayed: "unknown",
+      };
+    }
+    for (var ffi = 0; ffi < failed.length; ffi += 1) {
+      deliveryStatus[failed[ffi].recipient] = {
+        smtpReply: failed[ffi].smtpReply || "550 Permanent failure",
+        delivered: "no",
+        displayed: "unknown",
+      };
+    }
+
+    var newId = bCrypto.generateToken(12);                                                              // allow:raw-byte-literal — JMAP-server-assigned id
+    return {
+      id:             newId,
+      identityId:     sub.identityId,
+      emailId:        sub.emailId,
+      threadId:       sub.threadId || null,
+      envelope:       sub.envelope,
+      sendAt:         new Date().toISOString(),
+      undoStatus:     "final",
+      deliveryStatus: deliveryStatus,
+      dsnBlobIds:     [],
+      mdnBlobIds:     [],
+    };
+  }
+
+  function _err(type, description, properties) {
+    var e = new MailServerJmapError("urn:ietf:params:jmap:error:" + type, description);
+    e._jmapType = type;
+    if (properties) e._jmapProperties = properties;
+    return e;
+  }
+
+  function _jmapErrorShape(err) {
+    if (err && err._jmapType) {
+      var shape = { type: err._jmapType };
+      if (err.message) shape.description = err.message;
+      if (err._jmapProperties) shape.properties = err._jmapProperties;
+      return shape;
+    }
+    return { type: "serverFail", description: (err && err.message) || String(err) };
+  }
+
+  function _emit(action, metadata) {
+    try {
+      audit().safeEmit({ action: action, outcome: "success", metadata: metadata || {} });
+    } catch (_e) { /* drop-silent */ }
+  }
+}
+
 module.exports = {
-  create:               create,
-  MailServerJmapError:  MailServerJmapError,
+  create:                     create,
+  emailSubmissionSetHandler:  emailSubmissionSetHandler,
+  MailServerJmapError:        MailServerJmapError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.36",
+  "version": "0.11.38",
   "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:7efc7160-930c-489d-ad69-8455a414189a",
+  "serialNumber": "urn:uuid:05d5b9da-ac1d-46ee-8a2c-f1b169e68091",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T21:48:29.730Z",
+    "timestamp": "2026-05-21T23:11:16.432Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.36",
+      "bom-ref": "@blamejs/core@0.11.38",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.36",
+      "version": "0.11.38",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.36",
+      "purl": "pkg:npm/%40blamejs/core@0.11.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.36",
+      "ref": "@blamejs/core@0.11.38",
       "dependsOn": []
     }
   ]