machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/browser-broker-auth.mjs

@@ -0,0 +1,98 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+
+const CHALLENGE = /^[A-Za-z0-9_-]{32}$/;
+const PROOF = /^[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^[A-Za-z0-9_-]{32,100}$/;
+const AUTH_TTL_MS = 5_000;
+const MAX_PENDING_AUTH = 64;
+const ROLES = new Set(["extension", "runtime"]);
+
+export const BROKER_AUTH_REQUEST_HEADER = "x-machine-bridge-broker-auth";
+export const BROKER_AUTH_REQUEST_VALUE = "machine-bridge-browser-v2";
+
+export function createBrokerAuthChallenge() {
+  return randomBytes(24).toString("base64url");
+}
+
+export function createBrokerInitProof(token, role, clientChallenge) {
+  assertToken(token); assertRole(role);
+  if (!CHALLENGE.test(String(clientChallenge || ""))) throw new Error("browser broker authentication challenge is invalid");
+  return hmac(token, `machine-bridge-browser-${role}-init-v2\0${clientChallenge}`);
+}
+
+export function createBrokerServerProof(token, role, clientChallenge, serverNonce) {
+  return authProof(token, role, "server", clientChallenge, serverNonce);
+}
+
+export function verifyBrokerServerProof(token, role, clientChallenge, serverNonce, proof) {
+  if (!PROOF.test(String(proof || ""))) return false;
+  return safeEqual(createBrokerServerProof(token, role, clientChallenge, serverNonce), proof);
+}
+
+export function createBrokerClientProtocol(token, role, clientChallenge, serverNonce) {
+  assertRole(role);
+  const proof = authProof(token, role, "client", clientChallenge, serverNonce);
+  return `mbm-${role}-v2.${clientChallenge}.${serverNonce}.${proof}`;
+}
+
+export function createBrokerAuthRegistry(token, role, options = {}) {
+  assertToken(token);
+  assertRole(role);
+  const now = typeof options.now === "function" ? options.now : undefined;
+  const pending = new Map();
+  return {
+    issue(clientChallenge, initProof) {
+      if (!CHALLENGE.test(String(clientChallenge || "")) || !PROOF.test(String(initProof || ""))) return null;
+      if (!safeEqual(createBrokerInitProof(token, role, clientChallenge), initProof)) return null;
+      prunePending(pending);
+      const existing = pending.get(clientChallenge);
+      if (existing && !existing.deadline.expired()) {
+        return { serverNonce: existing.serverNonce, serverProof: createBrokerServerProof(token, role, clientChallenge, existing.serverNonce) };
+      }
+      while (pending.size >= MAX_PENDING_AUTH) pending.delete(pending.keys().next().value);
+      const serverNonce = createBrokerAuthChallenge();
+      pending.set(clientChallenge, { serverNonce, deadline: createMonotonicDeadline(AUTH_TTL_MS, now) });
+      return { serverNonce, serverProof: createBrokerServerProof(token, role, clientChallenge, serverNonce) };
+    },
+    consume(protocol) {
+      const parsed = parseBrokerProtocol(protocol, role);
+      if (!parsed) return false;
+      const issued = pending.get(parsed.clientChallenge);
+      pending.delete(parsed.clientChallenge);
+      if (!issued || issued.deadline.expired() || issued.serverNonce !== parsed.serverNonce) return false;
+      return safeEqual(createBrokerClientProtocol(token, role, parsed.clientChallenge, parsed.serverNonce), protocol);
+    },
+  };
+}
+
+export function parseBrokerAuthResponse(headers) {
+  const serverNonce = String(headers?.get?.("x-machine-bridge-broker-nonce") || "");
+  const serverProof = String(headers?.get?.("x-machine-bridge-broker-proof") || "");
+  return CHALLENGE.test(serverNonce) && PROOF.test(serverProof) ? { serverNonce, serverProof } : null;
+}
+
+function parseBrokerProtocol(value, role) {
+  const parts = String(value || "").split(".");
+  if (parts.length !== 4 || parts[0] !== `mbm-${role}-v2`) return null;
+  const [, clientChallenge, serverNonce, proof] = parts;
+  if (!CHALLENGE.test(clientChallenge) || !CHALLENGE.test(serverNonce) || !PROOF.test(proof)) return null;
+  return { clientChallenge, serverNonce };
+}
+
+function authProof(token, role, direction, clientChallenge, serverNonce) {
+  assertToken(token); assertRole(role);
+  if (!CHALLENGE.test(String(clientChallenge || "")) || !CHALLENGE.test(String(serverNonce || ""))) {
+    throw new Error("browser broker authentication challenge is invalid");
+  }
+  return hmac(token, `machine-bridge-browser-${role}-${direction}-v2\0${clientChallenge}\0${serverNonce}`);
+}
+
+function hmac(token, message) { return createHmac("sha256", token).update(message).digest("base64url"); }
+function assertToken(value) { if (!TOKEN.test(String(value || ""))) throw new Error("browser broker credential is invalid"); }
+function assertRole(value) { if (!ROLES.has(value)) throw new Error("browser broker authentication role is invalid"); }
+function safeEqual(left, right) {
+  const a = Buffer.from(String(left)); const b = Buffer.from(String(right));
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function prunePending(pending) { for (const [key, issued] of pending) if (issued.deadline.expired()) pending.delete(key); }

package/src/local/browser-broker-routes.mjs

@@ -1,18 +1,19 @@
 import { randomBytes } from "node:crypto";
 import { clampInt } from "./browser-command.mjs";
-import { closeProtocolSocket, parseBrowserSocketMessage, safeSocketSend } from "./browser-extension-protocol.mjs";
-
+import { browserPostDispatchTransportFailure, closeProtocolSocket, normalizeRuntimeBrowserRequest, parseBrowserSocketMessage, safeSocketSend } from "./browser-extension-protocol.mjs";
 export class BrowserBrokerRoutes {
-  constructor({ maximum, getExtensionSocket, extensionConnected, extensionStatusInfo, extensionReloadRequired }) {
+  constructor({ maximum, getExtensionSocket, extensionConnected, extensionStatusInfo, extensionReloadRequired, extensionGeneration = () => 0 }) {
     this.maximum = maximum;
     this.getExtensionSocket = getExtensionSocket;
     this.extensionConnected = extensionConnected;
     this.extensionStatusInfo = extensionStatusInfo;
-    this.extensionReloadRequired = extensionReloadRequired;
+    this.extensionReloadRequired = extensionReloadRequired; this.extensionGeneration = extensionGeneration;
     this.clients = new Set();
     this.routes = new Map();
   }
-
+  snapshot() {
+    return Object.freeze({ runtime_clients: this.clients.size, routed_requests: this.routes.size });
+  }
   acceptClient(socket) {
     this.clients.add(socket);
     socket.on("message", (data) => this.handleClientMessage(socket, data));
@@ -25,6 +26,7 @@ export class BrowserBrokerRoutes {
       extension_connected: this.extensionConnected(),
       extension_info: this.extensionStatusInfo(),
       extension_reload_required: this.extensionReloadRequired(),
+      extension_generation: this.extensionGeneration(),
     });
   }
 
@@ -44,16 +46,14 @@ export class BrowserBrokerRoutes {
       closeProtocolSocket(socket, parsed.code, parsed.reason);
       return;
     }
-    const message = parsed.message;
-    if (message.type === "ping") return;
-    if (message.type === "cancel" && typeof message.id === "string") {
-      this.cancelClientRequest(socket, message.id);
-      return;
-    }
-    if (message.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") {
-      closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
+    const incoming = parsed.message;
+    if (incoming.type === "ping") return;
+    if (incoming.type === "cancel" && typeof incoming.id === "string") {
+      this.cancelClientRequest(socket, incoming.id);
       return;
     }
+    const message = normalizeRuntimeBrowserRequest(incoming);
+    if (!message) { closeProtocolSocket(socket, 1002, "invalid runtime protocol message"); return; }
     if (!this.extensionConnected()) {
       safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
       return;
@@ -73,15 +73,24 @@ export class BrowserBrokerRoutes {
       const route = this.routes.get(routedId);
       if (!route) return;
       this.routes.delete(routedId);
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker request timed out" });
+      safeSocketSend(socket, {
+        type: "response", id: message.id, ok: false,
+        error: postDispatchRouteFailure(route, "browser broker request timed out"),
+      });
       this.sendExtension({ type: "cancel", id: routedId });
     }, timeoutMs);
     timeout.unref?.();
-    this.routes.set(routedId, { socket, id: message.id, timeout });
-    if (this.sendExtension({ ...message, id: routedId, timeout_ms: timeoutMs })) return;
+    const route = { socket, id: message.id, timeout, method: message.method, dispatchAttempted: false };
+    this.routes.set(routedId, route);
+    const send = this.sendExtensionRequest({ ...message, id: routedId, timeout_ms: timeoutMs });
+    route.dispatchAttempted = send.attempted;
+    if (send.ok) return;
     clearTimeout(timeout);
     this.routes.delete(routedId);
-    safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension send failed" });
+    safeSocketSend(socket, {
+      type: "response", id: message.id, ok: false,
+      error: postDispatchRouteFailure(route, "browser extension send failed"),
+    });
   }
 
   cancelClientRequest(socket, requestId) {
@@ -98,7 +107,16 @@ export class BrowserBrokerRoutes {
     if (!route) return false;
     clearTimeout(route.timeout);
     this.routes.delete(message.id);
-    safeSocketSend(route.socket, { ...message, id: route.id });
+    if (message.ok === true && message.result && typeof message.result === "object" && !Array.isArray(message.result)) {
+      safeSocketSend(route.socket, { type: "response", id: route.id, ok: true, result: message.result });
+    } else if (message.ok === false && typeof message.error === "string" && message.error && !message.error.includes("\0") && message.error.length <= 2000) {
+      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message.error });
+    } else {
+      safeSocketSend(route.socket, {
+        type: "response", id: route.id, ok: false,
+        error: postDispatchRouteFailure(route, "browser extension response was malformed"),
+      });
+    }
     return true;
   }
 
@@ -108,6 +126,7 @@ export class BrowserBrokerRoutes {
       extension_connected: connected,
       extension_info: connected ? this.extensionStatusInfo() : null,
       extension_reload_required: this.extensionReloadRequired(),
+      extension_generation: connected ? this.extensionGeneration() : 0,
     };
     for (const client of this.clients) safeSocketSend(client, message);
   }
@@ -115,7 +134,10 @@ export class BrowserBrokerRoutes {
   rejectAll(message) {
     for (const [id, route] of this.routes) {
       clearTimeout(route.timeout);
-      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message });
+      safeSocketSend(route.socket, {
+        type: "response", id: route.id, ok: false,
+        error: postDispatchRouteFailure(route, message),
+      });
       this.routes.delete(id);
     }
   }
