@blamejs/core 0.7.0 → 0.7.4

package/lib/validate-opts.js

@@ -219,6 +219,53 @@ function requireNonEmptyString(value, label, errorClass, code) {
   return value;
 }
 
+// optionalNonEmptyStringArray — required-shape validator for optional
+// array-of-non-empty-strings opts (scopes / allowedFileTypes / dependsOn /
+// rtlLanguages / eagerLocales / etc.). Replaces the recurring four-line
+// cascade `if (opts.X !== undefined) { if (!Array.isArray) throw; for
+// (i...) if (typeof !== "string" || === "") throw }` that 5+ primitives
+// previously rolled by hand.
+//
+// undefined / null → returns the value unchanged (caller can default).
+// non-array → throws via errorClass with the provided code.
+// any non-string or empty-string element → throws with index-pointing message.
+function optionalNonEmptyStringArray(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (!Array.isArray(value)) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be an array of non-empty strings, got " + typeof value,
+           "validate-opts/bad-string-array");
+  }
+  for (var i = 0; i < value.length; i += 1) {
+    if (typeof value[i] !== "string" || value[i].length === 0) {
+      _throw(errorClass, code, (label || "opt") +
+             "[" + i + "] must be a non-empty string",
+             "validate-opts/bad-string-array-element");
+    }
+  }
+  return value;
+}
+
+// optionalObjectWithMethod — required-shape validator for optional opts
+// that accept a "duck-typed handle": an object that exposes a specific
+// method. Replaces the recurring `if (opts.X !== undefined && opts.X !==
+// null) { if (typeof opts.X !== "object" || typeof opts.X.method !==
+// "function") throw ... }` cascade shared by file-upload (permissions),
+// notify (queue), seeders (db), webhook (nonceStore), and others.
+//
+// undefined / null → returns the value unchanged (caller can default).
+// non-object OR missing method → throws via errorClass with the operator-
+// facing description (e.g. "must be a b.permissions instance (check fn)").
+function optionalObjectWithMethod(value, method, label, errorClass, code, description) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "object" || typeof value[method] !== "function") {
+    _throw(errorClass, code, (label || "opt") + " " +
+           (description || ("must expose " + method + "() method")),
+           "validate-opts/bad-shaped-handle");
+  }
+  return value;
+}
+
 // makeAuditEmitter — closure factory parallel to safeAsync.makeDropCallback.
 // Replaces the per-file `function _emit(action, info) { if (!audit) return;
 // try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
@@ -263,6 +310,8 @@ module.exports.optionalFiniteNonNegative = optionalFiniteNonNegative;
 module.exports.optionalPositiveFinite = optionalPositiveFinite;
 module.exports.optionalFunction = optionalFunction;
 module.exports.optionalNonEmptyString = optionalNonEmptyString;
+module.exports.optionalNonEmptyStringArray = optionalNonEmptyStringArray;
+module.exports.optionalObjectWithMethod = optionalObjectWithMethod;
 module.exports.requireNonEmptyString = requireNonEmptyString;
 module.exports.observabilityShape = observabilityShape;
 module.exports.requireObject = requireObject;

package/lib/webhook.js

