@blamejs/core 0.11.37 → 0.11.38

package/CHANGELOG.md

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

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.37",
+  "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:df42b2e1-b180-4b98-a9b7-2bf6b7fe666e",
+  "serialNumber": "urn:uuid:05d5b9da-ac1d-46ee-8a2c-f1b169e68091",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T22:14:19.947Z",
+    "timestamp": "2026-05-21T23:11:16.432Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.37",
+      "bom-ref": "@blamejs/core@0.11.38",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.37",
+      "version": "0.11.38",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.37",
+      "purl": "pkg:npm/%40blamejs/core@0.11.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.37",
+      "ref": "@blamejs/core@0.11.38",
       "dependsOn": []
     }
   ]