@blamejs/core 0.8.42 → 0.8.49

package/lib/safe-url.js

@@ -1,64 +1,186 @@
 "use strict";
 /**
- * URL-safe — validate URL scheme + shape against an allowlist.
- *
- * Per the framework's modernity stance: outbound network calls
- * REQUIRE TLS by default. Operators with internal cleartext
- * endpoints (development, behind-VPN services, internal mesh) opt in
- * explicitly via opts.allowedProtocols. The framework refuses to
- * silently drop bytes on the wire as cleartext.
- *
- * Public API:
- *
- *   safeUrl.parse(url, opts?) → URL
- *     Returns a parsed URL object. Throws if the URL is malformed
- *     or its protocol is not in the allowlist.
- *
- *   opts:
- *     allowedProtocols  — array of accepted protocol strings
- *                         (e.g. ["https:"] or safeUrl.ALLOW_HTTP_TLS).
- *                         Default: ALLOW_HTTP_TLS.
- *     errorClass        — FrameworkError subclass for the thrown
- *                         error. Lets callers (object-store,
- *                         log-stream, http-client) surface their
- *                         own decorated error class. Default:
- *                         SafeUrlError.
- *     allowUserinfo     — accept URLs that carry user:pass@ credentials
- *                         in the authority. Default: false. Userinfo in
- *                         outbound URLs leaks into request logs, error
- *                         messages, metric labels, and trace spans;
- *                         credential placement belongs in headers /
- *                         cookies / a credential store, not the URL.
- *                         Operators with a legacy endpoint that
- *                         REQUIRES userinfo opt in explicitly per call.
- *
- * Constants — pre-baked allowlists for the common caller cases:
- *
- *   ALLOW_HTTP_TLS   ["https:"]                       (the secure HTTP default)
- *   ALLOW_HTTP_ALL   ["http:", "https:"]              (HTTP + cleartext opt-in)
- *   ALLOW_WS_TLS     ["wss:"]                         (the secure WS default)
- *   ALLOW_WS_ALL     ["ws:", "wss:"]                  (WS + cleartext opt-in)
- *   ALLOW_ANY        ["http:", "https:", "ws:", "wss:"]
- *
- * Why per-call constants instead of one global "secure" list:
- *   The http-client only speaks HTTP, so wss:// is a category error
- *   (operator passed a WebSocket URL to a non-WebSocket client). Each
- *   caller declares its own narrow allowlist; an off-protocol URL
- *   fails with a clear "protocol not allowed here" error rather than
- *   trying and failing weirdly later.
+ * @module b.safeUrl
+ * @nav    Validation
+ * @title  Safe Url
+ *
+ * @intro
+ *   Defensive URL parsing with a protocol allowlist (HTTPS-only by
+ *   default), authority validation, IDN-homograph defense, and a
+ *   length cap that runs BEFORE Node's WHATWG URL parser sees the
+ *   input. The framework's stance on outbound URLs: TLS-required by
+ *   default; cleartext (`http:` / `ws:`) is opt-in per call via
+ *   `opts.allowedProtocols`. `user:pass@` userinfo refuses by
+ *   default — credentials belong in headers / a credential store,
+ *   not in URL strings that leak into request logs, error messages,
+ *   metric labels, and trace spans. Mixed-script host labels
+ *   (Cyrillic 'о' inside an otherwise-Latin label, etc. — UTS #39 §5
+ *   homograph shape) refuse by default and emit
+ *   `safeurl.idn_homograph.refused` to the audit chain so a forensic
+ *   review can reconstruct every accepted host.
+ *
+ *   Pre-baked protocol allowlists are exposed as frozen arrays so
+ *   each caller can declare a NARROW per-call allowlist (the
+ *   http-client speaks HTTP, not WebSocket; a `wss://` URL handed to
+ *   it is a category error that should fail loudly here, not later
+ *   inside a transport):
+ *
+ *     ALLOW_HTTP_TLS   ["https:"]                        (secure HTTP default)
+ *     ALLOW_HTTP_ALL   ["http:", "https:"]               (HTTP + cleartext opt-in)
+ *     ALLOW_WS_TLS     ["wss:"]                          (secure WS default)
+ *     ALLOW_WS_ALL     ["ws:", "wss:"]                   (WS + cleartext opt-in)
+ *     ALLOW_ANY        ["http:", "https:", "ws:", "wss:"]
+ *
+ *   `parse` throws `SafeUrlError` (or a caller-supplied error class
+ *   via `opts.errorClass`, used by `b.objectStore` / `b.logStream` /
+ *   `b.httpClient` to surface their own decorated error type) with a
+ *   stable `.code`: `safe-url/missing` / `safe-url/too-long` /
+ *   `safe-url/malformed` / `safe-url/protocol-disallowed` /
+ *   `safe-url/userinfo-disallowed` / `safe-url/idn-homograph` /
+ *   `safe-url/bad-opt`. Operator code that wants a boolean
+ *   parse-without-throw shape wraps the throw in a try / catch.
+ *
+ * @card
+ *   Defensive URL parsing with a protocol allowlist (HTTPS-only by default), authority validation, IDN-homograph defense, and a length cap that runs BEFORE Node's WHATWG URL parser sees the input.
  */
 
 var C = require("./constants");
