fix(readme): update README: add issue reporting/security section, document connection tokens and token utilities, clarify architecture/API and improve examples/formatting

changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026-02-18 - 3.1.1 - fix(readme)
+update README: add issue reporting/security section, document connection tokens and token utilities, clarify architecture/API and improve examples/formatting
+
+- Added an 'Issue Reporting and Security' section linking to community.foss.global for bug/security reports and contributor onboarding.
+- Documented connection tokens: encodeConnectionToken/decodeConnectionToken utilities, token format (base64url), and examples for hub and edge provisioning.
+- Clarified Hub/Edge usage and examples: condensed event handlers, added token-based start() example, and provided explicit config alternative.
+- Improved README formatting: added emojis, rephrased architecture descriptions, fixed wording and license path capitalization, and expanded example scenarios and interfaces.
+
 ## 2026-02-17 - 3.1.0 - feat(edge)
 support connection tokens when starting an edge and add token encode/decode utilities
 

readme.md

@@ -2,13 +2,17 @@
 
 Edge ingress tunnel for DcRouter — accepts incoming TCP connections at the network edge and tunnels them to a DcRouter SmartProxy instance, preserving the original client IP via PROXY protocol v1.
 
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 ## Install
 
 ```sh
 pnpm install @serve.zone/remoteingress
 ```
 
-## Architecture
+## 🏗️ Architecture
 
 `@serve.zone/remoteingress` uses a **Hub/Edge** topology with a high-performance Rust core and a TypeScript API surface:
 
@@ -17,8 +21,8 @@ pnpm install @serve.zone/remoteingress
 │   Network Edge      │  ◄══════════════════════════►  │   Private Cluster   │
 │                     │   (multiplexed frames +        │                     │
 │  RemoteIngressEdge  │    shared-secret auth)         │  RemoteIngressHub   │
-│  Listens on :80,:443│                                │  Forwards to        │
+│  Accepts client TCP │                                │  Forwards to        │
-│  Accepts client TCP │                                │  SmartProxy on      │
+│  connections        │                                │  SmartProxy on      │
 │                     │                                │  local ports        │
 └─────────────────────┘                                └─────────────────────┘
         ▲                                                       │
@@ -28,26 +32,27 @@ pnpm install @serve.zone/remoteingress
 
 | Component | Role |
 |-----------|------|
-| **RemoteIngressEdge** | Deployed at the network edge (e.g. a VPS or cloud instance). Listens on public ports, accepts raw TCP connections, and multiplexes them over a single TLS tunnel to the hub. |
+| **RemoteIngressEdge** | Deployed at the network edge (e.g. a VPS or cloud instance). Accepts raw TCP connections and multiplexes them over a single TLS tunnel to the hub. |
 | **RemoteIngressHub** | Deployed alongside DcRouter/SmartProxy in a private cluster. Accepts edge connections, demuxes streams, and forwards each to SmartProxy with a PROXY protocol v1 header so the real client IP is preserved. |
 | **Rust Binary** (`remoteingress-bin`) | The performance-critical networking core. Managed via `@push.rocks/smartrust` RustBridge IPC — you never interact with it directly. Cross-compiled for `linux/amd64` and `linux/arm64`. |
 
-### Key Features
+### ✨ Key Features
 
-- **TLS-encrypted tunnel** between edge and hub (auto-generated self-signed cert or bring your own)
+- 🔒 **TLS-encrypted tunnel** between edge and hub (auto-generated self-signed cert or bring your own)
-- **Multiplexed streams** — thousands of client connections flow over a single tunnel
+- 🔀 **Multiplexed streams** — thousands of client connections flow over a single tunnel
-- **PROXY protocol v1** — SmartProxy sees the real client IP, not the tunnel IP
+- 🌐 **PROXY protocol v1** — SmartProxy sees the real client IP, not the tunnel IP
-- **Shared-secret authentication** — edges must present valid credentials to connect
+- 🔑 **Shared-secret authentication** — edges must present valid credentials to connect
-- **STUN-based public IP discovery** — the edge automatically discovers its public IP via Cloudflare STUN
+- 🎫 **Connection tokens** — encode all connection details into a single opaque string
-- **Auto-reconnect** with exponential backoff if the tunnel drops
+- 📡 **STUN-based public IP discovery** — the edge automatically discovers its public IP via Cloudflare STUN
-- **Event-driven** — both Hub and Edge extend `EventEmitter` for real-time monitoring
+- 🔄 **Auto-reconnect** with exponential backoff if the tunnel drops
-- **Rust core** — all frame encoding, TLS, and TCP proxying happen in native code for maximum throughput
+- 📣 **Event-driven** — both Hub and Edge extend `EventEmitter` for real-time monitoring
+- ⚡ **Rust core** — all frame encoding, TLS, and TCP proxying happen in native code for maximum throughput
 
-## Usage
+## 🚀 Usage
 
 Both classes are imported from the package and communicate with the Rust binary under the hood. All you need to do is configure and start them.
 
