@blamejs/core 0.14.18 → 0.14.19

package/lib/middleware/scim-server.js

@@ -19,8 +19,17 @@ var ScimServerError = framework_error.defineClass(
 
 var SCIM_CORE_SCHEMA_USER  = "urn:ietf:params:scim:schemas:core:2.0:User";
 var SCIM_CORE_SCHEMA_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group";
-var SCIM_MESSAGE_ERROR     = "urn:ietf:params:scim:api:messages:2.0:Error";
-var SCIM_MESSAGE_LIST      = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+var SCIM_MESSAGE_ERROR        = "urn:ietf:params:scim:api:messages:2.0:Error";
+var SCIM_MESSAGE_LIST         = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+var SCIM_MESSAGE_BULK_REQUEST  = "urn:ietf:params:scim:api:messages:2.0:BulkRequest";
+var SCIM_MESSAGE_BULK_RESPONSE = "urn:ietf:params:scim:api:messages:2.0:BulkResponse";
+
+// RFC 7644 §3.7.2 — a bulkId cross-reference is the literal token
+// "bulkId:" followed by the client-assigned identifier. Bounded: the
+// identifier is matched lazily-free (one or more non-quote chars) and
+// only ever applied to operator-defined bulkId strings, never to free
+// request text, so there is no super-linear backtracking exposure.
+var BULK_ID_REF_RE = /^bulkId:(.+)$/;
 
 var ALLOWED_FILTER_OPS = ["eq", "ne", "co", "sw", "ew", "pr", "gt", "ge", "lt", "le"];
 
@@ -37,6 +46,11 @@ var BEARER_RE = /^Bearer\s+(.+)$/i;
  * Returns a request middleware that handles SCIM 2.0 requests
  * (RFC 7642-7644). Operator supplies CRUD callbacks per resource.
  *
+ * Bulk operations (RFC 7644 §3.7) are opt-in: pass `opts.bulk` to
+ * enable the `/Bulk` POST endpoint and advertise it in
+ * ServiceProviderConfig. When omitted, `bulk.supported` stays `false`
+ * and `/Bulk` is not routed (back-compatible default).
+ *
  * @opts
  *   {
  *     basePath?:    string,
@@ -44,6 +58,10 @@ var BEARER_RE = /^Bearer\s+(.+)$/i;
  *     groups?:      ScimResourceImpl,
  *     bearer?:      (token) => Promise<actor>,
  *     maxPageSize?: number,
+ *     bulk?: {
+ *       maxOperations?:  number,   // default: 1000 (config-time positive int)
+ *       maxPayloadSize?: number,   // default: 1 MiB  (config-time positive int, bytes)
+ *     },
  *   }
  *
  * @example
@@ -51,6 +69,7 @@ var BEARER_RE = /^Bearer\s+(.+)$/i;
  *     basePath: "/scim/v2",
  *     users:  myUserAdapter,
  *     groups: myGroupAdapter,
+ *     bulk:   { maxOperations: 100 },
  *   });
  *   app.use(mw);
  */
