@blamejs/core 0.14.20 → 0.14.22

package/lib/middleware/health.js

@@ -317,10 +317,7 @@ function create(opts) {
       var entry = { ok: r.ok, ms: r.ms };
       if (r.detail) {
         // Merge detail keys other than `ok` into the entry.
-        var keys = Object.keys(r.detail);
-        for (var n = 0; n < keys.length; n++) {
-          if (keys[n] !== "ok") entry[keys[n]] = r.detail[keys[n]];
-        }
+        validateOpts.assignOwnEnumerable(entry, r.detail, ["ok"]);
       }
       if (r.error) entry.error = r.error;
       if (!r.critical) entry.critical = false;

package/lib/middleware/openapi-serve.js

@@ -179,6 +179,9 @@ function create(opts) {
       if (allowOriginHeader !== "*") headers["Vary"] = "Origin";
     }
     res.writeHead(200, headers);                                                    // HTTP 200
+    // HEAD carries the GET headers (incl. Content-Length) with no body
+    // (RFC 9110 §9.3.2).
+    if ((req.method || "GET").toUpperCase() === "HEAD") { res.end(); return; }
     res.end(body);
   }
 

package/lib/middleware/scim-server.js

@@ -57,7 +57,7 @@ var BEARER_RE = /^Bearer\s+(.+)$/i;
  *     users:        ScimResourceImpl,
  *     groups?:      ScimResourceImpl,
  *     bearer?:      (token) => Promise<actor>,