+var codepointClass = require("./codepoint-class");
+var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var { FrameworkError } = require("./framework-error");
+var nodeUrl = require("url");
 var { URL } = require("url");
 
+var audit = lazyRequire(function () { return require("./audit"); });
+
+/**
+ * @primitive b.safeUrl.ALLOW_HTTP_TLS
+ * @signature b.safeUrl.ALLOW_HTTP_TLS
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse, b.safeUrl.ALLOW_HTTP_ALL
+ *
+ * Frozen protocol allowlist for HTTPS-only HTTP traffic — `["https:"]`.
+ * The framework default for any outbound URL parsed without an
+ * explicit `opts.allowedProtocols`. Operators with a legitimate
+ * cleartext use case opt in per call via `ALLOW_HTTP_ALL`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeUrl.ALLOW_HTTP_TLS;
+ *   // → ["https:"]
+ */
 var ALLOW_HTTP_TLS = Object.freeze(["https:"]);
+
+/**
+ * @primitive b.safeUrl.ALLOW_HTTP_ALL
+ * @signature b.safeUrl.ALLOW_HTTP_ALL
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse, b.safeUrl.ALLOW_HTTP_TLS
+ *
+ * Frozen protocol allowlist accepting both HTTP and HTTPS —
+ * `["http:", "https:"]`. Pass to `parse` when the call site
+ * legitimately speaks cleartext (loopback admin endpoints, on-prem
+ * service mesh terminating TLS at a sidecar, legacy partner APIs).
+ * Never the framework default — TLS-required is.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var u = b.safeUrl.parse("http://127.0.0.1:8080/health", {
+ *     allowedProtocols: b.safeUrl.ALLOW_HTTP_ALL,
+ *   });
+ *   u.protocol;
+ *   // → "http:"
+ */
 var ALLOW_HTTP_ALL = Object.freeze(["http:", "https:"]);
+
+/**
+ * @primitive b.safeUrl.ALLOW_WS_TLS
+ * @signature b.safeUrl.ALLOW_WS_TLS
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse, b.safeUrl.ALLOW_WS_ALL
+ *
+ * Frozen protocol allowlist for secure WebSocket traffic — `["wss:"]`.
+ * The framework default for any WebSocket URL parsed without an
+ * explicit `opts.allowedProtocols`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeUrl.ALLOW_WS_TLS;
+ *   // → ["wss:"]
+ */
 var ALLOW_WS_TLS   = Object.freeze(["wss:"]);
+
+/**
+ * @primitive b.safeUrl.ALLOW_WS_ALL
+ * @signature b.safeUrl.ALLOW_WS_ALL
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse, b.safeUrl.ALLOW_WS_TLS
+ *
+ * Frozen protocol allowlist accepting both `ws:` and `wss:` —
+ * `["ws:", "wss:"]`. Opt-in per call when cleartext WebSocket is
+ * acceptable (loopback dev, sidecar-terminated TLS).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var u = b.safeUrl.parse("ws://127.0.0.1:9000/stream", {
+ *     allowedProtocols: b.safeUrl.ALLOW_WS_ALL,
+ *   });
+ *   u.protocol;
+ *   // → "ws:"
+ */
 var ALLOW_WS_ALL   = Object.freeze(["ws:", "wss:"]);
+
+/**
+ * @primitive b.safeUrl.ALLOW_ANY
+ * @signature b.safeUrl.ALLOW_ANY
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse, b.safeUrl.ALLOW_HTTP_TLS
+ *
+ * Frozen allowlist accepting every framework-supported scheme —
+ * `["http:", "https:", "ws:", "wss:"]`. Suited to a generic
+ * URL-validation surface where the caller already enforces the
+ * protocol downstream; narrower allowlists are preferred wherever
+ * possible.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeUrl.ALLOW_ANY.length;
+ *   // → 4
+ */
 var ALLOW_ANY      = Object.freeze(["http:", "https:", "ws:", "wss:"]);
 