-### Setting up the Hub (private cluster side)
+### Setting Up the Hub (Private Cluster Side)
 
 ```typescript
 import { RemoteIngressHub } from '@serve.zone/remoteingress';
@@ -95,32 +100,45 @@ console.log(status);
 await hub.stop();
 ```
 
-### Setting up the Edge (network edge side)
+### Setting Up the Edge (Network Edge Side)
+
+The edge can be configured in two ways: with an **opaque connection token** (recommended) or with explicit config fields.
+
+#### Option A: Connection Token (Recommended)
+
+A single token encodes all connection details — ideal for provisioning edges at scale:
 
 ```typescript
 import { RemoteIngressEdge } from '@serve.zone/remoteingress';
 
 const edge = new RemoteIngressEdge();
 
-// Listen for events
+edge.on('tunnelConnected', () => console.log('Tunnel established'));
-edge.on('tunnelConnected', () => {
+edge.on('tunnelDisconnected', () => console.log('Tunnel lost — will auto-reconnect'));
-  console.log('Tunnel to hub established');
+edge.on('publicIpDiscovered', ({ ip }) => console.log(`Public IP: ${ip}`));
-});
+
-edge.on('tunnelDisconnected', () => {
+// Single token contains hubHost, hubPort, edgeId, and secret
-  console.log('Tunnel to hub lost — will auto-reconnect');
+await edge.start({
-});
+  token: 'eyJoIjoiaHViLmV4YW1wbGUuY29tIiwicCI6ODQ0MywiZSI6ImVkZ2UtbnljLTAxIiwicyI6InN1cGVyc2VjcmV0dG9rZW4xIn0',
-edge.on('publicIpDiscovered', ({ ip }) => {
+});
-  console.log(`Public IP: ${ip}`);
+```
-});
+
+#### Option B: Explicit Config
+
+```typescript
+import { RemoteIngressEdge } from '@serve.zone/remoteingress';
+
+const edge = new RemoteIngressEdge();
+
+edge.on('tunnelConnected', () => console.log('Tunnel established'));
+edge.on('tunnelDisconnected', () => console.log('Tunnel lost — will auto-reconnect'));
+edge.on('publicIpDiscovered', ({ ip }) => console.log(`Public IP: ${ip}`));
 
-// Start the edge — it connects to the hub and starts listening for clients
 await edge.start({
   hubHost: 'hub.example.com',  // hostname or IP of the hub
   hubPort: 8443,               // must match hub's tunnelPort (default: 8443)
   edgeId: 'edge-nyc-01',       // unique edge identifier
   secret: 'supersecrettoken1', // must match the hub's allowed edge secret
-  listenPorts: [80, 443],      // public ports to accept TCP connections on
-  stunIntervalSecs: 300,       // STUN refresh interval in seconds (optional)
 });
 
 // Check status at any time
@@ -138,9 +156,39 @@ console.log(edgeStatus);
 await edge.stop();
 ```
 
-### API Reference
+### 🎫 Connection Tokens
 
-#### `RemoteIngressHub`
+Connection tokens let you distribute a single opaque string instead of four separate config values. The hub operator generates the token; the edge operator just pastes it in.
+
+```typescript
+import { encodeConnectionToken, decodeConnectionToken } from '@serve.zone/remoteingress';
+
+// Hub side: generate a token for a new edge
+const token = encodeConnectionToken({
+  hubHost: 'hub.example.com',
+  hubPort: 8443,
+  edgeId: 'edge-nyc-01',
+  secret: 'supersecrettoken1',
+});
+console.log(token);
+// => 'eyJoIjoiaHViLmV4YW1wbGUuY29tIiwi...'
+
+// Edge side: inspect a token (optional — start() does this automatically)
+const data = decodeConnectionToken(token);
+console.log(data);
+// {
+//   hubHost: 'hub.example.com',
+//   hubPort: 8443,
+//   edgeId: 'edge-nyc-01',
+//   secret: 'supersecrettoken1'
+// }
+```
+
+Tokens are base64url-encoded (URL-safe, no padding) — safe to pass as environment variables, CLI arguments, or store in config files.
+
+## 📖 API Reference
+
+### `RemoteIngressHub`
 
 | Method / Property | Description |
 |-------------------|-------------|
@@ -152,18 +200,48 @@ await edge.stop();
 
 **Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed`
 
-#### `RemoteIngressEdge`
+### `RemoteIngressEdge`
 
 | Method / Property | Description |
 |-------------------|-------------|
-| `start(config)` | Spawns the Rust binary, connects to the hub, and starts listening on the specified ports. |
+| `start(config)` | Spawns the Rust binary and connects to the hub. Accepts `{ token: string }` or `IEdgeConfig`. |
 | `stop()` | Gracefully shuts down the edge and kills the Rust process. |
 | `getStatus()` | Returns current edge status including connection state, public IP, and active streams. |
 | `running` | `boolean` — whether the Rust binary is alive. |
 
 **Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered`
 
