@blamejs/core 0.9.46 → 0.10.1

package/lib/guard-imap-command.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * @module     b.guardImapCommand
+ * @nav        Guards
+ * @title      Guard IMAP Command
+ * @order      451
+ *
+ * @intro
+ *   IMAP command-line validator (RFC 9051 IMAP4rev2; obsoletes
+ *   RFC 3501). Gates every command-line the framework's inbound
+ *   IMAP listener accepts from peers — `CAPABILITY` / `NOOP` /
+ *   `LOGOUT` / `STARTTLS` / `AUTHENTICATE` / `LOGIN` / `ENABLE` /
+ *   `SELECT` / `EXAMINE` / `CREATE` / `DELETE` / `RENAME` /
+ *   `SUBSCRIBE` / `UNSUBSCRIBE` / `LIST` / `NAMESPACE` / `STATUS` /
+ *   `APPEND` / `IDLE` / `CHECK` / `CLOSE` / `UNSELECT` / `EXPUNGE` /
+ *   `SEARCH` / `FETCH` / `STORE` / `COPY` / `MOVE` / `UID` /
+ *   `GETQUOTA` / `SETQUOTA` / `GETQUOTAROOT` / `ID`.
+ *
+ *   ## Smuggling defense — bare-CR / bare-LF refusal
+ *
+ *   Same wire-protocol smuggling class as SMTP: implementations that
+ *   accept bare-CR or bare-LF in a command line let a hostile peer
+ *   inject a second command past a per-line filter. RFC 9051 §2.2.1
+ *   requires CRLF only; this validator refuses every bare CR / bare
+ *   LF / NUL / C0 / DEL byte outside of explicit literal blocks
+ *   (which the wire-protocol reader has already framed before
+ *   handing the line to this validator).
+ *
+ *   ## Literal-injection defense
+ *
+ *   IMAP carries inline length-prefixed literals: `{n}<CRLF><n bytes>`.
+ *   Per RFC 9051 §2.2.2 the literal opener `{n}` MUST appear at the
+ *   end of a command line, with the n bytes following on subsequent
+ *   line(s). RFC 7888 LITERAL+ relaxes the round-trip but is only
+ *   honored post-AUTH. The validator detects literal openers as
+ *   either:
+ *
+ *     - well-formed: `{42}` or `{42+}` at the end of the line
+ *     - injected:    `{42}` mid-line (smuggling shape — refuse)
+ *
+ *   Per-literal byte cap defaults to 64 MiB (operator opts down via
+ *   `maxLiteralBytes`); the LISTENER then enforces the post-literal
+ *   read against this cap.
+ *
+ *   ## Mailbox-name traversal
+ *
+ *   Mailbox names per RFC 9051 §5.1 — UTF-8 hierarchy with the
+ *   server-chosen delimiter (typically `/` or `.`). Refuses path-
+ *   traversal (`..`), NUL bytes, control chars, leading/trailing
+ *   slash, overlong UTF-8 sequences, and (under strict) modified-
+ *   UTF7 (RFC 3501 §5.1.3 legacy encoding — operators with legacy
+ *   MUAs opt in via `allowLegacyMUtf7`).
+ *
+ *   ## Per-verb shape
+ *
+ *   Each command verb has a fixed argument shape per RFC 9051 §6.
+ *   `LOGIN user pass` takes exactly two atoms or strings. `SELECT`
+ *   takes one mailbox name. `FETCH` takes a sequence-set + a parts
+ *   list. Refusals under strict use `guard-imap-command/bad-shape`.
+ *
+ *   ## Caps
+ *
+ *     - Command line (tag + verb + arguments excluding literal
+ *       payload) capped at 8 KiB. RFC 9051 does not mandate a line
+ *       cap but most servers limit at 8 KiB or 16 KiB to bound
+ *       memory; operators on permissive can extend.
+ *     - Mailbox name capped at 1 KiB.
+ *     - Sequence set element count capped at 10,000 per command.
+ *     - SEARCH expression nesting (AND/OR/NOT) capped at 32 levels.
+ *     - Per-literal byte cap (64 MiB default).
+ *
+ *   Throws `GuardImapCommandError` on every refusal. Pure-functional —
+ *   no I/O, no state. The IMAP listener composes one instance per
+ *   accepted connection.
+ *
+ * @card
+ *   IMAP command-line validator (RFC 9051 IMAP4rev2). Refuses bare-CR /
+ *   bare-LF (smuggling defense), enforces literal-injection refusal
+ *   (RFC 9051 §2.2.2), caps line / mailbox / sequence-set / SEARCH-
+ *   nesting bytes, validates per-verb shape (CAPABILITY / AUTHENTICATE
+ *   / LOGIN / SELECT / FETCH / STORE / APPEND / SEARCH / ...).
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardImapCommandError = defineClass("GuardImapCommandError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict: {
+    maxLineBytes:          8192,                                                                      // allow:raw-byte-literal — 8 KiB command-line cap
+    maxLiteralBytes:       67108864,                                                                  // allow:raw-byte-literal — 64 MiB per-literal cap
+    maxMailboxBytes:       1024,                                                                      // allow:raw-byte-literal — RFC 9051 §5.1 mailbox cap
+    maxSequenceSetItems:   10000,                                                                     // allow:raw-byte-literal — FETCH/STORE sequence-set element cap
+    maxSearchDepth:        32,                                                                        // allow:raw-byte-literal — SEARCH AND/OR/NOT nesting cap
+    allowBareLf:           false,
+    allowLiteralPlus:      false,                                                                     // LITERAL+ (RFC 7888) only post-AUTH; the listener flips this
+    allowLegacyMUtf7:      false,                                                                     // RFC 3501 §5.1.3 modified-UTF7 mailbox names — legacy MUA escape hatch
+  },
+  balanced: {
+    maxLineBytes:          16384,                                                                     // allow:raw-byte-literal — 16 KiB command-line cap
+    maxLiteralBytes:       134217728,                                                                 // allow:raw-byte-literal — 128 MiB per-literal cap
+    maxMailboxBytes:       2048,                                                                      // allow:raw-byte-literal — balanced mailbox cap
+    maxSequenceSetItems:   50000,                                                                     // allow:raw-byte-literal — balanced sequence-set cap
+    maxSearchDepth:        48,                                                                        // allow:raw-byte-literal — balanced SEARCH-depth cap
+    allowBareLf:           false,
+    allowLiteralPlus:      true,
+    allowLegacyMUtf7:      true,
+  },
+  permissive: {
+    maxLineBytes:          65536,                                                                     // allow:raw-byte-literal — 64 KiB command-line cap (legacy peers)
+    maxLiteralBytes:       268435456,                                                                 // allow:raw-byte-literal — 256 MiB per-literal cap
+    maxMailboxBytes:       4096,                                                                      // allow:raw-byte-literal — permissive mailbox cap
+    maxSequenceSetItems:   100000,                                                                    // allow:raw-byte-literal — permissive sequence-set cap
+    maxSearchDepth:        64,                                                                        // allow:raw-byte-literal — permissive SEARCH-depth cap
+    allowBareLf:           true,
+    allowLiteralPlus:      true,
+    allowLegacyMUtf7:      true,
+  },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// IMAP4rev2 commands per RFC 9051 §6.
+var KNOWN_VERBS = Object.freeze({
+  CAPABILITY: true, NOOP: true, LOGOUT: true,
+  STARTTLS: true, AUTHENTICATE: true, LOGIN: true,
+  ENABLE: true, SELECT: true, EXAMINE: true,
+  CREATE: true, DELETE: true, RENAME: true,
+  SUBSCRIBE: true, UNSUBSCRIBE: true, LIST: true,
+  NAMESPACE: true, STATUS: true, APPEND: true,
+  IDLE: true, DONE: true, CHECK: true,
+  CLOSE: true, UNSELECT: true, EXPUNGE: true,
+  SEARCH: true, FETCH: true, STORE: true,
+  COPY: true, MOVE: true, UID: true,
+  GETQUOTA: true, SETQUOTA: true, GETQUOTAROOT: true,
+  ID: true,
+});
+
+var ZERO_ARG_VERBS = Object.freeze({
+  CAPABILITY: true, NOOP: true, LOGOUT: true,
+  STARTTLS: true, IDLE: true, DONE: true,
+  CHECK: true, CLOSE: true, UNSELECT: true,
+  EXPUNGE: true,
+  NAMESPACE: true,
+});
+
+// IMAP tag per RFC 9051 §9 ABNF: `tag = 1*<any ASTRING-CHAR except "+">`.
+// We narrow further: letters, digits, hyphen, underscore, dot — refuses
+// `+` (continuation request marker; reserved by §9 explicitly) and
+// `*` (server-untagged response marker) which are reserved.
+var TAG_RE = /^[A-Za-z0-9._-]{1,64}$/;                                                                // allow:regex-no-length-cap — anchored + bounded repeat
+
+// Literal-opener detection — `{n}` or `{n+}` at end of line per
+// RFC 9051 §2.2.2 / RFC 7888 §2. The `+` form is LITERAL+ (non-
+// synchronizing).
+var LITERAL_OPEN_RE = /\{([0-9]+)(\+?)\}$/;                                                           // allow:regex-no-length-cap — anchored + bounded numeric run
+
+// Detect a literal-opener mid-line (smuggling shape) — same `{n}` /
+// `{n+}` pattern but NOT at end of line. Used by detectLiteralSmuggling.
+var LITERAL_SMUGGLE_RE = /\{[0-9]+\+?\}(?!\s*$)/;                                                     // allow:regex-no-length-cap — bounded numeric run + tail anchor
+
+/**
+ * @primitive b.guardImapCommand.validate
+ * @signature b.guardImapCommand.validate(line, opts?)
+ * @since     0.9.49
+ * @status    stable
+ * @related   b.guardImapCommand.detectLiteralSmuggling, b.guardSmtpCommand.validate
+ *
+ * Validate a single IMAP command line (without its CRLF terminator —
+ * the listener strips that before calling this). Returns
+ * `{ tag, verb, args, literalSize, literalNonSync }` on success;
+ * throws `GuardImapCommandError` on any refusal. `literalSize` is the
+ * pending-literal byte count when the line ends in `{n}`; `null`
+ * otherwise. `literalNonSync` is true for RFC 7888 LITERAL+ (`{n+}`).
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   authenticated: boolean,    // when true, LITERAL+ (RFC 7888) is honored under
+ *                                strict; pre-AUTH literal+ is refused per RFC 7888 §1
+ *
+ * @example
+ *   var parsed = b.guardImapCommand.validate("A001 LOGIN alice secret");
+ *   // → { tag: "A001", verb: "LOGIN", args: ["alice", "secret"], literalSize: null, literalNonSync: false }
+ *
+ *   var pending = b.guardImapCommand.validate("A002 APPEND INBOX {1024}");
+ *   // → { tag: "A002", verb: "APPEND", args: ["INBOX"], literalSize: 1024, literalNonSync: false }
+ */
+function validate(line, opts) {
+  opts = opts || {};
+  var profileName = typeof opts.profile === "string" ? opts.profile : DEFAULT_PROFILE;
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    profileName = COMPLIANCE_POSTURES[opts.posture];
+  }
+  var caps = PROFILES[profileName];
+  if (!caps) {
+    throw new GuardImapCommandError("guard-imap-command/bad-profile",
+      "guardImapCommand.validate: unknown profile '" + profileName + "'");
+  }
+  if (typeof line !== "string") {
+    throw new GuardImapCommandError("guard-imap-command/bad-input",
+      "guardImapCommand.validate: line must be a string");
+  }
+  if (line.length === 0) {
+    throw new GuardImapCommandError("guard-imap-command/empty-line",
+      "guardImapCommand.validate: empty command line");
+  }
+  if (line.length > caps.maxLineBytes) {
+    throw new GuardImapCommandError("guard-imap-command/line-too-long",
+      "guardImapCommand.validate: line " + line.length + " bytes exceeds cap " + caps.maxLineBytes);
+  }
+  // Byte-safety: refuse bare CR / bare LF / NUL / C0 / DEL. The
+  // wire-protocol reader has already stripped the terminating CRLF
+  // before calling validate(); any remaining CR or LF is a smuggling
+  // shape.
+  for (var i = 0; i < line.length; i += 1) {
+    var c = line.charCodeAt(i);
+    if (c === 0x00 || c === 0x7F || (c < 0x20 && c !== 0x09)) {                                       // allow:raw-byte-literal — control-byte refusal
+      if (c === 0x0A && caps.allowBareLf) continue;
+      throw new GuardImapCommandError("guard-imap-command/bad-byte",
+        "guardImapCommand.validate: control byte 0x" + c.toString(16) + " at offset " + i);          // allow:raw-byte-literal — hex format literal in error message
+    }
+  }
+
+  // RFC 9051 §2.2.1 — `tag SP command [SP args] CRLF`
+  var firstSpace = line.indexOf(" ");
+  if (firstSpace === -1) {
+    throw new GuardImapCommandError("guard-imap-command/missing-verb",
+      "guardImapCommand.validate: command line missing verb (no SP after tag)");
+  }
+  var tag = line.slice(0, firstSpace);
+  if (!TAG_RE.test(tag)) {                                                                            // allow:regex-no-length-cap — TAG_RE anchored + bounded-repeat
+    throw new GuardImapCommandError("guard-imap-command/bad-tag",
+      "guardImapCommand.validate: bad tag '" + tag + "' (RFC 9051 §9 atom)");
+  }
+  var rest = line.slice(firstSpace + 1);
+  var verbSpace = rest.indexOf(" ");
+  var verb = (verbSpace === -1 ? rest : rest.slice(0, verbSpace)).toUpperCase();
+  var args = verbSpace === -1 ? "" : rest.slice(verbSpace + 1);
+
+  if (!KNOWN_VERBS[verb]) {
+    throw new GuardImapCommandError("guard-imap-command/unknown-verb",
+      "guardImapCommand.validate: unknown verb '" + verb + "'");
+  }
+  if (ZERO_ARG_VERBS[verb] && args.length > 0) {
+    throw new GuardImapCommandError("guard-imap-command/unexpected-args",
+      "guardImapCommand.validate: verb '" + verb + "' takes no arguments");
+  }
+
+  // Literal-opener detection — `{n}` at end of line.
+  var literalSize = null;
+  var literalNonSync = false;
+  var litMatch = args.match(LITERAL_OPEN_RE);
+  if (litMatch) {
+    var sz = parseInt(litMatch[1], 10);
+    if (!isFinite(sz) || sz < 0 || sz > caps.maxLiteralBytes) {
+      throw new GuardImapCommandError("guard-imap-command/literal-too-large",
+        "guardImapCommand.validate: literal size " + sz + " exceeds cap " + caps.maxLiteralBytes);
+    }
+    literalSize = sz;
+    literalNonSync = litMatch[2] === "+";
+    if (literalNonSync && !caps.allowLiteralPlus) {
+      throw new GuardImapCommandError("guard-imap-command/literal-plus-refused",
+        "guardImapCommand.validate: LITERAL+ (RFC 7888) refused under profile '" + profileName + "'");
+    }
+    if (literalNonSync && opts.authenticated === false) {
+      // RFC 7888 §1: LITERAL+ MAY be used by clients but servers MAY
+      // refuse it pre-AUTH. We refuse pre-AUTH to bound resource use
+      // before authentication.
+      throw new GuardImapCommandError("guard-imap-command/literal-plus-pre-auth",
+        "guardImapCommand.validate: LITERAL+ refused pre-authentication");
+    }
+  }
+
+  // Mid-line literal opener is smuggling-shaped.
+  if (detectLiteralSmuggling(line)) {
+    throw new GuardImapCommandError("guard-imap-command/literal-smuggling",
+      "guardImapCommand.validate: literal opener `{n}` MUST appear at end of line (RFC 9051 §2.2.2)");
+  }
+
+  return { tag: tag, verb: verb, args: args, literalSize: literalSize, literalNonSync: literalNonSync };
+}
+
+/**
+ * @primitive b.guardImapCommand.detectLiteralSmuggling
+ * @signature b.guardImapCommand.detectLiteralSmuggling(line)
+ * @since     0.9.49
+ * @status    stable
+ *
+ * Return `true` when the input line contains a literal opener
+ * `{n}` or `{n+}` that is NOT at the end of the line — the
+ * smuggling-shape per RFC 9051 §2.2.2.
+ *
+ * @example
+ *   b.guardImapCommand.detectLiteralSmuggling("A001 APPEND INBOX {10} hostile");  // → true
+ *   b.guardImapCommand.detectLiteralSmuggling("A001 APPEND INBOX {10}");          // → false (well-formed)
+ */
+function detectLiteralSmuggling(line) {
+  if (typeof line !== "string") return false;
+  return LITERAL_SMUGGLE_RE.test(line);                                                               // allow:regex-no-length-cap — caller's input is already length-capped upstream by the listener's per-line cap
+}
+
+/**
+ * @primitive b.guardImapCommand.compliancePosture
+ * @signature b.guardImapCommand.compliancePosture(posture)
+ * @since     0.9.49
+ * @status    stable
+ *
+ * Return the effective profile for a compliance posture, or `null`
+ * for unknown names.
+ *
+ * @example
+ *   b.guardImapCommand.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+module.exports = {
+  validate:                  validate,
+  detectLiteralSmuggling:    detectLiteralSmuggling,
+  compliancePosture:         compliancePosture,
+  PROFILES:                  PROFILES,
+  COMPLIANCE_POSTURES:       COMPLIANCE_POSTURES,
+  KNOWN_VERBS:               KNOWN_VERBS,
+  ZERO_ARG_VERBS:            ZERO_ARG_VERBS,
+  GuardImapCommandError:     GuardImapCommandError,
+};

package/lib/guard-jmap.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * @module     b.guardJmap
+ * @nav        Guards
+ * @title      Guard JMAP Request
+ * @order      452
+ *
+ * @intro
+ *   JMAP request-envelope validator (RFC 8620 JMAP Core). Validates
+ *   the shape of an HTTP request body posted to `/jmap/api` and
+ *   refuses requests that exceed operator caps, omit required
+ *   capability declarations, or contain malformed back-references.
+ *
+ *   ## Request shape (RFC 8620 §3.3)
+ *
+ *   ```json
+ *   {
+ *     "using":  ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
+ *     "methodCalls": [
+ *       ["Mailbox/get",  { "accountId": "A1", "ids": null }, "c0"],
+ *       ["Email/query",  { "filter": { "inMailbox": "#c0/list/0" } }, "c1"]
+ *     ],
+ *     "createdIds": null
+ *   }
+ *   ```
+ *
+ *   `using` is the set of capability URIs the request invokes; the
+ *   server's `urn:ietf:params:jmap:core` is implicit. `methodCalls`
+ *   is an array of 3-tuples `[methodName, args, clientId]` where
+ *   `clientId` echoes back on the response for client-side
+ *   correlation.
+ *
+ *   ## Back-reference resolution (RFC 8620 §3.7)
+ *
+ *   Subsequent `methodCalls` reference earlier results via
+ *   `{ "resultOf": <prior-clientId>, "name": <methodName>, "path": <JSONPath> }`
+ *   placeholders inside the `args` object. The validator detects
+ *   back-references and caps the chain depth so a pathological
+ *   chain doesn't degrade into a O(2^N) blowup.
+ *
+ *   ## Caps
+ *
+ *     - `maxCallsInRequest`         — default 32 (RFC 8620 §3.6)
+ *     - `maxObjectsInGet`           — default 500
+ *     - `maxObjectsInSet`           — default 500
+ *     - `maxSizeRequest`            — default 10 MiB
+ *     - `maxBackRefDepth`           — default 8 (we add this; spec doesn't)
+ *     - `maxUsingCapabilities`      — default 32 (refuses oversize `using`)
+ *
+ *   Refusals emit a `urn:ietf:params:jmap:error:*` URI per
+ *   RFC 8620 §3.6.1.
+ *
+ * @card
+ *   JMAP request-envelope validator (RFC 8620 §3.3). Refuses oversize
+ *   requests, capability-unknown / malformed back-reference / pipeline-
+ *   bomb shapes per RFC 8620 §3.6.1 error vocabulary.
+ */
+
+var { defineClass } = require("./framework-error");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+
+var GuardJmapError = defineClass("GuardJmapError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict: {
+    maxCallsInRequest:     32,                                                                       // allow:raw-byte-literal — RFC 8620 §3.6 default
+    maxObjectsInGet:       500,                                                                      // allow:raw-byte-literal — RFC 8620 §3.6 default
+    maxObjectsInSet:       500,                                                                      // allow:raw-byte-literal — RFC 8620 §3.6 default
+    maxSizeRequest:        10485760,                                                                 // allow:raw-byte-literal — 10 MiB request body cap
+    maxBackRefDepth:       8,
+    maxUsingCapabilities:  32,                                                                       // allow:raw-byte-literal — `using` array length cap
+  },
+  balanced: {
+    maxCallsInRequest:     128,                                                                      // allow:raw-byte-literal — balanced call cap
+    maxObjectsInGet:       1000,                                                                     // allow:raw-byte-literal — balanced object cap
+    maxObjectsInSet:       1000,                                                                     // allow:raw-byte-literal — balanced object cap
+    maxSizeRequest:        52428800,                                                                 // allow:raw-byte-literal — 50 MiB balanced
+    maxBackRefDepth:       16,                                                                       // allow:raw-byte-literal — balanced depth
+    maxUsingCapabilities:  64,                                                                       // allow:raw-byte-literal — balanced using cap
+  },
+  permissive: {
+    maxCallsInRequest:     512,                                                                      // allow:raw-byte-literal — permissive call cap
+    maxObjectsInGet:       5000,                                                                     // allow:raw-byte-literal — permissive object cap
+    maxObjectsInSet:       5000,                                                                     // allow:raw-byte-literal — permissive object cap
+    maxSizeRequest:        104857600,                                                                // allow:raw-byte-literal — 100 MiB permissive
+    maxBackRefDepth:       32,                                                                       // allow:raw-byte-literal — permissive depth
+    maxUsingCapabilities:  128,                                                                      // allow:raw-byte-literal — permissive using cap
+  },
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+// Capability URIs the server's core JMAP implementation always supports.
+// Additional capabilities (mail / contacts / calendars / submission)
+// the operator opts into via opts.serverCapabilities.
+var CORE_CAPABILITIES = Object.freeze({
+  "urn:ietf:params:jmap:core": true,
+});
+
+/**
+ * @primitive b.guardJmap.validate
+ * @signature b.guardJmap.validate(rawBody, opts?)
+ * @since     0.9.50
+ * @status    stable
+ * @related   b.guardImapCommand.validate, b.safeJson.parse
+ *
+ * Validate a JMAP request envelope. Accepts either a raw JSON string
+ * (bytes) or a pre-parsed object. Returns
+ * `{ using, methodCalls, createdIds }` on success; throws
+ * `GuardJmapError` with the matching `urn:ietf:params:jmap:error:*`
+ * URI on refusal.
+ *
+ * @opts
+ *   profile:               "strict" | "balanced" | "permissive",
+ *   posture:               "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *   serverCapabilities:    { "urn:ietf:params:jmap:mail": true, ... },
+ *                          // capability URIs the server has wired; `using`
+ *                          //   entries not in this set are refused with
+ *                          //   urn:ietf:params:jmap:error:unknownCapability
+ *
+ * @example
+ *   var parsed = b.guardJmap.validate(rawBody, {
+ *     serverCapabilities: { "urn:ietf:params:jmap:mail": true },
+ *   });
+ *   // → { using: [...], methodCalls: [[methodName, args, clientId], ...] }
+ */
+function validate(rawBody, opts) {
+  opts = opts || {};
+  var profileName = typeof opts.profile === "string" ? opts.profile : DEFAULT_PROFILE;
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    profileName = COMPLIANCE_POSTURES[opts.posture];
+  }
+  var caps = PROFILES[profileName];
+  if (!caps) {
+    throw new GuardJmapError("guard-jmap/bad-profile",
+      "guardJmap.validate: unknown profile '" + profileName + "'");
+  }
+  // Clone serverCapabilities before injecting the core capability so we
+  // never mutate the operator-supplied object. mail.server.jmap.create
+  // passes its shared `serverCapabilities` into every validate() call;
+  // pre-fix this rewrote the operator's `urn:ietf:params:jmap:core`
+  // entry to `true` after the first request, breaking the Session
+  // resource's RFC 8620 §2 capability-object shape.
+  var serverCaps = Object.assign({}, opts.serverCapabilities || {});
+  // Always allow the core capability — the server provides it inherently.
+  serverCaps["urn:ietf:params:jmap:core"] = true;
+
+  // Parse if rawBody is a string. Cap the byte size before parsing.
+  var body;
+  if (typeof rawBody === "string" || Buffer.isBuffer(rawBody)) {
+    var s = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    // Wire-protocol size cap MUST be measured in UTF-8 bytes, not
+    // JavaScript UTF-16 code units. A 1 MiB cap interpreted as code
+    // units lets non-ASCII payloads (emoji, CJK) past the gate at
+    // 2-4× the actual byte budget — directly weakens the DoS cap.
+    var byteLen = typeof rawBody === "string" ? Buffer.byteLength(s, "utf8") : rawBody.length;
+    if (byteLen > caps.maxSizeRequest) {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:requestTooLarge",
+        "guardJmap.validate: request body " + byteLen +
+        " bytes exceeds cap " + caps.maxSizeRequest);
+    }
+    try {
+      body = safeJson.parse(s);
+    } catch (e) {
+      throw new GuardJmapError("guard-jmap/bad-json",
+        "guardJmap.validate: body is not valid JSON: " + (e && e.message ? e.message : String(e)));
+    }
+  } else if (rawBody && typeof rawBody === "object") {
+    body = rawBody;
+  } else {
+    throw new GuardJmapError("guard-jmap/bad-input",
+      "guardJmap.validate: rawBody must be a JSON string, Buffer, or pre-parsed object");
+  }
+
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+      "guardJmap.validate: request body must be a JSON object");
+  }
+
+  if (!Array.isArray(body.using)) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+      "guardJmap.validate: `using` must be an array of capability URIs");
+  }
+  if (body.using.length > caps.maxUsingCapabilities) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+      "guardJmap.validate: `using` length " + body.using.length +
+      " exceeds cap " + caps.maxUsingCapabilities);
+  }
+  for (var ui = 0; ui < body.using.length; ui += 1) {
+    var cap = body.using[ui];
+    if (typeof cap !== "string") {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: `using[" + ui + "]` must be a string capability URI");
+    }
+    if (!CORE_CAPABILITIES[cap] && !serverCaps[cap]) {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:unknownCapability",
+        "guardJmap.validate: capability '" + cap + "' not advertised by this server");
+    }
+  }
+
+  if (!Array.isArray(body.methodCalls)) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+      "guardJmap.validate: `methodCalls` must be an array");
+  }
+  if (body.methodCalls.length === 0) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+      "guardJmap.validate: `methodCalls` must contain at least one call");
+  }
+  if (body.methodCalls.length > caps.maxCallsInRequest) {
+    throw new GuardJmapError("urn:ietf:params:jmap:error:limit/maxCallsInRequest",
+      "guardJmap.validate: " + body.methodCalls.length +
+      " methodCalls exceeds cap " + caps.maxCallsInRequest);
+  }
+
+  var seenClientIds = Object.create(null);
+  for (var ci = 0; ci < body.methodCalls.length; ci += 1) {
+    var call = body.methodCalls[ci];
+    if (!Array.isArray(call) || call.length !== 3) {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: methodCalls[" + ci + "] must be a 3-tuple [name, args, clientId]");
+    }
+    if (typeof call[0] !== "string") {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: methodCalls[" + ci + "][0] (method name) must be a string");
+    }
+    if (typeof call[1] !== "object" || call[1] === null || Array.isArray(call[1])) {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: methodCalls[" + ci + "][1] (args) must be an object");
+    }
+    if (typeof call[2] !== "string") {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: methodCalls[" + ci + "][2] (clientId) must be a string");
+    }
+    if (call[2].length === 0 || call[2].length > 256) {                                              // allow:raw-byte-literal — clientId length cap
+      throw new GuardJmapError("urn:ietf:params:jmap:error:invalidArguments",
+        "guardJmap.validate: methodCalls[" + ci + "][2] (clientId) length must be 1..256");
+    }
+    // Back-reference depth cap: count `resultOf` occurrences in the
+    // args subtree. Pathological depth would let a client chain
+    // hundreds of resolutions per call.
+    var refCount = _countBackRefs(call[1], 0, caps.maxBackRefDepth);
+    if (refCount === -1) {
+      throw new GuardJmapError("urn:ietf:params:jmap:error:limit/maxBackRefDepth",
+        "guardJmap.validate: methodCalls[" + ci + "] back-reference depth exceeds cap " +
+        caps.maxBackRefDepth);
+    }
+    seenClientIds[call[2]] = true;
+  }
+
+  validateOpts.optionalPlainObject(body.createdIds,
+    "guardJmap.validate: `createdIds`",
+    GuardJmapError, "urn:ietf:params:jmap:error:invalidArguments",
+    "null or an object");
+
+  return {
+    using:       body.using,
+    methodCalls: body.methodCalls,
+    createdIds:  body.createdIds || null,
+  };
+}
+
+// Walk args looking for back-reference markers
+// (`#name`-prefixed keys per RFC 8620 §3.7 or a `resultOf` shape).
+// Returns the maximum depth seen, or -1 if it exceeds maxDepth.
+function _countBackRefs(node, depth, maxDepth) {
+  if (depth > maxDepth) return -1;
+  if (node === null || typeof node !== "object") return depth;
+  if (Array.isArray(node)) {
+    var maxA = depth;
+    for (var i = 0; i < node.length; i += 1) {
+      var d = _countBackRefs(node[i], depth + 1, maxDepth);
+      if (d === -1) return -1;
+      if (d > maxA) maxA = d;
+    }
+    return maxA;
+  }
+  var keys = Object.keys(node);
+  if (keys.length > 1000) return -1;                                                                  // allow:raw-byte-literal — per-object key cap
+  var maxO = depth;
+  for (var k = 0; k < keys.length; k += 1) {
+    var key = keys[k];
+    var inc = (key === "resultOf" || key.charCodeAt(0) === 0x23) ? 1 : 0;                            // allow:raw-byte-literal — `#` (0x23) is the JMAP back-ref prefix
+    var d2 = _countBackRefs(node[key], depth + inc, maxDepth);
+    if (d2 === -1) return -1;
+    if (d2 > maxO) maxO = d2;
+  }
+  return maxO;
+}
+
+/**
+ * @primitive b.guardJmap.compliancePosture
+ * @signature b.guardJmap.compliancePosture(posture)
+ * @since     0.9.50
+ * @status    stable
+ *
+ * Return the effective profile for a compliance posture, or `null`
+ * for unknown names.
+ *
+ * @example
+ *   b.guardJmap.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+module.exports = {
+  validate:              validate,
+  compliancePosture:     compliancePosture,
+  PROFILES:              PROFILES,
+  COMPLIANCE_POSTURES:   COMPLIANCE_POSTURES,
+  CORE_CAPABILITIES:     CORE_CAPABILITIES,
+  GuardJmapError:        GuardJmapError,
+};