+/**
+ * @primitive b.safeUrl.SafeUrlError
+ * @signature b.safeUrl.SafeUrlError
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.parse
+ *
+ * Error class thrown by `parse` (or by the caller-supplied
+ * `opts.errorClass`, used by `b.objectStore` / `b.logStream` /
+ * `b.httpClient` to surface a decorated operational error type).
+ * Extends `FrameworkError`. Carries a stable `.code`:
+ * `safe-url/missing` / `safe-url/too-long` / `safe-url/malformed` /
+ * `safe-url/protocol-disallowed` / `safe-url/userinfo-disallowed` /
+ * `safe-url/idn-homograph` / `safe-url/bad-opt`. HTTP middleware
+ * inspects `.code` to translate the throw into a 400 without
+ * leaking parser internals.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   try {
+ *     b.safeUrl.parse("ftp://example.com/file.txt");
+ *   } catch (e) {
+ *     e instanceof b.safeUrl.SafeUrlError;   // → true
+ *     e.code;                                // → "safe-url/protocol-disallowed"
+ *   }
+ */
 class SafeUrlError extends FrameworkError {
   constructor(code, message) {
     super(message, code);
@@ -83,6 +205,71 @@ function _makeError(errorClass, code, message) {
 // payloads) override via opts.maxUrlLength.
 var DEFAULT_MAX_URL_LENGTH = C.BYTES.kib(8);
 
+/**
+ * @primitive b.safeUrl.parse
+ * @signature b.safeUrl.parse(url, opts?)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeUrl.SafeUrlError, b.safeUrl.ALLOW_HTTP_TLS, b.safeUrl.ALLOW_HTTP_ALL
+ *
+ * Parse a URL string (or an existing `URL` instance) through the
+ * framework's defensive gates: length cap BEFORE Node's WHATWG parser
+ * sees the input (RFC 7230 §3.1.1 — 8 KiB default), protocol
+ * allowlist (`https:` only by default), `user:pass@` userinfo refusal
+ * (credentials leak into request logs / error messages / metric
+ * labels / trace spans), and per-label IDN-homograph defense
+ * (UTS #39 §5 mixed-script — Cyrillic 'о' inside an otherwise-Latin
+ * label). Returns the parsed `URL` instance on success.
+ *
+ * Throws `SafeUrlError` (or the caller-supplied `opts.errorClass`)
+ * with one of the documented `.code` strings: `safe-url/missing` /
+ * `safe-url/too-long` / `safe-url/malformed` /
+ * `safe-url/protocol-disallowed` / `safe-url/userinfo-disallowed` /
+ * `safe-url/idn-homograph` / `safe-url/bad-opt`. Operator code that
+ * wants a boolean parse-without-throw shape wraps the call in a
+ * `try` / `catch`.
+ *
+ * @opts
+ *   allowedProtocols: string[],   // default ALLOW_HTTP_TLS (["https:"])
+ *   maxUrlLength:     number,     // default 8192 (RFC 7230 §3.1.1)
+ *   allowUserinfo:    boolean,    // default false; opt-in to user:pass@
+ *   allowMixedScript: boolean,    // default false; opt-in to mixed-script labels
+ *   allowedScripts:   string[],   // narrow mixed-script allowlist (e.g. ["latin","cyrillic"])
+ *   errorClass:       Function,   // throw this instead of SafeUrlError (used by b.httpClient / b.objectStore)
+ *
+ * @example
+ *   var b = require("blamejs");
+ *
+ *   // Default: HTTPS-only, length cap, userinfo refused, IDN-homograph defended.
+ *   var u = b.safeUrl.parse("https://example.com/path?q=1");
+ *   u.hostname;
+ *   // → "example.com"
+ *
+ *   // Cleartext is opt-in per call via the ALLOW_HTTP_ALL preset.
+ *   var http = b.safeUrl.parse("http://127.0.0.1:8080/health", {
+ *     allowedProtocols: b.safeUrl.ALLOW_HTTP_ALL,
+ *   });
+ *   http.protocol;
+ *   // → "http:"
+ *
+ *   // Disallowed protocol throws SafeUrlError.
+ *   try { b.safeUrl.parse("javascript:alert(1)"); }
+ *   catch (e) { e.code; }
+ *   // → "safe-url/protocol-disallowed"
+ *
+ *   // Userinfo refused by default — credentials belong in headers.
+ *   try { b.safeUrl.parse("https://alice:s3cr3t@example.com/"); }
+ *   catch (e) { e.code; }
+ *   // → "safe-url/userinfo-disallowed"
+ *
+ *   // Boolean parse-without-throw shape via try/catch wrapper.
+ *   function isValid(s) {
+ *     try { b.safeUrl.parse(s); return true; }
+ *     catch (_e) { return false; }
+ *   }
+ *   isValid("https://example.com/");   // → true
+ *   isValid("ftp://example.com/");     // → false
+ */
 function parse(url, opts) {
   opts = opts || {};
   var allowed = Array.isArray(opts.allowedProtocols) && opts.allowedProtocols.length > 0
@@ -145,6 +332,51 @@ function parse(url, opts) {
       "reads at call time), or pass opts.allowUserinfo: true to opt this URL in.");
   }
 
+  // IDN homograph defense — each host label MUST be single-script
+  // (UTS #39 §5). A label that mixes Cyrillic + Latin (e.g. `gооgle.com`
+  // with Cyrillic 'о' inside the otherwise-Latin label) presents
+  // visually as a trusted host while resolving via DNS to attacker-
+  // controlled infrastructure. Defaults to refuse; operators with
+  // legitimate non-Latin host labels opt in via `allowMixedScript: true`
+  // and the opt-in audits with the host so a forensic review can
+  // reconstruct which call sites accept mixed-script hosts. Per-label
+  // detection (not whole-host) so a legitimate `eu.shop.example.org`
+  // mixing Latin + Cyrillic across labels still refuses. Node's URL
+  // parser normalizes IDN hosts to Punycode (`xn--`), so we decode each
+  // label to Unicode first via nodeUrl.domainToUnicode and run the
+  // mixed-script catalog on the decoded codepoints.
+  if (opts.allowMixedScript !== true && parsed.hostname) {
+    var unicodeHost;
+    try { unicodeHost = nodeUrl.domainToUnicode(parsed.hostname); }
+    catch (_e) { unicodeHost = parsed.hostname; }
+    var labels = (unicodeHost || parsed.hostname).split(".");
+    var allowedScripts = Array.isArray(opts.allowedScripts) ? opts.allowedScripts : null;
+    for (var li = 0; li < labels.length; li += 1) {
+      var label = labels[li];
+      if (label.length === 0) continue;
+      var mixed = codepointClass.detectMixedScripts(label, allowedScripts);
+      if (mixed) {
+        try {
+          audit().safeEmit({
+            action:  "safeurl.idn_homograph.refused",
+            outcome: "denied",
+            metadata: {
+              host:    parsed.hostname,
+              label:   label,
+              scripts: mixed,
+            },
+          });
+        } catch (_e) { /* audit best-effort */ }
+        throw _makeError(errClass, "safe-url/idn-homograph",
+          "URL host label '" + label + "' mixes scripts (" + mixed.join(", ") +
+          ") — IDN homograph attack shape (UTS #39 §5). Refuses by default; " +
+          "operators with a legitimate mixed-script host pass " +
+          "opts.allowMixedScript: true (with an audited reason) or " +
+          "opts.allowedScripts: ['latin','cyrillic'] to allowlist specific scripts.");
+      }
+    }
+  }
+
   return parsed;
 }
 

package/lib/sandbox-worker.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * sandbox-worker — bootstrap module loaded inside the worker_threads
+ * Worker spawned by lib/sandbox.js. Runs UNTRUSTED operator-supplied
+ * source against a pre-stripped global scope.
+ *
+ * NOT operator-facing — operators interact via b.sandbox.run().
+ *
+ * Wire format:
+ *   workerData: {
+ *     source:          string,    // operator-supplied JS — function body
+ *     input:           any,       // pass-through input
+ *     allowedGlobals:  string[],  // intersected with KNOWN_SAFE_BUILTINS
+ *     maxResultBytes:  number,    // hard-cap on JSON.stringify(result)
+ *   }
+ *
+ * Posts back via parentPort:
+ *   { ok: true,  resultJson, runtimeMs, peakBytes }
+ *   { ok: false, code, message, runtimeMs, peakBytes }
+ *
+ * Containment summary:
+ *   - require / process / Buffer / setTimeout / setInterval / setImmediate /
+ *     queueMicrotask / global are deleted off globalThis before the
+ *     operator code is compiled.
+ *   - The operator source is compiled via the JS language's
+ *     string-to-callable primitive — the compiled function's outer
+ *     scope is GLOBAL (stripped) and CANNOT see the bootstrap's
+ *     own locals (require, workerThreads, parentPort).
+ *   - Resource limits (maxOldGenerationSizeMb / maxYoungGenerationSizeMb /
+ *     codeRangeSizeMb / stackSizeMb) are set by the host on Worker
+ *     construction; v8 kills the worker on heap overflow.
+ *   - Output is JSON-serialized; the worker refuses any result whose
+ *     stringified form exceeds maxResultBytes.
+ */
+
+var workerThreads = require("node:worker_threads");
+
+(function () {
+  var data = workerThreads.workerData || {};
+  var allowed = Array.isArray(data.allowedGlobals) ? data.allowedGlobals : [];
+  var maxResultBytes = (typeof data.maxResultBytes === "number") ? data.maxResultBytes : null;
+
+  var ALWAYS_AVAILABLE = [
+    "Object", "Array", "String", "Number", "Boolean", "Symbol",
+    "Promise", "Error", "TypeError", "RangeError", "RegExp",
+  ];
+
+  var keep = Object.create(null);
+  for (var i = 0; i < ALWAYS_AVAILABLE.length; i += 1) keep[ALWAYS_AVAILABLE[i]] = true;
+  for (var j = 0; j < allowed.length; j += 1) keep[allowed[j]] = true;
+
+  var NODE_BUILTINS = [
+    "process", "Buffer",
+    "setImmediate", "clearImmediate",
+    "setTimeout", "clearTimeout",
+    "setInterval", "clearInterval",
+    "queueMicrotask",
+    "global",
+  ];
+  for (var k = 0; k < NODE_BUILTINS.length; k += 1) {
+    var nm = NODE_BUILTINS[k];
+    if (!keep[nm]) {
+      try { delete globalThis[nm]; }
+      catch (_e1) { try { globalThis[nm] = undefined; } catch (_e2) { /* best-effort */ } }
+    }
+  }
+
+  try { delete globalThis.require; } catch (_e) { /* best-effort */ }
+
+  var startedAt = Date.now();
+  var peakBytes = 0;
+
+  function snapshotPeak() {
+    try {
+      var proc = (typeof process !== "undefined") ? process : null;
+      if (proc && typeof proc.memoryUsage === "function") {
+        var u = proc.memoryUsage();
+        if (u && typeof u.heapUsed === "number" && u.heapUsed > peakBytes) peakBytes = u.heapUsed;
+      }
+    } catch (_e) { /* process gone or stripped */ }
+  }
+
+  snapshotPeak();
+
+  // Compile operator source via the JS language's string-to-callable
+  // primitive. The compiled function's outer scope is GLOBAL (already
+  // stripped above); it cannot see this bootstrap's own locals.
+  var Compiler = (function () { return Function; }());
+
+  var fn;
+  try {
+    fn = new Compiler("input", data.source);
+  } catch (eParse) {
+    workerThreads.parentPort.postMessage({
+      ok: false, code: "sandbox/parse-error",
+      message: "sandbox source did not parse: " + (eParse && eParse.message),
+      runtimeMs: Date.now() - startedAt, peakBytes: peakBytes,
+    });
+    return;
+  }
+
+  try {
+    var result = fn(data.input);
+    snapshotPeak();
+    var runtimeMs = Date.now() - startedAt;
+    var serialized;
+    try { serialized = (result === undefined) ? undefined : JSON.stringify(result); }
+    catch (eSer) {
+      workerThreads.parentPort.postMessage({
+        ok: false, code: "sandbox/result-not-serializable",
+        message: "sandbox result is not JSON-serializable: " + (eSer && eSer.message),
+        runtimeMs: runtimeMs, peakBytes: peakBytes,
+      });
+      return;
+    }
+    if (maxResultBytes !== null && serialized && serialized.length > maxResultBytes) {
+      workerThreads.parentPort.postMessage({
+        ok: false, code: "sandbox/oversized-result",
+        message: "sandbox result exceeded maxResultBytes (" + serialized.length + " > " + maxResultBytes + ")",
+        runtimeMs: runtimeMs, peakBytes: peakBytes,
+      });
+      return;
+    }
+    workerThreads.parentPort.postMessage({
+      ok: true, resultJson: serialized, runtimeMs: runtimeMs, peakBytes: peakBytes,
+    });
+  } catch (eRun) {
+    snapshotPeak();
+    workerThreads.parentPort.postMessage({
+      ok: false, code: "sandbox/runtime-error",
+      message: "sandbox transform threw: " + (eRun && eRun.message ? eRun.message : String(eRun)),
+      runtimeMs: Date.now() - startedAt, peakBytes: peakBytes,
+    });
+  }
+}());