Initial

.github/workflows/node.js.yml

@@ -0,0 +1,31 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Node.js CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [22.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

.gitignore

@@ -0,0 +1,8 @@
+/node_modules
+/dist
+/build
+# npm pack output
+/*.tgz
+/*.crt
+/*.key
+/.env

Caddyfile

@@ -0,0 +1,3 @@
+{$TUNNEL_DOMAIN} {
+  reverse_proxy h2tunnel:80
+}

Dockerfile

@@ -0,0 +1,2 @@
+FROM node:22
+RUN npm install -g [email protected]

LICENSE

@@ -0,0 +1,8 @@
+Copyright 2024 Alexei Boronine
+
+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.
+

README.md

@@ -0,0 +1,80 @@
+# h2tunnel
+
+![NPM Version](https://img.shields.io/npm/v/h2tunnel)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/h2tunnel/h2tunnel/node.js.yml)
+
+
+A low level tool for a popular "tunneling" workflow, similar to the proprietary [ngrok](https://ngrok.com/)
+or the openssh-based `ssh -L` solution. All in [less than 600 LOC](https://github.com/boronine/h2tunnel/blob/main/src/h2tunnel.ts)
+with no dependencies.
+
+![Diagram](https://raw.githubusercontent.com/boronine/h2tunnel/main/diagram.drawio.svg)]
+
+## The "tunneling" workflow
+
+This workflow allows exposing your localhost development server to the internet. This requires a server component 
+hosted on a public IP address, and a client component running on your local machine. The client establishes a tunnel
+to the server, and the server acts as a reverse proxy, tunneling requests back to your local machine.
+
+## Usage
+
+### Forward localhost:8000 to http://example.com
+
+Generate `.key` and `.crt` files. These will be used by both client and server to authenticate each other.
+
+```bash
+openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -days 3650 -nodes -keyout h2tunnel.key -out h2tunnel.crt -subj "/CN=example.com"
+```
+
+On your server (example.com), we will be listening for tunnel connections on port 15001, and providing an HTTP proxy 
+on port 80. Make sure these are open in your firewall. `--mux-listen-port` can be any available port, it is necessary
+to run an HTTP2 multiplexer on localhost.
+
+```bash
+sudo h2tunnel server --crt h2tunnel.crt --key h2tunnel.key --tunnel-listen-ip 0.0.0.0 --tunnel-listen-port 15001 --proxy-listen-port 80 --proxy-listen-ip 0.0.0.0 --mux-listen-port=15002
+````
+
+On your local machine, we will connect to the tunnel and forward a local HTTP server on port 8000. `--demux-listen-port`
+can be any available port, it is necessary to run an HTTP2 demultiplexer on localhost.
+
+```bash
+python3 -m http.server # runs on port 8000
+h2tunnel client --key h2tunnel.key --crt h2tunnel.crt --tunnel-host=example.com --tunnel-port=15001 --local-http-port=8000 --demux-listen-port=15004
+```
+
+### Forward localhost:8000 to https://example.com
+
+This is the same as the previous example, but with an extra layer: a [Caddy](https://caddyserver.com/) reverse proxy
+that will auto-provision TLS certificates for your domain. This is useful if you want to expose an HTTPS server.
+
+The client command line is the same as before, but for the server we will use a docker compose setup.
+
+Specify your domain in the `.env` file:
+
+```
+TUNNEL_DOMAIN=example.com
+```
+
+Push the necessary files to the server:
+
+```bash
+scp .env Caddyfile Dockerfile docker-compose.yml h2tunnel.crt h2tunnel.key example.com:/home/myuser
+```
+
+Start the server:
+
+```bash
+docker compose up 
+```
+
+## Testing
+
+```bash
+npm run test
+```
+
+# Releasing
+
+```bash
+npm run build && npm version prerelease --preid=alpha && npm publish
+```

diagram.drawio

@@ -0,0 +1,52 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36" version="24.7.17">
+  <diagram name="Page-1" id="Whb8RC3Au8cvX3wrGirA">
+    <mxGraphModel dx="931" dy="605" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-29" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;remote&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="480" y="30" width="260" height="300" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-25" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;+ HTTP2 Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="610" y="80" width="120" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-27" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;localhost&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="70" y="30" width="390" height="300" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-28" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP1 Server&lt;/span&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="80" y="140" width="120" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-21" value="&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;HTTP2 Server&lt;/span&gt;&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;+ HTTP1 Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="210" y="80" width="120" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-16" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS&lt;/span&gt;&lt;span style=&quot;text-wrap: nowrap; background-color: initial;&quot;&gt;&amp;nbsp;Client&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="330" y="80" width="120" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-5" value="" style="ellipse;whiteSpace=wrap;html=1;align=center;aspect=fixed;fillColor=none;strokeColor=none;resizable=0;perimeter=centerPerimeter;rotatable=0;allowArrows=0;points=[];outlineConnect=1;" vertex="1" parent="1">
+          <mxGeometry x="470" y="130" width="10" height="10" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-13" value="&lt;div&gt;&lt;span style=&quot;text-wrap: nowrap;&quot;&gt;TLS Server&lt;/span&gt;&lt;/div&gt;" style="html=1;whiteSpace=wrap;verticalAlign=top;" vertex="1" parent="1">
+          <mxGeometry x="490" y="80" width="120" height="240" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-2" value="initiation + authentication + encryption" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0;dx=23.08;notch=20.25;rotation=0;fillColor=#fff2cc;strokeColor=#d6b656;horizontal=1;" vertex="1" parent="1">
+          <mxGeometry x="340" y="110" width="260" height="190" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-19" value="multiplexing&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=top;shape=mxgraph.arrows2.arrow;dy=0;dx=12.75;notch=19.75;flipH=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+          <mxGeometry x="220" y="140" width="500" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-26" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="90" y="170" width="680" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-31" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="90" y="200" width="680" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-32" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="90" y="230" width="680" height="20" as="geometry" />
+        </mxCell>
+        <mxCell id="e_OSxrDLTewV0Rg9lFOJ-33" value="" style="html=1;shadow=0;dashed=0;align=center;verticalAlign=middle;shape=mxgraph.arrows2.arrow;dy=0;dx=11.92;notch=9.75;flipH=1;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="90" y="260" width="680" height="20" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docker-compose.yml

@@ -0,0 +1,35 @@
+services:
+  caddy:
+    image: caddy
+    restart: unless-stopped
+    cap_add:
+      - NET_ADMIN
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    depends_on:
+      - h2tunnel
+    # Use this to provide TUNNEL_DOMAIN
+    env_file: .env
+    volumes:
+      - $PWD/Caddyfile:/etc/caddy/Caddyfile
+      - /data
+      - /config
+  h2tunnel:
+    build: .
+    restart: unless-stopped
+    cap_add:
+      - NET_ADMIN
+    secrets:
+      - crt
+      - key
+    ports:
+      - "80" # for caddy
+      - "15001:15001"
+    command: h2tunnel server --crt=/run/secrets/crt --key=/run/secrets/key --tunnel-listen-ip=0.0.0.0 --tunnel-listen-port=15001 --proxy-listen-port=80 --proxy-listen-ip=0.0.0.0 --mux-listen-port=15002
+secrets:
+  crt:
+    file: ./h2tunnel.crt
+  key:
+    file: ./h2tunnel.key

package.json

@@ -0,0 +1,48 @@
+{
+  "name": "h2tunnel",
+  "description": "localhost tunnel using HTTP2 multiplexing",
+  "version": "0.0.1-alpha.6",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Alexei Boronine",
+    "email": "[email protected]",
+    "url": "https://www.boronine.com"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "typescript": "^5.6.3",
+    "prettier": "^3.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boronine/h2tunnel.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/h2tunnel.d.ts",
+      "import": "./build/h2tunnel.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "build/h2tunnel.js",
+    "build/h2tunnel.d.ts",
+    "build/cli.js",
+    "build/cli.d.ts"
+  ],
+  "bin": {
+    "h2tunnel": "./build/cli.js"
+  },
+  "scripts": {
+    "format": "npx prettier --write .",
+    "build": "npx tsc",
+    "test": "npx tsc && node --enable-source-maps --experimental-test-coverage --test build/h2tunnel.test.js",
+    "dist": "npm pack"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}