@@ -63,11 +82,12 @@ function create(opts) {
   var basePath    = opts.basePath || "/scim/v2";
   var maxPageSize = opts.maxPageSize || 200;                                                                  // page-size count, not bytes
   var bearer      = opts.bearer || null;
+  var bulkCfg     = _resolveBulkConfig(opts.bulk);
 
   function middleware(req, res, next) {
     var url = req.url.split("?")[0];
     if (url.indexOf(basePath) !== 0) { next(); return; }
-    _dispatch(req, res, basePath, bearer, opts, maxPageSize)
+    _dispatch(req, res, basePath, bearer, opts, maxPageSize, bulkCfg)
       .catch(function (err) {
         _writeScimError(res, err.statusCode || 500, err.scimType || "internal",
           (err.message || String(err)).slice(0, 500));
@@ -92,7 +112,26 @@ function _validateResourceImpl(impl, name) {
   });
 }
 
-async function _dispatch(req, res, basePath, bearer, opts, maxPageSize) {
+// Config-time / entry-point tier: bad bulk caps THROW so the operator
+// catches a typo at boot rather than at request time. RFC 7644 §3.7.
+// Returns null when bulk is not opted into (back-compat default off).
+function _resolveBulkConfig(bulk) {
+  if (bulk === undefined || bulk === null) return null;
+  if (typeof bulk !== "object") {
+    throw new ScimServerError("middleware/scim-server/bad-bulk",
+      "middleware.scimServer: opts.bulk must be an object { maxOperations?, maxPayloadSize? }");
+  }
+  validateOpts.optionalPositiveInt(bulk.maxOperations, "middleware.scimServer: opts.bulk.maxOperations",
+    ScimServerError, "middleware/scim-server/bad-bulk-max-operations");
+  validateOpts.optionalPositiveInt(bulk.maxPayloadSize, "middleware.scimServer: opts.bulk.maxPayloadSize",
+    ScimServerError, "middleware/scim-server/bad-bulk-max-payload-size");
+  return {
+    maxOperations:  bulk.maxOperations  || 1000,
+    maxPayloadSize: bulk.maxPayloadSize || C.BYTES.mib(1),
+  };
+}
+
+async function _dispatch(req, res, basePath, bearer, opts, maxPageSize, bulkCfg) {
   var relUrl = req.url.slice(basePath.length) || "/";
   var qIdx   = relUrl.indexOf("?");
   var path   = qIdx === -1 ? relUrl : relUrl.slice(0, qIdx);
@@ -148,6 +187,19 @@ async function _dispatch(req, res, basePath, bearer, opts, maxPageSize) {
   var users   = opts.users;
   var groups  = opts.groups;
 
+  if (path === "/Bulk") {
+    if (req.method !== "POST") {
+      _writeScimError(res, H.METHOD_NOT_ALLOWED, "noTarget", req.method + " not allowed on /Bulk");
+      return;
+    }
+    if (!bulkCfg) {
+      _writeScimError(res, 501, "notSupported", "bulk operations are not enabled");
+      return;
+    }
+    await _handleBulk(req, res, opts, bulkCfg, ctx);
+    return;
+  }
+
   // RESOURCE_PATH_RE applies to a URL path; node http caps URL at 8 KiB.
   var match = path.length < C.BYTES.kib(8) && RESOURCE_PATH_RE.test(path) ? path.match(RESOURCE_PATH_RE) : null;   // allow:regex-no-length-cap URL bounded above
   if (!match) {
@@ -244,6 +296,230 @@ async function _dispatch(req, res, basePath, bearer, opts, maxPageSize) {
   _writeScimError(res, H.METHOD_NOT_ALLOWED, "noTarget", req.method + " not allowed on " + path);
 }
 
+// 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.
+async function _handleBulk(req, res, opts, bulkCfg, ctx) {
+  var body;
+  try {
+    body = await _readBulkBody(req, bulkCfg.maxPayloadSize);
+  } catch (e) {
+    // collectStream rejects with the configured errorClass on overflow.
+    if (e && e.code === "middleware/scim-server/bulk-too-large") {
+      _writeScimError(res, H.PAYLOAD_TOO_LARGE, "tooLarge",
+        "bulk payload exceeds maxPayloadSize of " + bulkCfg.maxPayloadSize + " bytes");
+      return;
+    }
+    throw e;
+  }
+
+  if (!body || typeof body !== "object" ||
+      !Array.isArray(body.schemas) ||
+      body.schemas.indexOf(SCIM_MESSAGE_BULK_REQUEST) === -1) {
+    _writeScimError(res, H.BAD_REQUEST, "invalidValue",
+      "BulkRequest body.schemas must include '" + SCIM_MESSAGE_BULK_REQUEST + "'");
+    return;
+  }
+  if (!Array.isArray(body.Operations)) {
+    _writeScimError(res, H.BAD_REQUEST, "invalidValue", "BulkRequest must include Operations[]");
+    return;
+  }
+  if (body.Operations.length > bulkCfg.maxOperations) {
+    _writeScimError(res, H.PAYLOAD_TOO_LARGE, "tooMany",
+      "bulk request has " + body.Operations.length +
+      " operations, exceeding maxOperations of " + bulkCfg.maxOperations);
+    return;
+  }
+
+  var failOnErrors = _parseFailOnErrors(body.failOnErrors);
+  var bulkIdMap    = Object.create(null);   // client bulkId -> assigned resource id
+  var results      = [];
+  var errorCount   = 0;
+
+  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) {
+      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;
+    }
+  }
+
+  _writeJson(res, H.OK, {
+    schemas:    [SCIM_MESSAGE_BULK_RESPONSE],
+    Operations: results,
+  });
+}
+
+// RFC 7644 §3.7 — failOnErrors is an OPTIONAL integer >= 1. Absent /
+// non-conforming values mean "process every operation" (null).
+function _parseFailOnErrors(value) {
+  if (typeof value !== "number" || !isFinite(value) || Math.floor(value) !== value || value < 1) {
+    return null;
+  }
+  return value;
+}
+
+// Dispatch one BulkOperation through the matching per-resource adapter.
+// Returns { entry, isError }; entry is the BulkResponse Operation object
+// (RFC 7644 §3.7). Adapter rejections become per-op error entries — one
+// failing operation never aborts the whole batch (unless failOnErrors).
+async function _runBulkOperation(op, index, opts, ctx, bulkIdMap) {
+  if (!op || typeof op !== "object" || typeof op.method !== "string") {
+    return _bulkErr(op, "400", "invalidSyntax",
+      "Operations[" + index + "] missing string method");
+  }
+  var method = op.method.toUpperCase();
+  if (method !== "POST" && method !== "PUT" && method !== "PATCH" && method !== "DELETE") {
+    return _bulkErr(op, "400", "invalidValue",
+      "Operations[" + index + "].method '" + op.method + "' not in POST/PUT/PATCH/DELETE");
+  }
+
+  var parsed = _parseBulkPath(op.path);
+  if (!parsed) {
+    return _bulkErr(op, "400", "invalidValue",
+      "Operations[" + index + "].path '" + String(op.path) + "' is not a valid bulk path");
+  }
+  var impl = parsed.resourceType === "Users" ? opts.users : opts.groups;
+  if (!impl) {
+    return _bulkErr(op, "404", "invalidValue", "/" + parsed.resourceType + " not configured");
+  }
+  // POST defines a bulkId-assigned resource; PUT/PATCH/DELETE target an id.
+  if (method === "POST" && !op.bulkId) {
+    return _bulkErr(op, "400", "invalidValue",
+      "Operations[" + index + "] POST requires a bulkId");
+  }
+  if (method !== "POST" && !parsed.resourceId) {
+    return _bulkErr(op, "400", "invalidValue",
+      "Operations[" + index + "] " + method + " requires a resource id in path");
+  }
+
+  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);
+  }
+
+  try {
+    if (method === "POST" || method === "PUT") {
+      // The same SCIM schema gate the singleton POST / PUT routes apply,
+      // so a bulk op cannot persist a resource with a missing or wrong
+      // schema that the singleton endpoints would reject (RFC 7644
+      // §3.5.1). A throw here is caught below and returned as the op's
+      // own error, not aborting the batch.
+      _assertSchema(data, parsed.resourceType === "Users" ? SCIM_CORE_SCHEMA_USER : SCIM_CORE_SCHEMA_GROUP);
+    }
+    if (method === "POST") {
+      var created = await impl.create(data || {}, ctx);
+      var newId   = created && created.id;
+      if (op.bulkId && newId !== undefined && newId !== null) {
+        bulkIdMap[String(op.bulkId)] = String(newId);
+      }
+      return _bulkOk(op, "201", _bulkLocation(parsed.resourceType, newId), created);
+    }
+    if (method === "PUT") {
+      var replaced = await impl.update(parsed.resourceId, data || {}, ctx);
+      return _bulkOk(op, "200", _bulkLocation(parsed.resourceType, parsed.resourceId), replaced);
+    }
+    if (method === "PATCH") {
+      var ops = data && Array.isArray(data.Operations) ? data.Operations : [];
+      var patched = await impl.patch(parsed.resourceId, ops, ctx);
+      return _bulkOk(op, "200", _bulkLocation(parsed.resourceType, parsed.resourceId), patched);
+    }
+    await impl.remove(parsed.resourceId, ctx);   // DELETE
+    return _bulkOk(op, "204", _bulkLocation(parsed.resourceType, parsed.resourceId), null);
+  } catch (e) {
+    var status   = e && e.statusCode ? String(e.statusCode) : "500";
+    var scimType = e && e.scimType ? e.scimType : null;
+    // Operator-adapter error detail is surfaced verbatim (it is the
+    // adapter's own message, not request-derived secret material).
+    return _bulkErr(op, status, scimType, (e && e.message) ? String(e.message) : "operation failed");
+  }
+}
+
+// A bulk path is "/Users", "/Users/<id>", "/Groups", or "/Groups/<id>".
+function _parseBulkPath(path) {
+  if (typeof path !== "string" || path.length === 0) return null;
+  // Reuse the singleton resource-path grammar; node http caps URL at 8 KiB.
+  var m = path.length < C.BYTES.kib(8) && RESOURCE_PATH_RE.test(path)                                          // allow:regex-no-length-cap path bounded above
+    ? path.match(RESOURCE_PATH_RE) : null;
+  if (!m) return null;
+  return { resourceType: m[1], resourceId: m[2] || null };
+}
+
+// RFC 7644 §3.7.2 — walk operation data and replace any string of the
+// form "bulkId:<clientId>" with the server-assigned id once known.
+// Operates only on operator/client-supplied bulk data of bounded size
+// (the whole payload is capped at maxPayloadSize before parse).
+function _resolveBulkIdRefs(value, bulkIdMap) {
+  if (typeof value === "string") {
+    var ref = BULK_ID_REF_RE.exec(value);
+    if (ref) {
+      var resolved = bulkIdMap[ref[1]];
+      return resolved !== undefined ? resolved : value;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    var arr = [];
+    for (var i = 0; i < value.length; i++) arr.push(_resolveBulkIdRefs(value[i], bulkIdMap));
+    return arr;
+  }
+  if (value && typeof value === "object") {
+    var out = {};
+    var keys = Object.keys(value);
+    for (var k = 0; k < keys.length; k++) {
+      if (keys[k] === "__proto__" || keys[k] === "constructor" || keys[k] === "prototype") continue;
+      out[keys[k]] = _resolveBulkIdRefs(value[keys[k]], bulkIdMap);
+    }
+    return out;
+  }
+  return value;
+}
+
+function _bulkLocation(resourceType, id) {
+  if (id === undefined || id === null) return undefined;
+  return "/" + resourceType + "/" + String(id);
+}
+
+function _bulkOk(op, status, location, response) {
+  var entry = { method: op && op.method, status: status };
+  if (op && op.bulkId) entry.bulkId = op.bulkId;
+  if (location) entry.location = location;
+  // Per §3.7 the response body is OPTIONAL; include it when the adapter
+  // returned a representation (omit on 204 No Content).
+  if (response !== null && response !== undefined) entry.response = response;
+  return { entry: entry, isError: false };
+}
+
+function _bulkErr(op, status, scimType, detail) {
+  var errBody = { schemas: [SCIM_MESSAGE_ERROR], status: status, detail: detail };
+  if (scimType) errBody.scimType = scimType;
+  var entry = { method: op && op.method, status: status, response: errBody };
+  if (op && op.bulkId) entry.bulkId = op.bulkId;
+  return { entry: entry, isError: true };
+}
+
+function _readBulkBody(req, maxBytes) {
+  if (req.body && Buffer.isBuffer(req.body)) {
+    return Promise.resolve(safeJson.parse(req.body.toString("utf8"), { maxBytes: maxBytes }));
+  }
+  if (req.body && typeof req.body === "object") return Promise.resolve(req.body);
+  return safeBuffer.collectStream(req, {
+    maxBytes:   maxBytes,
+    errorClass: ScimServerError,
+    sizeCode:   "middleware/scim-server/bulk-too-large",
+  }).then(function (buf) {
+    return safeJson.parse(buf.toString("utf8"), { maxBytes: maxBytes });
+  });
+}
+
 function _parseQuery(qs) {
   var out = {};
   if (!qs) return out;
@@ -321,11 +597,17 @@ function _writeScimError(res, status, scimType, detail) {
 }
 
 function _serviceProviderConfig(opts) {
+  // RFC 7644 §3.7 — advertise bulk only when the operator opted in via
+  // opts.bulk; otherwise report it unsupported (back-compat default).
+  var bulkCfg = _resolveBulkConfig(opts.bulk);
+  var bulk = bulkCfg
+    ? { supported: true,  maxOperations: bulkCfg.maxOperations, maxPayloadSize: bulkCfg.maxPayloadSize }
+    : { supported: false, maxOperations: 0, maxPayloadSize: 0 };
   return {
     schemas: ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
     documentationUri: opts.documentationUri || "https://datatracker.ietf.org/doc/html/rfc7643",
     patch:            { supported: true },
-    bulk:             { supported: false, maxOperations: 0, maxPayloadSize: 0 },
+    bulk:             bulk,
     filter:           { supported: true, maxResults: opts.maxPageSize || 200 },
     changePassword:   { supported: false },
     sort:             { supported: true },
@@ -370,9 +652,11 @@ function _schemas() {
 }
 
 module.exports = {
-  create:                 create,
-  ScimServerError:        ScimServerError,
-  SCIM_CORE_SCHEMA_USER:  SCIM_CORE_SCHEMA_USER,
-  SCIM_CORE_SCHEMA_GROUP: SCIM_CORE_SCHEMA_GROUP,
-  ALLOWED_FILTER_OPS:     ALLOWED_FILTER_OPS,
+  create:                         create,
+  ScimServerError:                ScimServerError,
+  SCIM_CORE_SCHEMA_USER:          SCIM_CORE_SCHEMA_USER,
+  SCIM_CORE_SCHEMA_GROUP:         SCIM_CORE_SCHEMA_GROUP,
+  SCIM_MESSAGE_BULK_REQUEST:      SCIM_MESSAGE_BULK_REQUEST,
+  SCIM_MESSAGE_BULK_RESPONSE:     SCIM_MESSAGE_BULK_RESPONSE,
+  ALLOWED_FILTER_OPS:             ALLOWED_FILTER_OPS,
 };

package/lib/openapi-paths-builder.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * OpenAPI 3.1 — paths / operations builder.
+ * OpenAPI 3.1 / 3.2 — paths / operations + webhooks builder.
  *
  * Internal to lib/openapi.js. Holds the per-path operation table
  * (method to operationObject) and produces the final `paths` map used
@@ -13,6 +13,14 @@
  *
  * Operation methods accepted: get / put / post / delete / options /
  * head / patch / trace (RFC 9110 + OpenAPI 3.1 §4.8.5).
+ *
+ * `WebhooksBuilder` shares the same Operation Object normalisation but
+ * keys by a free-form webhook NAME (not a URL pattern): the top-level
+ * `webhooks` field is a map of named Path Item Objects describing
+ * out-of-band requests the API initiates (OpenAPI 3.2 §4.8.2, "Fixed
+ * Fields" — `webhooks`; carried forward unchanged from 3.1.0 §4.1).
+ * Webhook keys are not URL templates, so the `/`-prefix and
+ * path-template-placeholder checks are intentionally not applied.
  */
 
 var validateOpts = require("./validate-opts");
@@ -39,25 +47,23 @@ function PathsBuilder() {
   this._paths = {};
 }
 
-PathsBuilder.prototype.add = function (method, urlPattern, opts) {
-  opts = opts || {};
+// _buildOperation — normalise a single Operation Object from operator
+// opts. Shared by PathsBuilder.add and WebhooksBuilder.add. `label` is
+// the caller-facing prefix used in error messages. `declaredPathParams`
+// (out-param object) records every in=path parameter so the caller can
+// verify path-template placeholders against it; webhooks have no URL
+// template so the caller simply ignores it.
+function _buildOperation(method, opts, label, declaredPathParams) {
   if (typeof method !== "string" || VALID_METHODS.indexOf(method.toLowerCase()) === -1) {
     throw new OpenApiError("openapi/bad-method",
-      "paths.add: method must be one of " + VALID_METHODS.join(", ") +
+      label + ": method must be one of " + VALID_METHODS.join(", ") +
       " - got " + JSON.stringify(method));
   }
-  validateOpts.requireNonEmptyString(urlPattern, "paths.add: urlPattern",
-    OpenApiError, "openapi/bad-path");
-  if (urlPattern.charAt(0) !== "/") {
-    throw new OpenApiError("openapi/bad-path",
-      "paths.add: urlPattern must start with '/' - got " +
-      JSON.stringify(urlPattern));
-  }
   validateOpts(opts, [
     "summary", "description", "operationId", "tags",
     "parameters", "requestBody", "responses",
     "security", "deprecated", "servers", "externalDocs",
-  ], "paths.add");
+  ], label);
 
   var op = {};
   if (typeof opts.summary === "string")     op.summary = opts.summary;
@@ -67,50 +73,65 @@ PathsBuilder.prototype.add = function (method, urlPattern, opts) {
     op.tags = opts.tags.map(function (t) {
       if (typeof t !== "string" || t.length === 0) {
         throw new OpenApiError("openapi/bad-tag",
-          "paths.add: tags must be non-empty strings");
+          label + ": tags must be non-empty strings");
       }
       return t;
     });
   }
 
   // Parameters
-  var declaredPathParams = Object.create(null);
   if (Array.isArray(opts.parameters)) {
     op.parameters = [];
     for (var i = 0; i < opts.parameters.length; i += 1) {
-      var p = _normaliseParameter(opts.parameters[i], "paths.add: parameters[" + i + "]");
+      var p = _normaliseParameter(opts.parameters[i], label + ": parameters[" + i + "]");
       op.parameters.push(p);
       if (p.in === "path") declaredPathParams[p.name] = true;
     }
   }
-  // Verify every {placeholder} in path is declared.
-  var placeholders = _extractPathParams(urlPattern);
-  for (var j = 0; j < placeholders.length; j += 1) {
-    if (!declaredPathParams[placeholders[j]]) {
-      throw new OpenApiError("openapi/missing-path-param",
-        "paths.add: path template " + JSON.stringify(urlPattern) +
-        " references {" + placeholders[j] +
-        "} but no parameter with in=path name=" + JSON.stringify(placeholders[j]) +
-        " was declared");
-    }
-  }
 
   // Request body
   if (opts.requestBody) {
-    op.requestBody = _normaliseRequestBody(opts.requestBody, "paths.add: requestBody");
+    op.requestBody = _normaliseRequestBody(opts.requestBody, label + ": requestBody");
   }
 
   // Responses (required)
   if (!opts.responses || typeof opts.responses !== "object") {
     throw new OpenApiError("openapi/missing-responses",
-      "paths.add: responses object is required (per OpenAPI 3.1 §4.8.5)");
+      label + ": responses object is required (per OpenAPI 3.1 §4.8.5)");
   }
-  op.responses = _normaliseResponses(opts.responses, "paths.add: responses");
+  op.responses = _normaliseResponses(opts.responses, label + ": responses");
 
   if (Array.isArray(opts.security)) op.security = opts.security.slice();
   if (opts.deprecated === true)     op.deprecated = true;
   if (Array.isArray(opts.servers))  op.servers = opts.servers.slice();
   if (opts.externalDocs)            op.externalDocs = opts.externalDocs;
+  return op;
+}
+
+PathsBuilder.prototype.add = function (method, urlPattern, opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(urlPattern, "paths.add: urlPattern",
+    OpenApiError, "openapi/bad-path");
+  if (urlPattern.charAt(0) !== "/") {
+    throw new OpenApiError("openapi/bad-path",
+      "paths.add: urlPattern must start with '/' - got " +
+      JSON.stringify(urlPattern));
+  }
+
+  var declaredPathParams = Object.create(null);
+  var op = _buildOperation(method, opts, "paths.add", declaredPathParams);
+
+  // Verify every {placeholder} in path is declared.
+  var placeholders = _extractPathParams(urlPattern);
+  for (var j = 0; j < placeholders.length; j += 1) {
+    if (!declaredPathParams[placeholders[j]]) {
+      throw new OpenApiError("openapi/missing-path-param",
+        "paths.add: path template " + JSON.stringify(urlPattern) +
+        " references {" + placeholders[j] +
+        "} but no parameter with in=path name=" + JSON.stringify(placeholders[j]) +
+        " was declared");
+    }
+  }
 
   if (!this._paths[urlPattern]) this._paths[urlPattern] = {};
   if (this._paths[urlPattern][method.toLowerCase()]) {
@@ -240,8 +261,63 @@ PathsBuilder.prototype.toMap = function () {
   return out;
 };
 
+// WebhooksBuilder — the top-level `webhooks` field is a map of named
+// Path Item Objects describing requests the API initiates out-of-band
+// (OpenAPI 3.2 §4.8.2 Fixed Fields → `webhooks`; unchanged from
+// 3.1.0 §4.1). Keys are free-form webhook names (e.g. "newPet"), NOT
+// URL templates — no `/`-prefix and no path-template-placeholder
+// validation. Each named entry holds the same Operation Objects as a
+// regular path item.
+function WebhooksBuilder() {
+  // Null-prototype map so a free-form webhook name that collides with an
+  // Object.prototype member (__proto__ / constructor / prototype) becomes
+  // an own property instead of mutating the prototype (CWE-1321).
+  this._webhooks = Object.create(null);
+}
+
+WebhooksBuilder.prototype.add = function (name, method, opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(name, "webhook.add: name",
+    OpenApiError, "openapi/bad-webhook");
+  if (name === "__proto__" || name === "constructor" || name === "prototype") {
+    throw new OpenApiError("openapi/bad-webhook",
+      "webhook.add: name must not be a reserved object key (" + JSON.stringify(name) + ")");
+  }
+  var declaredPathParams = Object.create(null);
+  var op = _buildOperation(method, opts, "webhook.add", declaredPathParams);
+  if (!this._webhooks[name]) this._webhooks[name] = {};
+  if (this._webhooks[name][method.toLowerCase()]) {
+    throw new OpenApiError("openapi/duplicate-operation",
+      "webhook.add: duplicate operation " + method.toUpperCase() +
+      " on webhook " + JSON.stringify(name));
+  }
+  this._webhooks[name][method.toLowerCase()] = op;
+  return op;
+};
+
+WebhooksBuilder.prototype.count = function () {
+  return Object.keys(this._webhooks).length;
+};
+
+WebhooksBuilder.prototype.toMap = function () {
+  var sorted = Object.keys(this._webhooks).sort();
+  var out = {};
+  for (var i = 0; i < sorted.length; i += 1) {
+    var name = sorted[i];
+    var item = this._webhooks[name];
+    var ordered = {};
+    for (var j = 0; j < VALID_METHODS.length; j += 1) {
+      var method = VALID_METHODS[j];
+      if (item[method]) ordered[method] = item[method];
+    }
+    out[name] = ordered;
+  }
+  return out;
+};
+
 module.exports = {
   PathsBuilder:        PathsBuilder,
+  WebhooksBuilder:     WebhooksBuilder,
   VALID_METHODS:       VALID_METHODS,
   _extractPathParams:  _extractPathParams,
   OpenApiError:        OpenApiError,