@@ -123,7 +145,8 @@ export class BrowserBrokerRoutes {
   close(message) {
     this.rejectAll(message);
     for (const client of this.clients) {
-      try { client.close(1001, "runtime stopped"); } catch {}
+      try { client.close(1001, "runtime stopped"); }
+      catch { /* Runtime shutdown is already authoritative; a concurrently closed broker client needs no retry. */ }
     }
     this.clients.clear();
   }
@@ -133,4 +156,24 @@ export class BrowserBrokerRoutes {
     if (!socket || socket.readyState !== 1) return false;
     return safeSocketSend(socket, message);
   }
+
+  sendExtensionRequest(message) {
+    const socket = this.getExtensionSocket();
+    if (!socket || socket.readyState !== 1) return { ok: false, attempted: false };
+    let payload;
+    try { payload = JSON.stringify(message); }
+    catch { return { ok: false, attempted: false }; }
+    try {
+      socket.send(payload);
+      return { ok: true, attempted: true };
+    } catch {
+      return { ok: false, attempted: true };
+    }
+  }
+}
+
+function postDispatchRouteFailure(route, fallback) {
+  return route?.dispatchAttempted
+    ? browserPostDispatchTransportFailure(route.method, fallback)
+    : String(fallback || "browser transport failed");
 }

