hbeam 0.1.8 → 0.1.9-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 A 1-to-1 end-to-end encrypted pipe over [HyperDHT](https://github.com/holepunchto/hyperdht).
 
-Pipe data between two machines through a peer-to-peer encrypted tunnel. No server, no accounts. Just a shared passphrase or a persistent identity.
+Pipe data between two machines through a peer-to-peer encrypted tunnel. No server, no accounts. By default, hbeam uses your persistent identity; use `--temp` for one-time passphrase sessions.
 
 ## Install
 
@@ -12,55 +12,40 @@ npm install -g hbeam
 
 ## CLI
 
-### Send
+### Send (identity by default)
 
-Pipe data in and hbeam generates a passphrase (copied to your clipboard):
+Pipe data in and hbeam announces using your persistent identity (created on first use at `~/.config/hbeam/identity.json`):
 
 ```bash
 echo 'hello world' | hbeam
 ```
 
-```
-  HBEAM ·····
-  PASSPHRASE
-  nbsk4wlqmfuw...
-```
-
 ### Receive
 
-Pass the passphrase on the other machine to receive:
+Connect a Beam stream by saved name:
 
 ```bash
-hbeam nbsk4wlqmfuw...
+hbeam connect workserver
 ```
 
-### Listen with a known passphrase
+### One-time passphrase mode
 
-Re-use a specific passphrase with `--listen`:
+Use `--temp` when you want a throwaway passphrase flow:
 
 ```bash
-echo 'hello again' | hbeam <passphrase> --listen
-```
-
-### Listen with a persistent identity
+# Generate and announce a one-time passphrase
+echo 'hello world' | hbeam --temp
 
-Listen on a stable public key instead of a one-off passphrase. Your identity is created automatically on first use and stored at `~/.config/hbeam/identity.json`:
+# Reuse a known passphrase and announce on it
+echo 'hello again' | hbeam <passphrase> --temp
 
-```bash
-hbeam --listen
+# Connect to an existing passphrase
+hbeam <passphrase>
 ```
 
-```
-  HBEAM ·····
-  PUBLIC KEY
-  a1b2c3d4e5f6...
-```
-
-Share your public key once — peers can reconnect any time without a new passphrase.
-
 ### Address book
 
-Save peers by name so you don't have to remember public keys:
+Save peers by name so you do not have to remember public keys:
 
 ```bash
 # Add a peer
@@ -99,6 +84,75 @@ hbeam whoami
   a1b2c3d4e5f6...
 ```
 
+### Expose - TCP over P2P
+
+Expose a local TCP service to a remote peer:
+
+```bash
+# Reverse proxy: expose localhost:3000 using your identity
+hbeam expose 3000
+
+# Reverse proxy: expose localhost:3000 with a one-time passphrase
+hbeam expose 3000 --temp
+```
+
+```
+  HBEAM ···
+
+  ANNOUNCING
+  a1b2c3d4e5f6...
+  ONLINE [96.9.225.80:34725]
+  FORWARDING localhost:3000
+```
+
+Access a remote peer's service locally:
+
+```bash
+# Open a remote app from a saved peer in your browser
+hbeam open workserver
+
+# Open a remote app by passphrase (one-time mode)
+hbeam open <passphrase> --temp
+
+# Open on a specific local port
+hbeam open workserver -p 8080
+```
+
+```
+  HBEAM ···
+
+  CONNECTING workserver
+  ONLINE [96.9.225.80:34725]
+  OPENED http://127.0.0.1:8080/
+```
+
+Any TCP traffic (HTTP, SSH, databases, etc.) can be tunneled. Both sides are end-to-end encrypted via Noise.
+
+### Gateway - local HTTP router for peers
+
+Run a local HTTP gateway that maps `{peer}.localhost` to remote peers over P2P:
+
+```bash
+# Start gateway on port 9000
+hbeam gateway -p 9000
+
+# Browser or curl traffic routed to address-book peer "workserver"
+open http://workserver.localhost:9000/
+curl http://workserver.localhost:9000/health
+
+# Route directly to a raw public key
+curl http://a1b2c3d4e5f6...localhost:9000/
+```
+
+You can also run gateway in one-time mode:
+
+```bash
+hbeam gateway -p 9000 --temp
+```
+
+The gateway resolves subdomains with the same target rules as `hbeam open`: hex public key, address-book name, then passphrase.
+Use this when you want one long-running local router for multiple peers. For single-peer app access, use `hbeam open`.
+
 ### Serve a single file
 
 Serve one file over an encrypted hbeam session:
@@ -107,10 +161,10 @@ Serve one file over an encrypted hbeam session:
 hbeam serve ./report.pdf
 ```
 
-This announces a one-time passphrase by default. To serve from your persistent identity instead:
+This serves from your persistent identity by default. For one-time passphrase mode instead:
 
 ```bash
-hbeam serve ./report.pdf --listen
+hbeam serve ./report.pdf --temp
 ```
 
 On the receiving side, connect normally (`hbeam <passphrase>` or `hbeam connect <name>`). hbeam detects the incoming file header and prompts where to save it. Use `-o` to skip the prompt:
@@ -129,23 +183,30 @@ hbeam <passphrase> > report.pdf
 ### Options
 
 ```
--l, --listen   Listen using passphrase or identity
+-t, --temp     Use one-time passphrase mode
 -o, --output   Save incoming file to a specific path
+-p, --port     Local listen port (open/gateway mode)
+--host         Target/listen host (expose mode, default: localhost)
 -h, --help     Show help
 -v, --version  Show version
 ```
 
 ## How it works
 
+Identity mode (default):
+
+1. A persistent Noise keypair is loaded from `~/.config/hbeam/identity.json` (or created on first use).
+2. A HyperDHT node announces (server) or connects (client) using that keypair.
+3. The Noise protocol negotiates an encrypted session between the two peers.
+4. Data flows through a `streamx` duplex stream - stdin/stdout on the CLI, or any readable/writable in code.
+
+One-time mode (`--temp`):
+
 1. A 32-byte random seed is generated and encoded as a base32 passphrase.
-2. A Noise keypair is deterministically derived from the passphrase using `sodium-universal`.
+2. A Noise keypair is deterministically derived from that passphrase using `sodium-universal`.
 3. An ephemeral HyperDHT node announces (server) or connects (client) using that keypair.
-4. The Noise protocol negotiates an encrypted session between the two peers.
-5. Data flows through a `streamx` duplex stream — stdin/stdout on the CLI, or any readable/writable in code.
-
-When using identity mode (`--listen` without a passphrase, or `connect`), a persistent keypair is loaded from `~/.config/hbeam/identity.json` instead of deriving one from a passphrase. The connection is still end-to-end encrypted via Noise.
 
-All traffic is end-to-end encrypted. The DHT is only used for peer discovery; it never sees the plaintext.
+All traffic is end-to-end encrypted. The DHT is only used for peer discovery; it never sees plaintext.
 
 ## Requirements