portless 0.3.0 → 0.4.0

package/README.md

@@ -86,11 +86,34 @@ flowchart TD
 
 Apps are assigned a random port (4000-4999) via the `PORT` environment variable. Most frameworks (Next.js, Vite, etc.) respect this automatically.
 
+## HTTP/2 + HTTPS
+
+Enable HTTP/2 for faster dev server page loads. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
+
+```bash
+# Start with HTTPS/2 -- generates certs and trusts them automatically
+portless proxy start --https
+
+# First run prompts for sudo once to add the CA to your system trust store.
+# After that, no prompts. No browser warnings.
+
+# Make it permanent (add to .bashrc / .zshrc)
+export PORTLESS_HTTPS=1
+portless proxy start    # HTTPS by default now
+
+# Use your own certs (e.g., from mkcert)
+portless proxy start --cert ./cert.pem --key ./key.pem
+
+# If you skipped sudo on first run, trust the CA later
+sudo portless trust
+```
+
 ## Commands
 
 ```bash
 portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
 portless list                    # Show active routes
+portless trust                   # Add local CA to system trust store
 
 # Disable portless (run command directly)
 PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
@@ -98,6 +121,7 @@ PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
 
 # Proxy control
 portless proxy start             # Start the proxy (port 1355, daemon)
+portless proxy start --https     # Start with HTTP/2 + TLS
 portless proxy start -p 80       # Start on port 80 (requires sudo)
 portless proxy start --foreground  # Start in foreground (for debugging)
 portless proxy stop              # Stop the proxy
@@ -105,10 +129,15 @@ portless proxy stop              # Stop the proxy
 # Options
 -p, --port <number>              # Port for the proxy (default: 1355)
                                  # Ports < 1024 require sudo
+--https                          # Enable HTTP/2 + TLS with auto-generated certs
+--cert <path>                    # Use a custom TLS certificate (implies --https)
+--key <path>                     # Use a custom TLS private key (implies --https)
+--no-tls                         # Disable HTTPS (overrides PORTLESS_HTTPS)
 --foreground                     # Run proxy in foreground instead of daemon
 
 # Environment variables
 PORTLESS_PORT=<number>           # Override the default proxy port
+PORTLESS_HTTPS=1                 # Always enable HTTPS
 PORTLESS_STATE_DIR=<path>        # Override the state directory
 
 # Info

package/dist/{chunk-Y5OVKUR4.js → chunk-VRBD6YAY.js}

@@ -5,8 +5,10 @@ function isErrnoException(err) {
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function formatUrl(hostname, proxyPort) {
-  return proxyPort === 80 ? `http://${hostname}` : `http://${hostname}:${proxyPort}`;
+function formatUrl(hostname, proxyPort, tls = false) {
+  const proto = tls ? "https" : "http";
+  const defaultPort = tls ? 443 : 80;
+  return proxyPort === defaultPort ? `${proto}://${hostname}` : `${proto}://${hostname}:${proxyPort}`;
 }
 function parseHostname(input) {
   let hostname = input.trim().replace(/^https?:\/\//, "").split("/")[0].toLowerCase();
@@ -30,24 +32,40 @@ function parseHostname(input) {
 
 // src/proxy.ts
 import * as http from "http";
+import * as http2 from "http2";
+import * as net from "net";
 var PORTLESS_HEADER = "X-Portless";
-function buildForwardedHeaders(req) {
+var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-connection",
+  "transfer-encoding",
+  "upgrade"
+]);
+function getRequestHost(req) {
+  const authority = req.headers[":authority"];
+  if (typeof authority === "string" && authority) return authority;
+  return req.headers.host || "";
+}
+function buildForwardedHeaders(req, tls) {
   const headers = {};
   const remoteAddress = req.socket.remoteAddress || "127.0.0.1";
-  const proto = "http";
-  const hostHeader = req.headers.host || "";
+  const proto = tls ? "https" : "http";
+  const defaultPort = tls ? "443" : "80";
+  const hostHeader = getRequestHost(req);
   headers["x-forwarded-for"] = req.headers["x-forwarded-for"] ? `${req.headers["x-forwarded-for"]}, ${remoteAddress}` : remoteAddress;
   headers["x-forwarded-proto"] = req.headers["x-forwarded-proto"] || proto;
   headers["x-forwarded-host"] = req.headers["x-forwarded-host"] || hostHeader;
-  headers["x-forwarded-port"] = req.headers["x-forwarded-port"] || hostHeader.split(":")[1] || "80";
+  headers["x-forwarded-port"] = req.headers["x-forwarded-port"] || hostHeader.split(":")[1] || defaultPort;
   return headers;
 }
 function createProxyServer(options) {
-  const { getRoutes, proxyPort, onError = (msg) => console.error(msg) } = options;
+  const { getRoutes, proxyPort, onError = (msg) => console.error(msg), tls } = options;
+  const isTls = !!tls;
   const handleRequest = (req, res) => {
     res.setHeader(PORTLESS_HEADER, "1");
     const routes = getRoutes();
-    const host = (req.headers.host || "").split(":")[0];
+    const host = getRequestHost(req).split(":")[0];
     if (!host) {
       res.writeHead(400, { "Content-Type": "text/plain" });
       res.end("Missing Host header");
@@ -66,7 +84,7 @@ function createProxyServer(options) {
             ${routes.length > 0 ? `
               <h2>Active apps:</h2>
               <ul>
-                ${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort))}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
+                ${routes.map((r) => `<li><a href="${escapeHtml(formatUrl(r.hostname, proxyPort, isTls))}">${escapeHtml(r.hostname)}</a> - localhost:${escapeHtml(String(r.port))}</li>`).join("")}
               </ul>
             ` : "<p><em>No apps running.</em></p>"}
             <p>Start an app with: <code>portless ${safeHost.replace(".localhost", "")} your-command</code></p>
@@ -75,11 +93,16 @@ function createProxyServer(options) {
       `);
       return;
     }
-    const forwardedHeaders = buildForwardedHeaders(req);
+    const forwardedHeaders = buildForwardedHeaders(req, isTls);
     const proxyReqHeaders = { ...req.headers };
     for (const [key, value] of Object.entries(forwardedHeaders)) {
       proxyReqHeaders[key] = value;
     }
+    for (const key of Object.keys(proxyReqHeaders)) {
+      if (key.startsWith(":")) {
+        delete proxyReqHeaders[key];
+      }
+    }
     const proxyReq = http.request(
       {
         hostname: "127.0.0.1",
@@ -89,12 +112,18 @@ function createProxyServer(options) {
         headers: proxyReqHeaders
       },
       (proxyRes) => {
-        res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+        const responseHeaders = { ...proxyRes.headers };
+        if (isTls) {
+          for (const h of HOP_BY_HOP_HEADERS) {
+            delete responseHeaders[h];
+          }
+        }
+        res.writeHead(proxyRes.statusCode || 502, responseHeaders);
         proxyRes.pipe(res);
       }
     );
     proxyReq.on("error", (err) => {
-      onError(`Proxy error for ${req.headers.host}: ${err.message}`);
+      onError(`Proxy error for ${getRequestHost(req)}: ${err.message}`);
       if (!res.headersSent) {
         const errWithCode = err;
         const message = errWithCode.code === "ECONNREFUSED" ? "Bad Gateway: the target app is not responding. It may have crashed." : "Bad Gateway: the target app may not be running.";
@@ -116,17 +145,22 @@ function createProxyServer(options) {
   };
   const handleUpgrade = (req, socket, head) => {
     const routes = getRoutes();
-    const host = (req.headers.host || "").split(":")[0];
+    const host = getRequestHost(req).split(":")[0];
     const route = routes.find((r) => r.hostname === host);
     if (!route) {
       socket.destroy();
       return;
     }
-    const forwardedHeaders = buildForwardedHeaders(req);
+    const forwardedHeaders = buildForwardedHeaders(req, isTls);
     const proxyReqHeaders = { ...req.headers };
     for (const [key, value] of Object.entries(forwardedHeaders)) {
       proxyReqHeaders[key] = value;
     }
+    for (const key of Object.keys(proxyReqHeaders)) {
+      if (key.startsWith(":")) {
+        delete proxyReqHeaders[key];
+      }
+    }
     const proxyReq = http.request({
       hostname: "127.0.0.1",
       port: route.port,
@@ -152,7 +186,7 @@ function createProxyServer(options) {
       socket.on("error", () => proxySocket.destroy());
     });
     proxyReq.on("error", (err) => {
-      onError(`WebSocket proxy error for ${req.headers.host}: ${err.message}`);
+      onError(`WebSocket proxy error for ${getRequestHost(req)}: ${err.message}`);
       socket.destroy();
     });
     proxyReq.on("response", (res) => {
@@ -173,6 +207,44 @@ function createProxyServer(options) {
     }
     proxyReq.end();
   };
+  if (tls) {
+    const h2Server = http2.createSecureServer({
+      cert: tls.cert,
+      key: tls.key,
+      allowHTTP1: true,
+      ...tls.SNICallback ? { SNICallback: tls.SNICallback } : {}
+    });
+    h2Server.on("request", (req, res) => {
+      handleRequest(req, res);
+    });
+    h2Server.on("upgrade", (req, socket, head) => {
+      handleUpgrade(req, socket, head);
+    });
+    const plainServer = http.createServer(handleRequest);
+    plainServer.on("upgrade", handleUpgrade);
+    const wrapper = net.createServer((socket) => {
+      socket.once("readable", () => {
+        const buf = socket.read(1);
+        if (!buf) {
+          socket.destroy();
+          return;
+        }
+        socket.unshift(buf);
+        if (buf[0] === 22) {
+          h2Server.emit("connection", socket);
+        } else {
+          plainServer.emit("connection", socket);
+        }
+      });
+    });
+    const origClose = wrapper.close.bind(wrapper);
+    wrapper.close = function(cb) {
+      h2Server.close();
+      plainServer.close();
+      return origClose(cb);
+    };
+    return wrapper;
+  }
   const httpServer = http.createServer(handleRequest);
   httpServer.on("upgrade", handleUpgrade);
   return httpServer;
@@ -190,6 +262,7 @@ function isValidRoute(value) {
   return typeof value === "object" && value !== null && typeof value.hostname === "string" && typeof value.port === "number" && typeof value.pid === "number";
 }
 var RouteStore = class _RouteStore {
+  /** The state directory path. */
   dir;
   routesPath;
   lockPath;

package/dist/cli.js

@@ -7,26 +7,401 @@ import {
   formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-Y5OVKUR4.js";
+} from "./chunk-VRBD6YAY.js";
 
 // src/cli.ts
 import chalk from "chalk";
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs3 from "fs";
+import * as path3 from "path";
 import { spawn as spawn2, spawnSync } from "child_process";
 
-// src/cli-utils.ts
+// src/certs.ts
 import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import * as tls from "tls";
+import { execFile as execFileCb, execFileSync } from "child_process";
+import { promisify } from "util";
+var CA_VALIDITY_DAYS = 3650;
+function fixOwnership(...paths) {
+  const uid = process.env.SUDO_UID;
+  const gid = process.env.SUDO_GID;
+  if (!uid || process.getuid?.() !== 0) return;
+  for (const p of paths) {
+    try {
+      fs.chownSync(p, parseInt(uid, 10), parseInt(gid || uid, 10));
+    } catch {
+    }
+  }
+}
+var SERVER_VALIDITY_DAYS = 365;
+var EXPIRY_BUFFER_MS = 7 * 24 * 60 * 60 * 1e3;
+var CA_COMMON_NAME = "portless Local CA";
+var OPENSSL_TIMEOUT_MS = 15e3;
+var CA_KEY_FILE = "ca-key.pem";
+var CA_CERT_FILE = "ca.pem";
+var SERVER_KEY_FILE = "server-key.pem";
+var SERVER_CERT_FILE = "server.pem";
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isCertValid(certPath) {
+  try {
+    const pem = fs.readFileSync(certPath, "utf-8");
+    const cert = new crypto.X509Certificate(pem);
+    const expiry = new Date(cert.validTo).getTime();
+    return Date.now() + EXPIRY_BUFFER_MS < expiry;
+  } catch {
+    return false;
+  }
+}
+function openssl(args, options) {
+  try {
+    return execFileSync("openssl", args, {
+      encoding: "utf-8",
+      timeout: OPENSSL_TIMEOUT_MS,
+      input: options?.input,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `openssl failed: ${message}
+
+Make sure openssl is installed (ships with macOS and most Linux distributions).`
+    );
+  }
+}
+var execFileAsync = promisify(execFileCb);
+async function opensslAsync(args) {
+  try {
+    const { stdout } = await execFileAsync("openssl", args, {
+      encoding: "utf-8",
+      timeout: OPENSSL_TIMEOUT_MS
+    });
+    return stdout;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `openssl failed: ${message}
+
+Make sure openssl is installed (ships with macOS and most Linux distributions).`
+    );
+  }
+}
+function generateCA(stateDir) {
+  const keyPath = path.join(stateDir, CA_KEY_FILE);
+  const certPath = path.join(stateDir, CA_CERT_FILE);
+  openssl(["ecparam", "-genkey", "-name", "prime256v1", "-noout", "-out", keyPath]);
+  openssl([
+    "req",
+    "-new",
+    "-x509",
+    "-key",
+    keyPath,
+    "-out",
+    certPath,
+    "-days",
+    CA_VALIDITY_DAYS.toString(),
+    "-subj",
+    `/CN=${CA_COMMON_NAME}`,
+    "-addext",
+    "basicConstraints=critical,CA:TRUE",
+    "-addext",
+    "keyUsage=critical,keyCertSign,cRLSign"
+  ]);
+  fs.chmodSync(keyPath, 384);
+  fs.chmodSync(certPath, 420);
+  fixOwnership(keyPath, certPath);
+  return { certPath, keyPath };
+}
+function generateServerCert(stateDir) {
+  const caKeyPath = path.join(stateDir, CA_KEY_FILE);
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  const serverKeyPath = path.join(stateDir, SERVER_KEY_FILE);
+  const serverCertPath = path.join(stateDir, SERVER_CERT_FILE);
+  const csrPath = path.join(stateDir, "server.csr");
+  const extPath = path.join(stateDir, "server-ext.cnf");
+  openssl(["ecparam", "-genkey", "-name", "prime256v1", "-noout", "-out", serverKeyPath]);
+  openssl(["req", "-new", "-key", serverKeyPath, "-out", csrPath, "-subj", "/CN=localhost"]);
+  fs.writeFileSync(
+    extPath,
+    [
+      "authorityKeyIdentifier=keyid,issuer",
+      "basicConstraints=CA:FALSE",
+      "keyUsage=digitalSignature,keyEncipherment",
+      "extendedKeyUsage=serverAuth",
+      "subjectAltName=DNS:localhost,DNS:*.localhost"
+    ].join("\n") + "\n"
+  );
+  openssl([
+    "x509",
+    "-req",
+    "-in",
+    csrPath,
+    "-CA",
+    caCertPath,
+    "-CAkey",
+    caKeyPath,
+    "-CAcreateserial",
+    "-out",
+    serverCertPath,
+    "-days",
+    SERVER_VALIDITY_DAYS.toString(),
+    "-extfile",
+    extPath
+  ]);
+  for (const tmp of [csrPath, extPath]) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+    }
+  }
+  fs.chmodSync(serverKeyPath, 384);
+  fs.chmodSync(serverCertPath, 420);
+  fixOwnership(serverKeyPath, serverCertPath);
+  return { certPath: serverCertPath, keyPath: serverKeyPath };
+}
+function ensureCerts(stateDir) {
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  const caKeyPath = path.join(stateDir, CA_KEY_FILE);
+  const serverCertPath = path.join(stateDir, SERVER_CERT_FILE);
+  let caGenerated = false;
+  if (!fileExists(caCertPath) || !fileExists(caKeyPath) || !isCertValid(caCertPath)) {
+    generateCA(stateDir);
+    caGenerated = true;
+  }
+  if (caGenerated || !fileExists(serverCertPath) || !isCertValid(serverCertPath)) {
+    generateServerCert(stateDir);
+  }
+  return {
+    certPath: serverCertPath,
+    keyPath: path.join(stateDir, SERVER_KEY_FILE),
+    caPath: caCertPath,
+    caGenerated
+  };
+}
+function isCATrusted(stateDir) {
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  if (!fileExists(caCertPath)) return false;
+  if (process.platform === "darwin") {
+    return isCATrustedMacOS(caCertPath);
+  } else if (process.platform === "linux") {
+    return isCATrustedLinux(stateDir);
+  }
+  return false;
+}
+function isCATrustedMacOS(caCertPath) {
+  try {
+    const fingerprint = openssl(["x509", "-in", caCertPath, "-noout", "-fingerprint", "-sha1"]).trim().replace(/^.*=/, "").replace(/:/g, "").toLowerCase();
+    for (const keychain of [loginKeychainPath(), "/Library/Keychains/System.keychain"]) {
+      try {
+        const result = execFileSync("security", ["find-certificate", "-a", "-Z", keychain], {
+          encoding: "utf-8",
+          timeout: 5e3,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        if (result.toLowerCase().includes(fingerprint)) return true;
+      } catch {
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function loginKeychainPath() {
+  try {
+    const result = execFileSync("security", ["default-keychain"], {
+      encoding: "utf-8",
+      timeout: 5e3
+    }).trim();
+    const match = result.match(/"(.+)"/);
+    if (match) return match[1];
+  } catch {
+  }
+  const home = process.env.HOME || `/Users/${process.env.USER || "unknown"}`;
+  return path.join(home, "Library", "Keychains", "login.keychain-db");
+}
+function isCATrustedLinux(stateDir) {
+  const systemCertPath = `/usr/local/share/ca-certificates/portless-ca.crt`;
+  if (!fileExists(systemCertPath)) return false;
+  try {
+    const ours = fs.readFileSync(path.join(stateDir, CA_CERT_FILE), "utf-8").trim();
+    const installed = fs.readFileSync(systemCertPath, "utf-8").trim();
+    return ours === installed;
+  } catch {
+    return false;
+  }
+}
+var HOST_CERTS_DIR = "host-certs";
+function sanitizeHostForFilename(hostname) {
+  return hostname.replace(/\./g, "_").replace(/[^a-z0-9_-]/gi, "");
+}
+async function generateHostCertAsync(stateDir, hostname) {
+  const caKeyPath = path.join(stateDir, CA_KEY_FILE);
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  const hostDir = path.join(stateDir, HOST_CERTS_DIR);
+  if (!fs.existsSync(hostDir)) {
+    await fs.promises.mkdir(hostDir, { recursive: true, mode: 493 });
+    fixOwnership(hostDir);
+  }
+  const safeName = sanitizeHostForFilename(hostname);
+  const keyPath = path.join(hostDir, `${safeName}-key.pem`);
+  const certPath = path.join(hostDir, `${safeName}.pem`);
+  const csrPath = path.join(hostDir, `${safeName}.csr`);
+  const extPath = path.join(hostDir, `${safeName}-ext.cnf`);
+  await opensslAsync(["ecparam", "-genkey", "-name", "prime256v1", "-noout", "-out", keyPath]);
+  await opensslAsync(["req", "-new", "-key", keyPath, "-out", csrPath, "-subj", `/CN=${hostname}`]);
+  const sans = [`DNS:${hostname}`];
+  const parts = hostname.split(".");
+  if (parts.length >= 2) {
+    sans.push(`DNS:*.${parts.slice(1).join(".")}`);
+  }
+  await fs.promises.writeFile(
+    extPath,
+    [
+      "authorityKeyIdentifier=keyid,issuer",
+      "basicConstraints=CA:FALSE",
+      "keyUsage=digitalSignature,keyEncipherment",
+      "extendedKeyUsage=serverAuth",
+      `subjectAltName=${sans.join(",")}`
+    ].join("\n") + "\n"
+  );
+  await opensslAsync([
+    "x509",
+    "-req",
+    "-in",
+    csrPath,
+    "-CA",
+    caCertPath,
+    "-CAkey",
+    caKeyPath,
+    "-CAcreateserial",
+    "-out",
+    certPath,
+    "-days",
+    SERVER_VALIDITY_DAYS.toString(),
+    "-extfile",
+    extPath
+  ]);
+  for (const tmp of [csrPath, extPath]) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+    }
+  }
+  await fs.promises.chmod(keyPath, 384);
+  await fs.promises.chmod(certPath, 420);
+  fixOwnership(keyPath, certPath);
+  return { certPath, keyPath };
+}
+function isSimpleLocalhostSubdomain(hostname) {
+  const parts = hostname.split(".");
+  return parts.length === 2 && parts[1] === "localhost";
+}
+function createSNICallback(stateDir, defaultCert, defaultKey) {
+  const cache = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  const defaultCtx = tls.createSecureContext({ cert: defaultCert, key: defaultKey });
+  return (servername, cb) => {
+    if (servername === "localhost" || isSimpleLocalhostSubdomain(servername)) {
+      cb(null, defaultCtx);
+      return;
+    }
+    if (cache.has(servername)) {
+      cb(null, cache.get(servername));
+      return;
+    }
+    const safeName = sanitizeHostForFilename(servername);
+    const hostDir = path.join(stateDir, HOST_CERTS_DIR);
+    const certPath = path.join(hostDir, `${safeName}.pem`);
+    const keyPath = path.join(hostDir, `${safeName}-key.pem`);
+    if (fileExists(certPath) && fileExists(keyPath) && isCertValid(certPath)) {
+      try {
+        const ctx = tls.createSecureContext({
+          cert: fs.readFileSync(certPath),
+          key: fs.readFileSync(keyPath)
+        });
+        cache.set(servername, ctx);
+        cb(null, ctx);
+        return;
+      } catch {
+      }
+    }
+    if (pending.has(servername)) {
+      pending.get(servername).then((ctx) => cb(null, ctx)).catch((err) => cb(err instanceof Error ? err : new Error(String(err))));
+      return;
+    }
+    const promise = generateHostCertAsync(stateDir, servername).then(async (generated) => {
+      const [cert, key] = await Promise.all([
+        fs.promises.readFile(generated.certPath),
+        fs.promises.readFile(generated.keyPath)
+      ]);
+      return tls.createSecureContext({ cert, key });
+    });
+    pending.set(servername, promise);
+    promise.then((ctx) => {
+      cache.set(servername, ctx);
+      pending.delete(servername);
+      cb(null, ctx);
+    }).catch((err) => {
+      pending.delete(servername);
+      cb(err instanceof Error ? err : new Error(String(err)));
+    });
+  };
+}
+function trustCA(stateDir) {
+  const caCertPath = path.join(stateDir, CA_CERT_FILE);
+  if (!fileExists(caCertPath)) {
+    return { trusted: false, error: "CA certificate not found. Run with --https first." };
+  }
+  try {
+    if (process.platform === "darwin") {
+      const keychain = loginKeychainPath();
+      execFileSync(
+        "security",
+        ["add-trusted-cert", "-r", "trustRoot", "-k", keychain, caCertPath],
+        { stdio: "pipe", timeout: 3e4 }
+      );
+      return { trusted: true };
+    } else if (process.platform === "linux") {
+      const dest = "/usr/local/share/ca-certificates/portless-ca.crt";
+      fs.copyFileSync(caCertPath, dest);
+      execFileSync("update-ca-certificates", [], { stdio: "pipe", timeout: 3e4 });
+      return { trusted: true };
+    }
+    return { trusted: false, error: `Unsupported platform: ${process.platform}` };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("authorization") || message.includes("permission") || message.includes("EACCES")) {
+      return {
+        trusted: false,
+        error: "Permission denied. Try: sudo portless trust"
+      };
+    }
+    return { trusted: false, error: message };
+  }
+}
+
+// src/cli-utils.ts
+import * as fs2 from "fs";
 import * as http from "http";
+import * as https from "https";
 import * as net from "net";
 import * as os from "os";
-import * as path from "path";
+import * as path2 from "path";
 import * as readline from "readline";
 import { execSync, spawn } from "child_process";
 var DEFAULT_PROXY_PORT = 1355;
 var PRIVILEGED_PORT_THRESHOLD = 1024;
 var SYSTEM_STATE_DIR = "/tmp/portless";
-var USER_STATE_DIR = path.join(os.homedir(), ".portless");
+var USER_STATE_DIR = path2.join(os.homedir(), ".portless");
 var MIN_APP_PORT = 4e3;
 var MAX_APP_PORT = 4999;
 var RANDOM_PORT_ATTEMPTS = 50;
@@ -56,29 +431,59 @@ function resolveStateDir(port) {
 }
 function readPortFromDir(dir) {
   try {
-    const raw = fs.readFileSync(path.join(dir, "proxy.port"), "utf-8").trim();
+    const raw = fs2.readFileSync(path2.join(dir, "proxy.port"), "utf-8").trim();
     const port = parseInt(raw, 10);
     return isNaN(port) ? null : port;
   } catch {
     return null;
   }
 }
+var TLS_MARKER_FILE = "proxy.tls";
+function readTlsMarker(dir) {
+  try {
+    return fs2.existsSync(path2.join(dir, TLS_MARKER_FILE));
+  } catch {
+    return false;
+  }
+}
+function writeTlsMarker(dir, enabled) {
+  const markerPath = path2.join(dir, TLS_MARKER_FILE);
+  if (enabled) {
+    fs2.writeFileSync(markerPath, "1", { mode: 420 });
+  } else {
+    try {
+      fs2.unlinkSync(markerPath);
+    } catch {
+    }
+  }
+}
+function isHttpsEnvEnabled() {
+  const val = process.env.PORTLESS_HTTPS;
+  return val === "1" || val === "true";
+}
 async function discoverState() {
   if (process.env.PORTLESS_STATE_DIR) {
     const dir = process.env.PORTLESS_STATE_DIR;
     const port = readPortFromDir(dir) ?? getDefaultPort();
-    return { dir, port };
+    const tls2 = readTlsMarker(dir);
+    return { dir, port, tls: tls2 };
   }
   const userPort = readPortFromDir(USER_STATE_DIR);
-  if (userPort !== null && await isProxyRunning(userPort)) {
-    return { dir: USER_STATE_DIR, port: userPort };
+  if (userPort !== null) {
+    const tls2 = readTlsMarker(USER_STATE_DIR);
+    if (await isProxyRunning(userPort, tls2)) {
+      return { dir: USER_STATE_DIR, port: userPort, tls: tls2 };
+    }
   }
   const systemPort = readPortFromDir(SYSTEM_STATE_DIR);
-  if (systemPort !== null && await isProxyRunning(systemPort)) {
-    return { dir: SYSTEM_STATE_DIR, port: systemPort };
+  if (systemPort !== null) {
+    const tls2 = readTlsMarker(SYSTEM_STATE_DIR);
+    if (await isProxyRunning(systemPort, tls2)) {
+      return { dir: SYSTEM_STATE_DIR, port: systemPort, tls: tls2 };
+    }
   }
   const defaultPort = getDefaultPort();
-  return { dir: resolveStateDir(defaultPort), port: defaultPort };
+  return { dir: resolveStateDir(defaultPort), port: defaultPort, tls: false };
 }
 async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   if (minPort > maxPort) {
@@ -106,15 +511,17 @@ async function findFreePort(minPort = MIN_APP_PORT, maxPort = MAX_APP_PORT) {
   }
   throw new Error(`No free port found in range ${minPort}-${maxPort}`);
 }
-function isProxyRunning(port) {
+function isProxyRunning(port, tls2 = false) {
   return new Promise((resolve) => {
-    const req = http.request(
+    const requestFn = tls2 ? https.request : http.request;
+    const req = requestFn(
       {
         hostname: "127.0.0.1",
         port,
         path: "/",
         method: "HEAD",
-        timeout: SOCKET_TIMEOUT_MS
+        timeout: SOCKET_TIMEOUT_MS,
+        ...tls2 ? { rejectUnauthorized: false } : {}
       },
       (res) => {
         res.resume();
@@ -141,10 +548,10 @@ function findPidOnPort(port) {
     return null;
   }
 }
-async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS) {
+async function waitForProxy(port, maxAttempts = WAIT_FOR_PROXY_MAX_ATTEMPTS, intervalMs = WAIT_FOR_PROXY_INTERVAL_MS, tls2 = false) {
   for (let i = 0; i < maxAttempts; i++) {
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    if (await isProxyRunning(port)) {
+    if (await isProxyRunning(port, tls2)) {
       return true;
     }
   }
@@ -211,14 +618,15 @@ var DEBOUNCE_MS = 100;
 var POLL_INTERVAL_MS = 3e3;
 var EXIT_TIMEOUT_MS = 2e3;
 var SUDO_SPAWN_TIMEOUT_MS = 3e4;
-function startProxyServer(store, proxyPort) {
+function startProxyServer(store, proxyPort, tlsOptions) {
   store.ensureDir();
+  const isTls = !!tlsOptions;
   const routesPath = store.getRoutesPath();
-  if (!fs2.existsSync(routesPath)) {
-    fs2.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
+  if (!fs3.existsSync(routesPath)) {
+    fs3.writeFileSync(routesPath, "[]", { mode: FILE_MODE });
   }
   try {
-    fs2.chmodSync(routesPath, FILE_MODE);
+    fs3.chmodSync(routesPath, FILE_MODE);
   } catch {
   }
   let cachedRoutes = store.loadRoutes();
@@ -232,7 +640,7 @@ function startProxyServer(store, proxyPort) {
     }
   };
   try {
-    watcher = fs2.watch(routesPath, () => {
+    watcher = fs3.watch(routesPath, () => {
       if (debounceTimer) clearTimeout(debounceTimer);
       debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);
     });
@@ -243,7 +651,8 @@ function startProxyServer(store, proxyPort) {
   const server = createProxyServer({
     getRoutes: () => cachedRoutes,
     proxyPort,
-    onError: (msg) => console.error(chalk.red(msg))
+    onError: (msg) => console.error(chalk.red(msg)),
+    tls: tlsOptions
   });
   server.on("error", (err) => {
     if (err.code === "EADDRINUSE") {
@@ -264,9 +673,11 @@ function startProxyServer(store, proxyPort) {
     process.exit(1);
   });
   server.listen(proxyPort, () => {
-    fs2.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
-    fs2.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
-    console.log(chalk.green(`HTTP proxy listening on port ${proxyPort}`));
+    fs3.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE });
+    fs3.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE });
+    writeTlsMarker(store.dir, isTls);
+    const proto = isTls ? "HTTPS/2" : "HTTP";
+    console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}`));
   });
   let exiting = false;
   const cleanup = () => {
@@ -278,13 +689,14 @@ function startProxyServer(store, proxyPort) {
       watcher.close();
     }
     try {
-      fs2.unlinkSync(store.pidPath);
+      fs3.unlinkSync(store.pidPath);
     } catch {
     }
     try {
-      fs2.unlinkSync(store.portFilePath);
+      fs3.unlinkSync(store.portFilePath);
     } catch {
     }
+    writeTlsMarker(store.dir, false);
     server.close(() => process.exit(0));
     setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref();
   };
@@ -293,19 +705,19 @@ function startProxyServer(store, proxyPort) {
   console.log(chalk.cyan("\nProxy is running. Press Ctrl+C to stop.\n"));
   console.log(chalk.gray(`Routes file: ${store.getRoutesPath()}`));
 }
-async function stopProxy(store, proxyPort) {
+async function stopProxy(store, proxyPort, tls2) {
   const pidPath = store.pidPath;
   const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
   const sudoHint = needsSudo ? "sudo " : "";
-  if (!fs2.existsSync(pidPath)) {
-    if (await isProxyRunning(proxyPort)) {
+  if (!fs3.existsSync(pidPath)) {
+    if (await isProxyRunning(proxyPort, tls2)) {
       console.log(chalk.yellow(`PID file is missing but port ${proxyPort} is still in use.`));
       const pid = findPidOnPort(proxyPort);
       if (pid !== null) {
         try {
           process.kill(pid, "SIGTERM");
           try {
-            fs2.unlinkSync(store.portFilePath);
+            fs3.unlinkSync(store.portFilePath);
           } catch {
           }
           console.log(chalk.green(`Killed process ${pid}. Proxy stopped.`));
@@ -336,37 +748,37 @@ async function stopProxy(store, proxyPort) {
     return;
   }
   try {
-    const pid = parseInt(fs2.readFileSync(pidPath, "utf-8"), 10);
+    const pid = parseInt(fs3.readFileSync(pidPath, "utf-8"), 10);
     if (isNaN(pid)) {
       console.error(chalk.red("Corrupted PID file. Removing it."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       return;
     }
     try {
       process.kill(pid, 0);
     } catch {
       console.log(chalk.yellow("Proxy process is no longer running. Cleaning up stale files."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       try {
-        fs2.unlinkSync(store.portFilePath);
+        fs3.unlinkSync(store.portFilePath);
       } catch {
       }
       return;
     }
-    if (!await isProxyRunning(proxyPort)) {
+    if (!await isProxyRunning(proxyPort, tls2)) {
       console.log(
         chalk.yellow(
           `PID file exists but port ${proxyPort} is not listening. The PID may have been recycled.`
         )
       );
       console.log(chalk.yellow("Removing stale PID file."));
-      fs2.unlinkSync(pidPath);
+      fs3.unlinkSync(pidPath);
       return;
     }
     process.kill(pid, "SIGTERM");
-    fs2.unlinkSync(pidPath);
+    fs3.unlinkSync(pidPath);
     try {
-      fs2.unlinkSync(store.portFilePath);
+      fs3.unlinkSync(store.portFilePath);
     } catch {
     }
     console.log(chalk.green("Proxy stopped."));
@@ -383,7 +795,7 @@ async function stopProxy(store, proxyPort) {
     }
   }
 }
-function listRoutes(store, proxyPort) {
+function listRoutes(store, proxyPort, tls2) {
   const routes = store.loadRoutes();
   if (routes.length === 0) {
     console.log(chalk.yellow("No active routes."));
@@ -392,23 +804,23 @@ function listRoutes(store, proxyPort) {
   }
   console.log(chalk.blue.bold("\nActive routes:\n"));
   for (const route of routes) {
-    const url = formatUrl(route.hostname, proxyPort);
+    const url = formatUrl(route.hostname, proxyPort, tls2);
     console.log(
       `  ${chalk.cyan(url)}  ${chalk.gray("->")}  ${chalk.white(`localhost:${route.port}`)}  ${chalk.gray(`(pid ${route.pid})`)}`
     );
   }
   console.log();
 }
-async function runApp(store, proxyPort, stateDir, name, commandArgs) {
+async function runApp(store, proxyPort, stateDir, name, commandArgs, tls2) {
   const hostname = parseHostname(name);
-  const appUrl = formatUrl(hostname, proxyPort);
   console.log(chalk.blue.bold(`
 portless
 `));
   console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`));
-  if (!await isProxyRunning(proxyPort)) {
+  if (!await isProxyRunning(proxyPort, tls2)) {
     const defaultPort = getDefaultPort();
     const needsSudo = defaultPort < PRIVILEGED_PORT_THRESHOLD;
+    const wantHttps = isHttpsEnvEnabled();
     if (needsSudo) {
       if (!process.stdin.isTTY) {
         console.error(chalk.red("Proxy is not running."));
@@ -429,7 +841,9 @@ portless
         return;
       }
       console.log(chalk.yellow("Starting proxy (requires sudo)..."));
-      const result = spawnSync("sudo", [process.execPath, process.argv[1], "proxy", "start"], {
+      const startArgs = [process.execPath, process.argv[1], "proxy", "start"];
+      if (wantHttps) startArgs.push("--https");
+      const result = spawnSync("sudo", startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
       });
@@ -441,7 +855,9 @@ portless
       }
     } else {
       console.log(chalk.yellow("Starting proxy..."));
-      const result = spawnSync(process.execPath, [process.argv[1], "proxy", "start"], {
+      const startArgs = [process.argv[1], "proxy", "start"];
+      if (wantHttps) startArgs.push("--https");
+      const result = spawnSync(process.execPath, startArgs, {
         stdio: "inherit",
         timeout: SUDO_SPAWN_TIMEOUT_MS
       });
@@ -452,16 +868,18 @@ portless
         process.exit(1);
       }
     }
-    if (!await waitForProxy(defaultPort)) {
+    const autoTls = readTlsMarker(stateDir);
+    if (!await waitForProxy(defaultPort, void 0, void 0, autoTls)) {
       console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
-      const logPath = path2.join(stateDir, "proxy.log");
+      const logPath = path3.join(stateDir, "proxy.log");
       console.error(chalk.blue("Try starting the proxy manually to see the error:"));
       console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start`));
-      if (fs2.existsSync(logPath)) {
+      if (fs3.existsSync(logPath)) {
         console.error(chalk.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
     }
+    tls2 = autoTls;
     console.log(chalk.green("Proxy started in background"));
   } else {
     console.log(chalk.gray("-- Proxy is running"));
@@ -469,8 +887,9 @@ portless
   const port = await findFreePort();
   console.log(chalk.green(`-- Using port ${port}`));
   store.addRoute(hostname, port, process.pid);
+  const finalUrl = formatUrl(hostname, proxyPort, tls2);
   console.log(chalk.cyan.bold(`
-  -> ${appUrl}
+  -> ${finalUrl}
 `));
   console.log(chalk.gray(`Running: PORT=${port} ${commandArgs.join(" ")}
 `));
@@ -512,13 +931,16 @@ ${chalk.bold("Install:")}
 
 ${chalk.bold("Usage:")}
   ${chalk.cyan("portless proxy start")}             Start the proxy (background daemon)
+  ${chalk.cyan("portless proxy start --https")}     Start with HTTP/2 + TLS (auto-generates certs)
   ${chalk.cyan("portless proxy start -p 80")}       Start on port 80 (requires sudo)
   ${chalk.cyan("portless proxy stop")}              Stop the proxy
   ${chalk.cyan("portless <name> <cmd>")}            Run your app through the proxy
   ${chalk.cyan("portless list")}                    Show active routes
+  ${chalk.cyan("portless trust")}                   Add local CA to system trust store
 
 ${chalk.bold("Examples:")}
   portless proxy start                # Start proxy on port 1355
+  portless proxy start --https        # Start with HTTPS/2 (faster page loads)
   portless myapp next dev             # -> http://myapp.localhost:1355
   portless api.myapp pnpm start       # -> http://api.myapp.localhost:1355
 
@@ -535,13 +957,23 @@ ${chalk.bold("How it works:")}
   3. Access via http://<name>.localhost:1355
   4. .localhost domains auto-resolve to 127.0.0.1
 
+${chalk.bold("HTTP/2 + HTTPS:")}
+  Use --https for HTTP/2 multiplexing (faster dev server page loads).
+  On first use, portless generates a local CA and adds it to your
+  system trust store. No browser warnings. No sudo required on macOS.
+
 ${chalk.bold("Options:")}
   -p, --port <number>           Port for the proxy to listen on (default: 1355)
                                 Ports < 1024 require sudo
+  --https                       Enable HTTP/2 + TLS with auto-generated certs
+  --cert <path>                 Use a custom TLS certificate (implies --https)
+  --key <path>                  Use a custom TLS private key (implies --https)
+  --no-tls                      Disable HTTPS (overrides PORTLESS_HTTPS)
   --foreground                  Run proxy in foreground (for debugging)
 
 ${chalk.bold("Environment variables:")}
   PORTLESS_PORT=<number>        Override the default proxy port (e.g. in .bashrc)
+  PORTLESS_HTTPS=1              Always enable HTTPS (set in .bashrc / .zshrc)
   PORTLESS_STATE_DIR=<path>     Override the state directory
   PORTLESS=0 | PORTLESS=skip    Run command directly without proxy
 
@@ -552,24 +984,40 @@ ${chalk.bold("Skip portless:")}
     process.exit(0);
   }
   if (args[0] === "--version" || args[0] === "-v") {
-    console.log("0.3.0");
+    console.log("0.4.0");
     process.exit(0);
   }
+  if (args[0] === "trust") {
+    const { dir: dir2 } = await discoverState();
+    const result = trustCA(dir2);
+    if (result.trusted) {
+      console.log(chalk.green("Local CA added to system trust store."));
+      console.log(chalk.gray("Browsers will now trust portless HTTPS certificates."));
+    } else {
+      console.error(chalk.red(`Failed to trust CA: ${result.error}`));
+      if (result.error?.includes("sudo")) {
+        console.error(chalk.blue("Run with sudo:"));
+        console.error(chalk.cyan("  sudo portless trust"));
+      }
+      process.exit(1);
+    }
+    return;
+  }
   if (args[0] === "list") {
-    const { dir: dir2, port: port2 } = await discoverState();
+    const { dir: dir2, port: port2, tls: tls3 } = await discoverState();
     const store2 = new RouteStore(dir2, {
       onWarning: (msg) => console.warn(chalk.yellow(msg))
     });
-    listRoutes(store2, port2);
+    listRoutes(store2, port2, tls3);
     return;
   }
   if (args[0] === "proxy") {
     if (args[1] === "stop") {
-      const { dir: dir2, port: port2 } = await discoverState();
+      const { dir: dir2, port: port2, tls: tls3 } = await discoverState();
       const store3 = new RouteStore(dir2, {
         onWarning: (msg) => console.warn(chalk.yellow(msg))
       });
-      await stopProxy(store3, port2);
+      await stopProxy(store3, port2, tls3);
       return;
     }
     if (args[1] !== "start") {
@@ -577,6 +1025,7 @@ ${chalk.bold("Skip portless:")}
 ${chalk.bold("Usage: portless proxy <command>")}
 
   ${chalk.cyan("portless proxy start")}                Start the proxy (daemon)
+  ${chalk.cyan("portless proxy start --https")}        Start with HTTP/2 + TLS
   ${chalk.cyan("portless proxy start --foreground")}   Start in foreground (for debugging)
   ${chalk.cyan("portless proxy start -p 80")}          Start on port 80 (requires sudo)
   ${chalk.cyan("portless proxy stop")}                 Stop the proxy
@@ -602,6 +1051,32 @@ ${chalk.bold("Usage: portless proxy <command>")}
         process.exit(1);
       }
     }
+    const hasNoTls = args.includes("--no-tls");
+    const hasHttpsFlag = args.includes("--https");
+    const wantHttps = !hasNoTls && (hasHttpsFlag || isHttpsEnvEnabled());
+    let customCertPath = null;
+    let customKeyPath = null;
+    const certIdx = args.indexOf("--cert");
+    if (certIdx !== -1) {
+      customCertPath = args[certIdx + 1] || null;
+      if (!customCertPath || customCertPath.startsWith("-")) {
+        console.error(chalk.red("Error: --cert requires a file path."));
+        process.exit(1);
+      }
+    }
+    const keyIdx = args.indexOf("--key");
+    if (keyIdx !== -1) {
+      customKeyPath = args[keyIdx + 1] || null;
+      if (!customKeyPath || customKeyPath.startsWith("-")) {
+        console.error(chalk.red("Error: --key requires a file path."));
+        process.exit(1);
+      }
+    }
+    if (customCertPath && !customKeyPath || !customCertPath && customKeyPath) {
+      console.error(chalk.red("Error: --cert and --key must be used together."));
+      process.exit(1);
+    }
+    const useHttps = wantHttps || !!(customCertPath && customKeyPath);
     const stateDir = resolveStateDir(proxyPort);
     const store2 = new RouteStore(stateDir, {
       onWarning: (msg) => console.warn(chalk.yellow(msg))
@@ -626,23 +1101,90 @@ ${chalk.bold("Usage: portless proxy <command>")}
       console.error(chalk.cyan("  portless proxy start"));
       process.exit(1);
     }
+    let tlsOptions;
+    if (useHttps) {
+      store2.ensureDir();
+      if (customCertPath && customKeyPath) {
+        try {
+          const cert = fs3.readFileSync(customCertPath);
+          const key = fs3.readFileSync(customKeyPath);
+          const certStr = cert.toString("utf-8");
+          const keyStr = key.toString("utf-8");
+          if (!certStr.includes("-----BEGIN CERTIFICATE-----")) {
+            console.error(chalk.red(`Error: ${customCertPath} is not a valid PEM certificate.`));
+            console.error(chalk.gray("Expected a file starting with -----BEGIN CERTIFICATE-----"));
+            process.exit(1);
+          }
+          if (!keyStr.match(/-----BEGIN [\w\s]*PRIVATE KEY-----/)) {
+            console.error(chalk.red(`Error: ${customKeyPath} is not a valid PEM private key.`));
+            console.error(
+              chalk.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----")
+            );
+            process.exit(1);
+          }
+          tlsOptions = { cert, key };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(chalk.red(`Error reading certificate files: ${message}`));
+          process.exit(1);
+        }
+      } else {
+        console.log(chalk.gray("Ensuring TLS certificates..."));
+        const certs = ensureCerts(stateDir);
+        if (certs.caGenerated) {
+          console.log(chalk.green("Generated local CA certificate."));
+        }
+        if (!isCATrusted(stateDir)) {
+          console.log(chalk.yellow("Adding CA to system trust store..."));
+          const trustResult = trustCA(stateDir);
+          if (trustResult.trusted) {
+            console.log(
+              chalk.green("CA added to system trust store. Browsers will trust portless certs.")
+            );
+          } else {
+            console.warn(chalk.yellow("Could not add CA to system trust store."));
+            if (trustResult.error) {
+              console.warn(chalk.gray(trustResult.error));
+            }
+            console.warn(
+              chalk.yellow("Browsers will show certificate warnings. To fix this later, run:")
+            );
+            console.warn(chalk.cyan("  portless trust"));
+          }
+        }
+        const cert = fs3.readFileSync(certs.certPath);
+        const key = fs3.readFileSync(certs.keyPath);
+        tlsOptions = {
+          cert,
+          key,
+          SNICallback: createSNICallback(stateDir, cert, key)
+        };
+      }
+    }
     if (isForeground) {
       console.log(chalk.blue.bold("\nportless proxy\n"));
-      startProxyServer(store2, proxyPort);
+      startProxyServer(store2, proxyPort, tlsOptions);
       return;
     }
     store2.ensureDir();
-    const logPath = path2.join(stateDir, "proxy.log");
-    const logFd = fs2.openSync(logPath, "a");
+    const logPath = path3.join(stateDir, "proxy.log");
+    const logFd = fs3.openSync(logPath, "a");
     try {
       try {
-        fs2.chmodSync(logPath, FILE_MODE);
+        fs3.chmodSync(logPath, FILE_MODE);
       } catch {
       }
       const daemonArgs = [process.argv[1], "proxy", "start", "--foreground"];
       if (portFlagIndex !== -1) {
         daemonArgs.push("--port", proxyPort.toString());
       }
+      if (useHttps) {
+        if (customCertPath && customKeyPath) {
+          daemonArgs.push("--cert", customCertPath, "--key", customKeyPath);
+        } else {
+          daemonArgs.push("--https");
+        }
+      }
       const child = spawn2(process.execPath, daemonArgs, {
         detached: true,
         stdio: ["ignore", logFd, logFd],
@@ -650,19 +1192,20 @@ ${chalk.bold("Usage: portless proxy <command>")}
       });
       child.unref();
     } finally {
-      fs2.closeSync(logFd);
+      fs3.closeSync(logFd);
     }
-    if (!await waitForProxy(proxyPort)) {
+    if (!await waitForProxy(proxyPort, void 0, void 0, useHttps)) {
       console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen)."));
       console.error(chalk.blue("Try starting the proxy in the foreground to see the error:"));
       const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD;
       console.error(chalk.cyan(`  ${needsSudo ? "sudo " : ""}portless proxy start --foreground`));
-      if (fs2.existsSync(logPath)) {
+      if (fs3.existsSync(logPath)) {
         console.error(chalk.gray(`Logs: ${logPath}`));
       }
       process.exit(1);
     }
-    console.log(chalk.green(`Proxy started on port ${proxyPort}`));
+    const proto = useHttps ? "HTTPS/2" : "HTTP";
+    console.log(chalk.green(`${proto} proxy started on port ${proxyPort}`));
     return;
   }
   const name = args[0];
@@ -675,11 +1218,11 @@ ${chalk.bold("Usage: portless proxy <command>")}
     console.error(chalk.cyan("  portless myapp next dev"));
     process.exit(1);
   }
-  const { dir, port } = await discoverState();
+  const { dir, port, tls: tls2 } = await discoverState();
   const store = new RouteStore(dir, {
     onWarning: (msg) => console.warn(chalk.yellow(msg))
   });
-  await runApp(store, port, dir, name, commandArgs);
+  await runApp(store, port, dir, name, commandArgs, tls2);
 }
 main().catch((err) => {
   const message = err instanceof Error ? err.message : String(err);

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+import * as node_tls from 'node:tls';
 import * as http from 'node:http';
+import * as net from 'node:net';
 
 /** Route info used by the proxy server to map hostnames to ports. */
 interface RouteInfo {
@@ -12,18 +14,31 @@ interface ProxyServerOptions {
     proxyPort: number;
     /** Optional error logger; defaults to console.error. */
     onError?: (message: string) => void;
+    /** When provided, enables HTTP/2 over TLS (HTTPS). */
+    tls?: {
+        cert: Buffer;
+        key: Buffer;
+        /** SNI callback for per-hostname certificate selection. */
+        SNICallback?: (servername: string, cb: (err: Error | null, ctx?: node_tls.SecureContext) => void) => void;
+    };
 }
 
 /** Response header used to identify a portless proxy (for health checks). */
 declare const PORTLESS_HEADER = "X-Portless";
+/** Server type returned by createProxyServer (plain HTTP/1.1 or net.Server TLS wrapper). */
+type ProxyServer = http.Server | net.Server;
 /**
  * Create an HTTP proxy server that routes requests based on the Host header.
  *
  * Uses Node's built-in http module for proxying (no external dependencies).
  * The `getRoutes` callback is invoked on every request so callers can provide
  * either a static list or a live-updating one.
+ *
+ * When `tls` is provided, creates an HTTP/2 secure server with HTTP/1.1
+ * fallback (`allowHTTP1: true`). This enables HTTP/2 multiplexing for
+ * browsers while keeping WebSocket upgrades working over HTTP/1.1.
  */
-declare function createProxyServer(options: ProxyServerOptions): http.Server;
+declare function createProxyServer(options: ProxyServerOptions): ProxyServer;
 
 /** File permission mode for route and state files. */
 declare const FILE_MODE = 420;
@@ -37,7 +52,8 @@ interface RouteMapping extends RouteInfo {
  * Supports file locking and stale-route cleanup.
  */
 declare class RouteStore {
-    private readonly dir;
+    /** The state directory path. */
+    readonly dir: string;
     private readonly routesPath;
     private readonly lockPath;
     readonly pidPath: string;
@@ -72,13 +88,14 @@ declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
  */
 declare function escapeHtml(str: string): string;
 /**
- * Format a .localhost URL, including the port only when it is not 80 (standard HTTP).
+ * Format a .localhost URL. Omits the port when it matches the protocol default
+ * (80 for HTTP, 443 for HTTPS).
  */
-declare function formatUrl(hostname: string, proxyPort: number): string;
+declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
 /**
  * Parse and normalize a hostname input for use as a .localhost subdomain.
  * Strips protocol prefixes, validates characters, and appends .localhost if needed.
  */
 declare function parseHostname(input: string): string;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, formatUrl, isErrnoException, parseHostname };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, formatUrl, isErrnoException, parseHostname };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-Y5OVKUR4.js";
+} from "./chunk-VRBD6YAY.js";
 export {
   DIR_MODE,
   FILE_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",