package/src/local/browser-broker-server.mjs

@@ -1,9 +1,17 @@
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
-import { isAllowedExtensionOrigin, isAllowedLoopbackHost } from "./browser-pairing-store.mjs";
+import { isAllowedExtensionOrigin, isAllowedLoopbackHost } from "./browser-pairing-http.mjs";
+import { EXPECTED_EXTENSION_ID } from "./browser-extension-identity.mjs";
+import { createBrokerAuthRegistry } from "./browser-broker-auth.mjs";
+import { createBrowserBrokerAuthHttpHandler } from "./browser-broker-auth-http.mjs";
 
-export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp, onSocket }) {
-  const server = createServer(onHttp);
+export async function startBrowserBrokerServer({ port, extensionToken, runtimeToken, maxPayload, onHttp, onSocket }) {
+  const runtimeAuth = createBrokerAuthRegistry(runtimeToken, "runtime");
+  const extensionAuth = createBrokerAuthRegistry(extensionToken, "extension");
+  const handleAuthHttp = createBrowserBrokerAuthHttpHandler({ port, extensionToken, runtimeAuth, extensionAuth });
+  const server = createServer((request, response) => {
+    if (!handleAuthHttp(request, response)) onHttp(request, response);
+  });
   const wss = new WebSocketServer({ noServer: true, maxPayload });
   server.on("upgrade", (request, socket, head) => {
     try {
@@ -16,8 +24,8 @@ export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp
       const protocol = String(request.headers["sec-websocket-protocol"] || "");
       const origin = String(request.headers.origin || "");
       let role = "";
-      if (url.pathname === "/extension" && protocol === `mbm.${token}` && isAllowedExtensionOrigin(origin)) role = "extension";
-      if (url.pathname === "/runtime" && protocol === `mbm-runtime.${token}` && !origin) role = "runtime";
+      if (url.pathname === "/extension" && isAllowedExtensionOrigin(origin, EXPECTED_EXTENSION_ID) && extensionAuth.consume(protocol)) role = "extension";
+      if (url.pathname === "/runtime" && !origin && runtimeAuth.consume(protocol)) role = "runtime";
       if (!role) {
         rejectUpgrade(socket, "401 Unauthorized");
         return;
@@ -38,8 +46,10 @@ export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp
     };
     const onError = (error) => {
       cleanup();
-      try { wss.close(); } catch {}
-      try { server.close(); } catch {}
+      try { wss.close(); }
+      catch { /* Startup failure already owns the result; closing an unopened/half-open WebSocket server is best-effort. */ }
+      try { server.close(); }
+      catch { /* Startup failure already owns the result; closing an unopened/half-open HTTP server is best-effort. */ }
       rejectPromise(error);
     };
     const onListening = () => {

package/src/local/browser-command.mjs

@@ -1,3 +1,5 @@
+import { BridgeError } from "./errors.mjs";
+
 const NAVIGATION_ACTIONS = new Set(["navigate", "reload", "back", "forward"]);
 const PAGE_ACTIONS = new Set([
   "click", "double_click", "hover", "fill", "type_text", "select", "check", "uncheck",
@@ -7,17 +9,37 @@ const FORM_ACTIONS = new Set(["fill", "select", "check", "uncheck", "click"]);
 const WAIT_STATES = new Set(["attached", "detached", "visible", "hidden", "enabled", "editable", "checked", "unchecked"]);
 const LOAD_STATES = new Set(["domcontentloaded", "complete"]);
 const INPUT_MODES = new Set(["auto", "trusted", "dom"]);
+const SNAPSHOT_IDENTITY_STRING_FIELDS = Object.freeze([
+  "tag", "type", "role", "name", "id", "field_name", "label", "placeholder", "href",
+]);
+const SNAPSHOT_IDENTITY_BOOLEAN_FIELDS = Object.freeze(["sensitive", "in_shadow_dom"]);
 
 export function normalizeBrowserAction(value) {
-  const action = String(value || "").trim();
-  if (!NAVIGATION_ACTIONS.has(action) && !PAGE_ACTIONS.has(action)) throw new Error("unsupported browser action");
-  return action;
+  if (typeof value !== "string" || (!NAVIGATION_ACTIONS.has(value) && !PAGE_ACTIONS.has(value))) throw new Error("unsupported browser action");
+  return value;
+}
+
+export function browserPairingLaunchCommand(url, platform = process.platform) {
+  if (platform === "darwin") return { cmd: "open", argv: [url] };
+  if (platform === "win32") return { cmd: "cmd.exe", argv: ["/d", "/s", "/c", "start", "", url] };
+  return { cmd: "xdg-open", argv: [url] };
+}
+
+export function browserPairingLaunchUnknown() {
+  return new BridgeError("execution_failed", "browser pairing page may have been opened; the launch outcome is unknown. Inspect the browser before retrying.", {
+    expose: true, retryable: false,
+  });
+}
+
+export function browserPairingLaunchUnavailable() {
+  return new BridgeError("unavailable", "browser pairing launcher unavailable before dispatch", {
+    retryable: true, details: { reason: "browser_pairing_launcher_unavailable_before_dispatch" },
+  });
 }
 
 export function normalizeFormAction(value) {
-  const action = String(value || "").trim();
-  if (!FORM_ACTIONS.has(action)) throw new Error("unsupported form field action");
-  return action;
+  if (typeof value !== "string" || !FORM_ACTIONS.has(value)) throw new Error("unsupported form field action");
+  return value;
 }
 
 export function normalizeBrowserSelector(value, action = "") {
@@ -42,29 +64,45 @@ export function normalizeBrowserSelector(value, action = "") {
 }
 
 export function normalizeInputMode(value) {
-  if (value === undefined || value === null || value === "") return "auto";
-  const mode = String(value);
-  if (!INPUT_MODES.has(mode)) throw new Error("input_mode must be auto, trusted, or dom");
-  return mode;
+  if (value === undefined) return "auto";
+  if (typeof value !== "string" || !INPUT_MODES.has(value)) throw new Error("input_mode must be auto, trusted, or dom");
+  return value;
+}
+
+export function normalizeBrowserSnapshotIdentity(value) {
+  if (value === undefined || value === null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected_ref_identity must be an object");
+  const allowed = new Set([...SNAPSHOT_IDENTITY_STRING_FIELDS, ...SNAPSHOT_IDENTITY_BOOLEAN_FIELDS]);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`unknown expected_ref_identity field: ${key}`);
+  const output = {};
+  for (const key of SNAPSHOT_IDENTITY_STRING_FIELDS) {
+    if (!Object.hasOwn(value, key)) continue;
+    output[key] = optionalString(value[key], `expected_ref_identity.${key}`, key === "href" ? 8192 : 2000);
+  }
+  for (const key of SNAPSHOT_IDENTITY_BOOLEAN_FIELDS) {
+    if (!Object.hasOwn(value, key)) continue;
+    if (typeof value[key] !== "boolean") throw new Error(`expected_ref_identity.${key} must be a boolean`);
+    output[key] = value[key];
+  }
+  return Object.keys(output).length ? output : null;
 }
 
 export function normalizeNavigationWait(value) {
-  if (value === undefined || value === null || value === "") return "none";
-  const wait = String(value);
-  if (!["none", ...LOAD_STATES].includes(wait)) throw new Error("wait_for must be none, domcontentloaded, or complete");
-  return wait;
+  if (value === undefined) return "none";
+  if (typeof value !== "string" || !["none", ...LOAD_STATES].includes(value)) throw new Error("wait_for must be none, domcontentloaded, or complete");
+  return value;
 }
 
 export function normalizeBrowserWait(args = {}) {
   const selector = args.selector === undefined ? null : normalizeBrowserSelector(args.selector, "wait");
-  const state = args.state === undefined || args.state === null || args.state === ""
-    ? (selector ? "visible" : "")
-    : String(args.state);
+  const state = args.state === undefined ? (selector ? "visible" : "") : args.state;
+  if (typeof state !== "string") throw new Error("state is not a supported browser wait state");
   if (state && !WAIT_STATES.has(state)) throw new Error("state is not a supported browser wait state");
   if (state && !selector) throw new Error("state requires selector");
   const text = optionalString(args.text, "text", 4000);
   const urlContains = optionalString(args.url_contains, "url_contains", 32768);
-  const loadState = args.load_state === undefined || args.load_state === null || args.load_state === "" ? "" : String(args.load_state);
+  const loadState = args.load_state === undefined ? "" : args.load_state;
+  if (typeof loadState !== "string") throw new Error("load_state must be domcontentloaded or complete");
   if (loadState && !LOAD_STATES.has(loadState)) throw new Error("load_state must be domcontentloaded or complete");
   if (!selector && !text && !urlContains && !loadState) throw new Error("browser_wait requires selector, text, url_contains, or load_state");
   const timeoutSeconds = clampInt(args.timeout_seconds, 30, 1, 120);
@@ -81,12 +119,13 @@ export function normalizeBrowserWait(args = {}) {
 }
 
 export function normalizeTabCommand(args = {}) {
-  const action = String(args.action || "").trim();
-  if (!["new", "activate", "close"].includes(action)) throw new Error("browser tab action must be new, activate, or close");
+  const action = args.action;
+  if (typeof action !== "string" || !["new", "activate", "close"].includes(action)) throw new Error("browser tab action must be new, activate, or close");
   const tabId = optionalInteger(args.tab_id, "tab_id", 1, Number.MAX_SAFE_INTEGER);
   const rawUrl = optionalString(args.url, "url", 32768);
   if (["activate", "close"].includes(action) && !tabId) throw new Error(`${action} requires tab_id`);
   if (action !== "new" && rawUrl) throw new Error("url is only valid for new tabs");
+  if (args.active !== undefined && typeof args.active !== "boolean") throw new Error("active must be boolean");
   return {
     action,
     tabId,
@@ -96,15 +135,27 @@ export function normalizeTabCommand(args = {}) {
 }
 
 export function validateNavigationUrl(value) {
-  if (!value) throw new Error("navigate requires url");
+  if (typeof value !== "string" || !value) throw new Error("navigate requires url");
   let parsed;
   try { parsed = new URL(value); } catch { throw new Error("url must be an absolute URL"); }
   if (!["http:", "https:", "file:"].includes(parsed.protocol)) throw new Error("url protocol must be http, https, or file");
   return parsed.href;
 }
 
+export function optionalBoolean(value, label, fallback) {
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") throw new Error(`${label} must be boolean`);
+  return value;
+}
+
+export function normalizeImageFormat(value, label = "format") {
+  if (value === undefined) return "png";
+  if (typeof value !== "string" || !["png", "jpeg"].includes(value)) throw new Error(`${label} must be png or jpeg`);
+  return value;
+}
+
 export function optionalString(value, label, maxLength) {
-  if (value === undefined || value === null || value === "") return "";
+  if (value === undefined) return "";
   if (typeof value !== "string" || value.includes("\0") || value.length > maxLength) {
     throw new Error(`${label} must be a string of at most ${maxLength} characters without NUL bytes`);
   }
@@ -112,15 +163,13 @@ export function optionalString(value, label, maxLength) {
 }
 
 export function optionalInteger(value, label, min, max) {
-  if (value === undefined || value === null || value === "") return null;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
-  return number;
+  if (value === undefined) return null;
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  return value;
 }
 
 export function clampInt(value, fallback, min, max) {
-  if (value === undefined || value === null || value === "") return fallback;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new Error(`expected an integer from ${min} to ${max}`);
-  return number;
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`expected an integer from ${min} to ${max}`);
+  return value;
 }