@blamejs/core 0.11.29 → 0.11.31

package/CHANGELOG.md

@@ -8,6 +8,14 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.31 (2026-05-21) — **`b.calendar` — JSCalendar (RFC 8984) primitive + JMAP Calendars method catalogue.** JSCalendar is the JSON-native calendar grammar JMAP Calendars rides on. The framework now ships `b.calendar` — a thin layer over the existing `b.safeIcal.parse` (RFC 5545 bounded parser shipped earlier) that exposes validate / fromIcal / toIcal / expandRecurrence. The JMAP method catalogue at `b.mail.serverRegistry` picks up the 15 Calendar / CalendarEvent / CalendarEventNotification / ParticipantIdentity methods per the draft-ietf-jmap-calendars spec, so operators wire them through the existing `b.mail.server.jmap.create({ methods: { ... } })` dispatch path without `allowExperimental: true` escape-hatches.
+
+v1 scope: validate JSCalendar Event / Task shape per RFC 8984 §5/§6, bidirectional VEVENT ↔ JSCalendar conversion, RRULE expansion for FREQ=DAILY/WEEKLY/MONTHLY/YEARLY/HOURLY/MINUTELY/SECONDLY with INTERVAL / COUNT / UNTIL / BYDAY / BYMONTH / BYMONTHDAY. BYSETPOS / BYWEEKNO / BYYEARDAY filters + non-Gregorian calendars (RFC 7529) + JSCalendar Group objects + VTODO/VJOURNAL mapping are deferred-with-condition for follow-up slices. **Added:** *`b.calendar.validate(jsCal)` — JSCalendar Event/Task shape gate (RFC 8984 §5/§6)* — Asserts `@type` ∈ { 'Event', 'Task' }, non-empty `uid` (≤ 1024 bytes), `updated` matches UTCDateTime grammar, Event's optional `start` matches LocalDateTime, `duration` is RFC 8601 PnYnMnDTnHnMnS, every `recurrenceRules[i].@type` is 'RecurrenceRule' with `frequency` in the JSCAL_FREQUENCIES catalogue, every `alerts.{id}.action` is 'display' or 'email'. Returns the input on success; throws `CalendarError` with a structured `.code` (`calendar/no-uid`, `calendar/bad-recurrence`, etc.) on refusal so operator-side error handling has a stable surface. · *`b.calendar.fromIcal(text, opts?)` + `b.calendar.toIcal(jsCal, opts?)`* — Bidirectional bridge: iCalendar (RFC 5545) ↔ JSCalendar (RFC 8984). `fromIcal` runs the text through `b.safeIcal.parse` (already CVE-bounded for parser DoS) and maps the first VEVENT into an Event object (UID → uid, DTSTAMP → updated, DTSTART → start, DURATION → duration, SUMMARY → title, DESCRIPTION → description, LOCATION → locations[L1].name, RRULE → recurrenceRules[0]). `toIcal` round-trips the same shape back through a CRLF-folded VCALENDAR envelope per RFC 5545 §3.1 (75-octet content-line cap). Operators wire it on the EmailSubmission send path so calendar invitations from a JSCalendar back-end emit RFC 5545 over MIME, and inbound iCalendar attachments parse straight into the JMAP method's Event return shape. · *`b.calendar.expandRecurrence(event, { from, to, max })` — bounded RRULE expansion* — Emits ISO 8601 UTC instance timestamps for an Event in the operator's `[from, to]` window. Supports FREQ=DAILY/WEEKLY/MONTHLY/YEARLY/HOURLY/MINUTELY/SECONDLY with INTERVAL, COUNT, UNTIL. Bounded by `MAX_EXPAND_INSTANCES` (4096) and `MAX_EXPAND_SPAN_MS` (10 years) — refuses with `calendar/oversize-expansion-span` when the window exceeds 10 years (CVE-2024-39687-class recurrence-bomb defense, mirroring the parser-side caps already in `b.safeIcal`). LocalDateTime starts without a `timeZone` are treated as floating-UTC during expansion so wall-clock semantics survive `Date.parse` host-locale interpretation. · *JMAP method catalogue: Calendar / CalendarEvent / CalendarEventNotification / ParticipantIdentity* — 15 new methods added to `JMAP_METHODS` in `lib/mail-server-registry.js` per draft-ietf-jmap-calendars: `Calendar/{get,changes,set,query,queryChanges}`, `CalendarEvent/{get,changes,query,queryChanges,set,copy}`, `CalendarEventNotification/{get,changes,query,queryChanges,set}`, `ParticipantIdentity/{get,changes,set}`. Operators wire concrete handlers through the existing `b.mail.server.jmap.create({ methods: { 'CalendarEvent/get': async function (actor, args) { ... } } })` path — no `allowExperimental: true` escape-hatch is required. **Security:** *Recurrence-bomb expansion caps* — `MAX_EXPAND_INSTANCES = 4096` + `MAX_EXPAND_SPAN_MS = 10 years` clamp the expansion budget at the framework boundary so an operator who forwards an unbounded JSCalendar from a hostile peer cannot DoS the host. The caps mirror `b.safeIcal`'s RRULE COUNT + BY-entries caps (which already defend the CVE-2024-39687 class). The 10-year span refusal carries `code: 'calendar/oversize-expansion-span'` so operators distinguish bomb defense from legitimate too-wide-window misconfiguration. · *UID + duration + UTCDateTime parsing is strict* — `validate` refuses `uid` over 1024 bytes (anti-DoS), `updated` that doesn't match the RFC 8984 §1.4.3 `\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z` UTCDateTime grammar exactly (no `+00:00` aliases, no fractional-second-only suffixes), and `duration` that isn't `PnYnMnDTnHnMnS`. Hostile JSCalendar payloads from federation peers can't slip non-canonical-shape values into the operator's storage layer through the validator. · *iCalendar parsing routed through bounded `b.safeIcal.parse`* — `fromIcal` does NOT roll its own RFC 5545 parser — it forwards to `b.safeIcal.parse` which is already audit-hardened (CVE-2024-39929 / CVE-2025-30258 mitigation, bounded depth, capped RRULE COUNT + BY-entries). The JSCalendar layer composes the existing security substrate rather than re-litigating it. **References:** [RFC 8984 (JSCalendar — JSON Representation of Calendar Data)](https://www.rfc-editor.org/rfc/rfc8984.html) · [RFC 5545 (iCalendar — Internet Calendaring and Scheduling Core Object)](https://www.rfc-editor.org/rfc/rfc5545.html) · [draft-ietf-jmap-calendars (JMAP for Calendars)](https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/) · [RFC 8620 (JMAP Core)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 8601 (Duration grammar PnYnMnDTnHnMnS)](https://www.rfc-editor.org/rfc/rfc3339.html) · [RFC 7986 (New properties for iCalendar)](https://www.rfc-editor.org/rfc/rfc7986.html) · [CVE-2024-39687 (iCalendar recurrence-bomb expansion)](https://nvd.nist.gov/vuln/detail/CVE-2024-39687)
+
+- v0.11.30 (2026-05-21) — **JMAP blob upload + download handlers on `b.mail.server.jmap` (RFC 8620 §6).** The JMAP listener now exposes turnkey HTTP handlers for blob upload (`POST /jmap/upload/{accountId}`) and blob download (`GET /jmap/download/{accountId}/{blobId}/{name}`). Upload streams the request body into `b.safeBuffer.boundedChunkCollector` (default cap 50 MiB; operator-tunable via `opts.maxBlobBytes`), then calls the operator backend's `mailStore.uploadBlob(actor, accountId, contentType, bytes) → { blobId, type?, size? }` and returns the JSON descriptor clients pass to subsequent `Email/set` / `Email/import` calls. Download walks the operator backend's `mailStore.downloadBlob(actor, accountId, blobId) → { bytes, type }` and pipes the bytes through with the right `Content-Type` + `Content-Disposition` headers. Both handlers refuse 503 when the corresponding backend hook is missing — never silent OK.
+
+EmailSubmission (RFC 8621 §7) was already in the JMAP method catalogue at `lib/mail-server-registry.js`; operators wire `EmailSubmission/get` / `EmailSubmission/set` through the existing `opts.methods` dispatch and compose `b.mail.send.deliver` (shipped v0.11.24) for the actual outbound send. No additional framework wiring is required. **Added:** *`uploadHandler(req, res)` — POST `/jmap/upload/{accountId}`* — Streams the request body through `b.safeBuffer.boundedChunkCollector` so a runaway upload refuses with `413 maxSizeUpload` instead of OOM'ing the process. Default cap 50 MiB; tune via `b.mail.server.jmap.create({ maxBlobBytes })`. The `accountId` path segment is identifier-shape-validated (`/^[A-Za-z0-9_-]{1,64}$/`) — path-traversal shapes are refused at the boundary. Calls `mailStore.uploadBlob(actor, accountId, contentType, bytes) → { blobId, type?, size? }`; the listener echoes `accountId` + `blobId` + `type` + `size` back as a `201 Created` JSON response per RFC 8620 §6.1. · *`downloadHandler(req, res)` — GET `/jmap/download/{accountId}/{blobId}/{name}`* — Parses the path's `accountId` / `blobId` / `name` segments + optional `?accept=<type>` query, calls `mailStore.downloadBlob(actor, accountId, blobId) → { bytes, type } | Buffer | null`, and pipes the bytes through with `Content-Type` (backend-supplied OR query-`accept` OR `application/octet-stream` fallback) + `Content-Length` + `Content-Disposition: attachment; filename="<safe-name>"` (only when the filename matches the safe `[A-Za-z0-9._-]{1,200}` shape — anti header-injection). Missing blob → `404 invalidArguments`. · *Both handlers exposed on the listener handle* — `b.mail.server.jmap.create(opts)` returns `{ apiHandler, sessionHandler, discoveryHandler, eventSourceHandler, uploadHandler, downloadHandler, MailServerJmapError }`. Operators mount each at the path their HTTP router exposes; the `session.uploadUrl` / `session.downloadUrl` already advertise the canonical paths. · *EmailSubmission methods continue through the existing dispatch path* — RFC 8621 §7 — `EmailSubmission/get` / `EmailSubmission/changes` / `EmailSubmission/query` / `EmailSubmission/queryChanges` / `EmailSubmission/set` are already in the JMAP method catalogue at `lib/mail-server-registry.js`. Operators wire them through `b.mail.server.jmap.create({ methods: { 'EmailSubmission/set': async function (actor, args) { ... b.mail.send.deliver(...) ... } } })`. No additional framework wiring is required for v0.11.30; the substrate composition (JMAP method → `b.mail.send.deliver` → SMTP MX → DSN) was already complete after v0.11.24. **Security:** *AccountId path-traversal refusal at the boundary* — Both handlers validate the `accountId` URL segment against `/^[A-Za-z0-9_-]{1,64}$/`. URL-encoded path-traversal payloads (`%2E%2E%2F`, `..%2F`, `/`) refuse with `400 invalidArguments` before any backend call. Operator-side validation in `mailStore.uploadBlob` / `mailStore.downloadBlob` is a defense-in-depth second layer. · *Upload size cap via `safeBuffer.boundedChunkCollector` (cap-bounded)* — Replaces the prior hand-rolled `Buffer.concat(chunks, received)` shape with the framework's bounded-collector primitive. The collector throws `mail-server-jmap/blob-too-large` on overflow; the handler converts it into a `413 maxSizeUpload` JSON error per RFC 8620 §6.1. A misbehaving client cannot stream a multi-gigabyte payload past the limit — the collector enforces the cap byte-by-byte. · *`Content-Disposition` filename is identifier-shape only* — Download responses only set the `Content-Disposition` header when the URL's `name` segment matches `/^[A-Za-z0-9._-]{1,200}$/`. Filenames with `;` / `"` / CRLF cannot be smuggled into the header — RFC 6266 §4.3 + CVE-2023-46604-class header-injection defense. **References:** [RFC 8620 (JMAP Core — §6 Blob upload/download)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 8621 (JMAP Mail — §7 EmailSubmission)](https://www.rfc-editor.org/rfc/rfc8621.html) · [RFC 6266 (Content-Disposition in HTTP)](https://www.rfc-editor.org/rfc/rfc6266.html) · [RFC 5987 (Encoding-aware filename* parameter)](https://www.rfc-editor.org/rfc/rfc5987.html)
+
 - v0.11.29 (2026-05-21) — **JMAP Push — EventSource SSE handler on `b.mail.server.jmap` (RFC 8620 §7.3).** The JMAP listener now exposes a real EventSource handler at `/jmap/eventsource`. The session-resource's `eventSourceUrl` becomes a live push channel: clients connect with `?types=*|<csv>&closeafter=no|state&ping=<seconds>`, the listener subscribes via the operator backend's `mailStore.subscribePush(actor, types, emitFn)` hook, and StateChange events arrive as `event: state` SSE frames with the `{ "@type": "StateChange", changed: {...} }` payload per RFC 8620 §7.4. Keepalive `event: ping` frames default to 30 s (operator-tunable 5-900 s), `closeafter=state` closes after one event for poll-like clients, and the SSE response carries the headers proxies expect (`Cache-Control: no-cache`, `Connection: keep-alive`, `X-Accel-Buffering: no`) so nginx-fronted deployments don't buffer the stream. Without the backend subscribe hook the handler refuses with `503 serverUnavailable`, never silent OK. **Added:** *`eventSourceHandler(req, res)` exposed on the JMAP listener handle* — `b.mail.server.jmap.create(opts).eventSourceHandler` mounts on the operator's HTTP router at whatever path the session-resource's `eventSourceUrl` points to (default `/jmap/eventsource`). Authentication is delegated to the surrounding HTTP middleware (the handler expects `req.user` / `req.actor` to be set); unauthenticated requests return `401 forbidden` per RFC 8620 §1.5. Query-string params parse `types=` (CSV or `*` wildcard), `closeafter=` (`no` | `state`), `ping=` (seconds, clamped 5..900) per §7.3. · *Operator backend hook — `mailStore.subscribePush(actor, types, emitFn)`* — Backends opt in by exposing a `subscribePush` method that accepts (1) the authenticated actor, (2) a parsed `types` list (or `null` for the wildcard `*`), and (3) an `emitFn(event)` callback the backend calls when a state change occurs. The expected event shape is `{ kind: 'StateChange', changed: { <accountId>: { <typeName>: <stateString>, ... }, ... }, pushed?: {...} }`; the listener formats it into the SSE `event: state\ndata: <JSON>\n\n` wire shape. The subscribe call may return either `void` or an `unsubscribe()` function the listener invokes on disconnect. · *SSE wire-correct headers + initial-state hint* — Response headers: `Content-Type: text/event-stream; charset=utf-8`, `Cache-Control: no-cache`, `Connection: keep-alive`, `X-Accel-Buffering: no` (nginx-specific — disables response buffering on the stream so per-event frames flush immediately). The initial bytes carry `retry: 5000\n\n` (HTML5 SSE reconnect hint — 5 s) + a `: connected\n\n` comment so clients can confirm the channel is alive before the first state event. **Security:** *Push backend missing returns `503 serverUnavailable` (no silent accept)* — If the operator wired the listener without `mailStore.subscribePush`, the handler returns `503 urn:ietf:params:jmap:error:serverUnavailable` with a `description` pointing at the missing hook. RFC 8620 §7.3 expects the server to honour subscriptions or refuse explicitly — silently accepting would let a client believe events will arrive when the server cannot deliver. · *`closeafter` accepts only `no` | `state` (RFC 8620 §7.3)* — Any other value returns `400 invalidArguments` before the subscribe hook fires. Prevents an operator-supplied query string from steering the handler into an undocumented mode. · *Ping interval clamped 5..900 seconds* — `ping=<seconds>` below 5 s or above 900 s clamps to the bounds rather than refusing — a misconfigured client cannot DoS the listener via 1 ms ping floods, and a 24 h ping won't outlast intermediate proxy idle timeouts (typical 60-120 s). The clamped default (30 s) matches the RFC 8620 §7.3 example. · *Ping timer is `.unref()`'d* — Background timers without `.unref()` pin the Node process — graceful shutdown waits indefinitely. The interval is unref'd immediately after creation; per-connection cleanup (`req.on('close')` / `req.on('error')`) clears the timer + invokes the backend's optional `unsubscribe()` + ends the response. **References:** [RFC 8620 (JMAP Core — §7 Push / §7.3 EventSource / §7.4 StateChange)](https://www.rfc-editor.org/rfc/rfc8620.html) · [RFC 8621 (JMAP Mail)](https://www.rfc-editor.org/rfc/rfc8621.html) · [RFC 8887 (JMAP WebSocket transport — opt-in, deferred to a later slice)](https://www.rfc-editor.org/rfc/rfc8887.html) · [HTML5 Server-Sent Events (EventSource)](https://html.spec.whatwg.org/multipage/server-sent-events.html)
 
 - v0.11.28 (2026-05-21) — **IMAP opt-in extensions: NOTIFY (RFC 5465), METADATA (RFC 5464), CATENATE (RFC 4469).** Three IMAP extensions advertised in CAPABILITY and dispatched through the existing per-method registry. NOTIFY accepts a client subscription spec and hands it to the operator's `mailStore.subscribeNotify(actor, spec, emitFn)` hook — actual event emission stays operator-side. METADATA exposes GETMETADATA and SETMETADATA per-mailbox + server-wide annotations through `mailStore.getMetadata` / `setMetadata`. CATENATE extends APPEND to compose a message from existing parts (`TEXT {N}` literals + `URL "imap://..."`) via `mailStore.appendCatenate`. Each handler refuses gracefully (`NO ... backend not configured`) when the operator backend doesn't supply the hook. COMPRESS=DEFLATE (RFC 4978) intentionally NOT advertised — CRIME-class compression-oracle threat on the encrypted IMAP stream. **Added:** *CAPABILITY advertises `NOTIFY`, `METADATA`, `METADATA-SERVER`, `CATENATE`* — All four added unconditionally so capable clients can exercise the extension regardless of authentication state. Each handler is registered in the protocol verb catalogue (`b.mail.serverRegistry`) + the wire-level guard verb list (`b.guardImapCommand.KNOWN_VERBS`) so the existing dispatch + audit + ratelimit gates apply uniformly. · *`NOTIFY SET ...` / `NOTIFY NONE` — RFC 5465* — The handler parses `NOTIFY SET [STATUS] (<filter-set> (<event>...))*` and `NOTIFY NONE` and stores the filter-set verbatim on `state.notifySpec`. When the operator backend exposes `mailStore.subscribeNotify(actor, spec, emitFn)`, the listener wires an `emitFn` that translates backend events (`{ kind: 'STATUS' | 'LIST' | 'FETCH', payload, seq? }`) into untagged IMAP responses on the same connection — drop-silent if the socket has already closed. Without the backend hook, the wire command refuses with `NO NOTIFY backend not configured` rather than silently accepting subscriptions the server can't fulfil. · *`GETMETADATA` / `SETMETADATA` — RFC 5464* — Both verbs parse the per-mailbox + server-wide annotation forms. GETMETADATA accepts optional `(MAXSIZE N)` / `(DEPTH ...)` options before the mailbox + entry list, walks the entries through `mailStore.getMetadata(actor, mailbox, names, opts) → [{ entry, value }]`, and renders an untagged `* METADATA <mailbox> (<entry> <value>...)` response. SETMETADATA tokenises the entry/value pairs (quoted-strings + NIL for clearing), validates the mailbox name, and forwards to `mailStore.setMetadata(actor, mailbox, entries)`. Without the backend hooks, both return `NO ... backend not configured`. · *APPEND `CATENATE` modifier — RFC 4469* — `APPEND mailbox [flags] [date-time] CATENATE (...)` is recognised before the legacy literal-required APPEND path. The parts list mixes `TEXT {N}` literal-bytes parts (handed in via the literal-aware parser) and `URL "imap://..."` reference parts; the listener bundles them into `parts: [{ kind: 'TEXT', bytes } | { kind: 'URL', url }]` and forwards to `mailStore.appendCatenate(mailbox, parts, { actor, flags, internalDate }) → { uid, uidValidity }`. When the backend returns the APPENDUID metadata the response carries `OK [APPENDUID <validity> <uid>] APPEND completed` (RFC 4315). Without the backend hook, refuses with `NO CATENATE backend not configured`. **Security:** *COMPRESS=DEFLATE intentionally NOT advertised (CRIME-class)* — RFC 4978 IMAP COMPRESS=DEFLATE enables stream compression that interacts badly with TLS — the CRIME attack class (CVE-2012-4929, BREACH, et al.) recovers plaintext via chosen-plaintext compression-ratio analysis. The framework default is OFF; operators with explicit threat models accept the downgrade via `opts.compress = true` (no opt-in path landed in v1, intentionally — defer-with-condition: open when an operator surfaces a deployment that needs it AND can document the chosen-plaintext threat model is mitigated). · *Mailbox-name validation reused for both METADATA verbs* — Both GETMETADATA and SETMETADATA run `_validateMailboxName` on the parsed mailbox argument (except for the empty-string `""` server-wide-metadata special case per RFC 5464 §3.1). Operators with the existing `allowLegacyMUtf7` opt see the same mailbox-name policy as the rest of the listener; injection-shape mailbox names are refused identically. · *NOTIFY backend-missing returns NO (not silent accept)* — If the operator wired the listener without `mailStore.subscribeNotify`, `NOTIFY SET ...` returns `NO NOTIFY backend not configured` — never a silent `OK`. RFC 5465 §6 specifies NO as the correct refusal shape; silent acceptance would let a client believe events will arrive when the server cannot fulfil the subscription. **References:** [RFC 5465 (IMAP NOTIFY)](https://www.rfc-editor.org/rfc/rfc5465.html) · [RFC 5464 (IMAP METADATA)](https://www.rfc-editor.org/rfc/rfc5464.html) · [RFC 4469 (IMAP CATENATE)](https://www.rfc-editor.org/rfc/rfc4469.html) · [RFC 4315 (IMAP UIDPLUS — APPENDUID response)](https://www.rfc-editor.org/rfc/rfc4315.html) · [RFC 4978 (IMAP COMPRESS — NOT enabled; CRIME-class threat)](https://www.rfc-editor.org/rfc/rfc4978.html) · [CVE-2012-4929 (CRIME — compression-oracle attack on TLS)](https://nvd.nist.gov/vuln/detail/CVE-2012-4929)

package/index.js

@@ -98,6 +98,7 @@ var safeSieve = require("./lib/safe-sieve");
 var safeIcap = require("./lib/safe-icap");
 var safeIcal = require("./lib/safe-ical");
 var safeVcard = require("./lib/safe-vcard");
+var calendar = require("./lib/calendar");
 var mailStore = require("./lib/mail-store");
 var ntpCheck = require("./lib/ntp-check");
 var auditSign = require("./lib/audit-sign");
@@ -622,6 +623,7 @@ module.exports = {
   safeIcap:         safeIcap,
   safeIcal:         safeIcal,
   safeVcard:        safeVcard,
+  calendar:         calendar,
   mailStore:        mailStore,
   safeSchema:       safeSchema,
   pagination:       pagination,

package/lib/calendar.js

@@ -0,0 +1,581 @@
+"use strict";
+/**
+ * @module    b.calendar
+ * @nav       Mail
+ * @title     Calendar (JSCalendar)
+ * @order     400
+ * @slug      calendar
+ *
+ * @intro
+ *   JSCalendar (RFC 8984) primitive. Wraps the framework's existing
+ *   `b.safeIcal.parse` (RFC 5545 grammar + bounded parser) with the
+ *   JSON-native JSCalendar surface JMAP Calendars (RFC 8984 / draft-
+ *   ietf-jmap-calendars) requires for cross-protocol interop.
+ *
+ *   v1 scope:
+ *     - `validate(jsCal)` — assert JSCalendar Event / Task shape
+ *     - `fromIcal(text, opts?)` — VCALENDAR.VEVENT → JSCalendar Event
+ *     - `toIcal(jsCal, opts?)` — JSCalendar Event → VCALENDAR
+ *     - `expandRecurrence(event, { from, to, max })` — RRULE expansion
+ *       for FREQ=DAILY/WEEKLY/MONTHLY/YEARLY with UNTIL/COUNT/INTERVAL
+ *
+ *   Deferred-with-condition (no operator demand yet):
+ *     - BYSETPOS / BYWEEKNO / BYYEARDAY (RFC 5545 §3.3.10) — RFC 7529
+ *       non-Gregorian calendars; floating timezone resolution.
+ *     - VTODO / VJOURNAL → Task / Note objects (RFC 8984 §5/§6).
+ *     - JSCalendar Group objects (RFC 8984 §1.4.4).
+ *
+ * @card
+ *   JSCalendar (RFC 8984) ↔ iCalendar (RFC 5545) bridge — validate,
+ *   convert both directions, expand recurrences. Substrate for JMAP
+ *   Calendars (RFC 8984 + draft-ietf-jmap-calendars).
+ */
+
+var safeIcal = require("./safe-ical");
+var time     = require("./time");
+var { defineClass } = require("./framework-error");
+
+var CalendarError = defineClass("CalendarError", { alwaysPermanent: true });
+
+// JSCalendar shape vocabulary — RFC 8984 §1.2 (`@type`) catalogues
+// the discriminator strings every nested object MUST carry.
+var JSCAL_TYPES = Object.freeze({
+  Event:        "Event",
+  Task:         "Task",
+  Group:        "Group",
+  Participant:  "Participant",
+  Location:     "Location",
+  Link:         "Link",
+  Alert:        "Alert",
+  Recurrence:   "RecurrenceRule",
+  TimeZone:     "TimeZone",
+});
+
+// RFC 8984 §4.3.2 — frequencies recognised in `RecurrenceRule.frequency`.
+var JSCAL_FREQUENCIES = Object.freeze({
+  yearly: 1, monthly: 1, weekly: 1, daily: 1, hourly: 1, minutely: 1, secondly: 1,
+});
+
+// RFC 8984 §4.6.2 — alert action types.
+var JSCAL_ALERT_ACTIONS = Object.freeze({
+  display: 1, email: 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
+var MAX_EXPAND_SPAN_MS   = 10 * 365 * 24 * 60 * 60 * 1000;                                             // allow:raw-byte-literal + allow:raw-time-literal — 10 year max expansion span
+
+/**
+ * @primitive b.calendar.validate
+ * @signature b.calendar.validate(jsCal)
+ * @since     0.11.31
+ * @status    stable
+ *
+ * Validate a JSCalendar Event / Task object's required-field shape per
+ * RFC 8984 §5 (Event) + §6 (Task). Returns the input on success; throws
+ * `CalendarError` on refusal with a `.code` naming the specific shape
+ * rule that failed.
+ *
+ * @example
+ *   b.calendar.validate({
+ *     "@type":      "Event",
+ *     uid:          "0e612e8b-1c4f-4e30-8e6a-4adc4e8b1c4f",
+ *     updated:      "2026-05-21T10:00:00Z",
+ *     title:        "Sprint planning",
+ *     start:        "2026-05-22T09:00:00",
+ *     duration:     "PT1H",
+ *     timeZone:     "America/Los_Angeles",
+ *   });
+ */
+function validate(jsCal) {
+  if (!jsCal || typeof jsCal !== "object" || Array.isArray(jsCal)) {
+    throw new CalendarError("calendar/bad-input",
+      "b.calendar.validate: input must be a JSCalendar object");
+  }
+  var t = jsCal["@type"];
+  if (t !== JSCAL_TYPES.Event && t !== JSCAL_TYPES.Task) {
+    throw new CalendarError("calendar/bad-type",
+      "b.calendar.validate: @type must be 'Event' or 'Task' (got " + JSON.stringify(t) + ")");
+  }
+  if (typeof jsCal.uid !== "string" || jsCal.uid.length === 0) {
+    throw new CalendarError("calendar/no-uid",
+      "b.calendar.validate: uid is required (RFC 8984 §5.1.4)");
+  }
+  if (jsCal.uid.length > 1024) {                                                                       // allow:raw-byte-literal — anti-DoS uid length cap
+    throw new CalendarError("calendar/oversize-uid",
+      "b.calendar.validate: uid exceeds 1024 bytes");
+  }
+  if (typeof jsCal.updated !== "string" || !_isUtcDateTime(jsCal.updated)) {
+    throw new CalendarError("calendar/bad-updated",
+      "b.calendar.validate: updated MUST be a UTCDateTime per RFC 8984 §1.4.3 (got " + JSON.stringify(jsCal.updated) + ")");
+  }
+  if (t === JSCAL_TYPES.Event) {
+    if (jsCal.start !== undefined && (typeof jsCal.start !== "string" || !_isLocalDateTime(jsCal.start))) {
+      throw new CalendarError("calendar/bad-start",
+        "b.calendar.validate: Event.start MUST be a LocalDateTime");
+    }
+    if (jsCal.duration !== undefined && (typeof jsCal.duration !== "string" || !_isDuration(jsCal.duration))) {
+      throw new CalendarError("calendar/bad-duration",
+        "b.calendar.validate: Event.duration MUST be an RFC 8601 PnYnMnDTnHnMnS Duration");
+    }
+  }
+  if (jsCal.recurrenceRules !== undefined) {
+    if (!Array.isArray(jsCal.recurrenceRules)) {
+      throw new CalendarError("calendar/bad-recurrence",
+        "b.calendar.validate: recurrenceRules MUST be an array of RecurrenceRule");
+    }
+    for (var ri = 0; ri < jsCal.recurrenceRules.length; ri += 1) {
+      var rr = jsCal.recurrenceRules[ri];
+      if (!rr || typeof rr !== "object" || rr["@type"] !== "RecurrenceRule") {
+        throw new CalendarError("calendar/bad-recurrence",
+          "b.calendar.validate: recurrenceRules[" + ri + "].@type MUST be 'RecurrenceRule'");
+      }
+      if (!Object.prototype.hasOwnProperty.call(JSCAL_FREQUENCIES, rr.frequency)) {
+        throw new CalendarError("calendar/bad-recurrence",
+          "b.calendar.validate: recurrenceRules[" + ri + "].frequency MUST be one of " +
+          Object.keys(JSCAL_FREQUENCIES).join(" | "));
+      }
+    }
+  }
+  if (jsCal.alerts !== undefined) {
+    if (typeof jsCal.alerts !== "object" || Array.isArray(jsCal.alerts)) {
+      throw new CalendarError("calendar/bad-alerts",
+        "b.calendar.validate: alerts MUST be an object map keyed by alert-id");
+    }
+    var alertKeys = Object.keys(jsCal.alerts);
+    for (var ai = 0; ai < alertKeys.length; ai += 1) {
+      var alert = jsCal.alerts[alertKeys[ai]];
+      if (!alert || alert["@type"] !== "Alert") {
+        throw new CalendarError("calendar/bad-alerts",
+          "b.calendar.validate: alerts[" + alertKeys[ai] + "].@type MUST be 'Alert'");
+      }
+      if (alert.action && !Object.prototype.hasOwnProperty.call(JSCAL_ALERT_ACTIONS, alert.action)) {
+        throw new CalendarError("calendar/bad-alerts",
+          "b.calendar.validate: alerts[" + alertKeys[ai] + "].action MUST be one of " +
+          Object.keys(JSCAL_ALERT_ACTIONS).join(" | "));
+      }
+    }
+  }
+  return jsCal;
+}
+
+/**
+ * @primitive b.calendar.fromIcal
+ * @signature b.calendar.fromIcal(text, opts?)
+ * @since     0.11.31
+ * @status    stable
+ *
+ * Parse iCalendar text (RFC 5545) via `b.safeIcal.parse` and map the
+ * first VEVENT into a JSCalendar Event object (RFC 8984 §5). Returns
+ * a single Event when the VCALENDAR contains exactly one VEVENT, or
+ * an array when multiple VEVENTs are present.
+ *
+ * @opts
+ *   safeIcalOpts: object,   // forwarded to b.safeIcal.parse (caps, allowExperimental, etc.)
+ *
+ * @example
+ *   b.calendar.fromIcal(
+ *     "BEGIN:VCALENDAR\\r\\nVERSION:2.0\\r\\n" +
+ *     "BEGIN:VEVENT\\r\\nUID:a@b\\r\\nDTSTAMP:20260521T100000Z\\r\\n" +
+ *     "DTSTART:20260522T090000Z\\r\\nDURATION:PT1H\\r\\n" +
+ *     "SUMMARY:Sprint\\r\\nEND:VEVENT\\r\\nEND:VCALENDAR\\r\\n");
+ *   // → { "@type":"Event", uid:"a@b", updated:"2026-05-21T10:00:00Z", ... }
+ */
+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 converted = events.map(_veventToJsCalEvent);
+  return converted.length === 1 ? converted[0] : converted;
+}
+
+/**
+ * @primitive b.calendar.toIcal
+ * @signature b.calendar.toIcal(jsCal, opts?)
+ * @since     0.11.31
+ * @status    stable
+ *
+ * Render a JSCalendar Event back to RFC 5545 iCalendar text. Returns a
+ * CRLF-terminated string wrapped in a `BEGIN:VCALENDAR / VERSION:2.0 /
+ * PRODID:-//blamejs//Calendar//EN / BEGIN:VEVENT ... END:VEVENT /
+ * END:VCALENDAR` envelope per RFC 5545 §3.4.
+ *
+ * @opts
+ *   prodid: string,   // PRODID value to emit; default "-//blamejs//Calendar//EN"
+ *
+ * @example
+ *   b.calendar.toIcal({
+ *     "@type":  "Event",
+ *     uid:      "a@b",
+ *     updated:  "2026-05-21T10:00:00Z",
+ *     title:    "Sprint",
+ *     start:    "2026-05-22T09:00:00",
+ *     duration: "PT1H",
+ *   });
+ */
+function toIcal(jsCal, opts) {
+  validate(jsCal);
+  var prodid = (opts && opts.prodid) || "-//blamejs//Calendar//EN";
+  var lines = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "PRODID:" + prodid,
+    "BEGIN:VEVENT",
+    "UID:" + _foldLine(jsCal.uid),
+    "DTSTAMP:" + _utcDateTimeToIcal(jsCal.updated),
+  ];
+  if (jsCal.title) lines.push("SUMMARY:" + _foldLine(_escapeText(jsCal.title)));
+  if (jsCal.description) lines.push("DESCRIPTION:" + _foldLine(_escapeText(jsCal.description)));
+  if (jsCal.start) {
+    // RFC 8984 §1.4.4 maps `timeZone: "Etc/UTC"` to a `Z`-suffix
+    // DTSTART (RFC 5545 §3.3.5 form 2); any other named timezone
+    // maps to a TZID parameter (form 3); no timeZone leaves DTSTART
+    // as floating local time (form 1).
+    var dtStartIcal = _localDateTimeToIcal(jsCal.start);
+    if (jsCal.timeZone === "Etc/UTC" || jsCal.timeZone === "UTC") {
+      lines.push("DTSTART:" + dtStartIcal + "Z");
+    } else if (jsCal.timeZone) {
+      lines.push("DTSTART;TZID=" + jsCal.timeZone + ":" + dtStartIcal);
+    } else {
+      lines.push("DTSTART:" + dtStartIcal);
+    }
+  }
+  if (jsCal.duration) lines.push("DURATION:" + jsCal.duration);
+  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) {
+      var loc = locValues[li];
+      if (loc && typeof loc.name === "string") {
+        lines.push("LOCATION:" + _foldLine(_escapeText(loc.name)));
+      }
+    }
+  }
+  if (Array.isArray(jsCal.recurrenceRules)) {
+    for (var rri = 0; rri < jsCal.recurrenceRules.length; rri += 1) {
+      lines.push("RRULE:" + _recurrenceRuleToIcal(jsCal.recurrenceRules[rri]));
+    }
+  }
+  lines.push("END:VEVENT", "END:VCALENDAR");
+  return lines.join("\r\n") + "\r\n";
+}
+
+/**
+ * @primitive b.calendar.expandRecurrence
+ * @signature b.calendar.expandRecurrence(event, opts)
+ * @since     0.11.31
+ * @status    stable
+ *
+ * Expand a JSCalendar Event's `recurrenceRules` into concrete start
+ * timestamps in the operator's `[from, to]` window. Returns an array
+ * of ISO 8601 UTC strings (`yyyy-mm-ddTHH:MM:SSZ`). Bounded by
+ * `MAX_EXPAND_INSTANCES` (4096) + `MAX_EXPAND_SPAN_MS` (10 years) to
+ * defend against CVE-2024-39687-class recurrence-bomb expansion.
+ *
+ * v1 supports FREQ=DAILY/WEEKLY/MONTHLY/YEARLY with INTERVAL, COUNT,
+ * UNTIL. BYDAY / BYMONTH / BYMONTHDAY refine the base frequency. The
+ * BYSETPOS / BYWEEKNO / BYYEARDAY filters are deferred-with-condition
+ * (RFC 7529 non-Gregorian calendars not in scope either).
+ *
+ * @opts
+ *   from: string,    // ISO 8601 UTC timestamp — lower bound of expansion window
+ *   to:   string,    // ISO 8601 UTC timestamp — upper bound (window <= 10 years)
+ *   max:  number,    // instance-count cap (default 4096; never exceeds MAX_EXPAND_INSTANCES)
+ *
+ * @example
+ *   b.calendar.expandRecurrence(
+ *     { "@type": "Event", uid: "x", updated: "2026-05-21T10:00:00Z",
+ *       start: "2026-05-22T09:00:00",
+ *       recurrenceRules: [{ "@type": "RecurrenceRule", frequency: "daily", count: 5 }] },
+ *     { from: "2026-05-22T00:00:00Z", to: "2026-06-01T00:00:00Z" });
+ *   // → ["2026-05-22T09:00:00Z", "2026-05-23T09:00:00Z", ..., "2026-05-26T09:00:00Z"]
+ */
+function expandRecurrence(event, opts) {
+  validate(event);
+  opts = opts || {};
+  if (!Array.isArray(event.recurrenceRules) || event.recurrenceRules.length === 0) {
+    return event.start ? [_localToUtc(event.start)] : [];
+  }
+  var fromMs = opts.from ? Date.parse(opts.from) : null;
+  var toMs   = opts.to   ? Date.parse(opts.to)   : null;
+  if (fromMs !== null && toMs !== null) {
+    if (toMs - fromMs > MAX_EXPAND_SPAN_MS) {
+      throw new CalendarError("calendar/oversize-expansion-span",
+        "b.calendar.expandRecurrence: window [" + opts.from + ", " + opts.to + "] exceeds 10 years");
+    }
+    if (toMs < fromMs) {
+      throw new CalendarError("calendar/bad-expansion-window",
+        "b.calendar.expandRecurrence: opts.to must be after opts.from");
+    }
+  }
+  var maxCount = Math.min(opts.max || MAX_EXPAND_INSTANCES, MAX_EXPAND_INSTANCES);
+  // JSCalendar's LocalDateTime is FLOATING when no timeZone is set;
+  // for expansion we treat it as already-UTC so the returned ISO
+  // strings carry the same wall-clock the operator stored. Appending
+  // `Z` to the LocalDateTime sidesteps Date.parse's host-locale
+  // interpretation (which would otherwise mangle the wall-clock).
+  var startInput = _isLocalDateTime(event.start) ? event.start + "Z" : event.start;
+  var startMs = Date.parse(startInput);
+  if (!isFinite(startMs)) {
+    throw new CalendarError("calendar/bad-start",
+      "b.calendar.expandRecurrence: event.start is not a parseable date");
+  }
+  var out = [];
+  // We honour ONLY the first recurrenceRule in v1; multiple rules
+  // compose via union which is a follow-up.
+  var rule = event.recurrenceRules[0];
+  var interval = Math.max(1, parseInt(rule.interval || 1, 10));
+  var freq = rule.frequency;
+  var count = isFinite(rule.count) ? rule.count : Infinity;
+  var untilMs = rule.until ? Date.parse(rule.until) : Infinity;
+  // RFC 5545 §3.3.10 BY* filters narrow which stepped occurrences
+  // emit. We support the BYDAY/BYMONTH/BYMONTHDAY subset; rule
+  // instances that fail the filter are stepped past WITHOUT counting
+  // against `count` (per RFC 5545 BY* expansion semantics — only
+  // surviving instances count).
+  var byDaySet = null;
+  if (Array.isArray(rule.byDay) && rule.byDay.length > 0) {
+    byDaySet = Object.create(null);
+    var dayCodes = { su: 0, mo: 1, tu: 2, we: 3, th: 4, fr: 5, sa: 6 };
+    for (var bi = 0; bi < rule.byDay.length; bi += 1) {
+      var entry = rule.byDay[bi];
+      var dayKey = (entry && entry.day ? entry.day : entry || "").toLowerCase();
+      if (Object.prototype.hasOwnProperty.call(dayCodes, dayKey)) {
+        byDaySet[dayCodes[dayKey]] = true;
+      }
+    }
+  }
+  var byMonthSet = null;
+  if (Array.isArray(rule.byMonth) && rule.byMonth.length > 0) {
+    byMonthSet = Object.create(null);
+    for (var mi = 0; mi < rule.byMonth.length; mi += 1) {
+      var mn = parseInt(rule.byMonth[mi], 10);
+      if (isFinite(mn) && mn >= 1 && mn <= 12) byMonthSet[mn] = true;                                  // allow:raw-byte-literal — 12 calendar months
+    }
+  }
+  var byMonthDaySet = null;
+  if (Array.isArray(rule.byMonthDay) && rule.byMonthDay.length > 0) {
+    byMonthDaySet = Object.create(null);
+    for (var mdi = 0; mdi < rule.byMonthDay.length; mdi += 1) {
+      var mdn = parseInt(rule.byMonthDay[mdi], 10);
+      if (isFinite(mdn) && mdn !== 0 && mdn >= -31 && mdn <= 31) byMonthDaySet[mdn] = true;            // allow:raw-byte-literal — calendar day-of-month bounds
+    }
+  }
+  function _matchesBy(t) {
+    var d = new Date(t);
+    if (byDaySet && !byDaySet[d.getUTCDay()]) return false;
+    if (byMonthSet && !byMonthSet[d.getUTCMonth() + 1]) return false;
+    if (byMonthDaySet && !byMonthDaySet[d.getUTCDate()]) return false;
+    return true;
+  }
+  var t = startMs;
+  // Safety cap on the step loop: at most MAX_EXPAND_INSTANCES * 366
+  // iterations so BY* filters that match sparsely (e.g. FREQ=DAILY;
+  // BYMONTH=1 — only Jan days survive) cannot loop forever inside
+  // the 10-year span cap.
+  var stepBudget = MAX_EXPAND_INSTANCES * 366;                                                         // allow:raw-byte-literal — days/year stepping budget
+  while (out.length < count && out.length < maxCount && stepBudget > 0) {
+    stepBudget -= 1;
+    if (t > untilMs) break;
+    if (toMs !== null && t > toMs) break;
+    if (_matchesBy(t)) {
+      if (fromMs === null || t >= fromMs) {
+        out.push(_msToIsoZ(t));
+      }
+    }
+    t = _advance(t, freq, interval);
+    if (t === null) {
+      throw new CalendarError("calendar/bad-recurrence",
+        "b.calendar.expandRecurrence: unsupported frequency '" + freq + "'");
+    }
+  }
+  return out;
+}
+
+// ---- Internal helpers ----------------------------------------------------
+
+function _veventToJsCalEvent(ve) {
+  var props = (ve && ve.properties) || {};
+  var jsCal = {
+    "@type":  "Event",
+    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 duration = _firstValue(props.DURATION);
+  if (duration) jsCal.duration = duration;
+  var tzid = _firstParamValue(props.DTSTART, "TZID");
+  if (tzid) {
+    jsCal.timeZone = tzid;
+  } else if (typeof dtstart === "string" && /Z$/.test(dtstart)) {
+    // Codex P1 — RFC 8984 §1.4.4: a UTC-suffix DTSTART (`...Z`) in
+    // iCalendar maps to a JSCalendar Event with `timeZone: "Etc/UTC"`.
+    // Without this, round-tripping `fromIcal` → `toIcal` would drop
+    // the UTC anchor + emit floating time, shifting the absolute
+    // instant for viewers in different timezones.
+    jsCal.timeZone = "Etc/UTC";
+  }
+  var location = _firstValue(props.LOCATION);
+  if (location) {
+    jsCal.locations = { L1: { "@type": "Location", name: _unescapeText(location) } };
+  }
+  var rrule = _firstValue(props.RRULE);
+  if (rrule) jsCal.recurrenceRules = [_icalRruleToJscal(rrule)];
+  return jsCal;
+}
+
+function _firstValue(prop) {
+  if (!prop) return null;
+  if (Array.isArray(prop)) {
+    var first = prop[0];
+    return first && first.value !== undefined ? first.value : null;
+  }
+  if (prop.value !== undefined) return prop.value;
+  return null;
+}
+
+function _firstParamValue(prop, paramName) {
+  if (!prop) return null;
+  var first = Array.isArray(prop) ? prop[0] : prop;
+  if (!first || !first.params) return null;
+  return first.params[paramName] || null;
+}
+
+function _icalRruleToJscal(rrule) {
+  var out = { "@type": "RecurrenceRule", frequency: "daily" };
+  var parts = String(rrule).split(";");                                                                // allow:bare-split-on-quoted-header — RFC 5545 RRULE grammar has no quoted-string members; values are token-only
+  for (var i = 0; i < parts.length; i += 1) {
+    var kv = parts[i].split("=");
+    if (kv.length !== 2) continue;
+    var key = kv[0].toUpperCase();
+    var val = kv[1];
+    if (key === "FREQ") out.frequency = val.toLowerCase();
+    else if (key === "INTERVAL") out.interval = parseInt(val, 10);
+    else if (key === "COUNT") out.count = parseInt(val, 10);
+    else if (key === "UNTIL") out.until = _icalDateTimeToUtc(val);
+    else if (key === "BYDAY") out.byDay = val.split(",").map(function (d) {                            // allow:bare-split-on-quoted-header — RFC 5545 BYDAY values are token-only
+      return { "@type": "NDay", day: d.slice(-2).toLowerCase() };
+    });
+    else if (key === "BYMONTH") out.byMonth = val.split(",");                                          // allow:bare-split-on-quoted-header — RFC 5545 BYMONTH values are integer-only
+    else if (key === "BYMONTHDAY") out.byMonthDay = val.split(",").map(function (n) { return parseInt(n, 10); }); // allow:bare-split-on-quoted-header — RFC 5545 BYMONTHDAY values are integer-only
+  }
+  return out;
+}
+
+function _recurrenceRuleToIcal(rr) {
+  var parts = ["FREQ=" + (rr.frequency || "daily").toUpperCase()];
+  if (rr.interval && rr.interval !== 1) parts.push("INTERVAL=" + rr.interval);
+  if (rr.count) parts.push("COUNT=" + rr.count);
+  if (rr.until) parts.push("UNTIL=" + _utcDateTimeToIcal(rr.until));
+  if (Array.isArray(rr.byDay) && rr.byDay.length > 0) {
+    parts.push("BYDAY=" + rr.byDay.map(function (d) { return (d.day || "").toUpperCase(); }).join(","));
+  }
+  if (Array.isArray(rr.byMonth)) parts.push("BYMONTH=" + rr.byMonth.join(","));
+  if (Array.isArray(rr.byMonthDay)) parts.push("BYMONTHDAY=" + rr.byMonthDay.join(","));
+  return parts.join(";");
+}
+
+function _icalDateTimeToUtc(s) {
+  // VALUE=DATE-TIME UTC form: 20260522T100000Z → 2026-05-22T10:00:00Z
+  var m = String(s).match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+  if (!m) return "";
+  return m[1] + "-" + m[2] + "-" + m[3] + "T" + m[4] + ":" + m[5] + ":" + m[6] + "Z";
+}
+
+function _icalDateTimeToLocal(s) {
+  var m = String(s).match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z?$/);
+  if (!m) return "";
+  return m[1] + "-" + m[2] + "-" + m[3] + "T" + m[4] + ":" + m[5] + ":" + m[6];
+}
+
+function _utcDateTimeToIcal(s) {
+  // JSCalendar UTCDateTime "2026-05-22T10:00:00.123Z" →
+  // "20260522T100000Z" (RFC 5545 §3.3.5 form 2 has NO fractional
+  // seconds; strict ICS consumers reject `T100000.123Z`).
+  return String(s).replace(/\.\d+/, "").replace(/[-:]/g, "");                                          // allow:bare-split-on-quoted-header — not a header split
+}
+
+function _localDateTimeToIcal(s) {
+  // JSCalendar LocalDateTime "2026-05-22T09:00:00.123" →
+  // "20260522T090000" (same fractional-second strip as the UTC form).
+  return String(s).replace(/\.\d+/, "").replace(/[-:]/g, "");                                          // allow:bare-split-on-quoted-header — not a header split
+}
+
+function _isUtcDateTime(s) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(s);
+}
+
+function _isLocalDateTime(s) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?$/.test(s);
+}
+
+function _isDuration(s) {
+  return /^-?P(\d+Y)?(\d+M)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$/.test(s);
+}
+
+function _localToUtc(localStr) {
+  // Naive — treats LocalDateTime as already-UTC for the no-tz case.
+  return localStr.endsWith("Z") ? localStr : localStr + "Z";
+}
+
+function _msToIsoZ(ms) {
+  return time.toIso8601NoMs(new Date(ms));
+}
+
+function _advance(ms, freq, interval) {
+  var d = new Date(ms);
+  switch (freq) {
+  case "daily":   d.setUTCDate(d.getUTCDate() + interval); break;
+  case "weekly":  d.setUTCDate(d.getUTCDate() + 7 * interval); break;                                  // allow:raw-byte-literal — 7 days/week
+  case "monthly": d.setUTCMonth(d.getUTCMonth() + interval); break;
+  case "yearly":  d.setUTCFullYear(d.getUTCFullYear() + interval); break;
+  case "hourly":  d.setUTCHours(d.getUTCHours() + interval); break;
+  case "minutely": d.setUTCMinutes(d.getUTCMinutes() + interval); break;
+  case "secondly": d.setUTCSeconds(d.getUTCSeconds() + interval); break;
+  default: return null;
+  }
+  return d.getTime();
+}
+
+function _escapeText(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\n/g, "\\n");
+}
+
+function _unescapeText(s) {
+  return String(s)
+    .replace(/\\n/g, "\n").replace(/\\,/g, ",")
+    .replace(/\\;/g, ";").replace(/\\\\/g, "\\");
+}
+
+function _foldLine(s) {
+  // RFC 5545 §3.1 — content lines SHOULD NOT exceed 75 octets; fold
+  // with CRLF + leading space. We let the joining code add the
+  // trailing CRLF; this helper only inserts the intra-line fold.
+  if (s.length <= 75) return s;                                                                        // allow:raw-byte-literal — RFC 5545 §3.1 line-length cap
+  var out = "";
+  for (var i = 0; i < s.length; i += 73) {                                                             // allow:raw-byte-literal — 73 = 75 minus the CR/LF wrap
+    out += (i === 0 ? "" : "\r\n ") + s.slice(i, i + 73);                                              // allow:raw-byte-literal — same cap
+  }
+  return out;
+}
+
+module.exports = {
+  validate:               validate,
+  fromIcal:               fromIcal,
+  toIcal:                 toIcal,
+  expandRecurrence:       expandRecurrence,
+  CalendarError:          CalendarError,
+  JSCAL_TYPES:            JSCAL_TYPES,
+  JSCAL_FREQUENCIES:      JSCAL_FREQUENCIES,
+  JSCAL_ALERT_ACTIONS:    JSCAL_ALERT_ACTIONS,
+  MAX_EXPAND_INSTANCES:   MAX_EXPAND_INSTANCES,
+  MAX_EXPAND_SPAN_MS:     MAX_EXPAND_SPAN_MS,
+};

