@nivalos/lithium.js 1.1.0

package/client/index.js

@@ -0,0 +1,359 @@
+// lithium client
+// Load with <script type="module"> (or import it). It pulls in whatever
+// proxy scripts it needs by itself, no extra <script> tags required.
+//
+//   import { init_lithium, navigate, back, on, config } from "/client/index.js"
+//   await init_lithium({ searchEngine: "google" })
+//   on("navigate", ({ url }) => console.log("now at", url))
+//   navigate("example.com")
+
+import * as net from "./net.js"
+
+// the server injects this into your html (see server/index.js)
+const server_config = () => (typeof window !== "undefined" && window.__LITHIUM_CONFIG__) || {}
+
+const state = {
+  proxy: null,
+  transport: null,
+  iface: null,
+  ready: false,
+  url: "", // last real URL the proxied page reported
+  search_engine: "google",
+  backend: null,
+  ctx: null,
+  poller: null,
+  unsubs: [], // listeners created from init_lithium's options
+  debug: false,
+  header_policy: { ...net.DEFAULT_POLICY },
+  network: [], // capped log of {method, url, status, ...}, see net.js
+}
+const NETWORK_LOG_CAP = 300
+
+function dbg(...args) {
+  if (state.debug) console.log("[lithium debug]", ...args)
+}
+
+// window errors are useful in debug mode but easy to miss otherwise; this
+// listens once at module load and checks state.debug live, so it works
+// across re-init without adding/removing listeners each time
+if (typeof window !== "undefined") {
+  window.addEventListener("error", (e) => { if (state.debug) console.error("[lithium debug] window error:", e.error ?? e.message) })
+  window.addEventListener("unhandledrejection", (e) => { if (state.debug) console.error("[lithium debug] unhandled rejection:", e.reason) })
+}
+
+// ------------------------------------------------------------------ events --
+// "ready"     () once init_lithium finished
+// "navigate"  ({ url, previousUrl }) whenever the proxied page changes URL,
+//             for every proxy
+const listeners = new Map()
+
+export function on(event, callback) {
+  if (typeof callback !== "function") throw new TypeError("[lithium] on(event, callback): callback must be a function")
+  if (!listeners.has(event)) listeners.set(event, new Set())
+  listeners.get(event).add(callback)
+  return () => off(event, callback) // handy: const stop = on(...); stop()
+}
+
+export function off(event, callback) {
+  listeners.get(event)?.delete(callback)
+}
+
+function emit(event, payload) {
+  for (const callback of [...(listeners.get(event) ?? [])]) {
+    try {
+      callback(payload)
+    } catch (err) {
+      console.error(`[lithium] a "${event}" listener threw:`, err)
+    }
+  }
+}
+
+function report_url(url) {
+  if (!url || url === state.url) return
+  const previousUrl = state.url
+  state.url = url
+  emit("navigate", { url, previousUrl })
+}
+
+// ------------------------------------------------------------------ config --
+// Read-only view of what the server started with, plus the search engine.
+export const config = {
+  get proxy() { return state.proxy ?? server_config().proxy ?? "ultraviolet" },
+  get transport() { return state.transport ?? server_config().transport ?? "epoxy" },
+  get interface() { return state.iface ?? server_config().interface ?? null },
+  get ready() { return state.ready },
+  get searchEngine() { return engine() },
+  set searchEngine(name) {
+    state.search_engine = name
+    localStorage.setItem("engine", name)
+  },
+  get debug() { return state.debug },
+  set debug(on) { state.debug = Boolean(on) },
+  // read-only snapshot (deep enough that mutating it can't affect live state);
+  // use set_header_policy() to change it live
+  get headers() { return { ...state.header_policy, block: [...state.header_policy.block], allow: state.header_policy.allow ? [...state.header_policy.allow] : null } },
+}
+
+// change the header policy without a full re-init (see net.js for what it can/can't do)
+export function set_header_policy(policy = {}) {
+  state.header_policy = { ...state.header_policy, ...policy }
+  dbg("header policy set:", state.header_policy)
+}
+
+// [{ type: "fetch"|"xhr", method, url, status, ok, duration, ts, requestHeaders, responseHeaders, blockedRequestHeaders, blockedResponseHeaders }, ...]
+// newest last, capped at 300 entries. See net.js for exactly what's covered.
+export function network_log() {
+  return [...state.network]
+}
+
+export function clear_network_log() {
+  state.network.length = 0
+}
+
+// read every time so a settings page can change it on the fly
+const engine = () => (typeof localStorage !== "undefined" && localStorage.getItem("engine")) || state.search_engine
+
+// -------------------------------------------------------------------- setup --
+// helper to load scripts dynamically
+function load_script(src) {
+  return new Promise((resolve, reject) => {
+    const script = document.createElement("script")
+    script.src = src
+    script.onload = resolve
+    script.onerror = () => reject(new Error(`failed to load ${src}`))
+    document.head.appendChild(script)
+  })
+}
+
+// The browser only says "script evaluation failed" when a service worker can't
+// start, which is nearly always an importScripts() that 404'd. Check every
+// file the worker imports and say which one is missing.
+async function diagnose_sw(proxy) {
+  const probe = async (path, note = "") => {
+    try {
+      const r = await fetch(path, { cache: "no-store" })
+      console.error(`[lithium]   ${r.status} ${path} (${r.headers.get("content-type")}) ${note}`)
+      return r
+    } catch (e) {
+      console.error(`[lithium]   failed ${path}: ${e.message}`)
+    }
+  }
+  console.error("[lithium] the service worker failed to start, checking the files it imports:")
+  if (proxy === "scramjet") {
+    await probe("/controller/controller.sw.js")
+    return
+  }
+  if (proxy !== "ultraviolet") {
+    await probe(`/sw.js?proxy=${proxy}`)
+    return
+  }
+  for (const p of ["/uv/uv.bundle.js", "/uv/uv.sw.js", "/uv/uv.handler.js", "/uv/uv.client.js"]) await probe(p)
+  const cfg = await probe("/uv/uv.config.js")
+  if (cfg?.ok) {
+    // the paths the config itself points at are what actually get imported
+    for (const m of (await cfg.text()).matchAll(/\b(handler|client|bundle|config|sw)\s*:\s*["']([^"']+)["']/g)) {
+      await probe(m[2], `<- config.${m[1]}`)
+    }
+  }
+}
+
+async function register_sw(proxy) {
+  let registration
+  try {
+    registration = await navigator.serviceWorker.register(`/sw.js?proxy=${proxy}`, {
+      scope: "/",
+      updateViaCache: "none",
+    })
+  } catch (err) {
+    await diagnose_sw(proxy).catch(() => {})
+    throw err
+  }
+  await navigator.serviceWorker.ready
+
+  // wait until the worker actually controls this page, or the first
+  // navigation can slip past it
+  if (!navigator.serviceWorker.controller) {
+    await new Promise((resolve) =>
+      navigator.serviceWorker.addEventListener("controllerchange", resolve, { once: true })
+    )
+  }
+  return navigator.serviceWorker.controller ?? registration.active
+}
+
+function wisp_url() {
+  return (location.protocol === "https:" ? "wss" : "ws") + "://" + location.host + "/wisp/"
+}
+
+// built-ins are bundled with the client, custom proxies name their own module
+function load_backend(proxy, conf) {
+  if (proxy === "ultraviolet") return import("./backends/ultraviolet.js")
+  if (proxy === "scramjet") return import("./backends/scramjet.js")
+  if (!conf.clientModule) throw new Error(`proxy "${proxy}" has no client module (was it registered with clientModule?)`)
+  return import(conf.clientModule)
+}
+
+// the iframe pages are shown in: #proxyFrame if you have one, else we make it
+// (create=false: just look, don't make one)
+function get_iframe(create = true) {
+  let iframe = document.getElementById("proxyFrame")
+  if (!iframe && create) {
+    iframe = document.createElement("iframe")
+    iframe.id = "proxyFrame"
+    iframe.style.cssText = "width:100%;height:100%;border:0"
+    ;(document.getElementById("container") || document.body).appendChild(iframe)
+  }
+  // network log + header policy: reinstalled every real navigation, since a
+  // new document means a new window. See net.js for what this can/can't see.
+  if (iframe && !iframe.__lithiumNetBound) {
+    iframe.__lithiumNetBound = true
+    iframe.addEventListener("load", () => {
+      try {
+        net.install(iframe.contentWindow, {
+          get_policy: () => state.header_policy,
+          emit: (entry) => {
+            state.network.push(entry)
+            if (state.network.length > NETWORK_LOG_CAP) state.network.shift()
+            emit("request", entry)
+          },
+          dbg,
+        })
+      } catch (err) {
+        dbg("network hook install failed:", err)
+      }
+    })
+  }
+  return iframe
+}
+
+// init the thing
+//   searchEngine  "google" | "duckduckgo"
+//   onReady       () => void          (same as on("ready", ...))
+//   onUrlChange   (url) => void       (same as on("navigate", ...), all proxies)
+export async function init_lithium(cfg = {}) {
+  const conf = server_config()
+  // same defaults as the server
+  const proxy = conf.proxy || "ultraviolet"
+  const transport = conf.transport || "epoxy"
+  const transport_url = conf.transportUrl || (proxy === "scramjet" ? `/${transport}/index.mjs` : `/bm/${transport}/index.mjs`)
+
+  // re-init: forget the previous run
+  for (const stop of state.unsubs) stop()
+  state.unsubs = []
+  clearInterval(state.poller)
+  state.ready = false
+  state.url = ""
+
+  state.proxy = proxy
+  state.transport = transport
+  state.iface = conf.interface ?? null
+  state.search_engine = cfg.searchEngine || "google"
+  state.debug = Boolean(cfg.debug)
+  state.header_policy = { ...net.DEFAULT_POLICY, ...(cfg.headers ?? {}) }
+  if (cfg.onReady) state.unsubs.push(on("ready", () => cfg.onReady()))
+  if (cfg.onUrlChange) state.unsubs.push(on("navigate", ({ url }) => cfg.onUrlChange(url)))
+
+  // keep these around so your own ui can read them
+  localStorage.setItem("proxy", proxy)
+  localStorage.setItem("transport", transport)
+  localStorage.setItem("engine", state.search_engine)
+  console.log("[lithium] config:", { proxy, transport })
+  dbg("init_lithium options:", cfg)
+  dbg("header policy:", state.header_policy)
+
+  try {
+    dbg(`registering service worker for "${proxy}"`)
+    const serviceworker = await register_sw(proxy)
+    dbg("service worker ready, loading backend module")
+    const backend = await load_backend(proxy, conf)
+    const ctx = {
+      proxy, transport, transport_url, serviceworker,
+      wisp_url: wisp_url(),
+      load_script,
+      iframe: get_iframe,
+      report_url,
+      state: {}, // for the backend's own use
+    }
+    await backend.init(ctx)
+    dbg("backend init complete")
+    state.backend = backend
+    state.ctx = ctx
+
+    if (typeof backend.current_url === "function") {
+      state.poller = setInterval(() => {
+        try { report_url(backend.current_url(ctx)) } catch { /* frame not loaded yet */ }
+      }, 500)
+    }
+  } catch (err) {
+    console.error("[lithium] init failed:", err)
+    if (state.debug) console.error("[lithium debug] full error:", err)
+    throw err // don't pretend we're ready
+  }
+
+  state.ready = true
+  emit("ready")
+}
+
+// ---------------------------------------------------------------- navigation --
+async function go(url) {
+  if (!state.ready) {
+    console.error("[lithium] not ready yet, await init_lithium() first")
+    return
+  }
+  get_iframe() // make sure it exists
+  document.getElementById("container")?.classList.add("browsing")
+  await state.backend.navigate(url, state.ctx)
+}
+
+// go somewhere on the internet: a URL, a domain, or a search
+export function navigate(input) {
+  const url = to_url(input, engine())
+  dbg("navigate ->", url)
+  return go(url)
+}
+
+// always a search, even if the text looks like a URL
+export function search(query) {
+  return go(search_url(query, engine()))
+}
+
+// the real URL of the page being shown ("" until something was loaded)
+export function current_url() {
+  return state.url
+}
+
+// history actions on the proxied page (works the same for every proxy)
+function with_frame(action, fn) {
+  try {
+    const win = state.ready ? get_iframe(false)?.contentWindow : null
+    if (win) fn(win)
+  } catch (err) {
+    console.error(`[lithium] ${action} failed:`, err)
+  }
+}
+export const back = () => with_frame("back", (w) => w.history.back())
+export const forward = () => with_frame("forward", (w) => w.history.forward())
+export const reload = () => with_frame("reload", (w) => w.location.reload())
+
+// ------------------------------------------------------------------ url utils --
+// checks if its a url or some random junk
+export function is_url(v = "") {
+  v = v.trim()
+  if (/^https?:\/\//i.test(v)) return true
+  if (/\s/.test(v)) return false // "what is 3.14" is a search, not a url
+  return (
+    /^[^\s/?#]+\.[a-z]{2,}(:\d+)?([/?#]|$)/i.test(v) || // example.com, a.b.co/path
+    /^\d{1,3}(\.\d{1,3}){3}(:\d+)?([/?#]|$)/.test(v) // 192.168.1.1:8080
+  )
+}
+
+export function search_url(query, engine = "google") {
+  const q = encodeURIComponent(String(query).trim())
+  return engine === "duckduckgo" ? `https://duckduckgo.com/?q=${q}` : `https://www.google.com/search?q=${q}`
+}
+
+// turn whatever was typed into a full url (or a search url)
+export function to_url(input, engine = "google") {
+  const val = input.trim()
+  if (!is_url(val)) return search_url(val, engine)
+  return /^https?:\/\//i.test(val) ? val : "https://" + val
+}

package/client/net.js

@@ -0,0 +1,114 @@
+// Best-effort network visibility + header policy for the proxied page.
+//
+// SCOPE, HONESTLY: Lithium's Node server never sees the proxied site's raw
+// HTTP traffic (that goes browser -> service worker -> wisp tunnel -> the
+// real site, as bytes, not parsed HTTP). So this works client-side instead:
+// it's installed on the proxied iframe's window (same-origin, since that's
+// how UV/Scramjet serve proxied pages) and wraps fetch()/XMLHttpRequest.
+//   - fetch(): full control. Request headers are filtered before sending,
+//     and the Response is rebuilt with filtered headers before the page's
+//     own code sees it.
+//   - XMLHttpRequest: observed only (logged), the header policy is NOT
+//     enforced on it — rebuilding a native XHR's headers isn't practical.
+//   - Anything that isn't fetch/XHR (<img>, <script src>, <link>, CSS,
+//     etc.) is invisible here entirely.
+//   - Only requests made AFTER this installs are seen. It installs on the
+//     iframe's "load" event, so very early/synchronous requests on that
+//     page can be missed.
+
+export const DEFAULT_POLICY = { mode: "filter", block: [], allow: null }
+
+// mode: "passthrough" -> do nothing (headers pass exactly as the proxy already
+//       delivered them); "filter" -> apply block/allow
+// block: header names (case-insensitive) to strip
+// allow: if an array, ONLY these header names survive (block still applies on top)
+export function apply_policy(headers, policy) {
+  if (policy.mode === "passthrough") return { headers, blocked: [] }
+  const out = new Headers()
+  const blocked = []
+  const block = new Set((policy.block ?? []).map((h) => h.toLowerCase()))
+  const allow = policy.allow ? new Set(policy.allow.map((h) => h.toLowerCase())) : null
+  for (const [k, v] of headers.entries()) {
+    const lk = k.toLowerCase()
+    if (block.has(lk) || (allow && !allow.has(lk))) {
+      blocked.push(k)
+      continue
+    }
+    out.append(k, v)
+  }
+  return { headers: out, blocked }
+}
+
+const headers_to_object = (headers) => Object.fromEntries(headers.entries())
+
+// win: the proxied iframe's contentWindow
+//   get_policy() -> current policy (read live, so changes apply mid-session)
+//   emit(entry)  -> called once per completed request
+//   dbg(...)     -> debug logger, called for policy decisions
+export function install(win, { get_policy, emit, dbg = () => {} }) {
+  if (!win || win.__lithiumNetHooked) return
+  win.__lithiumNetHooked = true
+
+  const orig_fetch = win.fetch?.bind(win)
+  if (orig_fetch) {
+    win.fetch = async (input, init = {}) => {
+      const policy = get_policy()
+      const url = typeof input === "string" ? input : input.url
+      const method = (init.method || (input instanceof Request ? input.method : "GET") || "GET").toUpperCase()
+      const started = win.performance?.now?.() ?? Date.now()
+
+      let req_headers = new Headers(init.headers || (input instanceof Request ? input.headers : undefined) || {})
+      const { headers: filtered_req, blocked: blocked_req } = apply_policy(req_headers, policy)
+      if (blocked_req.length) dbg(`blocked request headers on ${url}: ${blocked_req.join(", ")}`)
+
+      const finish = (fields) => emit({ type: "fetch", method, url, ts: Date.now(), duration: Math.round((win.performance?.now?.() ?? Date.now()) - started), requestHeaders: headers_to_object(filtered_req), blockedRequestHeaders: blocked_req, blockedResponseHeaders: [], responseHeaders: null, ...fields })
+
+      let response
+      try {
+        response = await orig_fetch(input instanceof Request ? new Request(input, { headers: filtered_req }) : input, { ...init, headers: filtered_req })
+      } catch (err) {
+        finish({ status: 0, ok: false, error: err.message })
+        throw err
+      }
+
+      if (policy.mode === "passthrough") {
+        finish({ status: response.status, ok: response.ok, responseHeaders: headers_to_object(response.headers) })
+        return response
+      }
+      const { headers: filtered_res, blocked: blocked_res } = apply_policy(response.headers, policy)
+      if (blocked_res.length) dbg(`blocked response headers on ${url}: ${blocked_res.join(", ")}`)
+      finish({ status: response.status, ok: response.ok, responseHeaders: headers_to_object(filtered_res), blockedResponseHeaders: blocked_res })
+      if (!blocked_res.length) return response
+      const body = await response.clone().blob()
+      return new Response(body, { status: response.status, statusText: response.statusText, headers: filtered_res })
+    }
+  }
+
+  const OrigXHR = win.XMLHttpRequest
+  if (OrigXHR) {
+    win.XMLHttpRequest = class extends OrigXHR {
+      open(method, url, ...rest) {
+        this.__lithium = { method, url, started: win.performance?.now?.() ?? Date.now() }
+        return super.open(method, url, ...rest)
+      }
+      send(...args) {
+        this.addEventListener("loadend", () => {
+          const info = this.__lithium || {}
+          let responseHeaders = null
+          try {
+            responseHeaders = Object.fromEntries(
+              this.getAllResponseHeaders().trim().split(/\r?\n/).filter(Boolean).map((l) => { const i = l.indexOf(":"); return [l.slice(0, i).trim(), l.slice(i + 1).trim()] })
+            )
+          } catch {}
+          emit({
+            type: "xhr", method: info.method || "GET", url: info.url || "", status: this.status, ok: this.status >= 200 && this.status < 400,
+            duration: Math.round((win.performance?.now?.() ?? Date.now()) - (info.started ?? 0)), ts: Date.now(),
+            requestHeaders: null, responseHeaders, blockedRequestHeaders: [], blockedResponseHeaders: [],
+            note: "XHR is observed only, header policy isn't enforced on it",
+          })
+        })
+        return super.send(...args)
+      }
+    }
+  }
+}

package/client/sw.js

@@ -0,0 +1,33 @@
+// lithium service worker
+// Registered as /sw.js?proxy=<ultraviolet|scramjet> by client/index.js, and
+// only loads the code for the proxy it was asked for. Has to be served from
+// the site root so its scope covers the proxied routes.
+const proxy = new URL(self.location.href).searchParams.get("proxy") || "ultraviolet"
+
+// Without these, the worker only takes control after a reload, so the very
+// first request from the iframe would skip the proxy entirely.
+self.addEventListener("install", () => self.skipWaiting())
+self.addEventListener("activate", (event) => event.waitUntil(self.clients.claim()))
+
+if (proxy === "scramjet") {
+  // Scramjet 2.x: the controller decides what to route. shouldRoute() is
+  // false for its own runtime files, so they don't get intercepted.
+  importScripts("/controller/controller.sw.js")
+
+  self.addEventListener("fetch", (event) => {
+    if ($scramjetController.shouldRoute(event)) {
+      event.respondWith($scramjetController.route(event))
+    }
+  })
+} else {
+  // Ultraviolet 3.x (transport is handled by bare-mux on the page side)
+  importScripts("/uv/uv.bundle.js")
+  importScripts("/uv/uv.config.js")
+  importScripts(self.__uv$config.sw || "/uv/uv.sw.js")
+
+  const uv = new UVServiceWorker()
+
+  self.addEventListener("fetch", (event) => {
+    if (uv.route(event)) event.respondWith(uv.fetch(event))
+  })
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nivalos/lithium.js",
+  "version": "1.1.0",
+  "description": "Creating a proxy has never been easier with Lithium.js",
+  "type": "module",
+  "main": "server/index.js",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": "./server/index.js"
+  },
+  "scripts": {
+    "start": "node server/start.js",
+    "test": "echo \"no automated tests are bundled, run `npx lithium doctor` to check your install\""
+  },
+  "keywords": [
+    "lithium",
+    "lithium-js",
+    "lithium-proxy",
+    "scramjet",
+    "ultraviolet",
+    "bare-mux",
+    "epoxy-transport",
+    "libcurl-transport",
+    "wisp-js",
+    "mercuryworkshop",
+    "proxy-server",
+    "web-unblocker",
+    "nodejs",
+    "express",
+    "self-hosted-proxy",
+    "reverse-proxy",
+    "bypass",
+    "webview",
+    "frontend-proxy",
+    "uv-proxy",
+    "school-unblocker",
+    "browser-proxy",
+    "javascript",
+    "network-tunneling"
+  ],
+  "author": "nivalos",
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "@mercuryworkshop/bare-mux": "^2.1.9",
+    "@mercuryworkshop/epoxy-transport": "^3.0.1",
+    "@mercuryworkshop/libcurl-transport": "^2.0.5",
+    "@mercuryworkshop/scramjet": "2.0.67-alpha.2",
+    "@mercuryworkshop/scramjet-controller": "0.0.14",
+    "@mercuryworkshop/scramjet-utils": "0.0.3",
+    "@mercuryworkshop/wisp-js": "^0.5.0",
+    "@titaniumnetwork-dev/ultraviolet": "^3.2.10",
+    "cheerio": "^1.2.0",
+    "epoxy-transport-bm": "npm:@mercuryworkshop/epoxy-transport@^2.1.28",
+    "express": "^5.2.1",
+    "libcurl-transport-bm": "npm:@mercuryworkshop/libcurl-transport@^1.5.2"
+  },
+  "files": [
+    "server",
+    "client",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "lithium": "bin/lithium.js"
+  }
+}

package/server/color.js

@@ -0,0 +1,16 @@
+// Minimal ANSI color helper for terminal output (zero dependencies, like a
+// tiny colorama for Node). Auto-disables when stdout isn't a TTY or NO_COLOR
+// is set (https://no-color.org); force with FORCE_COLOR=1.
+//   import { color, set_color } from "./color.js"
+//   console.log(color.green("ok"), color.red("failed"))
+const is_tty = () => Boolean(process.stdout && process.stdout.isTTY)
+let enabled = process.env.FORCE_COLOR ? true : !process.env.NO_COLOR && is_tty()
+
+export function set_color(on) { enabled = Boolean(on) }
+export function color_enabled() { return enabled }
+
+const wrap = (open, close) => (s) => (enabled ? `\x1b[${open}m${s}\x1b[${close}m` : String(s))
+export const color = {
+  red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39), blue: wrap(34, 39),
+  magenta: wrap(35, 39), cyan: wrap(36, 39), gray: wrap(90, 39), bold: wrap(1, 22), dim: wrap(2, 22),
+}