-### Wire Protocol
+### Token Utilities
+
+| Function | Description |
+|----------|-------------|
+| `encodeConnectionToken(data)` | Encodes `IConnectionTokenData` into a base64url token string. |
+| `decodeConnectionToken(token)` | Decodes a token back into `IConnectionTokenData`. Throws on malformed or incomplete tokens. |
+
+### Interfaces
+
+```typescript
+interface IHubConfig {
+  tunnelPort?: number;   // default: 8443
+  targetHost?: string;   // default: '127.0.0.1'
+}
+
+interface IEdgeConfig {
+  hubHost: string;
+  hubPort?: number;      // default: 8443
+  edgeId: string;
+  secret: string;
+}
+
+interface IConnectionTokenData {
+  hubHost: string;
+  hubPort: number;
+  edgeId: string;
+  secret: string;
+}
+```
+
+## 🔌 Wire Protocol
 
 The tunnel uses a custom binary frame protocol over TLS:
 
@@ -173,37 +251,64 @@ The tunnel uses a custom binary frame protocol over TLS:
 
 | Frame Type | Value | Direction | Purpose |
 |------------|-------|-----------|---------|
-| `OPEN` | `0x01` | Edge -> Hub | Open a new stream; payload is PROXY v1 header |
+| `OPEN` | `0x01` | Edge → Hub | Open a new stream; payload is PROXY v1 header |
-| `DATA` | `0x02` | Edge -> Hub | Client data flowing upstream |
+| `DATA` | `0x02` | Edge → Hub | Client data flowing upstream |
-| `CLOSE` | `0x03` | Edge -> Hub | Client closed the connection |
+| `CLOSE` | `0x03` | Edge → Hub | Client closed the connection |
-| `DATA_BACK` | `0x04` | Hub -> Edge | Response data flowing downstream |
+| `DATA_BACK` | `0x04` | Hub → Edge | Response data flowing downstream |
-| `CLOSE_BACK` | `0x05` | Hub -> Edge | Upstream (SmartProxy) closed the connection |
+| `CLOSE_BACK` | `0x05` | Hub → Edge | Upstream (SmartProxy) closed the connection |
 
 Max payload size per frame: **16 MB**.
 
-### Example Scenarios
+## 💡 Example Scenarios
 
-1. **Expose a private Kubernetes cluster to the internet** — Deploy an Edge on a public VPS, configure your DNS to point to the VPS IP. The Edge tunnels all traffic to the Hub running inside the cluster, which hands it off to SmartProxy/DcRouter. Your cluster stays fully private — no public-facing ports needed.
+### 1. Expose a Private Kubernetes Cluster to the Internet
 
-2. **Multi-region edge ingress** — Run multiple Edges in different geographic regions (NYC, Frankfurt, Tokyo) all connecting to a single Hub. Use GeoDNS to route users to their nearest Edge. The Hub sees the real client IPs via PROXY protocol regardless of which edge they connected through.
+Deploy an Edge on a public VPS, point your DNS to the VPS IP. The Edge tunnels all traffic to the Hub running inside the cluster, which hands it off to SmartProxy/DcRouter. Your cluster stays fully private — no public-facing ports needed.
 
-3. **Secure API exposure** — Your backend runs on a private network with no direct internet access. An Edge on a minimal cloud instance acts as the only public entry point. TLS tunnel + shared-secret auth ensure only your authorized Edge can forward traffic.
+### 2. Multi-Region Edge Ingress
+
+Run multiple Edges in different geographic regions (NYC, Frankfurt, Tokyo) all connecting to a single Hub. Use GeoDNS to route users to their nearest Edge. The Hub sees the real client IPs via PROXY protocol regardless of which edge they connected through.
+
+### 3. Secure API Exposure
+
+Your backend runs on a private network with no direct internet access. An Edge on a minimal cloud instance acts as the only public entry point. TLS tunnel + shared-secret auth ensure only your authorized Edge can forward traffic.
+
+### 4. Token-Based Edge Provisioning
+
+Generate connection tokens on the hub side and distribute them to edge operators. Each edge only needs a single token string to connect — no manual configuration of host, port, ID, and secret.
+
+```typescript
+// Hub operator generates token
+const token = encodeConnectionToken({
+  hubHost: 'hub.prod.example.com',
+  hubPort: 8443,
+  edgeId: 'edge-tokyo-01',
+  secret: 'generated-secret-abc123',
+});
+// Send `token` to the edge operator via secure channel
+
+// Edge operator starts with just the token
+const edge = new RemoteIngressEdge();
+await edge.start({ token });
+```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/remoteingress',
-  version: '3.1.0',
+  version: '3.1.1',
   description: 'Edge ingress tunnel for DcRouter - accepts incoming TCP connections at network edge and tunnels them to DcRouter SmartProxy preserving client IP via PROXY protocol v1.'
 }