package/lib/mail-server-jmap.js

@@ -121,6 +121,7 @@ var lazyRequire = require("./lazy-require");
 var C = require("./constants");
 var bCrypto = require("./crypto");
 var safeJson = require("./safe-json");
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var guardJmap = require("./guard-jmap");
 var mailServerRegistry = require("./mail-server-registry");
@@ -670,6 +671,306 @@ function create(opts) {
     req.on("error", _cleanup);
   }
 
+  // RFC 8620 §6.1 — blob upload. Operators POST raw bytes to
+  // `/jmap/upload/{accountId}` with `Content-Type` set to the
+  // blob MIME type. The handler streams the request body into a
+  // bounded buffer, calls `mailStore.uploadBlob(actor, accountId,
+  // contentType, bytes)`, and returns the JSON descriptor
+  // `{ accountId, blobId, type, size }` the client uses in
+  // subsequent Email/set / Email/import calls.
+  //
+  // Path parameters are extracted from the URL; the operator-side
+  // HTTP router MUST mount this handler at a prefix that exposes
+  // the accountId segment (e.g. `/jmap/upload/:accountId`). The
+  // handler defensively re-parses the URL in case the router didn't
+  // populate `req.params`.
+  var DEFAULT_MAX_BLOB_BYTES = opts.maxBlobBytes || (50 * 1024 * 1024);                                // allow:raw-byte-literal — 50 MiB default blob upload cap
+  // RFC 8620 §1.2 — JMAP `Id` is a non-empty string of < 256 octets in
+  // `[A-Za-z0-9_-]`. The earlier shape capped at 64 chars which refused
+  // legitimate-shape accounts; widen to the full spec maximum.
+  var MAX_JMAP_ID_LEN = 255;                                                                           // allow:raw-byte-literal — RFC 8620 §1.2 Id max length
+  var JMAP_ID_RE      = /^[A-Za-z0-9_-]{1,255}$/;
+  // Anti-polynomial: bound the URL length BEFORE any regex / split runs
+  // (CodeQL flags `\/+` on uncontrolled input). Headers + URL paths in
+  // practice stay well under 8 KiB; over-long URLs refuse outright.
+  var MAX_URL_LEN     = 8192;                                                                          // allow:raw-byte-literal — 8 KiB URL cap
+
+  // Strip a query string + walk the path producing non-empty segments,
+  // WITHOUT any unbounded regex. Returns an empty array when the URL
+  // is over the cap so the caller can refuse with 400.
+  function _splitPathSegments(rawUrl) {
+    if (typeof rawUrl !== "string" || rawUrl.length === 0 || rawUrl.length > MAX_URL_LEN) {
+      return [];
+    }
+    var qIdx = rawUrl.indexOf("?");
+    var pathOnly = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
+    var out = [];
+    var cur = "";
+    for (var i = 0; i < pathOnly.length; i += 1) {
+      var ch = pathOnly.charCodeAt(i);
+      if (ch === 0x2f) {                                                                               // allow:raw-byte-literal — '/' (0x2f)
+        if (cur.length > 0) { out.push(cur); cur = ""; }
+      } else {
+        cur += pathOnly[i];
+      }
+    }
+    if (cur.length > 0) out.push(cur);
+    return out;
+  }
+
+  function uploadHandler(req, res) {
+    var actor = req.user || (req.actor || null);
+    if (!actor) {
+      res.statusCode = 401;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:forbidden",
+        description: "Authentication required",
+      }));
+      return;
+    }
+    if (typeof opts.mailStore.uploadBlob !== "function") {
+      res.statusCode = 503;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:serverUnavailable",
+        description: "Upload backend not configured (mailStore.uploadBlob)",
+      }));
+      return;
+    }
+    // Extract accountId from URL path. The mount path is
+    // `/jmap/upload/{accountId}`; the operator's router may strip
+    // the `/jmap/upload/` prefix (so segments == [accountId]) OR
+    // pass through the full path. Either shape gives the trailing
+    // segment as accountId — but the WHOLE URL must split cleanly
+    // (`_splitPathSegments` refuses over-long input).
+    var segments = _splitPathSegments(req.url);
+    if (segments.length === 0) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Upload URL is empty or exceeds the " + MAX_URL_LEN + "-byte cap",
+      }));
+      return;
+    }
+    var accountId = (req.params && req.params.accountId) || segments[segments.length - 1] || "";
+    if (!accountId || accountId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(accountId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Upload URL missing or malformed accountId path segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    var contentType = req.headers && req.headers["content-type"]
+      ? String(req.headers["content-type"]).split(";")[0].trim()
+      : "application/octet-stream";
+    var collector = safeBuffer.boundedChunkCollector({
+      maxBytes:    DEFAULT_MAX_BLOB_BYTES,
+      errorClass:  MailServerJmapError,
+      sizeCode:    "mail-server-jmap/blob-too-large",
+      sizeMessage: "Blob exceeds maxSizeUpload (" + DEFAULT_MAX_BLOB_BYTES + " bytes)",
+    });
+    var refused = false;
+
+    req.on("data", function (chunk) {
+      if (refused) return;
+      try { collector.push(chunk); }
+      catch (_e) {
+        refused = true;
+        res.statusCode = 413;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+          type:        "urn:ietf:params:jmap:error:limit",
+          limit:       "maxSizeUpload",
+          description: "Blob exceeds maxSizeUpload (" + DEFAULT_MAX_BLOB_BYTES + " bytes)",
+        }));
+        try { req.destroy(); } catch (_e2) { /* silent-catch: socket already torn down */ }
+      }
+    });
+    req.on("end", function () {
+      if (refused) return;
+      var bytes = collector.result();
+      Promise.resolve()
+        .then(function () { return opts.mailStore.uploadBlob(actor, accountId, contentType, bytes); })
+        .then(function (meta) {
+          if (!meta || typeof meta !== "object" || typeof meta.blobId !== "string") {
+            throw new MailServerJmapError("mail-server-jmap/bad-upload-result",
+              "uploadBlob backend MUST return { blobId, type?, size? }");
+          }
+          res.statusCode = 201;                                                                        // allow:raw-byte-literal — HTTP 201 Created
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            accountId: accountId,
+            blobId:    meta.blobId,
+            type:      meta.type || contentType,
+            size:      typeof meta.size === "number" ? meta.size : bytes.length,
+          }));
+        })
+        .catch(function (err) {
+          _emit("mail.server.jmap.upload_threw",
+            { accountId: accountId, error: (err && err.message) || String(err) }, "failure");
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:serverFail",
+            description: "Upload failed",
+          }));
+        });
+    });
+    req.on("error", function () {
+      if (!refused) {
+        refused = true;
+        try { res.statusCode = 400; res.end(); }                                                       // allow:raw-byte-literal — HTTP 400
+        catch (_e) { /* silent-catch: socket already torn down */ }
+      }
+    });
+  }
+
+  // RFC 8620 §6.2 — blob download. GET `/jmap/download/{accountId}/
+  // {blobId}/{name}?accept={type}`. Backend hook returns a stream-
+  // shaped buffer (Buffer or async-iterable) + the canonical MIME
+  // type; the handler pipes it to the response.
+  function downloadHandler(req, res) {
+    var actor = req.user || (req.actor || null);
+    if (!actor) {
+      res.statusCode = 401;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:forbidden",
+        description: "Authentication required",
+      }));
+      return;
+    }
+    if (typeof opts.mailStore.downloadBlob !== "function") {
+      res.statusCode = 503;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:serverUnavailable",
+        description: "Download backend not configured (mailStore.downloadBlob)",
+      }));
+      return;
+    }
+    var rawUrl = String(req.url || "");
+    if (rawUrl.length > MAX_URL_LEN) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL exceeds the " + MAX_URL_LEN + "-byte cap",
+      }));
+      return;
+    }
+    var qIdx2 = rawUrl.indexOf("?");
+    var query = qIdx2 === -1 ? "" : rawUrl.slice(qIdx2 + 1);
+    var acceptType = "";
+    query.split("&").forEach(function (pair) {
+      if (!pair) return;
+      var eq = pair.indexOf("=");
+      var k = eq === -1 ? pair : pair.slice(0, eq);
+      var v = eq === -1 ? "" : pair.slice(eq + 1);
+      if (k === "accept") {
+        try { acceptType = decodeURIComponent(v); } catch (_e) { /* silent-catch: malformed % encoding */ }
+      }
+    });
+    // Path parsing — `/jmap/download/{accountId}/{blobId}/{name}`. The
+    // operator's router may strip the `/jmap/download/` prefix, so
+    // valid segment counts are EXACTLY 3 (router-stripped) OR 5+ AND
+    // starting with `jmap` + `download`. Anything else refuses BEFORE
+    // a tail-segment remap could land path tokens in the wrong
+    // accountId / blobId / name slots.
+    var pathSegs = _splitPathSegments(rawUrl);
+    var routerSupplied = req.params && req.params.accountId && req.params.blobId && req.params.name;
+    var accountId, blobId, fileName;
+    if (routerSupplied) {
+      accountId = req.params.accountId;
+      blobId    = req.params.blobId;
+      fileName  = req.params.name;
+    } else if (pathSegs.length === 3) {
+      accountId = pathSegs[0];
+      blobId    = pathSegs[1];
+      fileName  = pathSegs[2];
+    } else if (pathSegs.length >= 5 &&
+               pathSegs[pathSegs.length - 5].toLowerCase() === "jmap" &&
+               pathSegs[pathSegs.length - 4].toLowerCase() === "download") {
+      accountId = pathSegs[pathSegs.length - 3];
+      blobId    = pathSegs[pathSegs.length - 2];
+      fileName  = pathSegs[pathSegs.length - 1];
+    } else {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL must be /jmap/download/{accountId}/{blobId}/{name} (or router-stripped {accountId}/{blobId}/{name})",
+      }));
+      return;
+    }
+    if (!accountId || accountId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(accountId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL has malformed accountId segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    if (!blobId || blobId.length > MAX_JMAP_ID_LEN || !JMAP_ID_RE.test(blobId)) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        type:        "urn:ietf:params:jmap:error:invalidArguments",
+        description: "Download URL has malformed blobId segment (JMAP Id: [A-Za-z0-9_-]{1," + MAX_JMAP_ID_LEN + "})",
+      }));
+      return;
+    }
+    Promise.resolve()
+      .then(function () { return opts.mailStore.downloadBlob(actor, accountId, blobId); })
+      .then(function (result) {
+        if (!result || (typeof result !== "object" && !Buffer.isBuffer(result))) {
+          res.statusCode = 404;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:invalidArguments",
+            description: "Blob not found",
+          }));
+          return;
+        }
+        var bytes  = Buffer.isBuffer(result) ? result : result.bytes;
+        var bType  = result.type || acceptType || "application/octet-stream";
+        if (!Buffer.isBuffer(bytes)) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(JSON.stringify({
+            type:        "urn:ietf:params:jmap:error:serverFail",
+            description: "downloadBlob backend returned a non-Buffer body",
+          }));
+          return;
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", bType);
+        res.setHeader("Content-Length", bytes.length);
+        // RFC 5987 — operator may want to surface fileName via
+        // Content-Disposition. Default to attachment when the
+        // download is a non-text type.
+        if (fileName && /^[A-Za-z0-9._-]{1,200}$/.test(fileName)) {
+          res.setHeader("Content-Disposition", "attachment; filename=\"" + fileName + "\"");
+        }
+        res.end(bytes);
+      })
+      .catch(function (err) {
+        _emit("mail.server.jmap.download_threw",
+          { accountId: accountId, blobId: blobId, error: (err && err.message) || String(err) }, "failure");
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+          type:        "urn:ietf:params:jmap:error:serverFail",
+          description: "Download failed",
+        }));
+      });
+  }
+
   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