- *     maxPageSize?: number,
+ *     maxPageSize?: number,   // default: 200 (config-time positive int)
  *     bulk?: {
  *       maxOperations?:  number,   // default: 1000 (config-time positive int)
  *       maxPayloadSize?: number,   // default: 1 MiB  (config-time positive int, bytes)
@@ -80,6 +80,12 @@ function create(opts) {
   if (opts.groups) _validateResourceImpl(opts.groups, "groups");
 
   var basePath    = opts.basePath || "/scim/v2";
+  // Config-time / entry-point tier: a bad page-size cap THROWS so the
+  // operator catches the typo at boot rather than at request time, where
+  // a non-number would propagate NaN into impl.list({ count }) and
+  // ServiceProviderConfig.filter.maxResults.
+  validateOpts.optionalPositiveInt(opts.maxPageSize, "middleware.scimServer: opts.maxPageSize",
+    ScimServerError, "middleware/scim-server/bad-max-page-size");
   var maxPageSize = opts.maxPageSize || 200;                                                                  // page-size count, not bytes
   var bearer      = opts.bearer || null;
   var bulkCfg     = _resolveBulkConfig(opts.bulk);
@@ -297,11 +303,15 @@ async function _dispatch(req, res, basePath, bearer, opts, maxPageSize, bulkCfg)
 }
 
 // RFC 7644 §3.7 — /Bulk POST. Parses a BulkRequest, enforces the
-// config-time maxOperations / maxPayloadSize caps, optionally
-// short-circuits at failOnErrors, resolves bulkId cross-references
-// (§3.7.2), dispatches each operation through the same per-resource
-// create/update/delete logic the singleton endpoints use, and returns
-// a BulkResponse carrying one result object per operation.
+// config-time maxOperations / maxPayloadSize caps, plans a
+// dependency-ordered execution so bulkId cross-references (§3.7.2) —
+// including forward references — resolve to real ids before dispatch,
+// fails operations with undeclared / circular / failed-dependency
+// references per-op, optionally short-circuits at failOnErrors,
+// dispatches each surviving operation through the same per-resource
+// create/update/delete logic the singleton endpoints use, and returns a
+// BulkResponse carrying one result object per operation in the ORIGINAL
+// request order.
 async function _handleBulk(req, res, opts, bulkCfg, ctx) {
   var body;
   try {
@@ -336,26 +346,265 @@ async function _handleBulk(req, res, opts, bulkCfg, ctx) {
 
   var failOnErrors = _parseFailOnErrors(body.failOnErrors);
   var bulkIdMap    = Object.create(null);   // client bulkId -> assigned resource id
-  var results      = [];
-  var errorCount   = 0;
+  var ops          = body.Operations;
+
+  // RFC 7644 §3.7.2 — a bulkId reference may point at a resource a LATER
+  // operation creates (a forward reference), so processing strictly in
+  // request order leaves the token unresolved. Pre-scan to (a) collect
+  // every declared bulkId and (b) build each operation's dependency set
+  // by walking its data for "bulkId:<id>" cross-references, then execute
+  // in dependency order. The response array is still emitted in the
+  // ORIGINAL request order (results indexed by request position).
+  var plan = _planBulkOperations(ops);
+
+  var results    = new Array(ops.length);   // request-order result entries
+  var executed   = new Array(ops.length);   // index -> { isError } once run
+  var errorCount = 0;
+  var stopped    = false;
+
+  for (var s = 0; s < plan.order.length && !stopped; s++) {
+    var idx = plan.order[s];
+    var planned = plan.ops[idx];
+    var outcome;
+
+    if (planned.staticError) {
+      // Undeclared reference or a reference that lands in a dependency
+      // cycle — fail the op without ever dispatching to the adapter.
+      outcome = _bulkErr(ops[idx], planned.staticError.status,
+        planned.staticError.scimType, planned.staticError.detail);
+    } else if (_anyDependencyFailed(planned.refs, plan, executed, bulkIdMap)) {
+      // RFC 7644 §3.7.2 — a reference to an operation that FAILED cannot
+      // resolve to a real id; fail the dependent op with invalidValue
+      // rather than letting a literal "bulkId:<id>" token reach the
+      // adapter as if it were a real resource identifier.
+      outcome = _bulkErr(ops[idx], "400", "invalidValue",
+        "Operations[" + idx + "] references a bulkId whose creating operation failed");
+    } else {
+      outcome = await _runBulkOperation(ops[idx], idx, opts, ctx, bulkIdMap);
+    }
 
-  for (var i = 0; i < body.Operations.length; i++) {
-    var result = await _runBulkOperation(body.Operations[i], i, opts, ctx, bulkIdMap);
-    results.push(result.entry);
-    if (result.isError) {
+    results[idx]  = outcome.entry;
+    executed[idx] = { isError: outcome.isError };
+    if (outcome.isError) {
       errorCount++;
       // RFC 7644 §3.7 — once the error count reaches failOnErrors the
-      // service stops processing and returns the results so far.
-      if (failOnErrors !== null && errorCount >= failOnErrors) break;
+      // service stops processing and returns the results so far. Results
+      // already produced keep their request-order slots; unreached
+      // operations are omitted from the response.
+      if (failOnErrors !== null && errorCount >= failOnErrors) stopped = true;
     }
   }
 
+  // Compact to the operations actually reached, preserving request order.
+  var emitted = [];
+  for (var e = 0; e < results.length; e++) {
+    if (results[e] !== undefined) emitted.push(results[e]);
+  }
+
   _writeJson(res, H.OK, {
     schemas:    [SCIM_MESSAGE_BULK_RESPONSE],
-    Operations: results,
+    Operations: emitted,
   });
 }
 
+// RFC 7644 §3.7.2 — build the dependency-ordered execution plan for a
+// bulk job. Returns { ops, order } where ops[i] = { refs, staticError? }
+// (refs = the set of declared bulkIds operation i depends on) and order
+// is the request indices in a dependency-respecting (topological)
+// sequence. Operations referencing an UNDECLARED bulkId, or caught in a
+// dependency CYCLE, carry a staticError so the executor fails them
+// without dispatching to the adapter. A POST that declares a bulkId is
+// the only operation kind that can satisfy a reference.
+function _planBulkOperations(ops) {
+  var declared    = Object.create(null);   // bulkId -> declaring index
+  var planned     = new Array(ops.length);
+
+  for (var i = 0; i < ops.length; i++) {
+    var op = ops[i];
+    var bulkId = op && typeof op.bulkId === "string" ? op.bulkId : null;
+    var method = op && typeof op.method === "string" ? op.method.toUpperCase() : null;
+    // Only a POST (resource creation) assigns a server id to a bulkId.
+    if (bulkId && method === "POST" && declared[bulkId] === undefined) {
+      declared[bulkId] = i;
+    }
+    planned[i] = { refs: [], staticError: null, ownBulkId: method === "POST" ? bulkId : null };
+  }
+
+  for (var j = 0; j < ops.length; j++) {
+    // RFC 7644 §3.7.2 — a reference can appear in the operation DATA
+    // ("value": "bulkId:u1") or as the resource id in the operation
+    // PATH ("PATCH /Groups/bulkId:g1" targeting a group another
+    // operation in this request creates). Both surfaces feed the same
+    // dependency set so path-referencing operations order and fail
+    // exactly like data-referencing ones.
+    var refs = _collectBulkIdRefs(ops[j] && ops[j].data).concat(_pathBulkIdRefs(ops[j]));
+    var depSet = [];
+    for (var r = 0; r < refs.length; r++) {
+      var refId = refs[r];
+      var decl  = declared[refId];
+      if (decl === undefined) {
+        // RFC 7644 §3.7.2 — a reference to a bulkId no operation declares
+        // can never resolve; fail this op with invalidValue.
+        planned[j].staticError = {
+          status:   "400",
+          scimType: "invalidValue",
+          detail:   "Operations[" + j + "] references undeclared bulkId '" + refId + "'",
+        };
+        depSet = [];
+        break;
+      }
+      if (decl !== j && depSet.indexOf(decl) === -1) depSet.push(decl);
+    }
+    planned[j].refs = depSet;
+  }
+
+  var order = _topoOrderBulk(planned);
+  return { ops: planned, order: order };
+}
+
+// Walk operation data for "bulkId:<id>" cross-references, returning the
+// list of referenced bulkIds (the "<id>" portion). Bounded: the whole
+// payload was capped at maxPayloadSize before parse.
+function _collectBulkIdRefs(value) {
+  var out = [];
+  _walkBulkIdRefs(value, out);
+  return out;
+}
+
+// RFC 7644 §3.7.2 — bulkId references in an operation's PATH segments
+// (e.g. "PATCH /Groups/bulkId:g1"). Returns the referenced bulkIds.
+function _pathBulkIdRefs(op) {
+  if (!op || typeof op.path !== "string") return [];
+  var out = [];
+  var segs = op.path.split("/");
+  for (var i = 0; i < segs.length; i++) {
+    var ref = BULK_ID_REF_RE.exec(segs[i]);
+    if (ref) out.push(ref[1]);
+  }
+  return out;
+}
+
+// Substitute "bulkId:<id>" PATH segments with the server-assigned id,
+// exactly like data references resolve (RFC 7644 §3.7.2). Throws on an
+// unresolved token — surfaced as a per-op invalidValue by the caller —
+// so a literal token never reaches the path parser or the adapter.
+function _resolvePathBulkIdRefs(path, bulkIdMap) {
+  var segs = path.split("/");
+  for (var i = 0; i < segs.length; i++) {
+    var ref = BULK_ID_REF_RE.exec(segs[i]);
+    if (!ref) continue;
+    var resolved = bulkIdMap[ref[1]];
+    if (resolved === undefined) {
+      throw new ScimServerError("middleware/scim-server/unresolved-bulkid",
+        "references unresolved bulkId '" + ref[1] + "' in path");
+    }
+    segs[i] = resolved;
+  }
+  return segs.join("/");
+}
+
+function _walkBulkIdRefs(value, out) {
+  if (typeof value === "string") {
+    var ref = BULK_ID_REF_RE.exec(value);
+    if (ref) out.push(ref[1]);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (var i = 0; i < value.length; i++) _walkBulkIdRefs(value[i], out);
+    return;
+  }
+  if (value && typeof value === "object") {
+    var keys = Object.keys(value);
+    for (var k = 0; k < keys.length; k++) {
+      if (keys[k] === "__proto__" || keys[k] === "constructor" || keys[k] === "prototype") continue;
+      _walkBulkIdRefs(value[keys[k]], out);
+    }
+  }
+}
+
+// Dependency-respecting order over the planned operations. Operations
+// already carrying a staticError (undeclared reference) are treated as
+// dependency-free roots so they surface their own error in request
+// order. Any operation that cannot be ordered because it participates in
+// a CYCLE is marked with a 409 staticError per RFC 7644 §3.7.1 — "The
+// service provider MUST try to resolve circular cross-references ... but
+// MAY ... return HTTP status code 409 (Conflict)". The returned order
+// always covers every index exactly once.
+function _topoOrderBulk(planned) {
+  var n          = planned.length;
+  var visited    = new Array(n);   // 0 = unseen, 1 = on-stack, 2 = done
+  for (var v = 0; v < n; v++) visited[v] = 0;
+  var order      = [];
+  var inCycle    = Object.create(null);
+
+  // Iterative depth-first post-order so a dependency is emitted before
+  // the operation that needs it. A back-edge (a node still on-stack)
+  // marks a cycle; every node on the active stack at that point is part
+  // of an unresolvable circular reference.
+  for (var start = 0; start < n; start++) {
+    if (visited[start] !== 0) continue;
+    var stack = [{ node: start, edge: 0 }];
+    while (stack.length > 0) {
+      var top  = stack[stack.length - 1];
+      var node = top.node;
+      if (top.edge === 0) visited[node] = 1;
+      var deps = (planned[node].staticError) ? [] : planned[node].refs;
+      if (top.edge < deps.length) {
+        var dep = deps[top.edge];
+        top.edge++;
+        if (visited[dep] === 0) {
+          stack.push({ node: dep, edge: 0 });
+        } else if (visited[dep] === 1) {
+          // Back-edge to a node still on the active stack — every node
+          // from that node up to the current top forms the cycle.
+          var depPos = -1;
+          for (var p = 0; p < stack.length; p++) {
+            if (stack[p].node === dep) { depPos = p; break; }
+          }
+          for (var q = depPos; q >= 0 && q < stack.length; q++) {
+            inCycle[stack[q].node] = true;
+          }
+        }
+      } else {
+        visited[node] = 2;
+        order.push(node);
+        stack.pop();
+      }
+    }
+  }
+
+  for (var c = 0; c < n; c++) {
+    if (inCycle[c] && !planned[c].staticError) {
+      planned[c].staticError = {
+        status:   "409",
+        scimType: "invalidValue",
+        detail:   "Operations[" + c + "] is part of an unresolvable circular bulkId reference",
+      };
+    }
+  }
+  return order;
+}
+
+// True when any of the bulkIds this operation references belongs to a
+// creating operation that ran and FAILED (so no id was recorded in
+// bulkIdMap). A still-pending dependency cannot occur here because the
+// topological order guarantees dependencies execute first.
+function _anyDependencyFailed(refs, plan, executed, bulkIdMap) {
+  for (var i = 0; i < refs.length; i++) {
+    var declIdx = refs[i];
+    var rec = executed[declIdx];
+    if (rec && rec.isError) return true;
+    // A successfully-created dependency records its id in bulkIdMap; if
+    // it ran without error but produced no id, it cannot satisfy a
+    // reference either.
+    var declOp = plan.ops[declIdx];
+    if (rec && !rec.isError && declOp.ownBulkId && bulkIdMap[declOp.ownBulkId] === undefined) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // RFC 7644 §3.7 — failOnErrors is an OPTIONAL integer >= 1. Absent /
 // non-conforming values mean "process every operation" (null).
 function _parseFailOnErrors(value) {
@@ -380,7 +629,19 @@ async function _runBulkOperation(op, index, opts, ctx, bulkIdMap) {
       "Operations[" + index + "].method '" + op.method + "' not in POST/PUT/PATCH/DELETE");
   }
 
-  var parsed = _parseBulkPath(op.path);
+  // Resolve path bulkId references BEFORE parsing — the dependency-
+  // ordered executor guarantees a referenced creation already ran, so
+  // an unresolved token here is an unsatisfiable reference, failed
+  // per-op (RFC 7644 §3.7.2) rather than handed to the adapter.
+  var path = op.path;
+  if (typeof path === "string" && path.indexOf("bulkId:") !== -1) {
+    try { path = _resolvePathBulkIdRefs(path, bulkIdMap); }
+    catch (refErr) {
+      return _bulkErr(op, "400", "invalidValue",
+        "Operations[" + index + "] " + (refErr && refErr.message ? refErr.message : "has an unresolved bulkId reference in path"));
+    }
+  }
+  var parsed = _parseBulkPath(path);
   if (!parsed) {
     return _bulkErr(op, "400", "invalidValue",
       "Operations[" + index + "].path '" + String(op.path) + "' is not a valid bulk path");
@@ -402,8 +663,17 @@ async function _runBulkOperation(op, index, opts, ctx, bulkIdMap) {
   var data = op.data;
   if (method === "POST" || method === "PUT" || method === "PATCH") {
     // RFC 7644 §3.7.2 — substitute any bulkId cross-references that
-    // earlier operations have resolved before handing data to the adapter.
-    data = _resolveBulkIdRefs(op.data, bulkIdMap);
+    // earlier operations resolved before handing data to the adapter.
+    // The dependency-ordered executor guarantees every referenced
+    // operation ran first; an unresolved token here would mean an
+    // unsatisfiable reference, which is failed per-op rather than passed
+    // through to the adapter as a literal "bulkId:<id>" string.
+    try {
+      data = _resolveBulkIdRefs(op.data, bulkIdMap);
+    } catch (refErr) {
+      return _bulkErr(op, "400", "invalidValue",
+        "Operations[" + index + "] " + (refErr && refErr.message ? refErr.message : "has an unresolved bulkId reference"));
+    }
   }
 
   try {
@@ -462,7 +732,15 @@ function _resolveBulkIdRefs(value, bulkIdMap) {
     var ref = BULK_ID_REF_RE.exec(value);
     if (ref) {
       var resolved = bulkIdMap[ref[1]];
-      return resolved !== undefined ? resolved : value;
+      // A literal "bulkId:<id>" token MUST never reach the adapter as a
+      // real id. The dependency-ordered executor resolves every
+      // reference before dispatch; an unresolved token here signals an
+      // unsatisfiable reference, surfaced as a per-op error by the caller.
+      if (resolved === undefined) {
+        throw new ScimServerError("middleware/scim-server/unresolved-bulkid",
+          "references unresolved bulkId '" + ref[1] + "'");
+      }
+      return resolved;
     }
     return value;
   }

package/lib/middleware/security-txt.js

@@ -82,7 +82,6 @@ function _isoFuture(s) {
  *     hiring:             string,
  *     canonical:          string|string[],
  *     alsoAtRoot:         boolean,
- *     audit:              boolean,
  *   }
  *
  * @example
@@ -99,7 +98,7 @@ function create(opts) {
   validateOpts(opts, [
     "contact", "expires", "encryption", "policy", "ack",
     "preferredLanguages", "hiring", "canonical",
-    "alsoAtRoot", "audit",
+    "alsoAtRoot",
   ], "middleware.securityTxt");
 
   var contact = _arrayOfStrings(opts.contact, "contact");

package/lib/middleware/trace-log-correlation.js

@@ -52,13 +52,10 @@ function _baggageToObject(entries) {
 
 function _wrapLogger(baseLogger, req, opts) {
   if (!baseLogger || typeof baseLogger !== "object") return baseLogger;
-  var wrapped = Object.create(null);
   // Preserve any non-level properties the operator put on the
-  // logger (e.g. boot context, child-logger metadata).
-  var keys = Object.keys(baseLogger);
-  for (var i = 0; i < keys.length; i++) {
-    if (LOG_LEVELS.indexOf(keys[i]) === -1) wrapped[keys[i]] = baseLogger[keys[i]];
-  }
+  // logger (e.g. boot context, child-logger metadata); the level
+  // methods themselves are re-wrapped below.
+  var wrapped = validateOpts.assignOwnEnumerable(Object.create(null), baseLogger, LOG_LEVELS);
 
   function _enrichMeta(meta) {
     var enriched = Object.assign({}, meta || {});
@@ -123,7 +120,6 @@ function _wrapLogger(baseLogger, req, opts) {
  *     logger:         object,    // required b.log instance
  *     reqField:       string,    // default "log" → req.log
  *     includeBaggage: boolean,   // default true
- *     audit:          boolean,
  *   }
  *
  * @example
@@ -138,7 +134,7 @@ function _wrapLogger(baseLogger, req, opts) {
 function create(opts) {
   validateOpts.requireObject(opts, "middleware.traceLogCorrelation", TraceLogError);
   validateOpts(opts, [
-    "logger", "reqField", "includeBaggage", "audit",
+    "logger", "reqField", "includeBaggage",
   ], "middleware.traceLogCorrelation");
 
   if (!opts.logger || typeof opts.logger !== "object") {

package/lib/network-smtp-policy.js

@@ -21,7 +21,7 @@
  *
  *   policy.tlsRpt.recordShape({
  *     organization: "example.com",
- *     reportingMta: "mx1.example.com",
+ *     policies:     [ ... ],
  *     ...
  *   }) → { ... RFC 8460 TLS-RPT JSON shape ... }
  *
@@ -519,8 +519,8 @@ function daneVerifyChain(certChain, tlsaRecords, opts) {
 function tlsRptRecordShape(opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "organization", "reportingMta", "contact",
-    "datestart", "dateend", "policies",
+    "organization", "contact",
+    "datestart", "dateend", "policies", "reportId",
   ], "tlsRpt.recordShape");
 
   if (typeof opts.organization !== "string") {
@@ -637,7 +637,7 @@ async function tlsRptSubmit(report, opts) {
       "tlsRpt.submit: report must be an object");
   }
   opts = opts || {};
-  validateOpts(opts, ["rua", "httpClient", "timeoutMs", "audit"], "tlsRpt.submit");
+  validateOpts(opts, ["rua", "httpClient", "timeoutMs"], "tlsRpt.submit");
   if (!Array.isArray(opts.rua) || opts.rua.length === 0) {
     throw new SmtpPolicyError("smtp/tls-rpt-bad-rua",
       "tlsRpt.submit: opts.rua must be a non-empty array of URIs");

package/lib/object-store/sigv4-bucket-ops.js

@@ -418,7 +418,6 @@ function create(config) {
     "protocol", "region", "accessKeyId", "secretAccessKey", "sessionToken",
     "endpoint", "pathStyle", "forcePathStyle",
     "allowedProtocols", "allowInternal", "timeoutMs",
-    "ca",
     "audit", "observability", "auditSuccess", "auditFailures",
   ], "bucketOps");
   if (config.protocol && config.protocol !== "sigv4") {
@@ -464,7 +463,17 @@ function create(config) {
   }
 
   function _actor(callerOpts) {
-    return requestHelpers.resolveActorWithOverride(callerOpts || {}, null);
+    // `req` resolves IP / user-agent / userId from the live request;
+    // `actor` is an explicit override bag (e.g. { userId: "ops-admin" })
+    // for callers that perform a compliance-sensitive bucket change on
+    // behalf of an operator and want that identity on the audit row.
+    // Passed as the override seed: explicit `actor` fields win over the
+    // request-derived ones, while request-derived fields fill any key the
+    // operator left unset.
+    var seed = (callerOpts && callerOpts.actor && typeof callerOpts.actor === "object")
+      ? callerOpts.actor
+      : null;
+    return requestHelpers.resolveActorWithOverride(callerOpts || {}, seed);
   }
 
   // S3 subresource queries (`?lifecycle`, `?cors`, `?object-lock`,

package/lib/observability-tracer.js

@@ -156,7 +156,7 @@ function create(opts) {
   validateOpts(opts, [
     "service", "resource", "scope",
     "maxAttributes", "maxEvents", "maxAttributeValueLength",
-    "onEnd", "onStart", "audit",
+    "onEnd", "onStart",
   ], "tracer.create");
   validateOpts.requireNonEmptyString(opts.service,
     "tracer.create: service", TracerError, "tracer/bad-service");

package/lib/problem-details.js

@@ -132,19 +132,28 @@ function getBase() {
  *   - `status` (recommended) must be an integer 100..599.
  *   - `detail` (optional) must be a string when given.
  *   - `instance` (optional) must be a URI reference string when given.
- *   - Extensions: every additional key whose name is NOT in
+ *   - Extensions: every additional top-level key whose name is NOT in
  *     `RESERVED_FIELDS` is preserved at the top level. Reserved-name
- *     collisions throw `problem-details/reserved-extension`.
+ *     collisions throw `problem-details/reserved-extension`;
+ *     prototype-pollution-shaped top-level keys throw the same.
+ *   - `extensions`: a plain object whose keys are spread as top-level
+ *     sibling members (RFC 9457 §3.2) — the literal `extensions`
+ *     member is never emitted. Keys colliding with `RESERVED_FIELDS`
+ *     are ignored (reserved fields can't be overridden by an
+ *     extension); prototype-pollution-shaped keys are dropped
+ *     silently. When the same name appears both as a direct top-level
+ *     key and inside `extensions`, the direct top-level key wins.
  *
  * Returns a frozen plain object suitable for `JSON.stringify`.
  *
  * @opts
- *   type:     string,   // problem-type URI reference (default "about:blank")
- *   title:    string,   // short summary
- *   status:   number,   // integer 100..599
- *   detail:   string,   // human-readable explanation
- *   instance: string,   // URI reference for this specific occurrence
- *   ...extensions       // additional fields preserved as-is
+ *   type:       string,   // problem-type URI reference (default "about:blank")
+ *   title:      string,   // short summary
+ *   status:     number,   // integer 100..599
+ *   detail:     string,   // human-readable explanation
+ *   instance:   string,   // URI reference for this specific occurrence
+ *   extensions: object,   // keys spread as top-level siblings (§3.2); direct top-level key wins on collision
+ *   ...extensions         // additional top-level keys preserved as-is
  *
  * @example
  *   var p = b.problemDetails.create({
@@ -213,15 +222,44 @@ function create(opts) {
 
   // Extensions — every additional key. §3.2 endorses sibling
   // extensions as long as their names don't collide with reserved.
+  // The `extensions` key itself is NOT emitted as a literal nested
+  // member: a plain-object value is spread so each of its keys lands
+  // as a top-level sibling, subject to the same reserved / poisoned
+  // guards as direct top-level keys. A direct top-level extension key
+  // wins over the same name nested under `extensions`.
   var keys = Object.keys(opts);
-  for (var i = 0; i < keys.length; i += 1) {
-    var k = keys[i];
+  var directKeys = Object.create(null);
+  var i, k;
+  for (i = 0; i < keys.length; i += 1) {
+    k = keys[i];
+    if (k === "extensions") continue;
     if (RESERVED_FIELDS.indexOf(k) !== -1) continue;
     if (POISONED_KEYS.indexOf(k) !== -1) {
       throw new ProblemDetailsError("problem-details/reserved-extension",
         "create: extension key '" + k + "' refused (prototype-pollution shape)", true);
     }
     out[k] = opts[k];
+    directKeys[k] = true;
+  }
+
+  // Spread `extensions` (RFC 9457 §3.2 sibling members). Reserved
+  // names can't be overridden by an extension key; poisoned keys are
+  // dropped silently (an inbound extension map is a less-trusted shape
+  // than a hand-authored top-level key — a direct poisoned key still
+  // throws). A direct top-level key already present wins.
+  if (opts.extensions !== undefined && opts.extensions !== null) {
+    if (typeof opts.extensions !== "object" || Array.isArray(opts.extensions)) {
+      throw new ProblemDetailsError("problem-details/bad-extensions",
+        "create: extensions must be a plain object when provided", true);
+    }
+    var extKeys = Object.keys(opts.extensions);
+    for (i = 0; i < extKeys.length; i += 1) {
+      k = extKeys[i];
+      if (RESERVED_FIELDS.indexOf(k) !== -1) continue;
+      if (POISONED_KEYS.indexOf(k) !== -1) continue;
+      if (directKeys[k]) continue;
+      out[k] = opts.extensions[k];
+    }
   }
 
   return Object.freeze(out);
@@ -386,13 +424,20 @@ function respond(res, problem, req) {
  * `Cache-Control: no-store` are written; status code defaults to
  * 500 when omitted.
  *
+ * `extensions` keys are spread as top-level sibling members (RFC 9457
+ * §3.2) via `create` — the literal `extensions` member is never
+ * emitted. Keys colliding with the reserved `type` / `title` /
+ * `status` / `detail` / `instance` are ignored; prototype-pollution-
+ * shaped keys are dropped. A direct top-level key wins over the same
+ * name nested under `extensions`.
+ *
  * @opts
  *   status:    number,           // HTTP status code (100..599); default 500
  *   title:     string,           // operator-supplied short title
  *   detail:    string,           // operator-supplied human-readable explanation
  *   type:      string,           // problem-type URI (defaults to "about:blank")
  *   instance:  string,           // optional per-occurrence URI
- *   extensions: object,          // operator-specific extension fields
+ *   extensions: object,          // keys spread as top-level siblings (§3.2); direct top-level key wins on collision
  *
  * @example
  *   // Migrating from inline JSON-error shape:

package/lib/pubsub-cluster.js

@@ -24,18 +24,31 @@
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
 
 var logger = lazyRequire(function () { return require("./log").boot("pubsub-cluster"); });
 
+var PubsubError = defineClass("PubsubError");
+
 var DEFAULT_POLL_INTERVAL_MS = 100;
 var DEFAULT_RETENTION_MS     = C.TIME.minutes(1);
 var DEFAULT_PRUNE_EVERY_MS   = C.TIME.minutes(5);
 
 function create(opts) {
   var clusterInstance = opts.cluster;
-  var pollIntervalMs = Number(opts.pollIntervalMs) || DEFAULT_POLL_INTERVAL_MS;
-  var retentionMs    = Number(opts.retentionMs)    || DEFAULT_RETENTION_MS;
-  var pruneEveryMs   = Number(opts.pruneEveryMs)   || DEFAULT_PRUNE_EVERY_MS;
+  // Config-time: a typo (NaN-coercing string / negative / fractional) must
+  // surface at create, not silently fall back to the default and ship a
+  // mis-tuned poll loop. THROW on present-but-bad; absent keeps the default.
+  validateOpts.optionalPositiveInt(opts.pollIntervalMs,
+    "pubsub: pollIntervalMs", PubsubError, "BAD_OPT");
+  validateOpts.optionalPositiveInt(opts.retentionMs,
+    "pubsub: retentionMs", PubsubError, "BAD_OPT");
+  validateOpts.optionalPositiveInt(opts.pruneEveryMs,
+    "pubsub: pruneEveryMs", PubsubError, "BAD_OPT");
+  var pollIntervalMs = opts.pollIntervalMs !== undefined ? opts.pollIntervalMs : DEFAULT_POLL_INTERVAL_MS;
+  var retentionMs    = opts.retentionMs    !== undefined ? opts.retentionMs    : DEFAULT_RETENTION_MS;
+  var pruneEveryMs   = opts.pruneEveryMs   !== undefined ? opts.pruneEveryMs   : DEFAULT_PRUNE_EVERY_MS;
 
   var lastSeenId  = 0;
   var primed      = false;