@@ -408,12 +408,9 @@ function _validateVerifierOpts(opts) {
   validateOpts.optionalFiniteNonNegative(opts.toleranceMs, "webhook.verifier: toleranceMs", WebhookError);
   validateOpts.optionalFiniteNonNegative(opts.clockSkewMs, "webhook.verifier: clockSkewMs", WebhookError);
   validateOpts.optionalNonEmptyString(opts.signatureHeader, "webhook.verifier: signatureHeader", WebhookError);
-  if (opts.nonceStore !== undefined && opts.nonceStore !== null) {
-    if (typeof opts.nonceStore !== "object" ||
-        typeof opts.nonceStore.checkAndInsert !== "function") {
-      throw _err("BAD_OPT", "webhook.verifier: nonceStore must implement checkAndInsert(nonce, expireAt)");
-    }
-  }
+  validateOpts.optionalObjectWithMethod(opts.nonceStore, "checkAndInsert",
+    "webhook.verifier: nonceStore", WebhookError, "BAD_OPT",
+    "must implement checkAndInsert(nonce, expireAt)");
   validateOpts.optionalFunction(opts.now, "webhook.verifier: now", WebhookError);
   validateOpts.auditShape(opts.audit, "webhook.verifier", WebhookError);
   validateOpts.optionalBoolean(opts.auditFailures, "webhook.verifier: auditFailures", WebhookError);

package/lib/websocket.js

@@ -94,9 +94,20 @@ var { boot } = require("./log");
 var HTTP = requestHelpers.HTTP_STATUS;
 var log = boot("websocket");
 
-// RFC 6455 §1.3
+// RFC 6455 §1.3 — the standard handshake GUID. Operators running
+// closed-ecosystem clients with a custom magic string pass their own
+// via opts.handshakeGuid on the route; the framework's default stays
+// the RFC value so RFC-compliant clients work out of the box.
 var GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 
+// UUID-shape (8-4-4-4-12 hex) for opts.handshakeGuid validation. The
+// SHA-1 used in the handshake is NOT a security primitive (RFC 6455
+// requires it as a protocol marker), so the GUID itself doesn't need
+// to be cryptographically random — but it must match the client's
+// expected value byte-for-byte. Length + format check at config time
+// catches the typo class.
+var GUID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+
 var OPCODE_CONTINUATION = 0x0;
 var OPCODE_TEXT         = 0x1;
 var OPCODE_BINARY       = 0x2;
@@ -165,11 +176,13 @@ class WebSocketError extends FrameworkError {
 
 // ---- Handshake helpers ----
 
-function computeAcceptKey(secWebSocketKey) {
+function computeAcceptKey(secWebSocketKey, handshakeGuid) {
   // SHA-1 required by RFC 6455 §1.3 — see file-level note 2 above.
   // This is a protocol marker, not a security primitive.
+  // handshakeGuid defaults to the RFC value; operators with custom
+  // closed-ecosystem clients override per-route via opts.handshakeGuid.
   var hash = nodeCrypto.createHash("sha1");
-  hash.update(String(secWebSocketKey) + GUID);
+  hash.update(String(secWebSocketKey) + (handshakeGuid || GUID));
   return hash.digest("base64");
 }
 
@@ -224,12 +237,12 @@ function isOriginAllowed(req, origins) {
   return false;
 }
 
-function buildUpgradeResponse(secWebSocketKey, subprotocol, extensionHeader) {
+function buildUpgradeResponse(secWebSocketKey, subprotocol, extensionHeader, handshakeGuid) {
   var lines = [
     "HTTP/1.1 101 Switching Protocols",
     "Upgrade: websocket",
     "Connection: Upgrade",
-    "Sec-WebSocket-Accept: " + computeAcceptKey(secWebSocketKey),
+    "Sec-WebSocket-Accept: " + computeAcceptKey(secWebSocketKey, handshakeGuid),
   ];
   if (subprotocol) lines.push("Sec-WebSocket-Protocol: " + subprotocol);
   if (extensionHeader) lines.push("Sec-WebSocket-Extensions: " + extensionHeader);
@@ -834,6 +847,25 @@ class WebSocketConnection extends EventEmitter {
 function handleUpgrade(req, socket, head, opts) {
   opts = opts || {};
 
+  // Throw-at-config-time on the optional GUID override. A typo here
+  // would produce a Sec-WebSocket-Accept the client can't match,
+  // breaking the upgrade in a way that's hard to diagnose; the format
+  // check at the top of handleUpgrade catches it loudly. Empty /
+  // undefined falls through to the RFC default in computeAcceptKey.
+  var GUID_MAX_LENGTH = C.BYTES.bytes(64); // allow:raw-byte-literal — UUID is 36 chars; 64 is a tolerant upper bound for the regex engine.
+  if (opts.handshakeGuid !== undefined && opts.handshakeGuid !== null) {
+    // Length cap before the regex test — UUIDs are exactly 36 chars so
+    // a > GUID_MAX_LENGTH input never matches the format and shouldn't
+    // reach the regex engine. Bounds the engine on hostile input
+    // regardless of the GUID_RE shape.
+    if (typeof opts.handshakeGuid !== "string" ||
+        opts.handshakeGuid.length > GUID_MAX_LENGTH ||
+        !GUID_RE.test(opts.handshakeGuid)) {
+      throw new Error("websocket.handleUpgrade: handshakeGuid must be a UUID-shaped string (8-4-4-4-12 hex with dashes), got " +
+        JSON.stringify(opts.handshakeGuid));
+    }
+  }
+
   // Validate handshake first — refusing here writes a plain HTTP/1.1
   // response and closes the socket, matching what the upgrade-event
   // consumer would expect for a malformed request.
@@ -865,7 +897,7 @@ function handleUpgrade(req, socket, head, opts) {
   try {
     socket.write(buildUpgradeResponse(
       req.headers["sec-websocket-key"], subprotocol,
-      pmd ? pmd.responseHeader : null));
+      pmd ? pmd.responseHeader : null, opts.handshakeGuid));
   } catch (err) {
     log.error("failed to write upgrade response: " + err.message);
     try { socket.destroy(); } catch (_e) { /* socket already destroyed */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.0",
+  "version": "0.7.4",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:4a5334cd-4c53-4ca4-abf6-713bbb9cfef6",
+  "serialNumber": "urn:uuid:ddc45497-46e6-4b4b-94ee-8cb0849c82cd",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-04T02:46:52.648Z",
+    "timestamp": "2026-05-04T16:54:01.026Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.0",
+      "bom-ref": "@blamejs/core@0.7.4",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.0",
+      "version": "0.7.4",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.0",
+      "purl": "pkg:npm/%40blamejs/core@0.7.4",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.0",
+      "ref": "@blamejs/core@0.7.4",
       "dependsOn": []
     }
   ]