kliner 0.1.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WalnutsForNerds Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# Kliner
+
+Developer-friendly service-worker web proxy framework for local development.
+
+## Quick start
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+Open `http://localhost:8080/health`. The demo is available from `klinerdemo/` when served by your host app. Kliner is a framework, not an unrestricted public proxy: configure an allowlist before exposing it outside local development.
+
+## Install into an existing project
+
+```sh
+npx kliner install
+npm run kliner:start
+```
+
+Use `kliner init my-proxy` to generate a starter project and `kliner doctor` to diagnose an installation.
+
+## Configuration
+
+`kliner.config.js` supports `port`, `host`, `servicePath`, `websocketPath`, `allowlist`, `blocked`, `cors`, `requestTimeout`, `maxRequestSize`, `maxResponseSize`, and `logging.level`. Environment variables `KLINER_PORT`, `KLINER_HOST`, `KLINER_TARGET_ALLOWLIST`, and `KLINER_LOG_LEVEL` override the matching values.
+
+URL encoding is reversible URL encoding, not encryption. Operators are responsible for access control, HTTPS, rate limiting, and safe deployment.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "../src/config.js";
+
+const version = "0.1.0-beta";
+const runtimeFiles = ["src/server.js", "src/proxy.js", "src/codec.js", "src/ws-proxy.js", "src/config.js", "src/client/kli.js", "src/client/interceptor.js", "src/client/runtime.js", "scripts/build.js", "kliner.config.js"];
+const root = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+function copyRuntime(destination) {
+  for (const file of runtimeFiles) {
+    const target = path.join(destination, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (fs.existsSync(target)) { console.log(chalk.yellow(`  conflict: ${file} (preserved)`)); continue; }
+    fs.copyFileSync(path.join(root, file), target);
+    console.log(chalk.green(`  added: ${file}`));
+  }
+}
+
+function updatePackage(cwd) {
+  const file = path.join(cwd, "package.json");
+  const packageJson = JSON.parse(fs.readFileSync(file, "utf8"));
+  packageJson.scripts = { ...packageJson.scripts, "kliner:start": "node src/server.js", "kliner:dev": "nodemon src/server.js", "kliner:build": "node scripts/build.js", "kliner:doctor": "kliner doctor" };
+  packageJson.dependencies = { ...packageJson.dependencies, express: "^4.19.0", undici: "^6.19.0", ws: "^8.18.0", cors: "^2.8.5", dotenv: "^16.4.0", commander: "^12.1.0", chalk: "^5.3.0" };
+  packageJson.devDependencies = { ...packageJson.devDependencies, esbuild: "^0.23.0", nodemon: "^3.1.0" };
+  fs.writeFileSync(file, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+
+async function install(cwd = process.cwd()) {
+  const packageFile = path.join(cwd, "package.json");
+  if (!fs.existsSync(packageFile)) { console.error(chalk.red("No package.json found. Use kliner init or run this in a Node project.")); process.exitCode = 1; return; }
+  if (fs.existsSync(path.join(cwd, "src/kliner")) || fs.existsSync(path.join(cwd, "kliner.config.js"))) { console.log(chalk.yellow("Kliner is already installed. Use kliner doctor or kliner update.")); return; }
+  console.log(chalk.bold(`KLINER v${version}\nDetecting project...`));
+  updatePackage(cwd); copyRuntime(cwd);
+  console.log(chalk.green("Kliner installation complete. Run npm install, then npm run kliner:start."));
+}
+
+async function init(name) {
+  const destination = path.resolve(process.cwd(), name);
+  fs.mkdirSync(destination, { recursive: true });
+  fs.writeFileSync(path.join(destination, "package.json"), JSON.stringify({ name: path.basename(destination), version: "0.1.0", type: "module", scripts: { start: "node src/server.js", build: "node scripts/build.js" }, dependencies: { express: "^4.19.0", undici: "^6.19.0", ws: "^8.18.0", cors: "^2.8.5", dotenv: "^16.4.0" }, devDependencies: { esbuild: "^0.23.0", nodemon: "^3.1.0" } }, null, 2) + "\n");
+  copyRuntime(destination);
+  fs.mkdirSync(path.join(destination, "public"), { recursive: true });
+  fs.writeFileSync(path.join(destination, "public/index.html"), "<!doctype html><title>Kliner</title><script>navigator.serviceWorker?.register('/kli.js',{scope:'/service/'})</script><h1>Kliner</h1>\n");
+  console.log(chalk.green(`Created ${destination}`));
+}
+
+async function doctor() {
+  const cwd = process.cwd(); const checks = [["package.json", fs.existsSync(path.join(cwd, "package.json"))], ["Kliner configuration", fs.existsSync(path.join(cwd, "kliner.config.js"))], ["Service worker", fs.existsSync(path.join(cwd, "src/client/kli.js"))], ["Codec", fs.existsSync(path.join(cwd, "src/codec.js"))]];
+  for (const [label, ok] of checks) console.log(`${ok ? chalk.green("✓") : chalk.red("✗")} ${label}`);
+  try { await loadConfig(cwd); console.log(chalk.green("✓ Configuration valid")); } catch { console.log(chalk.red("✗ Configuration invalid")); process.exitCode = 1; }
+  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
+}
+
+const program = new Command().name("kliner").version(version).description("Developer-friendly service-worker web proxy framework");
+program.command("install").description("Install Kliner into the current project").action(() => install());
+program.command("init <directory>").description("Create a Kliner starter project").action(init);
+program.command("start").description("Start the proxy server").action(() => import("../src/server.js").then(({ startServer }) => startServer()));
+program.command("dev").description("Start the proxy with nodemon").action(() => spawn("npx", ["nodemon", "src/server.js"], { stdio: "inherit", shell: true }));
+program.command("build").description("Build the service worker").action(() => import("../scripts/build.js"));
+program.command("doctor").description("Diagnose the current project").action(doctor);
+program.parseAsync();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "kliner",
+  "version": "0.1.0-beta",
+  "description": "Developer-friendly service-worker web proxy framework",
+  "type": "module",
+  "bin": { "kliner": "bin/cli.js" },
+  "main": "./src/server.js",
+  "exports": {
+    ".": "./src/server.js",
+    "./codec": "./src/codec.js",
+    "./proxy": "./src/proxy.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js",
+    "build": "node scripts/build.js",
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "engines": { "node": ">=18.0.0" },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.19.0",
+    "undici": "^6.19.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": { "esbuild": "^0.23.0", "nodemon": "^3.1.0" },
+  "files": ["bin", "src", "scripts", "templates", "LICENSE", "README.md"]
+}

package/scripts/build.js

@@ -0,0 +1,4 @@
+import { build } from "esbuild";
+
+await build({ entryPoints: ["src/client/kli.js"], bundle: true, format: "iife", platform: "browser", outfile: "dist/kli.js", define: { "self.__KLINER_SERVICE_PATH__": JSON.stringify("/service/") } });
+console.log("Built dist/kli.js");

package/src/client/interceptor.js

@@ -0,0 +1,7 @@
+export function installInterceptors({ servicePath = "/service/" } = {}) {
+  const originalFetch = globalThis.fetch;
+  if (originalFetch) globalThis.fetch = (input, init) => {
+    const target = new URL(typeof input === "string" ? input : input.url, globalThis.location?.href);
+    return originalFetch(`${servicePath}${target.href}`, init);
+  };
+}

package/src/client/kli.js

@@ -0,0 +1,22 @@
+const SERVICE_PREFIX = self.__KLINER_SERVICE_PATH__ || "/service/";
+
+function encodedTarget(url) {
+  const bytes = new TextEncoder().encode(new URL(url).href);
+  let binary = "";
+  bytes.forEach((byte) => { binary += String.fromCharCode(byte); });
+  return `k1.${btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")}`;
+}
+
+self.addEventListener("install", () => self.skipWaiting());
+self.addEventListener("activate", (event) => event.waitUntil(self.clients.claim()));
+self.addEventListener("fetch", (event) => {
+  const requestUrl = new URL(event.request.url);
+  if (requestUrl.origin === self.location.origin && requestUrl.pathname.startsWith(SERVICE_PREFIX)) return;
+  if (!["http:", "https:"].includes(requestUrl.protocol)) return;
+  event.respondWith(fetch(`${SERVICE_PREFIX}${encodedTarget(requestUrl.href)}`, {
+    method: event.request.method,
+    headers: event.request.headers,
+    body: ["GET", "HEAD"].includes(event.request.method) ? undefined : event.request.body,
+    redirect: "follow"
+  }));
+});

package/src/client/runtime.js

@@ -0,0 +1,4 @@
+export async function registerKliner({ script = "/kli.js", scope = "/service/" } = {}) {
+  if (!("serviceWorker" in navigator)) throw new Error("Service workers are not supported");
+  return navigator.serviceWorker.register(script, { scope });
+}

package/src/codec.js

@@ -0,0 +1,43 @@
+const PREFIX = "k1.";
+
+function toBase64Url(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function fromBase64Url(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+
+export function encodeKlinerUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    const error = new Error("Invalid target URL");
+    error.code = "KLINER_INVALID_URL";
+    throw error;
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    const error = new Error("Only HTTP and HTTPS targets are supported");
+    error.code = "KLINER_INVALID_URL";
+    throw error;
+  }
+  return `${PREFIX}${toBase64Url(parsed.href)}`;
+}
+
+export function decodeKlinerUrl(encoded) {
+  if (typeof encoded !== "string" || !encoded.startsWith(PREFIX)) {
+    const error = new Error("Invalid Kliner URL encoding");
+    error.code = "KLINER_CODEC_ERROR";
+    throw error;
+  }
+  try {
+    const url = new URL(fromBase64Url(encoded.slice(PREFIX.length)));
+    if (!["http:", "https:"].includes(url.protocol)) throw new Error();
+    return url.href;
+  } catch {
+    const error = new Error("Invalid Kliner URL encoding");
+    error.code = "KLINER_CODEC_ERROR";
+    throw error;
+  }
+}

package/src/config.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const defaults = {
+  port: 8080,
+  host: "localhost",
+  servicePath: "/service/",
+  websocketPath: "/service/ws",
+  allowlist: [],
+  blocked: [],
+  cors: { origin: "http://localhost:8080" },
+  requestTimeout: 30000,
+  maxRequestSize: 10 * 1024 * 1024,
+  maxResponseSize: 100 * 1024 * 1024,
+  logging: { level: "info" }
+};
+
+export async function loadConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, "kliner.config.js");
+  let project = {};
+  if (fs.existsSync(configPath)) project = (await import(`${configPath}?t=${Date.now()}`)).default ?? {};
+  const envList = process.env.KLINER_TARGET_ALLOWLIST?.split(",").map((item) => item.trim()).filter(Boolean);
+  return {
+    ...defaults,
+    ...project,
+    port: Number(process.env.KLINER_PORT ?? project.port ?? defaults.port),
+    host: process.env.KLINER_HOST ?? project.host ?? defaults.host,
+    allowlist: envList ?? project.allowlist ?? defaults.allowlist,
+    logging: { ...defaults.logging, ...(project.logging ?? {}), level: process.env.KLINER_LOG_LEVEL ?? project.logging?.level ?? defaults.logging.level }
+  };
+}
+
+export function matchesTarget(target, patterns = []) {
+  return patterns.some((pattern) => {
+    try { return new RegExp(pattern).test(target.hostname); } catch { return target.hostname === pattern || target.host === pattern; }
+  });
+}
+
+export function isAllowed(target, config) {
+  if (matchesTarget(target, config.blocked)) return false;
+  return config.allowlist.length === 0 || matchesTarget(target, config.allowlist);
+}

package/src/proxy.js

@@ -0,0 +1,51 @@
+import { request } from "undici";
+import { decodeKlinerUrl, encodeKlinerUrl } from "./codec.js";
+import { isAllowed } from "./config.js";
+
+const hopByHop = new Set(["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"]);
+
+export function rewriteResponse(text, baseUrl, contentType) {
+  if (/text\/html/i.test(contentType)) {
+    return text.replace(/(\b(?:href|src|action|poster)\s*=\s*["'])([^"']+)(["'])/gi, (match, start, value, end) => {
+      if (/^(?:data:|javascript:|mailto:|#)/i.test(value)) return match;
+      return `${start}${new URL(value, baseUrl).href}${end}`;
+    });
+  }
+  if (/text\/css/i.test(contentType)) return text.replace(/url\(\s*(["']?)([^)"']+)\1\s*\)/gi, (match, quote, value) => `url(${quote}${new URL(value, baseUrl).href}${quote})`);
+  return text;
+}
+
+export async function proxyRequest(req, res, config, logger = () => {}) {
+  let target;
+  try { target = new URL(decodeKlinerUrl(req.params[0] || req.params.encoded)); } catch (error) {
+    res.status(400).json({ error: error.code ?? "KLINER_CODEC_ERROR", message: error.message }); return;
+  }
+  if (!isAllowed(target, config)) { res.status(403).json({ error: "KLINER_TARGET_BLOCKED" }); return; }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.requestTimeout);
+  try {
+    const headers = { ...req.headers };
+    delete headers.host; delete headers.connection; delete headers["content-length"];
+    const upstream = await request(target, { method: req.method, headers, body: ["GET", "HEAD"].includes(req.method) ? undefined : req, signal: controller.signal, maxRedirections: 5 });
+    logger(req.method, target.href, upstream.statusCode, upstream.headers["content-type"]);
+    for (const [name, value] of Object.entries(upstream.headers)) {
+      if (hopByHop.has(name) || name === "content-length" || name === "content-encoding") continue;
+      if (name === "location") {
+        const redirect = new URL(value, target);
+        if (isAllowed(redirect, config)) res.setHeader(name, `${config.servicePath}${encodeKlinerUrl(redirect.href)}`);
+        continue;
+      }
+      res.setHeader(name, value);
+    }
+    res.status(upstream.statusCode);
+    const type = String(upstream.headers["content-type"] ?? "");
+    if (/text\/html|text\/css/i.test(type)) {
+      const body = await upstream.body.text();
+      if (Buffer.byteLength(body) > config.maxResponseSize) throw Object.assign(new Error("Response too large"), { code: "KLINER_RESPONSE_TOO_LARGE" });
+      res.send(rewriteResponse(body, target.href, type));
+    } else upstream.body.pipe(res);
+  } catch (error) {
+    if (res.headersSent) res.destroy(error);
+    else res.status(error.name === "AbortError" ? 504 : 502).json({ error: error.name === "AbortError" ? "KLINER_TIMEOUT" : "KLINER_TARGET_UNREACHABLE" });
+  } finally { clearTimeout(timeout); }
+}

package/src/server.js

@@ -0,0 +1,36 @@
+import http from "node:http";
+import express from "express";
+import cors from "cors";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { proxyRequest } from "./proxy.js";
+import { attachWebSocketProxy } from "./ws-proxy.js";
+
+export async function createApp(config) {
+  config ??= await loadConfig();
+  const app = express();
+  app.use(cors(config.cors));
+  app.get("/health", (_req, res) => res.json({ status: "ok", name: "kliner", version: "0.1.0-beta" }));
+  app.get("/status", (_req, res) => res.json({ status: "ok", allowlist: config.allowlist, servicePath: config.servicePath }));
+  const clientPath = path.dirname(fileURLToPath(import.meta.url));
+  app.get("/kli.js", (_req, res) => res.sendFile(path.join(clientPath, "client", "kli.js")));
+  app.all(`${config.servicePath}:encoded(*)`, (req, res) => proxyRequest(req, res, config, (method, target, status, type) => {
+    if (config.logging.level !== "silent") console.log(`[${new Date().toISOString().slice(11, 19)}] ${method} ${target} ${status} ${type ?? ""}`);
+  }));
+  app.use((error, _req, res, _next) => res.status(500).json({ error: "KLINER_CONFIGURATION_ERROR", message: config.logging.level === "debug" ? error.message : "Kliner request failed" }));
+  return app;
+}
+
+export async function startServer(config) {
+  config ??= await loadConfig();
+  const app = await createApp(config);
+  const server = http.createServer(app);
+  attachWebSocketProxy(server, config);
+  return new Promise((resolve) => server.listen(config.port, config.host, () => {
+    console.log(`Kliner proxy running at http://${config.host}:${config.port}`);
+    resolve(server);
+  }));
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) startServer();

package/src/ws-proxy.js

@@ -0,0 +1,24 @@
+import { WebSocketServer, WebSocket } from "ws";
+import { decodeKlinerUrl } from "./codec.js";
+import { isAllowed } from "./config.js";
+
+export function attachWebSocketProxy(server, config, path = config.websocketPath) {
+  const wss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (request, socket, head) => {
+    if (!request.url.startsWith(path)) return;
+    const encoded = new URL(request.url, "http://localhost").searchParams.get("url");
+    let target;
+    try { target = new URL(decodeKlinerUrl(encoded)); } catch { socket.destroy(); return; }
+    if (!isAllowed(target, config) || !["http:", "https:"].includes(target.protocol)) { socket.destroy(); return; }
+    wss.handleUpgrade(request, socket, head, (client) => {
+      const upstream = new WebSocket(target.href, { headers: { origin: target.origin } });
+      client.on("message", (data, isBinary) => { if (upstream.readyState === WebSocket.OPEN) upstream.send(data, { binary: isBinary }); });
+      upstream.on("open", () => client.emit("open"));
+      upstream.on("message", (data, isBinary) => { if (client.readyState === WebSocket.OPEN) client.send(data, { binary: isBinary }); });
+      const close = () => { client.close(); upstream.close(); };
+      client.on("close", close); upstream.on("close", close);
+      client.on("error", close); upstream.on("error", close);
+    });
+  });
+  return wss;
+}