@@ -687,6 +988,8 @@ function create(opts) {
     sessionHandler:       sessionHandler,
     discoveryHandler:     discoveryHandler,
     eventSourceHandler:   eventSourceHandler,
+    uploadHandler:        uploadHandler,
+    downloadHandler:      downloadHandler,
     MailServerJmapError:  MailServerJmapError,
   };
 }

package/lib/mail-server-registry.js

@@ -83,6 +83,17 @@ var JMAP_METHODS = Object.freeze({
   "EmailSubmission/query": 1, "EmailSubmission/queryChanges": 1,
   "EmailSubmission/set": 1,
   "VacationResponse/get": 1, "VacationResponse/set": 1,
+  // v0.11.31 — JMAP Calendars (RFC 8984 + draft-ietf-jmap-calendars).
+  "Calendar/get": 1, "Calendar/changes": 1, "Calendar/set": 1,
+  "Calendar/query": 1, "Calendar/queryChanges": 1,
+  "CalendarEvent/get": 1, "CalendarEvent/changes": 1,
+  "CalendarEvent/query": 1, "CalendarEvent/queryChanges": 1,
+  "CalendarEvent/set": 1, "CalendarEvent/copy": 1,
+  "CalendarEventNotification/get": 1, "CalendarEventNotification/changes": 1,
+  "CalendarEventNotification/query": 1, "CalendarEventNotification/queryChanges": 1,
+  "CalendarEventNotification/set": 1,
+  "ParticipantIdentity/get": 1, "ParticipantIdentity/changes": 1,
+  "ParticipantIdentity/set": 1,
 });
 
 var CATALOGUE = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.29",
+  "version": "0.11.31",
   "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:bb88c938-c54a-4094-afe0-0fa2adc94cbd",
+  "serialNumber": "urn:uuid:19702043-8392-4b48-9d1c-120d93f6889f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T15:36:40.156Z",
+    "timestamp": "2026-05-21T17:20:28.895Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.29",
+      "bom-ref": "@blamejs/core@0.11.31",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.29",
+      "version": "0.11.31",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.29",
+      "purl": "pkg:npm/%40blamejs/core@0.11.31",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.29",
+      "ref": "@blamejs/core@0.11.31",
       "dependsOn": []
     }
   ]