v4.11.0

.dockerignore

@@ -0,0 +1 @@
+node_modules/

.gitignore

@@ -17,4 +17,5 @@ node_modules/
 dist/
 dist_*/
 
-# custom
+# custom
+rust/target/

Dockerfile

@@ -0,0 +1,46 @@
+# gitzone dockerfile_service
+## STAGE 1 // BUILD
+FROM registry.gitlab.com/hosttoday/ht-docker-node:npmci as node1
+COPY ./ /app
+WORKDIR /app
+ARG NPMCI_TOKEN_NPM2
+ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
+RUN npmci npm prepare
+RUN pnpm config set store-dir .pnpm-store
+RUN rm -rf node_modules && pnpm install
+RUN pnpm run build
+
+# gitzone dockerfile_service
+## STAGE 2 // install production
+FROM registry.gitlab.com/hosttoday/ht-docker-node:npmci as node2
+WORKDIR /app
+COPY --from=node1 /app /app
+RUN rm -rf .pnpm-store
+ARG NPMCI_TOKEN_NPM2
+ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
+RUN npmci npm prepare
+RUN pnpm config set store-dir .pnpm-store
+RUN rm -rf node_modules/ && pnpm install --prod
+
+
+## STAGE 3 // rebuild dependencies for alpine
+FROM registry.gitlab.com/hosttoday/ht-docker-node:alpinenpmci as node3
+WORKDIR /app
+COPY --from=node2 /app /app
+ARG NPMCI_TOKEN_NPM2
+ENV NPMCI_TOKEN_NPM2 $NPMCI_TOKEN_NPM2
+RUN npmci npm prepare
+RUN pnpm config set store-dir .pnpm-store
+RUN pnpm rebuild -r
+
+## STAGE 4 // the final production image with all dependencies in place
+FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine as node4
+WORKDIR /app
+COPY --from=node3 /app /app
+
+### Healthchecks
+RUN pnpm install -g @servezone/healthy
+HEALTHCHECK --interval=30s --timeout=30s --start-period=30s --retries=3 CMD [ "healthy" ]
+
+EXPOSE 80
+CMD ["npm", "start"]

changelog.md

@@ -0,0 +1,431 @@
+# Changelog
+
+## 2026-03-19 - 4.11.0 - feat(remoteingress-core)
+add UDP tunneling support between edge and hub
+
+- extend edge and hub handshake/config updates with UDP listen ports
+- add UDP tunnel frame types and PROXY protocol v2 header helpers in the protocol crate
+- introduce UDP session management on the edge and upstream UDP forwarding on the hub
+- add Node.js integration tests covering UDP echo and concurrent datagrams
+- expose UDP listen port configuration in the TypeScript hub API
+
+## 2026-03-19 - 4.10.0 - feat(core,edge,hub,transport)
+add QUIC tunnel transport support with optional edge transport selection
+
+- adds a shared transport module with QUIC configuration helpers, control message framing, and PROXY header handling
+- enables the hub to accept QUIC connections on the tunnel port alongside existing TCP/TLS support
+- adds edge transportMode configuration with quic and quicWithFallback options and propagates it through restarts
+- includes end-to-end QUIC transport tests covering large payloads and concurrent streams
+
+## 2026-03-18 - 4.9.1 - fix(readme)
+document QoS tiers, heartbeat frames, and adaptive flow control in the protocol overview
+
+- Adds PING, PONG, WINDOW_UPDATE, and WINDOW_UPDATE_BACK frame types to the protocol documentation
+- Describes the 3-tier priority queues for control, normal data, and sustained traffic
+- Explains sustained stream classification and adaptive per-stream window sizing
+
+## 2026-03-18 - 4.9.0 - feat(protocol)
+add sustained-stream tunnel scheduling to isolate high-throughput traffic
+
+- Introduce a third low-priority sustained queue in TunnelIo with a forced drain budget to prevent long-lived high-bandwidth streams from starving control and normal data frames.
+- Classify upload and download streams as sustained after exceeding the throughput threshold for the minimum duration, and route their DATA and CLOSE frames through the sustained channel.
+- Wire the new sustained channel through edge and hub stream handling so sustained traffic is scheduled consistently on both sides of the tunnel.
+
+## 2026-03-18 - 4.8.19 - fix(remoteingress-protocol)
+reduce per-stream flow control windows and increase control channel buffering
+
+- Lower the initial and maximum per-stream window from 16MB to 4MB and scale adaptive windows against a 200MB total budget with a 1MB minimum.
+- Increase edge and hub control frame channel capacity from 256 to 512 to better handle prioritized control traffic.
+- Update flow-control tests and comments to reflect the new window sizing and budget behavior.
+
+## 2026-03-17 - 4.8.18 - fix(rust-protocol)
+switch tunnel frame buffers from Vec<u8> to Bytes to reduce copying and memory overhead
+
+- Add the bytes crate to core and protocol crates
+- Update frame encoding, reader payloads, channel queues, and stream backchannels to use Bytes
+- Adjust edge and hub data/control paths to send framed payloads as Bytes
+
+## 2026-03-17 - 4.8.17 - fix(protocol)
+increase per-stream flow control windows and remove adaptive read caps
+
+- Raise the initial per-stream window from 4MB to 16MB and expand the adaptive window budget to 800MB with a 4MB floor
+- Stop limiting edge and hub reads by the adaptive per-stream target window, keeping reads capped only by the current window and 32KB chunk size
+- Update protocol tests to match the new adaptive window scaling and budget boundaries
+
+## 2026-03-17 - 4.8.16 - fix(release)
+bump package version to 4.8.15
+
+- Updates the package.json version field from 4.8.13 to 4.8.15.
+
+## 2026-03-17 - 4.8.13 - fix(remoteingress-protocol)
+require a flush after each written frame to bound TLS buffer growth
+
+- Remove the unflushed byte threshold and stop queueing additional writes while a flush is pending
+- Simplify write and flush error logging after dropping unflushed byte tracking
+- Update tunnel I/O comments to reflect the stricter flush behavior that avoids OOM and connection resets
+
+## 2026-03-17 - 4.8.12 - fix(tunnel)
+prevent tunnel backpressure buffering from exhausting memory and cancel stream handlers before TLS shutdown
+
+- stop self-waking and writing new frames while a flush is pending to avoid unbounded TLS session buffer growth under load
+- reorder edge and hub shutdown cleanup so stream cancellation happens before TLS close_notify, preventing handlers from blocking on dead channels
+- add load tests covering sustained large transfers, burst traffic, and rapid stream churn to verify tunnel stability
+
+## 2026-03-17 - 4.8.11 - fix(remoteingress-core)
+stop data frame send loops promptly when stream cancellation is triggered
+
+- Use cancellation-aware tokio::select! around data channel sends in both edge and hub stream forwarding paths
+- Prevent stalled or noisy shutdown behavior when stream or client cancellation happens while awaiting frame delivery
+
+## 2026-03-17 - 4.8.10 - fix(remoteingress-core)
+guard tunnel frame sends with cancellation to prevent async send deadlocks
+
+- Wrap OPEN, CLOSE, CLOSE_BACK, WINDOW_UPDATE, and cleanup channel sends in cancellation-aware tokio::select! blocks.
+- Avoid indefinite blocking when tunnel, stream, or writer tasks are cancelled while awaiting channel capacity.
+- Improve shutdown reliability for edge and hub stream handling under tunnel failure conditions.
+
+## 2026-03-17 - 4.8.9 - fix(repo)
+no changes to commit
+
+
+## 2026-03-17 - 4.8.8 - fix(remoteingress-core)
+cancel stale edge connections when an edge reconnects
+
+- Remove any existing edge entry before registering a reconnected edge
+- Trigger the previous connection's cancellation token so stale sessions shut down immediately instead of waiting for TCP keepalive
+
+## 2026-03-17 - 4.8.7 - fix(remoteingress-core)
+perform graceful TLS shutdown on edge and hub tunnel streams
+
+- Send TLS close_notify before cleanup to avoid peer disconnect warnings on both tunnel endpoints
+- Wrap stream shutdown in a 2 second timeout so connection teardown does not block cleanup
+
+## 2026-03-17 - 4.8.6 - fix(remoteingress-core)
+initialize disconnect reason only when set in hub loop break paths
+
+- Replace the default "unknown" disconnect reason with an explicitly assigned string and document that all hub loop exits set it before use
+- Add an allow attribute for unused assignments to avoid warnings around the deferred initialization pattern
+
+## 2026-03-17 - 4.8.5 - fix(repo)
+no changes to commit
+
+
+## 2026-03-17 - 4.8.4 - fix(remoteingress-core)
+prevent stream stalls by guaranteeing flow-control updates and avoiding bounded per-stream channel overflows
+
+- Replace bounded per-stream data channels with unbounded channels on edge and hub, relying on existing WINDOW_UPDATE flow control to limit bytes in flight
+- Use awaited sends for FRAME_WINDOW_UPDATE and FRAME_WINDOW_UPDATE_BACK so updates are not dropped and streams do not deadlock under backpressure
+- Clean up stream state when channel receivers have already exited instead of closing active streams because a bounded queue filled
+
+## 2026-03-17 - 4.8.3 - fix(protocol,edge)
+optimize tunnel frame handling and zero-copy uploads in edge I/O
+
+- extract hub frame processing into a shared edge handler to remove duplicated tunnel logic
+- add zero-copy frame header encoding and read payloads directly into framed buffers for client-to-hub uploads
+- refactor TunnelIo read/write state to avoid unsafe queue access and reduce buffer churn with incremental parsing
+
+## 2026-03-17 - 4.8.2 - fix(rust-edge)
+refactor tunnel I/O to preserve TLS state and prioritize control frames
+
+- replace split TLS handling with a single-owner TunnelIo to avoid handshake and buffered read corruption
+- prioritize control frames over data frames to prevent WINDOW_UPDATE starvation and flow-control deadlocks
+- improve tunnel reliability with incremental frame parsing, liveness/error events, and corrupt frame header logging
+
+## 2026-03-17 - 4.8.1 - fix(remoteingress-core)
+remove tunnel writer timeouts from edge and hub buffered writes
+
+- Drops the 30 second timeout wrapper around writer.write_all and writer.flush in both edge and hub tunnel writers.
+- Updates error logging to report write failures without referring to stalled writes.
+
+## 2026-03-17 - 4.8.0 - feat(events)
+include disconnect reasons in edge and hub management events
+
+- Add reason fields to tunnelDisconnected and edgeDisconnected events emitted from the Rust core and binary bridge
+- Propagate specific disconnect causes such as EOF, liveness timeout, writer failure, handshake failure, and hub cancellation
+- Update TypeScript edge and hub classes to log and forward disconnect reason data
+- Extend serialization tests to cover the new reason fields
+
+## 2026-03-17 - 4.7.2 - fix(remoteingress-core)
+add tunnel write timeouts and scale initial stream windows by active stream count
+
+- Wrap tunnel frame writes and flushes in a 30-second timeout on both edge and hub to detect stalled writers and trigger faster reconnect or cleanup.
+- Compute each stream's initial send window from the current active stream count instead of using a fixed window to keep total in-flight data within the 32MB budget.
+
+## 2026-03-17 - 4.7.1 - fix(remoteingress-core)
+improve tunnel failure detection and reconnect handling
+
+- Enable TCP keepalive on edge and hub connections to detect silent network failures sooner
+- Trigger immediate reconnect or disconnect when tunnel writer tasks fail instead of waiting for liveness timeouts
+- Prevent active stream counter underflow during concurrent connection cleanup
+
+## 2026-03-16 - 4.7.0 - feat(edge,protocol,test)
+add configurable edge bind address and expand flow-control test coverage
+
+- adds an optional bindAddress configuration for edge TCP listeners, defaulting to 0.0.0.0 when not provided
+- passes bindAddress through the TypeScript edge client and Rust edge runtime so local test setups can bind to localhost
+- adds protocol unit tests for adaptive stream window sizing and window update frame encoding/decoding
+- introduces end-to-end flow-control tests and updates the test script to build before running tests
+
+## 2026-03-16 - 4.6.1 - fix(remoteingress-core)
+avoid spurious tunnel disconnect events and increase control channel capacity
+
+- Emit TunnelDisconnected only after an established connection is actually lost, preventing false disconnect events during failed reconnect attempts.
+- Increase edge and hub control-channel buffer sizes from 64 to 256 to better prioritize control frames under load.
+
+## 2026-03-16 - 4.6.0 - feat(remoteingress-core)
+add adaptive per-stream flow control based on active stream counts
+
+- Track active stream counts on edge and hub connections to size per-stream flow control windows dynamically.
+- Cap WINDOW_UPDATE increments and read sizes to the adaptive window so bandwidth is shared more evenly across concurrent streams.
+- Apply the adaptive logic to both upload and download paths on edge and hub stream handlers.
+
+## 2026-03-16 - 4.5.12 - fix(remoteingress-core)
+improve tunnel liveness handling and enable TCP keepalive for accepted client sockets
+
+- Avoid disconnecting edges when PING or PONG frames cannot be queued because the control channel is temporarily full.
+- Enable TCP_NODELAY and TCP keepalive on accepted client connections to help detect stale or dropped clients.
+
+## 2026-03-16 - 4.5.11 - fix(repo)
+no changes to commit
+
+
+## 2026-03-16 - 4.5.10 - fix(remoteingress-core)
+guard zero-window reads to avoid false EOF handling on stalled streams
+
+- Prevent upload and download loops from calling read on an empty buffer when flow-control window remains at 0 after stall timeout
+- Log a warning and close the affected stream instead of misinterpreting Ok(0) as end-of-file
+
+## 2026-03-16 - 4.5.9 - fix(remoteingress-core)
+delay stream close until downstream response draining finishes to prevent truncated transfers
+
+- Waits for the hub-to-client download task to finish before sending the stream CLOSE frame
+- Prevents upstream reads from being cancelled mid-response during asymmetric transfers such as git fetch
+- Retains the existing timeout so stalled downloads still clean up safely
+
+## 2026-03-16 - 4.5.8 - fix(remoteingress-core)
+ensure upstream writes cancel promptly and reliably deliver CLOSE_BACK frames
+
+- listen for stream cancellation while waiting on upstream write timeouts so FRAME_CLOSE does not block for up to 60 seconds
+- replace try_send with send().await when emitting CLOSE_BACK frames to avoid silently dropping close notifications when the data channel is full
+
+## 2026-03-16 - 4.5.7 - fix(remoteingress-core)
+improve tunnel reconnect and frame write efficiency
+
+- Reuse the TLS connector across edge reconnections to preserve session resumption state and reduce reconnect latency.
+- Buffer hub and edge frame writes to coalesce small control and data frames into fewer TLS records and syscalls while still flushing each frame promptly.
+
+## 2026-03-16 - 4.5.6 - fix(remoteingress-core)
+disable Nagle's algorithm on edge, hub, and upstream TCP sockets to reduce control-frame latency
+
+- Enable TCP_NODELAY on the edge connection to the hub for faster PING/PONG and WINDOW_UPDATE delivery
+- Apply TCP_NODELAY on accepted hub streams before TLS handling
+- Enable TCP_NODELAY on SmartProxy upstream connections before sending the PROXY header
+
+## 2026-03-16 - 4.5.5 - fix(remoteingress-core)
+wait for hub-to-client draining before cleanup and reliably send close frames
+
+- switch CLOSE frame delivery on the data channel from try_send to send().await to avoid dropping it when the channel is full
+- delay stream cleanup until the hub-to-client task finishes or times out so large downstream responses continue after upload EOF
+- add a bounded 5-minute wait for download draining to prevent premature termination of asymmetric transfers such as git fetch
+
+## 2026-03-15 - 4.5.4 - fix(remoteingress-core)
+preserve stream close ordering and add flow-control stall timeouts
+
+- Send CLOSE and CLOSE_BACK frames on the data channel so they arrive after the final stream data frames.
+- Log and abort stalled upload and download paths when flow-control windows stay empty for 120 seconds.
+- Apply a 60-second timeout when writing buffered stream data to the upstream connection to prevent hung streams.
+
+## 2026-03-15 - 4.5.3 - fix(remoteingress-core)
+prioritize control frames over data in edge and hub tunnel writers
+
+- Split tunnel/frame writers into separate control and data channels in edge and hub
+- Use biased select loops so PING, PONG, WINDOW_UPDATE, OPEN, and CLOSE frames are sent before data frames
+- Route stream data through dedicated data channels while keeping OPEN, CLOSE, and flow-control updates on control channels to prevent keepalive starvation under load
+
+## 2026-03-15 - 4.5.2 - fix(remoteingress-core)
+improve stream flow control retries and increase channel buffer capacity
+
+- increase per-stream mpsc channel capacity from 128 to 256 on both edge and hub paths
+- only reset accumulated window update bytes after a successful try_send to avoid dropping flow-control credits when the update channel is busy
+
+## 2026-03-15 - 4.5.1 - fix(protocol)
+increase per-stream flow control window and channel buffers to improve high-RTT throughput
+
+- raise the initial stream window from 256 KB to 4 MB to allow more in-flight data per stream
+- increase edge and hub mpsc channel capacities from 16 to 128 to better absorb throughput under flow control
+
+## 2026-03-15 - 4.5.0 - feat(remoteingress-core)
+add per-stream flow control for edge and hub tunnel data transfer
+
+- introduce WINDOW_UPDATE frame types and protocol helpers for per-stream flow control
+- track per-stream send windows on both edge and hub to limit reads based on available capacity
+- send window updates after downstream writes to reduce channel pressure during large transfers
+
+## 2026-03-15 - 4.4.1 - fix(remoteingress-core)
+prevent stream data loss by applying backpressure and closing saturated channels
+
+- replace non-blocking frame writes with awaited sends in per-stream tasks so large transfers respect backpressure instead of dropping data
+- close and remove streams when back-channel or data channels fill up to avoid TCP stream corruption from silently dropped frames
+
+## 2026-03-03 - 4.4.0 - feat(remoteingress)
+add heartbeat PING/PONG and liveness timeouts; implement fast-reconnect/backoff reset and JS crash-recovery auto-restart
+
+- protocol: add FRAME_PING and FRAME_PONG and unit tests for ping/pong frames
+- edge (Rust): reset backoff after successful connection, respond to PING with PONG, track liveness via deadline and reconnect on timeout, use Duration/Instant helpers
+- hub (Rust): send periodic PING to edges, handle PONGs, enforce liveness timeout and disconnect inactive edges, use tokio interval and time utilities
+- ts: RemoteIngressEdge and RemoteIngressHub: add crash-recovery auto-restart with exponential backoff and max attempts, save/restore config and allowed edges, register/remove exit handlers, ensure stop() marks stopping and cleans up listeners
+- minor API/typing: introduce TAllowedEdge alias and persist allowed edges for restart recovery
+
+## 2026-02-26 - 4.3.0 - feat(hub)
+add optional TLS certificate/key support to hub start config and bridge
+
+- TypeScript: add tls.certPem and tls.keyPem to IHubConfig and include tlsCertPem/tlsKeyPem in startHub bridge command when both are provided
+- TypeScript: extend startHub params with tlsCertPem and tlsKeyPem and conditionally send them
+- Rust: change HubConfig serde attributes for tls_cert_pem and tls_key_pem from skip to default so absent PEM fields deserialize as None
+- Enables optional provisioning of TLS certificate and key to the hub when provided from the JS side
+
+## 2026-02-26 - 4.2.0 - feat(core)
+expose edge peer address in hub events and migrate writers to channel-based, non-blocking framing with stream limits and timeouts
+
+- Add peerAddr to ConnectedEdgeStatus and HubEvent::EdgeConnected and surface it to the TS frontend event (management:edgeConnected).
+- Replace Arc<Mutex<WriteHalf>> writers with dedicated mpsc channel writer tasks in both hub and edge crates to serialize writes off the main tasks.
+- Use non-blocking try_send for data frames to avoid head-of-line blocking and drop frames with warnings when channels are full.
+- Introduce MAX_STREAMS_PER_EDGE semaphore to limit concurrent streams per edge and reject excess opens with a CLOSE_BACK frame.
+- Add a 10s timeout when connecting to SmartProxy to avoid hanging connections.
+- Ensure writer tasks are aborted on shutdown/cleanup and propagate cancellation tokens appropriately.
+
+## 2026-02-26 - 4.1.0 - feat(remoteingress-bin)
+use mimalloc as the global allocator to reduce memory overhead and improve allocation performance
+
+- added mimalloc = "0.1" dependency to rust/crates/remoteingress-bin/Cargo.toml
+- registered mimalloc as the #[global_allocator] in rust/crates/remoteingress-bin/src/main.rs
+- updated Cargo.lock with libmimalloc-sys and mimalloc package entries
+
+## 2026-02-26 - 4.0.1 - fix(hub)
+cancel per-stream tokens on stream close and avoid duplicate StreamClosed events; bump @types/node devDependency to ^25.3.0
+
+- Add CancellationToken to per-stream entries so each stream can be cancelled independently.
+- Ensure StreamClosed event is only emitted when a stream was actually present (guards against duplicate events).
+- Cancel the stream-specific token on FRAME_CLOSE to stop associated tasks and free resources.
+- DevDependency bump: @types/node updated from ^25.2.3 to ^25.3.0.
+
+## 2026-02-19 - 4.0.0 - BREAKING CHANGE(remoteingress-core)
+add cancellation tokens and cooperative shutdown; switch event channels to bounded mpsc and improve cleanup
+
+- Introduce tokio-util::sync::CancellationToken for hub/edge and per-connection/stream cancellation, enabling cooperative shutdown of spawned tasks.
+- Replace unbounded mpsc channels with bounded mpsc::channel(1024) and switch from UnboundedSender/Receiver to Sender/Receiver; use try_send where non-blocking sends are appropriate.
+- Wire cancellation tokens through edge and hub codepaths: child tokens per connection, per-port, per-stream; cancel tokens in stop() and Drop impls to ensure deterministic task termination and cleanup.
+- Reset stream id counters and clear listener state on reconnect; improved error handling around accept/read loops using tokio::select! and cancellation checks.
+- Update Cargo.toml and Cargo.lock to add tokio-util (and related futures entries) as dependencies.
+- BREAKING: public API/types changed — take_event_rx return types and event_tx/event_rx fields now use bounded mpsc::Sender/mpsc::Receiver instead of the unbounded variants; callers must adapt to the new types and bounded behavior.
+
+## 2026-02-18 - 3.3.0 - feat(readme)
+document dynamic port assignment and runtime port updates; clarify TLS multiplexing, frame format, and handshake sequence
+
+- Adds documentation for dynamic port configuration: hub-assigned listen ports, hot-reloadable via FRAME_CONFIG frames
+- Introduces new FRAME type CONFIG (0x06) and describes payload as JSON; notes immediate push of port changes to connected edges
+- Clarifies that the tunnel is a single encrypted TLS multiplexed connection to the hub (preserves PROXY v1 behavior)
+- Specifies frame integer fields are big-endian and that stream IDs are 32-bit unsigned integers
+- Adds new events: portsAssigned and portsUpdated, and updates examples showing updateAllowedEdges usage and live port changes
+
+## 2026-02-18 - 3.2.1 - fix(tests)
+add comprehensive unit and async tests across Rust crates and TypeScript runtime
+
+- Added IPC serialization tests in remoteingress-bin (IPC request/response/event)
+- Added serde and async tests for Edge and Handshake configs and EdgeEvent/EdgeStatus in remoteingress-core (edge.rs)
+- Added extensive Hub tests: constant_time_eq, PROXY header port parsing, serde/camelCase checks, Hub events and async TunnelHub behavior (hub.rs)
+- Added STUN parser unit tests including XOR_MAPPED_ADDRESS, MAPPED_ADDRESS fallback, truncated attribute handling and other edge cases (stun.rs)
+- Added protocol frame encoding and FrameReader tests covering all frame types, payload limits and EOF conditions (remoteingress-protocol)
+- Added TypeScript Node tests for token encode/decode edge cases and RemoteIngressHub/RemoteIngressEdge class basics (test/*.node.ts)
+
+## 2026-02-18 - 3.2.0 - feat(remoteingress (edge/hub/protocol))
+add dynamic port configuration: handshake, FRAME_CONFIG frames, and hot-reloadable listeners
+
+- Introduce a JSON handshake from hub -> edge with initial listen ports and stun interval so edges can configure listeners at connect time.
+- Add FRAME_CONFIG (0x06) to the protocol and implement runtime config updates pushed from hub to connected edges.
+- Edge now applies initial ports and supports hot-reloading: spawn/abort listeners when ports change, and emit PortsAssigned / PortsUpdated events.
+- Hub now stores allowed edge metadata (listen_ports, stun_interval_secs), sends handshake responses on auth, and forwards config updates to connected edges.
+- TypeScript bridge/client updated to emit new port events and periodically log status; updateAllowedEdges API accepts listenPorts and stunIntervalSecs.
+- Stun interval handling moved to use handshake-provided/stored value instead of config.listen_ports being static.
+
+## 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
+
+- Add classes.token.ts with encodeConnectionToken/decodeConnectionToken using a base64url compact JSON format
+- Export token utilities from ts/index.ts
+- RemoteIngressEdge.start now accepts a { token } option and decodes it to an IEdgeConfig before starting
+- Add tests covering export availability, encode→decode roundtrip, malformed token, and missing fields
+- Non-breaking change — recommend a minor version bump
+
+## 2026-02-17 - 3.0.4 - fix(build)
+bump dev dependencies, update build script, and refresh README docs
+
+- Bumped devDependencies: @git.zone/tsbuild ^2.1.25 → ^4.1.2, @git.zone/tsbundle ^2.0.5 → ^2.8.3, @git.zone/tsrun ^1.2.46 → ^2.0.1, @git.zone/tstest ^1.0.44 → ^3.1.8, @push.rocks/tapbundle ^5.0.15 → ^6.0.3, @types/node ^20.8.7 → ^25.2.3
+- Bumped runtime dependency: @push.rocks/qenv ^6.0.5 → ^6.1.3
+- Changed build script: replaced "tsbuild --web --allowimplicitany" with "tsbuild tsfolders --allowimplicitany" (kept tsrust invocation)
+- README updates: added RustBridge notes (localPaths must be full file paths), production binary naming conventions, rust core uses ring as rustls provider; removed emoji from example console output; clarified stunIntervalSecs is optional; renamed example status variable to edgeStatus; minor wire-protocol formatting and wording/legal text tweaks
+
+## 2026-02-17 - 3.0.3 - fix(rust,ts)
+initialize rustls ring CryptoProvider at startup; add rustls dependency and features; make native binary lookup platform-aware
+
+- Install rustls::crypto::ring default_provider at startup to ensure ring-based crypto is available before any TLS usage.
+- Add rustls dependency to remoteingress-bin and update remoteingress-core rustls configuration (disable default-features; enable ring, logging, std, tls12).
+- Adjust TS classes to prefer platform-suffixed production binaries, add exact fallback names, and include explicit cargo output paths for release/debug.
+- Cargo.lock updated to include rustls entry.
+
+## 2026-02-16 - 3.0.2 - fix(readme)
+Document Hub/Edge architecture and new RemoteIngressHub/RemoteIngressEdge API; add Rust core binary, protocol and usage details; note removal of ConnectorPublic/ConnectorPrivate (breaking change)
+
+- Adds comprehensive README describing v3 Hub↔Edge topology and usage examples
+- Introduces Rust core binary (remoteingress-bin) and RustBridge IPC via @push.rocks/smartrust
+- Documents custom multiplexed binary frame protocol over TLS and PROXY protocol v1 for client IP preservation
+- Notes STUN-based public IP discovery and cross-compiled linux/amd64 and linux/arm64 binaries
+- Calls out removal/rename of ConnectorPublic/ConnectorPrivate to RemoteIngressHub/RemoteIngressEdge (breaking API change)
+- Updates install instruction to use pnpm and expands API reference, events, and examples
+
+## 2026-02-16 - 3.0.1 - fix(remoteingress)
+no changes detected in diff; no code modifications to release
+
+- No files changed in the provided diff.
+- No release or version bump required based on current changes.
+
+## 2026-02-16 - 3.0.0 - BREAKING CHANGE(remoteingress)
+migrate core to Rust, add RemoteIngressHub/RemoteIngressEdge JS bridge, and bump package to v2.0.0
+
+- Added Rust workspace and crates: remoteingress-protocol, remoteingress-core, remoteingress-bin (IPC management mode via JSON over stdin/stdout).
+- Implemented protocol framing, PROXY v1 header builder, and async FrameReader in remoteingress-protocol.
+- Implemented hub and edge tunnel logic in Rust including TLS handling, PROXY parsing, and STUN public IP discovery.
+- Added TypeScript runtime bridge classes RemoteIngressHub and RemoteIngressEdge that use @push.rocks/smartrust to spawn/manage the Rust binary.
+- Removed legacy connector public/private TS files and simplified ts/index exports to expose hub/edge classes.
+- Updated package.json: bumped version to 2.0.0, adjusted description, added tsrust build step, new dependency @push.rocks/smartrust and keywords, and included dist_rust in files/glob.
+- Added rust build config for cross-target linkers and new Cargo.toml manifests for the workspace.
+
+## 2024-04-14 - 1.0.2 - 1.0.4 - releases
+Version-only tag commits (no code changes) for recent releases.
+
+- 1.0.2 (2024-03-24) — release tag / version bump only
+- 1.0.3 (2024-04-14) — release tag / version bump only
+- 1.0.4 (2024-04-14) — release tag / version bump only
+
+## 2024-04-14 - 1.0.3 - core
+Core updates and fixes.
+
+- fix(core): update
+
+## 2024-04-14 - 1.0.2 - core
+Core updates and fixes.
+
+- fix(core): update
+
+## 2024-03-24 - 1.0.1 - core
+Core updates and fixes.
+
+- fix(core): update

cli.child.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+process.env.CLI_CALL = 'true';
+import * as cliTool from './ts/index.js';
+cliTool.runCli();

cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+process.env.CLI_CALL = 'true';
+const cliTool = await import('./dist_ts/index.js');
+cliTool.runCli();

cli.ts.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+process.env.CLI_CALL = 'true';
+
+import * as tsrun from '@git.zone/tsrun';
+tsrun.runPath('./cli.child.js', import.meta.url);

npmextra.json

@@ -1,18 +1,50 @@
 {
-  "gitzone": {
+  "@git.zone/tsrust": {
+    "targets": [
+      "linux_amd64",
+      "linux_arm64"
+    ]
+  },
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
       "gitscope": "serve.zone",
       "gitrepo": "remoteingress",
-      "description": "a remoteingress service for serve.zone",
+      "description": "Provides a service for creating private tunnels and reaching private clusters from the outside, facilitating secure remote access as part of the @serve.zone stack.",
       "npmPackagename": "@serve.zone/remoteingress",
       "license": "MIT",
-      "projectDomain": "serve.zone"
+      "projectDomain": "serve.zone",
+      "keywords": [
+        "remote access",
+        "private tunnels",
+        "network security",
+        "TLS encryption",
+        "connector",
+        "serve.zone stack",
+        "private clusters access",
+        "public access management",
+        "TypeScript application",
+        "node.js package",
+        "secure communications",
+        "TLS/SSL certificates",
+        "development tools",
+        "software development",
+        "private network integration"
+      ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
+  "@git.zone/tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

package.json

@@ -1,27 +1,31 @@
 {
   "name": "@serve.zone/remoteingress",
-  "version": "1.0.2",
+  "version": "4.11.0",
   "private": false,
-  "description": "a remoteingress service for serve.zone",
+  "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.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/ --web)",
-    "build": "(tsbuild --web --allowimplicitany)",
+    "test": "(pnpm run build && tstest test/ --verbose --logfile --timeout 60)",
+    "build": "(tsbuild tsfolders --allowimplicitany && tsrust)",
     "buildDocs": "(tsdoc)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.25",
-    "@git.zone/tsbundle": "^2.0.5",
-    "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.44",
-    "@push.rocks/tapbundle": "^5.0.15",
-    "@types/node": "^20.8.7"
+    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsbundle": "^2.8.3",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tsrust": "^1.3.0",
+    "@git.zone/tstest": "^3.1.8",
+    "@push.rocks/tapbundle": "^6.0.3",
+    "@types/node": "^25.3.0"
+  },
+  "dependencies": {
+    "@push.rocks/qenv": "^6.1.3",
+    "@push.rocks/smartrust": "^1.2.1"
   },
-  "dependencies": {},
   "repository": {
     "type": "git",
     "url": "git+https://code.foss.global/serve.zone/remoteingress.git"
@@ -40,9 +44,23 @@
     "dist_*/**/*",
     "dist_ts/**/*",
     "dist_ts_web/**/*",
+    "dist_rust/**/*",
     "assets/**/*",
     "cli.js",
     "npmextra.json",
     "readme.md"
+  ],
+  "keywords": [
+    "remote access",
+    "ingress tunnel",
+    "network edge",
+    "PROXY protocol",
+    "multiplexed tunnel",
+    "TCP proxy",
+    "TLS tunnel",
+    "serve.zone stack",
+    "TypeScript",
+    "Rust",
+    "SmartProxy"
   ]
 }

readme.hints.md

@@ -0,0 +1,12 @@
+* This module is part of the @serve.zone stack
+* v3.0.0+ uses a Hub/Edge architecture with a Rust core binary (`remoteingress-bin`)
+* TypeScript classes `RemoteIngressHub` and `RemoteIngressEdge` bridge to Rust via `@push.rocks/smartrust` RustBridge IPC
+* Custom multiplexed binary frame protocol over TLS for tunneling TCP connections
+* PROXY protocol v1 preserves client IP when forwarding to SmartProxy/DcRouter
+* Edge authenticates to Hub via shared secret over TLS
+* STUN-based public IP discovery at the edge (Cloudflare STUN server)
+* Cross-compiled Rust binary for linux/amd64 and linux/arm64
+* Old `ConnectorPublic`/`ConnectorPrivate` classes no longer exist (removed in v2.0.0/v3.0.0)
+* `localPaths` in RustBridge config must be full file paths (not directories) — smartrust's `RustBinaryLocator` checks `isExecutable()` on each entry directly
+* Production binaries are named with platform suffixes: `remoteingress-bin_linux_amd64`, `remoteingress-bin_linux_arm64`
+* Rust core uses `ring` as the rustls CryptoProvider (explicitly installed in main.rs, aws-lc-rs disabled via default-features=false)

readme.md

@@ -1,31 +1,405 @@
 # @serve.zone/remoteingress
-a remoteingress service for serve.zone
 
-## Availabililty and Links
-* [npmjs.org (npm package)](https://www.npmjs.com/package/@serve.zone/remoteingress)
-* [gitlab.com (source)](https://code.foss.global/serve.zone/remoteingress)
-* [github.com (source mirror)](https://github.com/serve.zone/remoteingress)
-* [docs (typedoc)](https://serve.zone.gitlab.io/remoteingress/)
+Edge ingress tunnel for DcRouter — accepts incoming TCP connections at the network edge and tunnels them over a single encrypted TLS connection to a DcRouter SmartProxy instance, preserving the original client IP via PROXY protocol v1.
 
-## Status for master
+## Issue Reporting and Security
 
-Status Category | Status Badge
--- | --
-GitLab Pipelines | [![pipeline status](https://code.foss.global/serve.zone/remoteingress/badges/master/pipeline.svg)](https://lossless.cloud)
-GitLab Pipline Test Coverage | [![coverage report](https://code.foss.global/serve.zone/remoteingress/badges/master/coverage.svg)](https://lossless.cloud)
-npm | [![npm downloads per month](https://badgen.net/npm/dy/@serve.zone/remoteingress)](https://lossless.cloud)
-Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/serve.zone/remoteingress)](https://lossless.cloud)
-TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
-node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
-Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
-PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@serve.zone/remoteingress)](https://lossless.cloud)
-PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@serve.zone/remoteingress)](https://lossless.cloud)
-BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@serve.zone/remoteingress)](https://lossless.cloud)
+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.
 
-## Usage
-Use TypeScript for best in class intellisense
-For further information read the linked docs at the top of this readme.
+## Install
 
-## Legal
-> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc)
-| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
+```sh
+pnpm install @serve.zone/remoteingress
+```
+
+## 🏗️ Architecture
+
+`@serve.zone/remoteingress` uses a **Hub/Edge** topology with a high-performance Rust core and a TypeScript API surface:
+
+```
+┌─────────────────────┐          TLS Tunnel            ┌─────────────────────┐
+│   Network Edge      │  ◄══════════════════════════►  │   Private Cluster   │
+│                     │   (multiplexed frames +        │                     │
+│  RemoteIngressEdge  │    shared-secret auth)         │  RemoteIngressHub   │
+│  Accepts client TCP │                                │  Forwards to        │
+│  connections on     │                                │  SmartProxy on      │
+│  hub-assigned ports │                                │  local ports        │
+└─────────────────────┘                                └─────────────────────┘
+        ▲                                                       │
+        │  TCP from end users                                   ▼
+   Internet                                             DcRouter / SmartProxy
+```
+
+| Component | Role |
+|-----------|------|
+| **RemoteIngressEdge** | Deployed at the network edge (e.g. a VPS or cloud instance). Listens on ports assigned by the hub, accepts raw TCP connections, and multiplexes them over a single TLS tunnel to the hub. Ports are hot-reloadable — the hub can change them at runtime. |
+| **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. Controls which ports each edge listens on. |
+| **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
+
+- 🔒 **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
+- 🌐 **PROXY protocol v1** — SmartProxy sees the real client IP, not the tunnel IP
+- 🔑 **Shared-secret authentication** — edges must present valid credentials to connect
+- 🎫 **Connection tokens** — encode all connection details into a single opaque string
+- 📡 **STUN-based public IP discovery** — the edge automatically discovers its public IP via Cloudflare STUN
+- 🔄 **Auto-reconnect** with exponential backoff if the tunnel drops
+- 🎛️ **Dynamic port configuration** — the hub assigns listen ports per edge and can hot-reload them at runtime via `FRAME_CONFIG` frames
+- 📣 **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
+- 🎚️ **3-tier QoS** — control frames, normal data, and sustained (elephant flow) traffic each get their own priority queue
+- 📊 **Adaptive flow control** — per-stream windows scale with active stream count to prevent memory overuse
+
+## 🚀 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)
+
+```typescript
+import { RemoteIngressHub } from '@serve.zone/remoteingress';
+
+const hub = new RemoteIngressHub();
+
+// Listen for events
+hub.on('edgeConnected', ({ edgeId }) => {
+  console.log(`Edge ${edgeId} connected`);
+});
+hub.on('edgeDisconnected', ({ edgeId }) => {
+  console.log(`Edge ${edgeId} disconnected`);
+});
+hub.on('streamOpened', ({ edgeId, streamId }) => {
+  console.log(`Stream ${streamId} opened from edge ${edgeId}`);
+});
+hub.on('streamClosed', ({ edgeId, streamId }) => {
+  console.log(`Stream ${streamId} closed from edge ${edgeId}`);
+});
+
+// Start the hub — it will listen for incoming edge TLS connections
+await hub.start({
+  tunnelPort: 8443,        // port edges connect to (default: 8443)
+  targetHost: '127.0.0.1', // SmartProxy host to forward streams to (default: 127.0.0.1)
+});
+
+// Register which edges are allowed to connect, including their listen ports
+await hub.updateAllowedEdges([
+  {
+    id: 'edge-nyc-01',
+    secret: 'supersecrettoken1',
+    listenPorts: [80, 443],        // ports the edge should listen on
+    stunIntervalSecs: 300,         // STUN discovery interval (default: 300)
+  },
+  {
+    id: 'edge-fra-02',
+    secret: 'supersecrettoken2',
+    listenPorts: [443, 8080],
+  },
+]);
+
+// Dynamically update ports for a connected edge — changes are pushed instantly
+await hub.updateAllowedEdges([
+  {
+    id: 'edge-nyc-01',
+    secret: 'supersecrettoken1',
+    listenPorts: [80, 443, 8443],  // added port 8443 — edge picks it up in real time
+  },
+]);
+
+// Check status at any time
+const status = await hub.getStatus();
+console.log(status);
+// {
+//   running: true,
+//   tunnelPort: 8443,
+//   connectedEdges: [
+//     { edgeId: 'edge-nyc-01', connectedAt: 1700000000, activeStreams: 12 }
+//   ]
+// }
+
+// Graceful shutdown
+await hub.stop();
+```
+
+### 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();
+
+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}`));
+edge.on('portsAssigned', ({ listenPorts }) => console.log(`Listening on ports: ${listenPorts}`));
+edge.on('portsUpdated', ({ listenPorts }) => console.log(`Ports updated: ${listenPorts}`));
+
+// Single token contains hubHost, hubPort, edgeId, and secret
+await edge.start({
+  token: 'eyJoIjoiaHViLmV4YW1wbGUuY29tIiwicCI6ODQ0MywiZSI6ImVkZ2UtbnljLTAxIiwicyI6InN1cGVyc2VjcmV0dG9rZW4xIn0',
+});
+```
+
+#### 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}`));
+edge.on('portsAssigned', ({ listenPorts }) => console.log(`Listening on ports: ${listenPorts}`));
+edge.on('portsUpdated', ({ listenPorts }) => console.log(`Ports updated: ${listenPorts}`));
+
+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
+});
+
+// Check status at any time
+const edgeStatus = await edge.getStatus();
+console.log(edgeStatus);
+// {
+//   running: true,
+//   connected: true,
+//   publicIp: '203.0.113.42',
+//   activeStreams: 5,
+//   listenPorts: [80, 443]
+// }
+
+// Graceful shutdown
+await edge.stop();
+```
+
+### 🎫 Connection Tokens
+
+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 |
+|-------------------|-------------|
+| `start(config?)` | Spawns the Rust binary and starts the tunnel listener. Config: `{ tunnelPort?: number, targetHost?: string }` |
+| `stop()` | Gracefully shuts down the hub and kills the Rust process. |
+| `updateAllowedEdges(edges)` | Dynamically update which edges are authorized and what ports they listen on. Each edge: `{ id: string, secret: string, listenPorts?: number[], stunIntervalSecs?: number }`. If ports change for a connected edge, the update is pushed immediately via a `FRAME_CONFIG` frame. |
+| `getStatus()` | Returns current hub status including connected edges and active stream counts. |
+| `running` | `boolean` — whether the Rust binary is alive. |
+
+**Events:** `edgeConnected`, `edgeDisconnected`, `streamOpened`, `streamClosed`
+
+### `RemoteIngressEdge`
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `start(config)` | Spawns the Rust binary and connects to the hub. Accepts `{ token: string }` or `IEdgeConfig`. Listen ports are received from the hub during handshake. |
+| `stop()` | Gracefully shuts down the edge and kills the Rust process. |
+| `getStatus()` | Returns current edge status including connection state, public IP, listen ports, and active streams. |
+| `running` | `boolean` — whether the Rust binary is alive. |
+
+**Events:** `tunnelConnected`, `tunnelDisconnected`, `publicIpDiscovered`, `portsAssigned`, `portsUpdated`
+
+### 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:
+
+```
+[stream_id: 4 bytes BE][type: 1 byte][length: 4 bytes BE][payload: N bytes]
+```
+
+| Frame Type | Value | Direction | Purpose |
+|------------|-------|-----------|---------|
+| `OPEN` | `0x01` | Edge → Hub | Open a new stream; payload is PROXY v1 header |
+| `DATA` | `0x02` | Edge → Hub | Client data flowing upstream |
+| `CLOSE` | `0x03` | Edge → Hub | Client closed the connection |
+| `DATA_BACK` | `0x04` | Hub → Edge | Response data flowing downstream |
+| `CLOSE_BACK` | `0x05` | Hub → Edge | Upstream (SmartProxy) closed the connection |
+| `CONFIG` | `0x06` | Hub → Edge | Runtime configuration update (e.g. port changes); payload is JSON |
+| `PING` | `0x07` | Hub → Edge | Heartbeat probe (sent every 15s) |
+| `PONG` | `0x08` | Edge → Hub | Heartbeat response |
+| `WINDOW_UPDATE` | `0x09` | Edge → Hub | Per-stream flow control: edge consumed N bytes, hub can send more |
+| `WINDOW_UPDATE_BACK` | `0x0A` | Hub → Edge | Per-stream flow control: hub consumed N bytes, edge can send more |
+
+Max payload size per frame: **16 MB**. Stream IDs are 32-bit unsigned integers.
+
+### Handshake Sequence
+
+1. Edge opens a TLS connection to the hub
+2. Edge sends: `EDGE <edgeId> <secret>\n`
+3. Hub verifies credentials (constant-time comparison) and responds with JSON: `{"listenPorts":[...],"stunIntervalSecs":300}\n`
+4. Edge starts TCP listeners on the assigned ports
+5. Frame protocol begins — `OPEN`/`DATA`/`CLOSE` frames flow in both directions
+6. Hub can push `CONFIG` frames at any time to update the edge's listen ports
+
+## 🎚️ QoS & Flow Control
+
+The tunnel multiplexer uses a **3-tier priority system** and **per-stream flow control** to ensure fair bandwidth sharing across thousands of concurrent streams.
+
+### Priority Tiers
+
+All outbound frames are queued into one of three priority levels:
+
+| Tier | Queue | Frames | Behavior |
+|------|-------|--------|----------|
+| 🔴 **Control** (highest) | `ctrl_queue` | PING, PONG, WINDOW_UPDATE, OPEN, CLOSE, CONFIG | Always drained first. Never delayed. |
+| 🟡 **Data** (normal) | `data_queue` | DATA, DATA_BACK from normal streams | Drained when ctrl is empty. Gated at 64 buffered items for backpressure. |
+| 🟢 **Sustained** (lowest) | `sustained_queue` | DATA, DATA_BACK from elephant flows | Drained freely when ctrl+data are empty. Otherwise guaranteed **1 MB/s** via forced drain every second. |
+
+This prevents large bulk transfers (e.g. git clones, file downloads) from starving interactive traffic and ensures `WINDOW_UPDATE` frames are never delayed — which would cause flow control deadlocks.
+
+### Sustained Stream Classification
+
+A stream is automatically classified as **sustained** (elephant flow) when:
+- It has been active for **>10 seconds**, AND
+- Its average throughput exceeds **20 Mbit/s** (2.5 MB/s)
+
+Once classified, the stream's flow control window is locked to the **1 MB floor** and its data frames move to the lowest-priority queue. Classification is one-way — a stream never gets promoted back to normal.
+
+### Adaptive Per-Stream Windows
+
+Each stream has a send window that limits bytes-in-flight. The window size adapts to the number of active streams using a shared **200 MB memory budget**:
+
+| Active Streams | Window per Stream |
+|---|---|
+| 1–50 | 4 MB (maximum) |
+| 51–100 | Scales down (4 MB → 2 MB) |
+| 200+ | 1 MB (floor) |
+
+The consumer sends `WINDOW_UPDATE` frames after processing data, allowing the producer to send more. This prevents any single stream from consuming unbounded memory and provides natural backpressure.
+
+## 💡 Example Scenarios
+
+### 1. Expose a Private Kubernetes Cluster to the Internet
+
+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.
+
+### 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 });
+```
+
+### 5. Dynamic Port Management
+
+The hub controls which ports each edge listens on. Ports can be changed at runtime without restarting the edge — the hub pushes a `CONFIG` frame and the edge hot-reloads its TCP listeners.
+
+```typescript
+// Initially assign ports 80 and 443
+await hub.updateAllowedEdges([
+  { id: 'edge-nyc-01', secret: 'secret', listenPorts: [80, 443] },
+]);
+
+// Later, add port 8080 — the connected edge picks it up instantly
+await hub.updateAllowedEdges([
+  { id: 'edge-nyc-01', secret: 'secret', listenPorts: [80, 443, 8080] },
+]);
+```
+
+## License and Legal Information
+
+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 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
+
+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.

rust/.cargo/config.toml

@@ -0,0 +1,5 @@
+[target.x86_64-unknown-linux-gnu]
+linker = "x86_64-linux-gnu-gcc"
+
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"

rust/Cargo.toml

@@ -0,0 +1,7 @@
+[workspace]
+resolver = "2"
+members = [
+  "crates/remoteingress-protocol",
+  "crates/remoteingress-core",
+  "crates/remoteingress-bin",
+]

rust/crates/remoteingress-bin/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "remoteingress-bin"
+version = "2.0.0"
+edition = "2021"
+
+[[bin]]
+name = "remoteingress-bin"
+path = "src/main.rs"
+
+[dependencies]
+remoteingress-core = { path = "../remoteingress-core" }
+remoteingress-protocol = { path = "../remoteingress-protocol" }
+tokio = { version = "1", features = ["full"] }
+clap = { version = "4", features = ["derive"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+log = "0.4"
+env_logger = "0.11"
+rustls = { version = "0.23", default-features = false, features = ["ring"] }
+mimalloc = "0.1"

rust/crates/remoteingress-bin/src/main.rs

@@ -0,0 +1,429 @@
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
+use clap::Parser;
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use tokio::io::{AsyncBufReadExt, BufReader};
+use tokio::sync::Mutex;
+
+use remoteingress_core::hub::{AllowedEdge, HubConfig, HubEvent, TunnelHub};
+use remoteingress_core::edge::{EdgeConfig, EdgeEvent, TunnelEdge};
+
+#[derive(Parser)]
+#[command(name = "remoteingress-bin", version = "2.0.0")]
+struct Cli {
+    /// Run in IPC management mode (JSON over stdin/stdout)
+    #[arg(long)]
+    management: bool,
+}
+
+// IPC message types
+#[derive(Deserialize)]
+struct IpcRequest {
+    id: String,
+    method: String,
+    params: serde_json::Value,
+}
+
+#[derive(Serialize)]
+struct IpcResponse {
+    id: String,
+    success: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    result: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    error: Option<String>,
+}
+
+#[derive(Serialize)]
+struct IpcEvent {
+    event: String,
+    data: serde_json::Value,
+}
+
+fn send_ipc_line(line: &str) {
+    // Write to stdout synchronously, since we're line-buffered
+    use std::io::Write;
+    let stdout = std::io::stdout();
+    let mut out = stdout.lock();
+    let _ = out.write_all(line.as_bytes());
+    let _ = out.write_all(b"\n");
+    let _ = out.flush();
+}
+
+fn send_event(event: &str, data: serde_json::Value) {
+    let evt = IpcEvent {
+        event: event.to_string(),
+        data,
+    };
+    if let Ok(json) = serde_json::to_string(&evt) {
+        send_ipc_line(&json);
+    }
+}
+
+fn send_response(id: &str, result: serde_json::Value) {
+    let resp = IpcResponse {
+        id: id.to_string(),
+        success: true,
+        result: Some(result),
+        error: None,
+    };
+    if let Ok(json) = serde_json::to_string(&resp) {
+        send_ipc_line(&json);
+    }
+}
+
+fn send_error(id: &str, error: &str) {
+    let resp = IpcResponse {
+        id: id.to_string(),
+        success: false,
+        result: None,
+        error: Some(error.to_string()),
+    };
+    if let Ok(json) = serde_json::to_string(&resp) {
+        send_ipc_line(&json);
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    // Install the ring CryptoProvider before any TLS usage
+    rustls::crypto::ring::default_provider()
+        .install_default()
+        .expect("Failed to install rustls ring CryptoProvider");
+
+    let cli = Cli::parse();
+
+    if !cli.management {
+        eprintln!("remoteingress-bin: use --management for IPC mode");
+        std::process::exit(1);
+    }
+
+    // Initialize logging to stderr (stdout is for IPC)
+    env_logger::Builder::from_default_env()
+        .target(env_logger::Target::Stderr)
+        .filter_level(log::LevelFilter::Info)
+        .init();
+
+    // Send ready event
+    send_event("ready", serde_json::json!({ "version": "2.0.0" }));
+
+    // State
+    let hub: Arc<Mutex<Option<Arc<TunnelHub>>>> = Arc::new(Mutex::new(None));
+    let edge: Arc<Mutex<Option<Arc<TunnelEdge>>>> = Arc::new(Mutex::new(None));
+
+    // Read commands from stdin
+    let stdin = tokio::io::stdin();
+    let reader = BufReader::new(stdin);
+    let mut lines = reader.lines();
+
+    while let Ok(Some(line)) = lines.next_line().await {
+        let line = line.trim().to_string();
+        if line.is_empty() {
+            continue;
+        }
+
+        let request: IpcRequest = match serde_json::from_str(&line) {
+            Ok(r) => r,
+            Err(e) => {
+                log::error!("Invalid IPC request: {}", e);
+                continue;
+            }
+        };
+
+        let hub = hub.clone();
+        let edge = edge.clone();
+
+        tokio::spawn(async move {
+            handle_request(request, hub, edge).await;
+        });
+    }
+}
+
+async fn handle_request(
+    req: IpcRequest,
+    hub: Arc<Mutex<Option<Arc<TunnelHub>>>>,
+    edge: Arc<Mutex<Option<Arc<TunnelEdge>>>>,
+) {
+    match req.method.as_str() {
+        "ping" => {
+            send_response(&req.id, serde_json::json!({ "pong": true }));
+        }
+
+        "startHub" => {
+            let config: HubConfig = match serde_json::from_value(req.params.clone()) {
+                Ok(c) => c,
+                Err(e) => {
+                    send_error(&req.id, &format!("invalid hub config: {}", e));
+                    return;
+                }
+            };
+
+            let tunnel_hub = Arc::new(TunnelHub::new(config));
+
+            // Forward hub events to IPC
+            if let Some(mut event_rx) = tunnel_hub.take_event_rx().await {
+                tokio::spawn(async move {
+                    while let Some(event) = event_rx.recv().await {
+                        match &event {
+                            HubEvent::EdgeConnected { edge_id, peer_addr } => {
+                                send_event(
+                                    "edgeConnected",
+                                    serde_json::json!({ "edgeId": edge_id, "peerAddr": peer_addr }),
+                                );
+                            }
+                            HubEvent::EdgeDisconnected { edge_id, reason } => {
+                                send_event(
+                                    "edgeDisconnected",
+                                    serde_json::json!({ "edgeId": edge_id, "reason": reason }),
+                                );
+                            }
+                            HubEvent::StreamOpened {
+                                edge_id,
+                                stream_id,
+                            } => {
+                                send_event(
+                                    "streamOpened",
+                                    serde_json::json!({
+                                        "edgeId": edge_id,
+                                        "streamId": stream_id,
+                                    }),
+                                );
+                            }
+                            HubEvent::StreamClosed {
+                                edge_id,
+                                stream_id,
+                            } => {
+                                send_event(
+                                    "streamClosed",
+                                    serde_json::json!({
+                                        "edgeId": edge_id,
+                                        "streamId": stream_id,
+                                    }),
+                                );
+                            }
+                        }
+                    }
+                });
+            }
+
+            match tunnel_hub.start().await {
+                Ok(()) => {
+                    *hub.lock().await = Some(tunnel_hub);
+                    send_response(&req.id, serde_json::json!({ "started": true }));
+                }
+                Err(e) => {
+                    send_error(&req.id, &format!("failed to start hub: {}", e));
+                }
+            }
+        }
+
+        "stopHub" => {
+            let mut h = hub.lock().await;
+            if let Some(hub_instance) = h.take() {
+                hub_instance.stop().await;
+                send_response(&req.id, serde_json::json!({ "stopped": true }));
+            } else {
+                send_response(
+                    &req.id,
+                    serde_json::json!({ "stopped": true, "wasRunning": false }),
+                );
+            }
+        }
+
+        "updateAllowedEdges" => {
+            #[derive(Deserialize)]
+            #[serde(rename_all = "camelCase")]
+            struct UpdateEdgesParams {
+                edges: Vec<AllowedEdge>,
+            }
+
+            let params: UpdateEdgesParams = match serde_json::from_value(req.params.clone()) {
+                Ok(p) => p,
+                Err(e) => {
+                    send_error(&req.id, &format!("invalid params: {}", e));
+                    return;
+                }
+            };
+
+            let h = hub.lock().await;
+            if let Some(hub_instance) = h.as_ref() {
+                hub_instance.update_allowed_edges(params.edges).await;
+                send_response(&req.id, serde_json::json!({ "updated": true }));
+            } else {
+                send_error(&req.id, "hub not running");
+            }
+        }
+
+        "getHubStatus" => {
+            let h = hub.lock().await;
+            if let Some(hub_instance) = h.as_ref() {
+                let status = hub_instance.get_status().await;
+                send_response(
+                    &req.id,
+                    serde_json::to_value(&status).unwrap_or_default(),
+                );
+            } else {
+                send_response(
+                    &req.id,
+                    serde_json::json!({
+                        "running": false,
+                        "tunnelPort": 0,
+                        "connectedEdges": []
+                    }),
+                );
+            }
+        }
+
+        "startEdge" => {
+            let config: EdgeConfig = match serde_json::from_value(req.params.clone()) {
+                Ok(c) => c,
+                Err(e) => {
+                    send_error(&req.id, &format!("invalid edge config: {}", e));
+                    return;
+                }
+            };
+
+            let tunnel_edge = Arc::new(TunnelEdge::new(config));
+
+            // Forward edge events to IPC
+            if let Some(mut event_rx) = tunnel_edge.take_event_rx().await {
+                tokio::spawn(async move {
+                    while let Some(event) = event_rx.recv().await {
+                        match &event {
+                            EdgeEvent::TunnelConnected => {
+                                send_event("tunnelConnected", serde_json::json!({}));
+                            }
+                            EdgeEvent::TunnelDisconnected { reason } => {
+                                send_event("tunnelDisconnected", serde_json::json!({ "reason": reason }));
+                            }
+                            EdgeEvent::PublicIpDiscovered { ip } => {
+                                send_event(
+                                    "publicIpDiscovered",
+                                    serde_json::json!({ "ip": ip }),
+                                );
+                            }
+                            EdgeEvent::PortsAssigned { listen_ports } => {
+                                send_event(
+                                    "portsAssigned",
+                                    serde_json::json!({ "listenPorts": listen_ports }),
+                                );
+                            }
+                            EdgeEvent::PortsUpdated { listen_ports } => {
+                                send_event(
+                                    "portsUpdated",
+                                    serde_json::json!({ "listenPorts": listen_ports }),
+                                );
+                            }
+                        }
+                    }
+                });
+            }
+
+            match tunnel_edge.start().await {
+                Ok(()) => {
+                    *edge.lock().await = Some(tunnel_edge);
+                    send_response(&req.id, serde_json::json!({ "started": true }));
+                }
+                Err(e) => {
+                    send_error(&req.id, &format!("failed to start edge: {}", e));
+                }
+            }
+        }
+
+        "stopEdge" => {
+            let mut e = edge.lock().await;
+            if let Some(edge_instance) = e.take() {
+                edge_instance.stop().await;
+                send_response(&req.id, serde_json::json!({ "stopped": true }));
+            } else {
+                send_response(
+                    &req.id,
+                    serde_json::json!({ "stopped": true, "wasRunning": false }),
+                );
+            }
+        }
+
+        "getEdgeStatus" => {
+            let e = edge.lock().await;
+            if let Some(edge_instance) = e.as_ref() {
+                let status = edge_instance.get_status().await;
+                send_response(
+                    &req.id,
+                    serde_json::to_value(&status).unwrap_or_default(),
+                );
+            } else {
+                send_response(
+                    &req.id,
+                    serde_json::json!({
+                        "running": false,
+                        "connected": false,
+                        "publicIp": null,
+                        "activeStreams": 0,
+                        "listenPorts": []
+                    }),
+                );
+            }
+        }
+
+        _ => {
+            send_error(&req.id, &format!("unknown method: {}", req.method));
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_ipc_request_deserialize() {
+        let json = r#"{"id": "1", "method": "ping", "params": {}}"#;
+        let req: IpcRequest = serde_json::from_str(json).unwrap();
+        assert_eq!(req.id, "1");
+        assert_eq!(req.method, "ping");
+        assert!(req.params.is_object());
+    }
+
+    #[test]
+    fn test_ipc_response_skip_error_when_none() {
+        let resp = IpcResponse {
+            id: "1".to_string(),
+            success: true,
+            result: Some(serde_json::json!({"pong": true})),
+            error: None,
+        };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert_eq!(json["id"], "1");
+        assert_eq!(json["success"], true);
+        assert_eq!(json["result"]["pong"], true);
+        assert!(json.get("error").is_none());
+    }
+
+    #[test]
+    fn test_ipc_response_skip_result_when_none() {
+        let resp = IpcResponse {
+            id: "2".to_string(),
+            success: false,
+            result: None,
+            error: Some("something failed".to_string()),
+        };
+        let json = serde_json::to_value(&resp).unwrap();
+        assert_eq!(json["id"], "2");
+        assert_eq!(json["success"], false);
+        assert_eq!(json["error"], "something failed");
+        assert!(json.get("result").is_none());
+    }
+
+    #[test]
+    fn test_ipc_event_serialize() {
+        let evt = IpcEvent {
+            event: "ready".to_string(),
+            data: serde_json::json!({"version": "2.0.0"}),
+        };
+        let json = serde_json::to_value(&evt).unwrap();
+        assert_eq!(json["event"], "ready");
+        assert_eq!(json["data"]["version"], "2.0.0");
+    }
+}

rust/crates/remoteingress-core/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "remoteingress-core"
+version = "2.0.0"
+edition = "2021"
+
+[dependencies]
+remoteingress-protocol = { path = "../remoteingress-protocol" }
+tokio = { version = "1", features = ["full"] }
+tokio-rustls = "0.26"
+bytes = "1"
+rustls = { version = "0.23", default-features = false, features = ["ring", "logging", "std", "tls12"] }
+rcgen = "0.13"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+log = "0.4"
+rustls-pemfile = "2"
+tokio-util = "0.7"
+socket2 = "0.5"
+quinn = "0.11"

rust/crates/remoteingress-core/src/lib.rs

@@ -0,0 +1,7 @@
+pub mod hub;
+pub mod edge;
+pub mod stun;
+pub mod transport;
+pub mod udp_session;
+
+pub use remoteingress_protocol as protocol;

rust/crates/remoteingress-core/src/stun.rs

@@ -0,0 +1,264 @@
+use std::net::Ipv4Addr;
+use tokio::net::UdpSocket;
+use tokio::time::{timeout, Duration};
+
+const STUN_SERVER: &str = "stun.cloudflare.com:3478";
+const STUN_TIMEOUT: Duration = Duration::from_secs(3);
+
+// STUN constants
+const STUN_BINDING_REQUEST: u16 = 0x0001;
+const STUN_MAGIC_COOKIE: u32 = 0x2112A442;
+const ATTR_XOR_MAPPED_ADDRESS: u16 = 0x0020;
+const ATTR_MAPPED_ADDRESS: u16 = 0x0001;
+
+/// Discover our public IP via STUN Binding Request (RFC 5389).
+/// Returns `None` on timeout or parse failure.
+pub async fn discover_public_ip() -> Option<String> {
+    discover_public_ip_from(STUN_SERVER).await
+}
+
+pub async fn discover_public_ip_from(server: &str) -> Option<String> {
+    let result = timeout(STUN_TIMEOUT, async {
+        let socket = UdpSocket::bind("0.0.0.0:0").await.ok()?;
+        socket.connect(server).await.ok()?;
+
+        // Build STUN Binding Request (20 bytes)
+        let mut request = [0u8; 20];
+        // Message Type: Binding Request (0x0001)
+        request[0..2].copy_from_slice(&STUN_BINDING_REQUEST.to_be_bytes());
+        // Message Length: 0 (no attributes)
+        request[2..4].copy_from_slice(&0u16.to_be_bytes());
+        // Magic Cookie
+        request[4..8].copy_from_slice(&STUN_MAGIC_COOKIE.to_be_bytes());
+        // Transaction ID: 12 random bytes
+        let txn_id: [u8; 12] = rand_bytes();
+        request[8..20].copy_from_slice(&txn_id);
+
+        socket.send(&request).await.ok()?;
+
+        let mut buf = [0u8; 512];
+        let n = socket.recv(&mut buf).await.ok()?;
+        if n < 20 {
+            return None;
+        }
+
+        parse_stun_response(&buf[..n], &txn_id)
+    })
+    .await;
+
+    match result {
+        Ok(ip) => ip,
+        Err(_) => None, // timeout
+    }
+}
+
+fn parse_stun_response(data: &[u8], _txn_id: &[u8; 12]) -> Option<String> {
+    if data.len() < 20 {
+        return None;
+    }
+
+    // Verify it's a Binding Response (0x0101)
+    let msg_type = u16::from_be_bytes([data[0], data[1]]);
+    if msg_type != 0x0101 {
+        return None;
+    }
+
+    let msg_len = u16::from_be_bytes([data[2], data[3]]) as usize;
+    let magic = u32::from_be_bytes([data[4], data[5], data[6], data[7]]);
+
+    // Parse attributes
+    let attrs = &data[20..std::cmp::min(20 + msg_len, data.len())];
+    let mut offset = 0;
+
+    while offset + 4 <= attrs.len() {
+        let attr_type = u16::from_be_bytes([attrs[offset], attrs[offset + 1]]);
+        let attr_len = u16::from_be_bytes([attrs[offset + 2], attrs[offset + 3]]) as usize;
+        offset += 4;
+
+        if offset + attr_len > attrs.len() {
+            break;
+        }
+
+        let attr_data = &attrs[offset..offset + attr_len];
+
+        match attr_type {
+            ATTR_XOR_MAPPED_ADDRESS if attr_data.len() >= 8 => {
+                let family = attr_data[1];
+                if family == 0x01 {
+                    // IPv4
+                    let port_xored = u16::from_be_bytes([attr_data[2], attr_data[3]]);
+                    let _port = port_xored ^ (STUN_MAGIC_COOKIE >> 16) as u16;
+                    let ip_xored = u32::from_be_bytes([
+                        attr_data[4],
+                        attr_data[5],
+                        attr_data[6],
+                        attr_data[7],
+                    ]);
+                    let ip = ip_xored ^ magic;
+                    return Some(Ipv4Addr::from(ip).to_string());
+                }
+            }
+            ATTR_MAPPED_ADDRESS if attr_data.len() >= 8 => {
+                let family = attr_data[1];
+                if family == 0x01 {
+                    // IPv4 (non-XOR fallback)
+                    let ip = u32::from_be_bytes([
+                        attr_data[4],
+                        attr_data[5],
+                        attr_data[6],
+                        attr_data[7],
+                    ]);
+                    return Some(Ipv4Addr::from(ip).to_string());
+                }
+            }
+            _ => {}
+        }
+
+        // Pad to 4-byte boundary
+        offset += (attr_len + 3) & !3;
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a synthetic STUN Binding Response with given attributes.
+    fn build_stun_response(attrs: &[(u16, &[u8])]) -> Vec<u8> {
+        let mut attrs_bytes = Vec::new();
+        for &(attr_type, attr_data) in attrs {
+            attrs_bytes.extend_from_slice(&attr_type.to_be_bytes());
+            attrs_bytes.extend_from_slice(&(attr_data.len() as u16).to_be_bytes());
+            attrs_bytes.extend_from_slice(attr_data);
+            // Pad to 4-byte boundary
+            let pad = (4 - (attr_data.len() % 4)) % 4;
+            attrs_bytes.extend(std::iter::repeat(0u8).take(pad));
+        }
+
+        let mut response = Vec::new();
+        // msg_type = 0x0101 (Binding Response)
+        response.extend_from_slice(&0x0101u16.to_be_bytes());
+        // message length
+        response.extend_from_slice(&(attrs_bytes.len() as u16).to_be_bytes());
+        // magic cookie
+        response.extend_from_slice(&STUN_MAGIC_COOKIE.to_be_bytes());
+        // transaction ID (12 bytes)
+        response.extend_from_slice(&[0u8; 12]);
+        // attributes
+        response.extend_from_slice(&attrs_bytes);
+        response
+    }
+
+    #[test]
+    fn test_xor_mapped_address_ipv4() {
+        // IP 203.0.113.1 = 0xCB007101, XOR'd with magic 0x2112A442 = 0xEA12D543
+        let attr_data: [u8; 8] = [
+            0x00, 0x01, // reserved + family (IPv4)
+            0x11, 0x2B, // port XOR'd with 0x2112 (port 0x3039 = 12345)
+            0xEA, 0x12, 0xD5, 0x43, // IP XOR'd
+        ];
+        let data = build_stun_response(&[(ATTR_XOR_MAPPED_ADDRESS, &attr_data)]);
+        let txn_id = [0u8; 12];
+        let result = parse_stun_response(&data, &txn_id);
+        assert_eq!(result, Some("203.0.113.1".to_string()));
+    }
+
+    #[test]
+    fn test_mapped_address_fallback_ipv4() {
+        // IP 192.168.1.1 = 0xC0A80101 (no XOR)
+        let attr_data: [u8; 8] = [
+            0x00, 0x01, // reserved + family (IPv4)
+            0x00, 0x50, // port 80
+            0xC0, 0xA8, 0x01, 0x01, // IP
+        ];
+        let data = build_stun_response(&[(ATTR_MAPPED_ADDRESS, &attr_data)]);
+        let txn_id = [0u8; 12];
+        let result = parse_stun_response(&data, &txn_id);
+        assert_eq!(result, Some("192.168.1.1".to_string()));
+    }
+
+    #[test]
+    fn test_response_too_short() {
+        let data = vec![0u8; 19]; // < 20 bytes
+        let txn_id = [0u8; 12];
+        assert_eq!(parse_stun_response(&data, &txn_id), None);
+    }
+
+    #[test]
+    fn test_wrong_msg_type() {
+        // Build with correct helper then overwrite msg_type to 0x0001 (Binding Request)
+        let mut data = build_stun_response(&[]);
+        data[0] = 0x00;
+        data[1] = 0x01;
+        let txn_id = [0u8; 12];
+        assert_eq!(parse_stun_response(&data, &txn_id), None);
+    }
+
+    #[test]
+    fn test_no_mapped_address_attributes() {
+        // Valid response with no attributes
+        let data = build_stun_response(&[]);
+        let txn_id = [0u8; 12];
+        assert_eq!(parse_stun_response(&data, &txn_id), None);
+    }
+
+    #[test]
+    fn test_xor_preferred_over_mapped() {
+        // XOR gives 203.0.113.1, MAPPED gives 192.168.1.1
+        let xor_data: [u8; 8] = [
+            0x00, 0x01,
+            0x11, 0x2B,
+            0xEA, 0x12, 0xD5, 0x43,
+        ];
+        let mapped_data: [u8; 8] = [
+            0x00, 0x01,
+            0x00, 0x50,
+            0xC0, 0xA8, 0x01, 0x01,
+        ];
+        // XOR listed first — should be preferred
+        let data = build_stun_response(&[
+            (ATTR_XOR_MAPPED_ADDRESS, &xor_data),
+            (ATTR_MAPPED_ADDRESS, &mapped_data),
+        ]);
+        let txn_id = [0u8; 12];
+        let result = parse_stun_response(&data, &txn_id);
+        assert_eq!(result, Some("203.0.113.1".to_string()));
+    }
+
+    #[test]
+    fn test_truncated_attribute_data() {
+        // Attribute claims 8 bytes but only 4 are present
+        let mut data = build_stun_response(&[]);
+        // Manually append a truncated XOR_MAPPED_ADDRESS attribute
+        let attr_type = ATTR_XOR_MAPPED_ADDRESS.to_be_bytes();
+        let attr_len = 8u16.to_be_bytes(); // claims 8 bytes
+        let truncated = [0x00, 0x01, 0x11, 0x2B]; // only 4 bytes
+        // Update message length
+        let new_msg_len = (attr_type.len() + attr_len.len() + truncated.len()) as u16;
+        data[2..4].copy_from_slice(&new_msg_len.to_be_bytes());
+        data.extend_from_slice(&attr_type);
+        data.extend_from_slice(&attr_len);
+        data.extend_from_slice(&truncated);
+
+        let txn_id = [0u8; 12];
+        // Should return None, not panic
+        assert_eq!(parse_stun_response(&data, &txn_id), None);
+    }
+}
+
+/// Generate 12 random bytes for transaction ID.
+fn rand_bytes() -> [u8; 12] {
+    let mut bytes = [0u8; 12];
+    // Use a simple approach: mix timestamp + counter
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default();
+    let nanos = now.as_nanos();
+    bytes[0..8].copy_from_slice(&(nanos as u64).to_le_bytes());
+    // Fill remaining with process-id based data
+    let pid = std::process::id();
+    bytes[8..12].copy_from_slice(&pid.to_le_bytes());
+    bytes
+}

rust/crates/remoteingress-core/src/transport/mod.rs

@@ -0,0 +1,22 @@
+pub mod quic;
+
+use serde::{Deserialize, Serialize};
+
+/// Transport mode for the tunnel connection between edge and hub.
+///
+/// - `TcpTls`: TCP + TLS with frame-based multiplexing via TunnelIo (default).
+/// - `Quic`: QUIC with native stream multiplexing (one QUIC stream per tunneled connection).
+/// - `QuicWithFallback`: Try QUIC first, fall back to TCP+TLS if UDP is blocked.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum TransportMode {
+    TcpTls,
+    Quic,
+    QuicWithFallback,
+}
+
+impl Default for TransportMode {
+    fn default() -> Self {
+        TransportMode::TcpTls
+    }
+}

rust/crates/remoteingress-core/src/transport/quic.rs

@@ -0,0 +1,191 @@
+use std::sync::Arc;
+
+/// QUIC control stream message types (reuses frame type constants for consistency).
+pub const CTRL_CONFIG: u8 = 0x06;
+pub const CTRL_PING: u8 = 0x07;
+pub const CTRL_PONG: u8 = 0x08;
+
+/// Header size for control stream messages: [type:1][length:4] = 5 bytes.
+pub const CTRL_HEADER_SIZE: usize = 5;
+
+/// Build a quinn ClientConfig that skips server certificate verification
+/// (auth is via shared secret, same as the TCP+TLS path).
+pub fn build_quic_client_config() -> quinn::ClientConfig {
+    let mut tls_config = rustls::ClientConfig::builder()
+        .dangerous()
+        .with_custom_certificate_verifier(Arc::new(NoCertVerifier))
+        .with_no_client_auth();
+
+    // QUIC mandates ALPN negotiation (RFC 9001 §8.1).
+    // Must match the server's ALPN protocol.
+    tls_config.alpn_protocols = vec![b"remoteingress".to_vec()];
+
+    let quic_config = quinn::crypto::rustls::QuicClientConfig::try_from(tls_config)
+        .expect("failed to build QUIC client config from rustls config");
+
+    let mut transport = quinn::TransportConfig::default();
+    transport.keep_alive_interval(Some(std::time::Duration::from_secs(15)));
+    transport.max_idle_timeout(Some(
+        quinn::IdleTimeout::try_from(std::time::Duration::from_secs(45)).unwrap(),
+    ));
+    // Match MAX_STREAMS_PER_EDGE (1024) from hub.rs.
+    // Default is 100 which is too low for high-concurrency tunneling.
+    transport.max_concurrent_bidi_streams(1024u32.into());
+
+    let mut client_config = quinn::ClientConfig::new(Arc::new(quic_config));
+    client_config.transport_config(Arc::new(transport));
+    client_config
+}
+
+/// Build a quinn ServerConfig from the same TLS server config used for TCP+TLS.
+pub fn build_quic_server_config(
+    tls_server_config: rustls::ServerConfig,
+) -> Result<quinn::ServerConfig, Box<dyn std::error::Error + Send + Sync>> {
+    let quic_config = quinn::crypto::rustls::QuicServerConfig::try_from(tls_server_config)?;
+
+    let mut transport = quinn::TransportConfig::default();
+    transport.keep_alive_interval(Some(std::time::Duration::from_secs(15)));
+    transport.max_idle_timeout(Some(
+        quinn::IdleTimeout::try_from(std::time::Duration::from_secs(45)).unwrap(),
+    ));
+    transport.max_concurrent_bidi_streams(1024u32.into());
+
+    let mut server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_config));
+    server_config.transport_config(Arc::new(transport));
+    Ok(server_config)
+}
+
+/// Write a control message to a QUIC send stream.
+/// Format: [type:1][length:4][payload:N]
+pub async fn write_ctrl_message(
+    send: &mut quinn::SendStream,
+    msg_type: u8,
+    payload: &[u8],
+) -> Result<(), std::io::Error> {
+    let len = payload.len() as u32;
+    let mut header = [0u8; CTRL_HEADER_SIZE];
+    header[0] = msg_type;
+    header[1..5].copy_from_slice(&len.to_be_bytes());
+    send.write_all(&header).await?;
+    if !payload.is_empty() {
+        send.write_all(payload).await?;
+    }
+    Ok(())
+}
+
+/// Read a control message from a QUIC recv stream.
+/// Returns (msg_type, payload). Returns None on EOF.
+pub async fn read_ctrl_message(
+    recv: &mut quinn::RecvStream,
+) -> Result<Option<(u8, Vec<u8>)>, std::io::Error> {
+    let mut header = [0u8; CTRL_HEADER_SIZE];
+    match recv.read_exact(&mut header).await {
+        Ok(()) => {}
+        Err(e) => {
+            if let quinn::ReadExactError::FinishedEarly(_) = e {
+                return Ok(None);
+            }
+            return Err(std::io::Error::new(std::io::ErrorKind::Other, e));
+        }
+    }
+    let msg_type = header[0];
+    let len = u32::from_be_bytes([header[1], header[2], header[3], header[4]]) as usize;
+    let mut payload = vec![0u8; len];
+    if len > 0 {
+        recv.read_exact(&mut payload).await.map_err(|e| {
+            std::io::Error::new(std::io::ErrorKind::Other, e)
+        })?;
+    }
+    Ok(Some((msg_type, payload)))
+}
+
+/// Write the PROXY v1 header as the first bytes on a QUIC data stream.
+/// The header is length-prefixed so the receiver knows where it ends and data begins.
+/// Format: [header_len:4][proxy_header:N]
+pub async fn write_proxy_header(
+    send: &mut quinn::SendStream,
+    proxy_header: &str,
+) -> Result<(), std::io::Error> {
+    let header_bytes = proxy_header.as_bytes();
+    let len = header_bytes.len() as u32;
+    send.write_all(&len.to_be_bytes()).await?;
+    send.write_all(header_bytes).await?;
+    Ok(())
+}
+
+/// Read the PROXY v1 header from the first bytes of a QUIC data stream.
+/// Returns the header string.
+pub async fn read_proxy_header(
+    recv: &mut quinn::RecvStream,
+) -> Result<String, std::io::Error> {
+    let mut len_buf = [0u8; 4];
+    recv.read_exact(&mut len_buf).await.map_err(|e| {
+        std::io::Error::new(std::io::ErrorKind::Other, e)
+    })?;
+    let len = u32::from_be_bytes(len_buf) as usize;
+    if len > 8192 {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "proxy header too long",
+        ));
+    }
+    let mut header = vec![0u8; len];
+    recv.read_exact(&mut header).await.map_err(|e| {
+        std::io::Error::new(std::io::ErrorKind::Other, e)
+    })?;
+    String::from_utf8(header).map_err(|_| {
+        std::io::Error::new(std::io::ErrorKind::InvalidData, "proxy header not UTF-8")
+    })
+}
+
+/// TLS certificate verifier that accepts any certificate (auth is via shared secret).
+/// Same as the one in edge.rs but placed here so the QUIC module is self-contained.
+#[derive(Debug)]
+struct NoCertVerifier;
+
+impl rustls::client::danger::ServerCertVerifier for NoCertVerifier {
+    fn verify_server_cert(
+        &self,
+        _end_entity: &rustls::pki_types::CertificateDer<'_>,
+        _intermediates: &[rustls::pki_types::CertificateDer<'_>],
+        _server_name: &rustls::pki_types::ServerName<'_>,
+        _ocsp_response: &[u8],
+        _now: rustls::pki_types::UnixTime,
+    ) -> Result<rustls::client::danger::ServerCertVerified, rustls::Error> {
+        Ok(rustls::client::danger::ServerCertVerified::assertion())
+    }
+
+    fn verify_tls12_signature(
+        &self,
+        _message: &[u8],
+        _cert: &rustls::pki_types::CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn verify_tls13_signature(
+        &self,
+        _message: &[u8],
+        _cert: &rustls::pki_types::CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn supported_verify_schemes(&self) -> Vec<rustls::SignatureScheme> {
+        vec![
+            rustls::SignatureScheme::RSA_PKCS1_SHA256,
+            rustls::SignatureScheme::RSA_PKCS1_SHA384,
+            rustls::SignatureScheme::RSA_PKCS1_SHA512,
+            rustls::SignatureScheme::ECDSA_NISTP256_SHA256,
+            rustls::SignatureScheme::ECDSA_NISTP384_SHA384,
+            rustls::SignatureScheme::ECDSA_NISTP521_SHA512,
+            rustls::SignatureScheme::RSA_PSS_SHA256,
+            rustls::SignatureScheme::RSA_PSS_SHA384,
+            rustls::SignatureScheme::RSA_PSS_SHA512,
+            rustls::SignatureScheme::ED25519,
+            rustls::SignatureScheme::ED448,
+        ]
+    }
+}

rust/crates/remoteingress-core/src/udp_session.rs

@@ -0,0 +1,210 @@
+use std::collections::HashMap;
+use std::net::SocketAddr;
+use tokio::time::Instant;
+
+/// Key identifying a unique UDP "session" (one client endpoint talking to one destination port).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct UdpSessionKey {
+    pub client_addr: SocketAddr,
+    pub dest_port: u16,
+}
+
+/// A single UDP session tracked by the edge.
+pub struct UdpSession {
+    pub stream_id: u32,
+    pub client_addr: SocketAddr,
+    pub dest_port: u16,
+    pub last_activity: Instant,
+}
+
+/// Manages UDP sessions with idle timeout expiry.
+pub struct UdpSessionManager {
+    /// Forward map: session key → session data.
+    sessions: HashMap<UdpSessionKey, UdpSession>,
+    /// Reverse map: stream_id → session key (for dispatching return traffic).
+    by_stream_id: HashMap<u32, UdpSessionKey>,
+    /// Idle timeout duration.
+    idle_timeout: std::time::Duration,
+}
+
+impl UdpSessionManager {
+    pub fn new(idle_timeout: std::time::Duration) -> Self {
+        Self {
+            sessions: HashMap::new(),
+            by_stream_id: HashMap::new(),
+            idle_timeout,
+        }
+    }
+
+    /// Look up an existing session by key. Updates last_activity on hit.
+    pub fn get_mut(&mut self, key: &UdpSessionKey) -> Option<&mut UdpSession> {
+        let session = self.sessions.get_mut(key)?;
+        session.last_activity = Instant::now();
+        Some(session)
+    }
+
+    /// Look up a session's client address by stream_id (for return traffic).
+    pub fn client_addr_for_stream(&self, stream_id: u32) -> Option<SocketAddr> {
+        let key = self.by_stream_id.get(&stream_id)?;
+        self.sessions.get(key).map(|s| s.client_addr)
+    }
+
+    /// Look up a session by stream_id. Updates last_activity on hit.
+    pub fn get_by_stream_id(&mut self, stream_id: u32) -> Option<&mut UdpSession> {
+        let key = self.by_stream_id.get(&stream_id)?;
+        let session = self.sessions.get_mut(key)?;
+        session.last_activity = Instant::now();
+        Some(session)
+    }
+
+    /// Insert a new session. Returns a mutable reference to it.
+    pub fn insert(&mut self, key: UdpSessionKey, stream_id: u32) -> &mut UdpSession {
+        let session = UdpSession {
+            stream_id,
+            client_addr: key.client_addr,
+            dest_port: key.dest_port,
+            last_activity: Instant::now(),
+        };
+        self.by_stream_id.insert(stream_id, key);
+        self.sessions.entry(key).or_insert(session)
+    }
+
+    /// Remove a session by stream_id.
+    pub fn remove_by_stream_id(&mut self, stream_id: u32) -> Option<UdpSession> {
+        if let Some(key) = self.by_stream_id.remove(&stream_id) {
+            self.sessions.remove(&key)
+        } else {
+            None
+        }
+    }
+
+    /// Expire idle sessions. Returns the stream_ids of expired sessions.
+    pub fn expire_idle(&mut self) -> Vec<u32> {
+        let now = Instant::now();
+        let timeout = self.idle_timeout;
+        let expired_keys: Vec<UdpSessionKey> = self
+            .sessions
+            .iter()
+            .filter(|(_, s)| now.duration_since(s.last_activity) >= timeout)
+            .map(|(k, _)| *k)
+            .collect();
+
+        let mut expired_ids = Vec::with_capacity(expired_keys.len());
+        for key in expired_keys {
+            if let Some(session) = self.sessions.remove(&key) {
+                self.by_stream_id.remove(&session.stream_id);
+                expired_ids.push(session.stream_id);
+            }
+        }
+        expired_ids
+    }
+
+    /// Number of active sessions.
+    pub fn len(&self) -> usize {
+        self.sessions.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+
+    fn addr(port: u16) -> SocketAddr {
+        SocketAddr::from(([127, 0, 0, 1], port))
+    }
+
+    #[test]
+    fn test_insert_and_lookup() {
+        let mut mgr = UdpSessionManager::new(Duration::from_secs(60));
+        let key = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        mgr.insert(key, 1);
+
+        assert_eq!(mgr.len(), 1);
+        assert!(mgr.get_mut(&key).is_some());
+        assert_eq!(mgr.get_mut(&key).unwrap().stream_id, 1);
+    }
+
+    #[test]
+    fn test_client_addr_for_stream() {
+        let mut mgr = UdpSessionManager::new(Duration::from_secs(60));
+        let key = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        mgr.insert(key, 42);
+
+        assert_eq!(mgr.client_addr_for_stream(42), Some(addr(5000)));
+        assert_eq!(mgr.client_addr_for_stream(99), None);
+    }
+
+    #[test]
+    fn test_remove_by_stream_id() {
+        let mut mgr = UdpSessionManager::new(Duration::from_secs(60));
+        let key = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        mgr.insert(key, 1);
+
+        let removed = mgr.remove_by_stream_id(1);
+        assert!(removed.is_some());
+        assert_eq!(mgr.len(), 0);
+        assert!(mgr.get_mut(&key).is_none());
+        assert_eq!(mgr.client_addr_for_stream(1), None);
+    }
+
+    #[test]
+    fn test_remove_nonexistent() {
+        let mut mgr = UdpSessionManager::new(Duration::from_secs(60));
+        assert!(mgr.remove_by_stream_id(999).is_none());
+    }
+
+    #[tokio::test]
+    async fn test_expire_idle() {
+        let mut mgr = UdpSessionManager::new(Duration::from_millis(50));
+        let key1 = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        let key2 = UdpSessionKey { client_addr: addr(5001), dest_port: 53 };
+        mgr.insert(key1, 1);
+        mgr.insert(key2, 2);
+
+        // Nothing expired yet
+        assert!(mgr.expire_idle().is_empty());
+        assert_eq!(mgr.len(), 2);
+
+        // Wait for timeout
+        tokio::time::sleep(Duration::from_millis(60)).await;
+
+        let expired = mgr.expire_idle();
+        assert_eq!(expired.len(), 2);
+        assert_eq!(mgr.len(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_activity_prevents_expiry() {
+        let mut mgr = UdpSessionManager::new(Duration::from_millis(100));
+        let key = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        mgr.insert(key, 1);
+
+        // Touch session at 50ms (before 100ms timeout)
+        tokio::time::sleep(Duration::from_millis(50)).await;
+        mgr.get_mut(&key); // refreshes last_activity
+
+        // At 80ms from last touch, should still be alive
+        tokio::time::sleep(Duration::from_millis(80)).await;
+        assert!(mgr.expire_idle().is_empty());
+        assert_eq!(mgr.len(), 1);
+
+        // Wait for full timeout from last activity
+        tokio::time::sleep(Duration::from_millis(30)).await;
+        let expired = mgr.expire_idle();
+        assert_eq!(expired.len(), 1);
+    }
+
+    #[test]
+    fn test_multiple_sessions_same_client_different_ports() {
+        let mut mgr = UdpSessionManager::new(Duration::from_secs(60));
+        let key1 = UdpSessionKey { client_addr: addr(5000), dest_port: 53 };
+        let key2 = UdpSessionKey { client_addr: addr(5000), dest_port: 443 };
+        mgr.insert(key1, 1);
+        mgr.insert(key2, 2);
+
+        assert_eq!(mgr.len(), 2);
+        assert_eq!(mgr.get_mut(&key1).unwrap().stream_id, 1);
+        assert_eq!(mgr.get_mut(&key2).unwrap().stream_id, 2);
+    }
+}

rust/crates/remoteingress-protocol/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "remoteingress-protocol"
+version = "2.0.0"
+edition = "2021"
+
+[dependencies]
+tokio = { version = "1", features = ["io-util", "sync", "time"] }
+tokio-util = "0.7"
+bytes = "1"
+log = "0.4"
+
+[dev-dependencies]
+tokio = { version = "1", features = ["io-util", "macros", "rt"] }

test/test.classes.node.ts

@@ -0,0 +1,35 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import { EventEmitter } from 'events';
+import { RemoteIngressHub, RemoteIngressEdge } from '../ts/index.js';
+
+tap.test('RemoteIngressHub constructor does not throw', async () => {
+  const hub = new RemoteIngressHub();
+  expect(hub).toBeTruthy();
+});
+
+tap.test('RemoteIngressHub is instanceof EventEmitter', async () => {
+  const hub = new RemoteIngressHub();
+  expect(hub).toBeInstanceOf(EventEmitter);
+});
+
+tap.test('RemoteIngressHub.running is false before start', async () => {
+  const hub = new RemoteIngressHub();
+  expect(hub.running).toBeFalse();
+});
+
+tap.test('RemoteIngressEdge constructor does not throw', async () => {
+  const edge = new RemoteIngressEdge();
+  expect(edge).toBeTruthy();
+});
+
+tap.test('RemoteIngressEdge is instanceof EventEmitter', async () => {
+  const edge = new RemoteIngressEdge();
+  expect(edge).toBeInstanceOf(EventEmitter);
+});
+
+tap.test('RemoteIngressEdge.running is false before start', async () => {
+  const edge = new RemoteIngressEdge();
+  expect(edge.running).toBeFalse();
+});
+
+export default tap.start();

test/test.flowcontrol.node.ts

@@ -0,0 +1,475 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as net from 'net';
+import * as crypto from 'crypto';
+import { RemoteIngressHub, RemoteIngressEdge } from '../ts/index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Find N free ports by binding to port 0 and collecting OS-assigned ports. */
+async function findFreePorts(count: number): Promise<number[]> {
+  const servers: net.Server[] = [];
+  const ports: number[] = [];
+  for (let i = 0; i < count; i++) {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    ports.push((server.address() as net.AddressInfo).port);
+    servers.push(server);
+  }
+  await Promise.all(servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+  return ports;
+}
+
+type TrackingServer = net.Server & { destroyAll: () => void };
+
+/** Start a TCP echo server that tracks connections for force-close. */
+function startEchoServer(port: number, host: string): Promise<TrackingServer> {
+  return new Promise((resolve, reject) => {
+    const connections = new Set<net.Socket>();
+    const server = net.createServer((socket) => {
+      connections.add(socket);
+      socket.on('close', () => connections.delete(socket));
+
+      // Skip PROXY protocol v1 header line before echoing
+      let proxyHeaderParsed = false;
+      let pendingBuf = Buffer.alloc(0);
+      socket.on('data', (data: Buffer) => {
+        if (!proxyHeaderParsed) {
+          pendingBuf = Buffer.concat([pendingBuf, data]);
+          const idx = pendingBuf.indexOf('\r\n');
+          if (idx !== -1) {
+            proxyHeaderParsed = true;
+            const remainder = pendingBuf.subarray(idx + 2);
+            if (remainder.length > 0) {
+              socket.write(remainder);
+            }
+          }
+          return;
+        }
+        socket.write(data);
+      });
+      socket.on('error', () => {});
+    }) as TrackingServer;
+
+    server.destroyAll = () => {
+      for (const conn of connections) conn.destroy();
+      connections.clear();
+    };
+
+    server.on('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+/**
+ * Start a server that sends a large response immediately on first data received.
+ * Does NOT wait for end (the tunnel protocol has no half-close).
+ * On receiving first data chunk after PROXY header, sends responseSize bytes then closes.
+ */
+function startLargeResponseServer(port: number, host: string, responseSize: number): Promise<TrackingServer> {
+  return new Promise((resolve, reject) => {
+    const connections = new Set<net.Socket>();
+    const server = net.createServer((socket) => {
+      connections.add(socket);
+      socket.on('close', () => connections.delete(socket));
+
+      let proxyHeaderParsed = false;
+      let pendingBuf = Buffer.alloc(0);
+      let responseSent = false;
+
+      socket.on('data', (data: Buffer) => {
+        if (!proxyHeaderParsed) {
+          pendingBuf = Buffer.concat([pendingBuf, data]);
+          const idx = pendingBuf.indexOf('\r\n');
+          if (idx !== -1) {
+            proxyHeaderParsed = true;
+            const remainder = pendingBuf.subarray(idx + 2);
+            if (remainder.length > 0 && !responseSent) {
+              responseSent = true;
+              sendLargeResponse(socket, responseSize);
+            }
+          }
+          return;
+        }
+        if (!responseSent) {
+          responseSent = true;
+          sendLargeResponse(socket, responseSize);
+        }
+      });
+      socket.on('error', () => {});
+    }) as TrackingServer;
+
+    server.destroyAll = () => {
+      for (const conn of connections) conn.destroy();
+      connections.clear();
+    };
+
+    server.on('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+function sendLargeResponse(socket: net.Socket, totalBytes: number) {
+  const chunkSize = 32 * 1024;
+  let sent = 0;
+  const writeChunk = () => {
+    while (sent < totalBytes) {
+      const toWrite = Math.min(chunkSize, totalBytes - sent);
+      // Use a deterministic pattern for verification
+      const chunk = Buffer.alloc(toWrite, (sent % 256) & 0xff);
+      const canContinue = socket.write(chunk);
+      sent += toWrite;
+      if (!canContinue) {
+        socket.once('drain', writeChunk);
+        return;
+      }
+    }
+    socket.end();
+  };
+  writeChunk();
+}
+
+/** Force-close a server: destroy all connections, then close. */
+async function forceCloseServer(server: TrackingServer): Promise<void> {
+  server.destroyAll();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+}
+
+interface TestTunnel {
+  hub: RemoteIngressHub;
+  edge: RemoteIngressEdge;
+  edgePort: number;
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Start a full hub + edge tunnel.
+ * Edge binds to 127.0.0.1, upstream server binds to 127.0.0.2.
+ * Hub targetHost = 127.0.0.2 so hub -> upstream doesn't loop back to edge.
+ */
+async function startTunnel(edgePort: number, hubPort: number): Promise<TestTunnel> {
+  const hub = new RemoteIngressHub();
+  const edge = new RemoteIngressEdge();
+
+  await hub.start({
+    tunnelPort: hubPort,
+    targetHost: '127.0.0.2',
+  });
+
+  await hub.updateAllowedEdges([
+    { id: 'test-edge', secret: 'test-secret', listenPorts: [edgePort] },
+  ]);
+
+  const connectedPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Edge did not connect within 10s')), 10000);
+    edge.once('tunnelConnected', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+
+  await edge.start({
+    hubHost: '127.0.0.1',
+    hubPort,
+    edgeId: 'test-edge',
+    secret: 'test-secret',
+    bindAddress: '127.0.0.1',
+  });
+
+  await connectedPromise;
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  return {
+    hub,
+    edge,
+    edgePort,
+    cleanup: async () => {
+      await edge.stop();
+      await hub.stop();
+    },
+  };
+}
+
+/**
+ * Send data through the tunnel and collect the echoed response.
+ */
+function sendAndReceive(port: number, data: Buffer, timeoutMs = 30000): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalReceived = 0;
+    const expectedLength = data.length;
+    let settled = false;
+
+    const client = net.createConnection({ host: '127.0.0.1', port }, () => {
+      client.write(data);
+      client.end();
+    });
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        client.destroy();
+        reject(new Error(`Timeout after ${timeoutMs}ms — received ${totalReceived}/${expectedLength} bytes`));
+      }
+    }, timeoutMs);
+
+    client.on('data', (chunk: Buffer) => {
+      chunks.push(chunk);
+      totalReceived += chunk.length;
+      if (totalReceived >= expectedLength && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.destroy();
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('end', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Connect to the tunnel, send a small request, and collect a large response.
+ * Does NOT call end() — the tunnel has no half-close.
+ * Instead, collects until expectedResponseSize bytes arrive.
+ */
+function sendAndReceiveLarge(
+  port: number,
+  data: Buffer,
+  expectedResponseSize: number,
+  timeoutMs = 60000,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalReceived = 0;
+    let settled = false;
+
+    const client = net.createConnection({ host: '127.0.0.1', port }, () => {
+      client.write(data);
+      // Do NOT call client.end() — the server will respond immediately
+      // and the tunnel CLOSE will happen when the download finishes
+    });
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        client.destroy();
+        reject(new Error(`Timeout after ${timeoutMs}ms — received ${totalReceived}/${expectedResponseSize} bytes`));
+      }
+    }, timeoutMs);
+
+    client.on('data', (chunk: Buffer) => {
+      chunks.push(chunk);
+      totalReceived += chunk.length;
+      if (totalReceived >= expectedResponseSize && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.destroy();
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('end', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  });
+}
+
+function sha256(buf: Buffer): string {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+let tunnel: TestTunnel;
+let echoServer: TrackingServer;
+let hubPort: number;
+let edgePort: number;
+
+tap.test('setup: start echo server and tunnel', async () => {
+  [hubPort, edgePort] = await findFreePorts(2);
+
+  echoServer = await startEchoServer(edgePort, '127.0.0.2');
+  tunnel = await startTunnel(edgePort, hubPort);
+
+  expect(tunnel.hub.running).toBeTrue();
+});
+
+tap.test('single stream: 32MB transfer exceeding initial 4MB window (multiple refills)', async () => {
+  const size = 32 * 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  const expectedHash = sha256(data);
+
+  const received = await sendAndReceive(edgePort, data, 60000);
+
+  expect(received.length).toEqual(size);
+  expect(sha256(received)).toEqual(expectedHash);
+});
+
+tap.test('200 concurrent streams with 64KB each', async () => {
+  const streamCount = 200;
+  const payloadSize = 64 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 30000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('512 concurrent streams at minimum window boundary (16KB each)', async () => {
+  const streamCount = 512;
+  const payloadSize = 16 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 60000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('asymmetric transfer: 4KB request -> 4MB response', async () => {
+  // Swap to large-response server
+  await forceCloseServer(echoServer);
+  const responseSize = 4 * 1024 * 1024; // 4 MB
+  const largeServer = await startLargeResponseServer(edgePort, '127.0.0.2', responseSize);
+
+  try {
+    const requestData = crypto.randomBytes(4 * 1024); // 4 KB
+    const received = await sendAndReceiveLarge(edgePort, requestData, responseSize, 60000);
+    expect(received.length).toEqual(responseSize);
+  } finally {
+    // Always restore echo server even on failure
+    await forceCloseServer(largeServer);
+    echoServer = await startEchoServer(edgePort, '127.0.0.2');
+  }
+});
+
+tap.test('100 streams x 1MB each (100MB total exceeding 200MB budget)', async () => {
+  const streamCount = 100;
+  const payloadSize = 1 * 1024 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 120000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('active stream counter tracks concurrent connections', async () => {
+  const N = 50;
+
+  // Open N connections and keep them alive (send data but don't close)
+  const sockets: net.Socket[] = [];
+  const connectPromises = Array.from({ length: N }, () => {
+    return new Promise<net.Socket>((resolve, reject) => {
+      const sock = net.createConnection({ host: '127.0.0.1', port: edgePort }, () => {
+        resolve(sock);
+      });
+      sock.on('error', () => {});
+      setTimeout(() => reject(new Error('connect timeout')), 5000);
+    });
+  });
+
+  const connected = await Promise.all(connectPromises);
+  sockets.push(...connected);
+
+  // Brief delay for stream registration to propagate
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // Verify the edge reports >= N active streams.
+  // This counter is the input to compute_window_for_stream_count(),
+  // so its accuracy determines whether adaptive window sizing is correct.
+  const status = await tunnel.edge.getStatus();
+  expect(status.activeStreams).toBeGreaterThanOrEqual(N);
+
+  // Clean up: destroy all sockets (the tunnel's 300s stream timeout will handle cleanup)
+  for (const sock of sockets) {
+    sock.destroy();
+  }
+});
+
+tap.test('50 streams x 2MB each (forces multiple window refills per stream)', async () => {
+  // At 50 concurrent streams: adaptive window = 200MB/50 = 4MB per stream
+  // Each stream sends 2MB → needs ~3 WINDOW_UPDATE refill cycles per stream
+  const streamCount = 50;
+  const payloadSize = 2 * 1024 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 120000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('teardown: stop tunnel and echo server', async () => {
+  await tunnel.cleanup();
+  await forceCloseServer(echoServer);
+});
+
+export default tap.start();

test/test.loadtest.node.ts

@@ -0,0 +1,402 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as net from 'net';
+import * as stream from 'stream';
+import * as crypto from 'crypto';
+import { RemoteIngressHub, RemoteIngressEdge } from '../ts/index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers (self-contained — same patterns as test.flowcontrol.node.ts)
+// ---------------------------------------------------------------------------
+
+async function findFreePorts(count: number): Promise<number[]> {
+  const servers: net.Server[] = [];
+  const ports: number[] = [];
+  for (let i = 0; i < count; i++) {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    ports.push((server.address() as net.AddressInfo).port);
+    servers.push(server);
+  }
+  await Promise.all(servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+  return ports;
+}
+
+type TrackingServer = net.Server & { destroyAll: () => void };
+
+function startEchoServer(port: number, host: string): Promise<TrackingServer> {
+  return new Promise((resolve, reject) => {
+    const connections = new Set<net.Socket>();
+    const server = net.createServer((socket) => {
+      connections.add(socket);
+      socket.on('close', () => connections.delete(socket));
+      let proxyHeaderParsed = false;
+      let pendingBuf = Buffer.alloc(0);
+      socket.on('data', (data: Buffer) => {
+        if (!proxyHeaderParsed) {
+          pendingBuf = Buffer.concat([pendingBuf, data]);
+          const idx = pendingBuf.indexOf('\r\n');
+          if (idx !== -1) {
+            proxyHeaderParsed = true;
+            const remainder = pendingBuf.subarray(idx + 2);
+            if (remainder.length > 0) socket.write(remainder);
+          }
+          return;
+        }
+        socket.write(data);
+      });
+      socket.on('error', () => {});
+    }) as TrackingServer;
+    server.destroyAll = () => {
+      for (const conn of connections) conn.destroy();
+      connections.clear();
+    };
+    server.on('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+function sendAndReceive(port: number, data: Buffer, timeoutMs = 30000): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalReceived = 0;
+    const expectedLength = data.length;
+    let settled = false;
+
+    const client = net.createConnection({ host: '127.0.0.1', port }, () => {
+      client.write(data);
+      client.end();
+    });
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        client.destroy();
+        reject(new Error(`Timeout after ${timeoutMs}ms — received ${totalReceived}/${expectedLength} bytes`));
+      }
+    }, timeoutMs);
+
+    client.on('data', (chunk: Buffer) => {
+      chunks.push(chunk);
+      totalReceived += chunk.length;
+      if (totalReceived >= expectedLength && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.destroy();
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('end', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  });
+}
+
+function sha256(buf: Buffer): string {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Throttle Proxy: rate-limits TCP traffic between edge and hub
+// ---------------------------------------------------------------------------
+
+class ThrottleTransform extends stream.Transform {
+  private bytesPerSec: number;
+  private bucket: number;
+  private lastRefill: number;
+  private destroyed_: boolean = false;
+
+  constructor(bytesPerSecond: number) {
+    super();
+    this.bytesPerSec = bytesPerSecond;
+    this.bucket = bytesPerSecond;
+    this.lastRefill = Date.now();
+  }
+
+  _transform(chunk: Buffer, _encoding: BufferEncoding, callback: stream.TransformCallback) {
+    if (this.destroyed_) return;
+
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    this.bucket = Math.min(this.bytesPerSec, this.bucket + elapsed * this.bytesPerSec);
+    this.lastRefill = now;
+
+    if (chunk.length <= this.bucket) {
+      this.bucket -= chunk.length;
+      callback(null, chunk);
+    } else {
+      // Not enough budget — delay the entire chunk (don't split)
+      const deficit = chunk.length - this.bucket;
+      this.bucket = 0;
+      const delayMs = Math.min((deficit / this.bytesPerSec) * 1000, 1000);
+      setTimeout(() => {
+        if (this.destroyed_) { callback(); return; }
+        this.lastRefill = Date.now();
+        this.bucket = 0;
+        callback(null, chunk);
+      }, delayMs);
+    }
+  }
+
+  _destroy(err: Error | null, callback: (error: Error | null) => void) {
+    this.destroyed_ = true;
+    callback(err);
+  }
+}
+
+interface ThrottleProxy {
+  server: net.Server;
+  close: () => Promise<void>;
+}
+
+async function startThrottleProxy(
+  listenPort: number,
+  targetHost: string,
+  targetPort: number,
+  bytesPerSecond: number,
+): Promise<ThrottleProxy> {
+  const connections = new Set<net.Socket>();
+  const server = net.createServer((clientSock) => {
+    connections.add(clientSock);
+    const upstream = net.createConnection({ host: targetHost, port: targetPort });
+    connections.add(upstream);
+
+    const throttleUp = new ThrottleTransform(bytesPerSecond);
+    const throttleDown = new ThrottleTransform(bytesPerSecond);
+
+    clientSock.pipe(throttleUp).pipe(upstream);
+    upstream.pipe(throttleDown).pipe(clientSock);
+
+    let cleaned = false;
+    const cleanup = (source: string, err?: Error) => {
+      if (cleaned) return;
+      cleaned = true;
+      if (err) {
+        console.error(`[ThrottleProxy] cleanup triggered by ${source}: ${err.message}`);
+      } else {
+        console.error(`[ThrottleProxy] cleanup triggered by ${source} (no error)`);
+      }
+      console.error(`[ThrottleProxy] stack:`, new Error().stack);
+      throttleUp.destroy();
+      throttleDown.destroy();
+      clientSock.destroy();
+      upstream.destroy();
+      connections.delete(clientSock);
+      connections.delete(upstream);
+    };
+    clientSock.on('error', (e) => cleanup('clientSock.error', e));
+    upstream.on('error', (e) => cleanup('upstream.error', e));
+    throttleUp.on('error', (e) => cleanup('throttleUp.error', e));
+    throttleDown.on('error', (e) => cleanup('throttleDown.error', e));
+    clientSock.on('close', () => cleanup('clientSock.close'));
+    upstream.on('close', () => cleanup('upstream.close'));
+  });
+
+  await new Promise<void>((resolve) => server.listen(listenPort, '127.0.0.1', resolve));
+  return {
+    server,
+    close: async () => {
+      for (const c of connections) c.destroy();
+      connections.clear();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Test state
+// ---------------------------------------------------------------------------
+
+let hub: RemoteIngressHub;
+let edge: RemoteIngressEdge;
+let echoServer: TrackingServer;
+let throttle: ThrottleProxy;
+let hubPort: number;
+let proxyPort: number;
+let edgePort: number;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+tap.test('setup: start throttled tunnel (100 Mbit/s)', async () => {
+  [hubPort, proxyPort, edgePort] = await findFreePorts(3);
+
+  echoServer = await startEchoServer(edgePort, '127.0.0.2');
+
+  // Throttle proxy: edge → proxy → hub at 100 Mbit/s (12.5 MB/s)
+  throttle = await startThrottleProxy(proxyPort, '127.0.0.1', hubPort, 12.5 * 1024 * 1024);
+
+  hub = new RemoteIngressHub();
+  edge = new RemoteIngressEdge();
+
+  await hub.start({ tunnelPort: hubPort, targetHost: '127.0.0.2' });
+  await hub.updateAllowedEdges([
+    { id: 'test-edge', secret: 'test-secret', listenPorts: [edgePort] },
+  ]);
+
+  const connectedPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Edge did not connect within 10s')), 10000);
+    edge.once('tunnelConnected', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+
+  // Edge connects through throttle proxy
+  await edge.start({
+    hubHost: '127.0.0.1',
+    hubPort: proxyPort,
+    edgeId: 'test-edge',
+    secret: 'test-secret',
+    bindAddress: '127.0.0.1',
+  });
+
+  await connectedPromise;
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('throttled: 5 streams x 20MB each through 100Mbit tunnel', async () => {
+  const streamCount = 5;
+  const payloadSize = 20 * 1024 * 1024; // 20MB per stream = 100MB total round-trip
+
+  const payloads = Array.from({ length: streamCount }, () => crypto.randomBytes(payloadSize));
+  const promises = payloads.map((data) => {
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 300000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+  expect(failures.length).toEqual(0);
+
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('throttled: slow consumer with 20MB does not kill other streams', async () => {
+  // Open a connection that creates download-direction backpressure:
+  // send 20MB but DON'T read the response — client TCP receive buffer fills
+  const slowSock = net.createConnection({ host: '127.0.0.1', port: edgePort });
+  await new Promise<void>((resolve) => slowSock.on('connect', resolve));
+  const slowData = crypto.randomBytes(20 * 1024 * 1024);
+  slowSock.write(slowData);
+  slowSock.end();
+  // Don't read — backpressure builds on the download path
+
+  // Wait for backpressure to develop
+  await new Promise((r) => setTimeout(r, 2000));
+
+  // Meanwhile, 5 normal echo streams with 20MB each must complete
+  const payload = crypto.randomBytes(20 * 1024 * 1024);
+  const hash = sha256(payload);
+  const promises = Array.from({ length: 5 }, () =>
+    sendAndReceive(edgePort, payload, 300000).then((r) => ({
+      hash: sha256(r),
+      sizeOk: r.length === payload.length,
+    }))
+  );
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.hash !== hash);
+  expect(failures.length).toEqual(0);
+
+  // Tunnel still alive
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+
+  slowSock.destroy();
+});
+
+tap.test('throttled: rapid churn — 3 x 20MB long + 50 x 1MB short streams', async () => {
+  // 3 long streams (20MB each) running alongside 50 short streams (1MB each)
+  const longPayload = crypto.randomBytes(20 * 1024 * 1024);
+  const longHash = sha256(longPayload);
+  const longPromises = Array.from({ length: 3 }, () =>
+    sendAndReceive(edgePort, longPayload, 300000).then((r) => ({
+      hash: sha256(r),
+      sizeOk: r.length === longPayload.length,
+    }))
+  );
+
+  const shortPayload = crypto.randomBytes(1024 * 1024);
+  const shortHash = sha256(shortPayload);
+  const shortPromises = Array.from({ length: 50 }, () =>
+    sendAndReceive(edgePort, shortPayload, 300000).then((r) => ({
+      hash: sha256(r),
+      sizeOk: r.length === shortPayload.length,
+    }))
+  );
+
+  const [longResults, shortResults] = await Promise.all([
+    Promise.all(longPromises),
+    Promise.all(shortPromises),
+  ]);
+
+  const longFails = longResults.filter((r) => !r.sizeOk || r.hash !== longHash);
+  const shortFails = shortResults.filter((r) => !r.sizeOk || r.hash !== shortHash);
+  expect(longFails.length).toEqual(0);
+  expect(shortFails.length).toEqual(0);
+
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('throttled: 3 burst waves of 5 streams x 20MB each', async () => {
+  for (let wave = 0; wave < 3; wave++) {
+    const streamCount = 5;
+    const payloadSize = 20 * 1024 * 1024; // 20MB per stream = 100MB per wave
+
+    const promises = Array.from({ length: streamCount }, () => {
+      const data = crypto.randomBytes(payloadSize);
+      return sendAndReceive(edgePort, data, 300000).then((r) => r.length === payloadSize);
+    });
+
+    const results = await Promise.all(promises);
+    const ok = results.filter(Boolean).length;
+    expect(ok).toEqual(streamCount);
+
+    // Brief pause between waves
+    await new Promise((r) => setTimeout(r, 500));
+
+    const status = await edge.getStatus();
+    expect(status.connected).toBeTrue();
+  }
+});
+
+tap.test('throttled: tunnel still works after all load tests', async () => {
+  const data = crypto.randomBytes(1024);
+  const hash = sha256(data);
+  const received = await sendAndReceive(edgePort, data, 30000);
+  expect(sha256(received)).toEqual(hash);
+
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('teardown: stop tunnel', async () => {
+  await edge.stop();
+  await hub.stop();
+  if (throttle) await throttle.close();
+  await new Promise<void>((resolve) => echoServer.close(() => resolve()));
+});
+
+export default tap.start();

test/test.quic.node.ts

@@ -0,0 +1,283 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as net from 'net';
+import * as crypto from 'crypto';
+import { RemoteIngressHub, RemoteIngressEdge } from '../ts/index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers (same patterns as test.flowcontrol.node.ts)
+// ---------------------------------------------------------------------------
+
+async function findFreePorts(count: number): Promise<number[]> {
+  const servers: net.Server[] = [];
+  const ports: number[] = [];
+  for (let i = 0; i < count; i++) {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    ports.push((server.address() as net.AddressInfo).port);
+    servers.push(server);
+  }
+  await Promise.all(servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+  return ports;
+}
+
+type TrackingServer = net.Server & { destroyAll: () => void };
+
+function startEchoServer(port: number, host: string): Promise<TrackingServer> {
+  return new Promise((resolve, reject) => {
+    const connections = new Set<net.Socket>();
+    const server = net.createServer((socket) => {
+      connections.add(socket);
+      socket.on('close', () => connections.delete(socket));
+      let proxyHeaderParsed = false;
+      let pendingBuf = Buffer.alloc(0);
+      socket.on('data', (data: Buffer) => {
+        if (!proxyHeaderParsed) {
+          pendingBuf = Buffer.concat([pendingBuf, data]);
+          const idx = pendingBuf.indexOf('\r\n');
+          if (idx !== -1) {
+            proxyHeaderParsed = true;
+            const remainder = pendingBuf.subarray(idx + 2);
+            if (remainder.length > 0) socket.write(remainder);
+          }
+          return;
+        }
+        socket.write(data);
+      });
+      socket.on('error', () => {});
+    }) as TrackingServer;
+    server.destroyAll = () => {
+      for (const conn of connections) conn.destroy();
+      connections.clear();
+    };
+    server.on('error', reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+async function forceCloseServer(server: TrackingServer): Promise<void> {
+  server.destroyAll();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+}
+
+interface TestTunnel {
+  hub: RemoteIngressHub;
+  edge: RemoteIngressEdge;
+  edgePort: number;
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Start a full hub + edge tunnel using QUIC transport.
+ * Edge binds to 127.0.0.1, upstream server binds to 127.0.0.2.
+ */
+async function startQuicTunnel(edgePort: number, hubPort: number): Promise<TestTunnel> {
+  const hub = new RemoteIngressHub();
+  const edge = new RemoteIngressEdge();
+
+  await hub.start({
+    tunnelPort: hubPort,
+    targetHost: '127.0.0.2',
+  });
+
+  await hub.updateAllowedEdges([
+    { id: 'test-edge', secret: 'test-secret', listenPorts: [edgePort] },
+  ]);
+
+  const connectedPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('QUIC edge did not connect within 10s')), 10000);
+    edge.once('tunnelConnected', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+
+  await edge.start({
+    hubHost: '127.0.0.1',
+    hubPort,
+    edgeId: 'test-edge',
+    secret: 'test-secret',
+    bindAddress: '127.0.0.1',
+    transportMode: 'quic',
+  });
+
+  await connectedPromise;
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  return {
+    hub,
+    edge,
+    edgePort,
+    cleanup: async () => {
+      await edge.stop();
+      await hub.stop();
+    },
+  };
+}
+
+function sendAndReceive(port: number, data: Buffer, timeoutMs = 30000): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalReceived = 0;
+    const expectedLength = data.length;
+    let settled = false;
+
+    const client = net.createConnection({ host: '127.0.0.1', port }, () => {
+      client.write(data);
+      client.end();
+    });
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        client.destroy();
+        reject(new Error(`Timeout after ${timeoutMs}ms — received ${totalReceived}/${expectedLength} bytes`));
+      }
+    }, timeoutMs);
+
+    client.on('data', (chunk: Buffer) => {
+      chunks.push(chunk);
+      totalReceived += chunk.length;
+      if (totalReceived >= expectedLength && !settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.destroy();
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('end', () => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(Buffer.concat(chunks));
+      }
+    });
+
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  });
+}
+
+function sha256(buf: Buffer): string {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// QUIC Transport E2E Tests
+// ---------------------------------------------------------------------------
+
+let tunnel: TestTunnel;
+let echoServer: TrackingServer;
+let hubPort: number;
+let edgePort: number;
+
+tap.test('QUIC setup: start echo server and QUIC tunnel', async () => {
+  [hubPort, edgePort] = await findFreePorts(2);
+
+  echoServer = await startEchoServer(edgePort, '127.0.0.2');
+  tunnel = await startQuicTunnel(edgePort, hubPort);
+
+  expect(tunnel.hub.running).toBeTrue();
+  const status = await tunnel.edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('QUIC: single stream echo — 1KB', async () => {
+  const data = crypto.randomBytes(1024);
+  const hash = sha256(data);
+  const received = await sendAndReceive(edgePort, data, 10000);
+  expect(received.length).toEqual(1024);
+  expect(sha256(received)).toEqual(hash);
+});
+
+tap.test('QUIC: single stream echo — 1MB', async () => {
+  const size = 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  const hash = sha256(data);
+  const received = await sendAndReceive(edgePort, data, 30000);
+  expect(received.length).toEqual(size);
+  expect(sha256(received)).toEqual(hash);
+});
+
+tap.test('QUIC: single stream echo — 16MB', async () => {
+  const size = 16 * 1024 * 1024;
+  const data = crypto.randomBytes(size);
+  const hash = sha256(data);
+  const received = await sendAndReceive(edgePort, data, 60000);
+  expect(received.length).toEqual(size);
+  expect(sha256(received)).toEqual(hash);
+});
+
+tap.test('QUIC: 10 concurrent streams x 1MB each', async () => {
+  const streamCount = 10;
+  const payloadSize = 1024 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 30000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('QUIC: 50 concurrent streams x 64KB each', async () => {
+  const streamCount = 50;
+  const payloadSize = 64 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 30000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('QUIC: 200 concurrent streams x 16KB each', async () => {
+  const streamCount = 200;
+  const payloadSize = 16 * 1024;
+
+  const promises = Array.from({ length: streamCount }, () => {
+    const data = crypto.randomBytes(payloadSize);
+    const hash = sha256(data);
+    return sendAndReceive(edgePort, data, 60000).then((received) => ({
+      sent: hash,
+      received: sha256(received),
+      sizeOk: received.length === payloadSize,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || r.sent !== r.received);
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('QUIC: tunnel still connected after all tests', async () => {
+  const status = await tunnel.edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('QUIC teardown: stop tunnel and echo server', async () => {
+  await tunnel.cleanup();
+  await forceCloseServer(echoServer);
+});
+
+export default tap.start();

test/test.token.node.ts

@@ -0,0 +1,152 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import { encodeConnectionToken, decodeConnectionToken, type IConnectionTokenData } from '../ts/classes.token.js';
+
+tap.test('token roundtrip with unicode chars in secret', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'hub.example.com',
+    hubPort: 8443,
+    edgeId: 'edge-1',
+    secret: 'sécret-with-ünïcödé-日本語',
+  };
+  const token = encodeConnectionToken(data);
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.secret).toEqual(data.secret);
+});
+
+tap.test('token roundtrip with empty edgeId', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'hub.test',
+    hubPort: 443,
+    edgeId: '',
+    secret: 'key',
+  };
+  const token = encodeConnectionToken(data);
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.edgeId).toEqual('');
+});
+
+tap.test('token roundtrip with port 0', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'h',
+    hubPort: 0,
+    edgeId: 'e',
+    secret: 's',
+  };
+  const token = encodeConnectionToken(data);
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.hubPort).toEqual(0);
+});
+
+tap.test('token roundtrip with port 65535', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'h',
+    hubPort: 65535,
+    edgeId: 'e',
+    secret: 's',
+  };
+  const token = encodeConnectionToken(data);
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.hubPort).toEqual(65535);
+});
+
+tap.test('token roundtrip with very long secret (10k chars)', async () => {
+  const longSecret = 'x'.repeat(10000);
+  const data: IConnectionTokenData = {
+    hubHost: 'host',
+    hubPort: 1234,
+    edgeId: 'edge',
+    secret: longSecret,
+  };
+  const token = encodeConnectionToken(data);
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.secret).toEqual(longSecret);
+  expect(decoded.secret.length).toEqual(10000);
+});
+
+tap.test('token string is URL-safe', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'hub.example.com',
+    hubPort: 8443,
+    edgeId: 'edge-001',
+    secret: 'super+secret/key==with+special/chars',
+  };
+  const token = encodeConnectionToken(data);
+  expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
+});
+
+tap.test('decode empty string throws', async () => {
+  let error: Error | undefined;
+  try {
+    decodeConnectionToken('');
+  } catch (e) {
+    error = e as Error;
+  }
+  expect(error).toBeInstanceOf(Error);
+});
+
+tap.test('decode valid base64 but wrong JSON shape throws missing required fields', async () => {
+  // Encode { "a": 1, "b": 2 } — valid JSON but wrong shape
+  const token = Buffer.from(JSON.stringify({ a: 1, b: 2 }), 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  let error: Error | undefined;
+  try {
+    decodeConnectionToken(token);
+  } catch (e) {
+    error = e as Error;
+  }
+  expect(error).toBeInstanceOf(Error);
+  expect(error!.message).toInclude('missing required fields');
+});
+
+tap.test('decode valid JSON but wrong field types throws missing required fields', async () => {
+  // h is number instead of string, p is string instead of number
+  const token = Buffer.from(JSON.stringify({ h: 123, p: 'notnum', e: 'e', s: 's' }), 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  let error: Error | undefined;
+  try {
+    decodeConnectionToken(token);
+  } catch (e) {
+    error = e as Error;
+  }
+  expect(error).toBeInstanceOf(Error);
+  expect(error!.message).toInclude('missing required fields');
+});
+
+tap.test('decode with extra fields succeeds', async () => {
+  const token = Buffer.from(
+    JSON.stringify({ h: 'host', p: 443, e: 'edge', s: 'secret', extra: 'ignored' }),
+    'utf-8',
+  )
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  const decoded = decodeConnectionToken(token);
+  expect(decoded.hubHost).toEqual('host');
+  expect(decoded.hubPort).toEqual(443);
+  expect(decoded.edgeId).toEqual('edge');
+  expect(decoded.secret).toEqual('secret');
+});
+
+tap.test('encode is deterministic', async () => {
+  const data: IConnectionTokenData = {
+    hubHost: 'hub.test',
+    hubPort: 8443,
+    edgeId: 'edge-1',
+    secret: 'deterministic-key',
+  };
+  const token1 = encodeConnectionToken(data);
+  const token2 = encodeConnectionToken(data);
+  expect(token1).toEqual(token2);
+});
+
+export default tap.start();

test/test.ts

@@ -1,8 +1,61 @@
-import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
-import * as remoteingress from '../ts/index.js'
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as remoteingress from '../ts/index.js';
 
-tap.test('first test', async () => {
-  console.log(remoteingress)
-})
+tap.test('should export RemoteIngressHub', async () => {
+  expect(remoteingress.RemoteIngressHub).toBeTypeOf('function');
+});
 
-tap.start()
+tap.test('should export RemoteIngressEdge', async () => {
+  expect(remoteingress.RemoteIngressEdge).toBeTypeOf('function');
+});
+
+tap.test('should export encodeConnectionToken and decodeConnectionToken', async () => {
+  expect(remoteingress.encodeConnectionToken).toBeTypeOf('function');
+  expect(remoteingress.decodeConnectionToken).toBeTypeOf('function');
+});
+
+tap.test('should roundtrip encode → decode a connection token', async () => {
+  const data: remoteingress.IConnectionTokenData = {
+    hubHost: 'hub.example.com',
+    hubPort: 8443,
+    edgeId: 'edge-001',
+    secret: 'super-secret-key',
+  };
+  const token = remoteingress.encodeConnectionToken(data);
+  const decoded = remoteingress.decodeConnectionToken(token);
+  expect(decoded.hubHost).toEqual(data.hubHost);
+  expect(decoded.hubPort).toEqual(data.hubPort);
+  expect(decoded.edgeId).toEqual(data.edgeId);
+  expect(decoded.secret).toEqual(data.secret);
+});
+
+tap.test('should throw on malformed token', async () => {
+  let error: Error | undefined;
+  try {
+    remoteingress.decodeConnectionToken('not-valid-json!!!');
+  } catch (e) {
+    error = e as Error;
+  }
+  expect(error).toBeInstanceOf(Error);
+  expect(error!.message).toInclude('Invalid connection token');
+});
+
+tap.test('should throw on token with missing fields', async () => {
+  // Encode a partial object (missing 'p' and 's')
+  const partial = Buffer.from(JSON.stringify({ h: 'host', e: 'edge' }), 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  let error: Error | undefined;
+  try {
+    remoteingress.decodeConnectionToken(partial);
+  } catch (e) {
+    error = e as Error;
+  }
+  expect(error).toBeInstanceOf(Error);
+  expect(error!.message).toInclude('missing required fields');
+});
+
+export default tap.start();

test/test.udp.node.ts

@@ -0,0 +1,193 @@
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as dgram from 'dgram';
+import * as net from 'net';
+import * as crypto from 'crypto';
+import { RemoteIngressHub, RemoteIngressEdge } from '../ts/index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function findFreePorts(count: number): Promise<number[]> {
+  const servers: net.Server[] = [];
+  const ports: number[] = [];
+  for (let i = 0; i < count; i++) {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    ports.push((server.address() as net.AddressInfo).port);
+    servers.push(server);
+  }
+  await Promise.all(servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+  return ports;
+}
+
+/**
+ * Start a UDP echo server that:
+ * 1. Receives the first datagram (PROXY v2 header — 28 bytes) and discards it
+ * 2. Echoes all subsequent datagrams back to the sender
+ */
+function startUdpEchoServer(port: number, host: string): Promise<dgram.Socket> {
+  return new Promise((resolve, reject) => {
+    const server = dgram.createSocket('udp4');
+    let proxyHeaderReceived = false;
+
+    server.on('message', (msg, rinfo) => {
+      if (!proxyHeaderReceived) {
+        // First datagram is the PROXY v2 header (28 bytes for IPv4)
+        // In the current implementation, the hub connects directly via UDP
+        // so the first real datagram is the actual data (no PROXY header yet)
+        // For now, just echo everything back
+        proxyHeaderReceived = true;
+      }
+      // Echo back
+      server.send(msg, rinfo.port, rinfo.address);
+    });
+
+    server.on('error', reject);
+    server.bind(port, host, () => resolve(server));
+  });
+}
+
+/**
+ * Send a UDP datagram through the tunnel and wait for the echo response.
+ */
+function udpSendAndReceive(
+  port: number,
+  data: Buffer,
+  timeoutMs = 10000,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const client = dgram.createSocket('udp4');
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        client.close();
+        reject(new Error(`UDP timeout after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+
+    client.on('message', (msg) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.close();
+        resolve(msg);
+      }
+    });
+
+    client.on('error', (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        client.close();
+        reject(err);
+      }
+    });
+
+    client.send(data, port, '127.0.0.1');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Test state
+// ---------------------------------------------------------------------------
+
+let hub: RemoteIngressHub;
+let edge: RemoteIngressEdge;
+let echoServer: dgram.Socket;
+let hubPort: number;
+let edgeUdpPort: number;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+tap.test('UDP setup: start echo server and tunnel with UDP ports', async () => {
+  [hubPort, edgeUdpPort] = await findFreePorts(2);
+
+  // Start UDP echo server on upstream (127.0.0.2)
+  echoServer = await startUdpEchoServer(edgeUdpPort, '127.0.0.2');
+
+  hub = new RemoteIngressHub();
+  edge = new RemoteIngressEdge();
+
+  await hub.start({ tunnelPort: hubPort, targetHost: '127.0.0.2' });
+  await hub.updateAllowedEdges([
+    { id: 'test-edge', secret: 'test-secret', listenPorts: [], listenPortsUdp: [edgeUdpPort] },
+  ]);
+
+  const connectedPromise = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Edge did not connect within 10s')), 10000);
+    edge.once('tunnelConnected', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+
+  await edge.start({
+    hubHost: '127.0.0.1',
+    hubPort,
+    edgeId: 'test-edge',
+    secret: 'test-secret',
+    bindAddress: '127.0.0.1',
+  });
+
+  await connectedPromise;
+  // Wait for UDP listener to bind
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('UDP: single datagram echo — 64 bytes', async () => {
+  const data = crypto.randomBytes(64);
+  const received = await udpSendAndReceive(edgeUdpPort, data, 5000);
+  expect(received.length).toEqual(64);
+  expect(Buffer.compare(received, data)).toEqual(0);
+});
+
+tap.test('UDP: single datagram echo — 1KB', async () => {
+  const data = crypto.randomBytes(1024);
+  const received = await udpSendAndReceive(edgeUdpPort, data, 5000);
+  expect(received.length).toEqual(1024);
+  expect(Buffer.compare(received, data)).toEqual(0);
+});
+
+tap.test('UDP: 10 sequential datagrams', async () => {
+  for (let i = 0; i < 10; i++) {
+    const data = crypto.randomBytes(128);
+    const received = await udpSendAndReceive(edgeUdpPort, data, 5000);
+    expect(received.length).toEqual(128);
+    expect(Buffer.compare(received, data)).toEqual(0);
+  }
+});
+
+tap.test('UDP: 10 concurrent datagrams from different source ports', async () => {
+  const promises = Array.from({ length: 10 }, () => {
+    const data = crypto.randomBytes(256);
+    return udpSendAndReceive(edgeUdpPort, data, 5000).then((received) => ({
+      sizeOk: received.length === 256,
+      dataOk: Buffer.compare(received, data) === 0,
+    }));
+  });
+
+  const results = await Promise.all(promises);
+  const failures = results.filter((r) => !r.sizeOk || !r.dataOk);
+  expect(failures.length).toEqual(0);
+});
+
+tap.test('UDP: tunnel still connected after tests', async () => {
+  const status = await edge.getStatus();
+  expect(status.connected).toBeTrue();
+});
+
+tap.test('UDP teardown: stop tunnel and echo server', async () => {
+  await edge.stop();
+  await hub.stop();
+  await new Promise<void>((resolve) => echoServer.close(() => resolve()));
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -1,8 +1,8 @@
 /**
- * autocreated commitinfo by @pushrocks/commitinfo
+ * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
   name: '@serve.zone/remoteingress',
-  version: '1.0.2',
-  description: 'a remoteingress service for serve.zone'
+  version: '4.11.0',
+  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.'
 }

ts/classes.remoteingressedge.ts

@@ -0,0 +1,251 @@
+import * as plugins from './plugins.js';
+import { EventEmitter } from 'events';
+import { decodeConnectionToken } from './classes.token.js';
+
+// Command map for the edge side of remoteingress-bin
+type TEdgeCommands = {
+  ping: {
+    params: Record<string, never>;
+    result: { pong: boolean };
+  };
+  startEdge: {
+    params: {
+      hubHost: string;
+      hubPort: number;
+      edgeId: string;
+      secret: string;
+      bindAddress?: string;
+      transportMode?: 'tcpTls' | 'quic' | 'quicWithFallback';
+    };
+    result: { started: boolean };
+  };
+  stopEdge: {
+    params: Record<string, never>;
+    result: { stopped: boolean; wasRunning?: boolean };
+  };
+  getEdgeStatus: {
+    params: Record<string, never>;
+    result: {
+      running: boolean;
+      connected: boolean;
+      publicIp: string | null;
+      activeStreams: number;
+      listenPorts: number[];
+    };
+  };
+};
+
+export interface IEdgeConfig {
+  hubHost: string;
+  hubPort?: number;
+  edgeId: string;
+  secret: string;
+  bindAddress?: string;
+  transportMode?: 'tcpTls' | 'quic' | 'quicWithFallback';
+}
+
+const MAX_RESTART_ATTEMPTS = 10;
+const MAX_RESTART_BACKOFF_MS = 30_000;
+
+export class RemoteIngressEdge extends EventEmitter {
+  private bridge: InstanceType<typeof plugins.smartrust.RustBridge<TEdgeCommands>>;
+  private started = false;
+  private stopping = false;
+  private savedConfig: IEdgeConfig | null = null;
+  private restartBackoffMs = 1000;
+  private restartAttempts = 0;
+  private statusInterval: ReturnType<typeof setInterval> | undefined;
+
+  constructor() {
+    super();
+
+    const packageDir = plugins.path.resolve(
+      plugins.path.dirname(new URL(import.meta.url).pathname),
+      '..',
+    );
+
+    this.bridge = new plugins.smartrust.RustBridge<TEdgeCommands>({
+      binaryName: 'remoteingress-bin',
+      cliArgs: ['--management'],
+      requestTimeoutMs: 30_000,
+      readyTimeoutMs: 10_000,
+      localPaths: [
+        // Platform-suffixed binary in dist_rust (production)
+        plugins.path.join(packageDir, 'dist_rust', `remoteingress-bin_${process.platform === 'win32' ? 'windows' : 'linux'}_${process.arch === 'x64' ? 'amd64' : process.arch}`),
+        // Exact binaryName fallback in dist_rust
+        plugins.path.join(packageDir, 'dist_rust', 'remoteingress-bin'),
+        // Development build paths (cargo output uses exact name)
+        plugins.path.join(packageDir, 'rust', 'target', 'release', 'remoteingress-bin'),
+        plugins.path.join(packageDir, 'rust', 'target', 'debug', 'remoteingress-bin'),
+      ],
+      searchSystemPath: false,
+    });
+
+    // Forward events from Rust binary
+    this.bridge.on('management:tunnelConnected', () => {
+      this.emit('tunnelConnected');
+    });
+    this.bridge.on('management:tunnelDisconnected', (data: { reason?: string }) => {
+      const reason = data?.reason ?? 'unknown';
+      console.log(`[RemoteIngressEdge] Tunnel disconnected: ${reason}`);
+      this.emit('tunnelDisconnected', data);
+    });
+    this.bridge.on('management:publicIpDiscovered', (data: { ip: string }) => {
+      this.emit('publicIpDiscovered', data);
+    });
+    this.bridge.on('management:portsAssigned', (data: { listenPorts: number[] }) => {
+      console.log(`[RemoteIngressEdge] Ports assigned by hub: ${data.listenPorts.join(', ')}`);
+      this.emit('portsAssigned', data);
+    });
+    this.bridge.on('management:portsUpdated', (data: { listenPorts: number[] }) => {
+      console.log(`[RemoteIngressEdge] Ports updated by hub: ${data.listenPorts.join(', ')}`);
+      this.emit('portsUpdated', data);
+    });
+  }
+
+  /**
+   * Start the edge — spawns the Rust binary and connects to the hub.
+   * Accepts either a connection token or an explicit IEdgeConfig.
+   */
+  public async start(config: { token: string } | IEdgeConfig): Promise<void> {
+    let edgeConfig: IEdgeConfig;
+
+    if ('token' in config) {
+      const decoded = decodeConnectionToken(config.token);
+      edgeConfig = {
+        hubHost: decoded.hubHost,
+        hubPort: decoded.hubPort,
+        edgeId: decoded.edgeId,
+        secret: decoded.secret,
+      };
+    } else {
+      edgeConfig = config;
+    }
+
+    this.savedConfig = edgeConfig;
+    this.stopping = false;
+
+    const spawned = await this.bridge.spawn();
+    if (!spawned) {
+      throw new Error('Failed to spawn remoteingress-bin');
+    }
+
+    // Register crash recovery handler
+    this.bridge.on('exit', this.handleCrashRecovery);
+
+    await this.bridge.sendCommand('startEdge', {
+      hubHost: edgeConfig.hubHost,
+      hubPort: edgeConfig.hubPort ?? 8443,
+      edgeId: edgeConfig.edgeId,
+      secret: edgeConfig.secret,
+      ...(edgeConfig.bindAddress ? { bindAddress: edgeConfig.bindAddress } : {}),
+      ...(edgeConfig.transportMode ? { transportMode: edgeConfig.transportMode } : {}),
+    });
+
+    this.started = true;
+    this.restartAttempts = 0;
+    this.restartBackoffMs = 1000;
+
+    // Start periodic status logging
+    this.statusInterval = setInterval(async () => {
+      try {
+        const status = await this.getStatus();
+        console.log(
+          `[RemoteIngressEdge] Status: connected=${status.connected}, ` +
+          `streams=${status.activeStreams}, ports=[${status.listenPorts.join(',')}], ` +
+          `publicIp=${status.publicIp ?? 'unknown'}`
+        );
+      } catch {
+        // Bridge may be shutting down
+      }
+    }, 60_000);
+  }
+
+  /**
+   * Stop the edge and kill the Rust process.
+   */
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    if (this.statusInterval) {
+      clearInterval(this.statusInterval);
+      this.statusInterval = undefined;
+    }
+    if (this.started) {
+      try {
+        await this.bridge.sendCommand('stopEdge', {} as Record<string, never>);
+      } catch {
+        // Process may already be dead
+      }
+      this.bridge.removeListener('exit', this.handleCrashRecovery);
+      this.bridge.kill();
+      this.started = false;
+    }
+  }
+
+  /**
+   * Get the current edge status.
+   */
+  public async getStatus() {
+    return this.bridge.sendCommand('getEdgeStatus', {} as Record<string, never>);
+  }
+
+  /**
+   * Check if the bridge is running.
+   */
+  public get running(): boolean {
+    return this.bridge.running;
+  }
+
+  /**
+   * Handle unexpected Rust binary crash — auto-restart with backoff.
+   */
+  private handleCrashRecovery = async (code: number | null, signal: string | null) => {
+    if (this.stopping || !this.started || !this.savedConfig) {
+      return;
+    }
+
+    console.error(
+      `[RemoteIngressEdge] Rust binary crashed (code=${code}, signal=${signal}), ` +
+      `attempt ${this.restartAttempts + 1}/${MAX_RESTART_ATTEMPTS}`
+    );
+
+    this.started = false;
+
+    if (this.restartAttempts >= MAX_RESTART_ATTEMPTS) {
+      console.error('[RemoteIngressEdge] Max restart attempts reached, giving up');
+      this.emit('crashRecoveryFailed');
+      return;
+    }
+
+    await new Promise(resolve => setTimeout(resolve, this.restartBackoffMs));
+    this.restartBackoffMs = Math.min(this.restartBackoffMs * 2, MAX_RESTART_BACKOFF_MS);
+    this.restartAttempts++;
+
+    try {
+      const spawned = await this.bridge.spawn();
+      if (!spawned) {
+        console.error('[RemoteIngressEdge] Failed to respawn binary');
+        return;
+      }
+
+      this.bridge.on('exit', this.handleCrashRecovery);
+
+      await this.bridge.sendCommand('startEdge', {
+        hubHost: this.savedConfig.hubHost,
+        hubPort: this.savedConfig.hubPort ?? 8443,
+        edgeId: this.savedConfig.edgeId,
+        secret: this.savedConfig.secret,
+        ...(this.savedConfig.bindAddress ? { bindAddress: this.savedConfig.bindAddress } : {}),
+        ...(this.savedConfig.transportMode ? { transportMode: this.savedConfig.transportMode } : {}),
+      });
+
+      this.started = true;
+      this.restartAttempts = 0;
+      this.restartBackoffMs = 1000;
+      console.log('[RemoteIngressEdge] Successfully recovered from crash');
+      this.emit('crashRecovered');
+    } catch (err) {
+      console.error(`[RemoteIngressEdge] Crash recovery failed: ${err}`);
+    }
+  };
+}

ts/classes.remoteingresshub.ts

@@ -0,0 +1,233 @@
+import * as plugins from './plugins.js';
+import { EventEmitter } from 'events';
+
+// Command map for the hub side of remoteingress-bin
+type THubCommands = {
+  ping: {
+    params: Record<string, never>;
+    result: { pong: boolean };
+  };
+  startHub: {
+    params: {
+      tunnelPort: number;
+      targetHost?: string;
+      tlsCertPem?: string;
+      tlsKeyPem?: string;
+    };
+    result: { started: boolean };
+  };
+  stopHub: {
+    params: Record<string, never>;
+    result: { stopped: boolean; wasRunning?: boolean };
+  };
+  updateAllowedEdges: {
+    params: {
+      edges: Array<{ id: string; secret: string; listenPorts?: number[]; listenPortsUdp?: number[]; stunIntervalSecs?: number }>;
+    };
+    result: { updated: boolean };
+  };
+  getHubStatus: {
+    params: Record<string, never>;
+    result: {
+      running: boolean;
+      tunnelPort: number;
+      connectedEdges: Array<{
+        edgeId: string;
+        connectedAt: number;
+        activeStreams: number;
+        peerAddr: string;
+      }>;
+    };
+  };
+};
+
+export interface IHubConfig {
+  tunnelPort?: number;
+  targetHost?: string;
+  tls?: {
+    certPem?: string;
+    keyPem?: string;
+  };
+}
+
+type TAllowedEdge = { id: string; secret: string; listenPorts?: number[]; listenPortsUdp?: number[]; stunIntervalSecs?: number };
+
+const MAX_RESTART_ATTEMPTS = 10;
+const MAX_RESTART_BACKOFF_MS = 30_000;
+
+export class RemoteIngressHub extends EventEmitter {
+  private bridge: InstanceType<typeof plugins.smartrust.RustBridge<THubCommands>>;
+  private started = false;
+  private stopping = false;
+  private savedConfig: IHubConfig | null = null;
+  private savedEdges: TAllowedEdge[] = [];
+  private restartBackoffMs = 1000;
+  private restartAttempts = 0;
+
+  constructor() {
+    super();
+
+    const packageDir = plugins.path.resolve(
+      plugins.path.dirname(new URL(import.meta.url).pathname),
+      '..',
+    );
+
+    this.bridge = new plugins.smartrust.RustBridge<THubCommands>({
+      binaryName: 'remoteingress-bin',
+      cliArgs: ['--management'],
+      requestTimeoutMs: 30_000,
+      readyTimeoutMs: 10_000,
+      localPaths: [
+        // Platform-suffixed binary in dist_rust (production)
+        plugins.path.join(packageDir, 'dist_rust', `remoteingress-bin_${process.platform === 'win32' ? 'windows' : 'linux'}_${process.arch === 'x64' ? 'amd64' : process.arch}`),
+        // Exact binaryName fallback in dist_rust
+        plugins.path.join(packageDir, 'dist_rust', 'remoteingress-bin'),
+        // Development build paths (cargo output uses exact name)
+        plugins.path.join(packageDir, 'rust', 'target', 'release', 'remoteingress-bin'),
+        plugins.path.join(packageDir, 'rust', 'target', 'debug', 'remoteingress-bin'),
+      ],
+      searchSystemPath: false,
+    });
+
+    // Forward events from Rust binary
+    this.bridge.on('management:edgeConnected', (data: { edgeId: string; peerAddr: string }) => {
+      this.emit('edgeConnected', data);
+    });
+    this.bridge.on('management:edgeDisconnected', (data: { edgeId: string; reason?: string }) => {
+      const reason = data?.reason ?? 'unknown';
+      console.log(`[RemoteIngressHub] Edge ${data.edgeId} disconnected: ${reason}`);
+      this.emit('edgeDisconnected', data);
+    });
+    this.bridge.on('management:streamOpened', (data: { edgeId: string; streamId: number }) => {
+      this.emit('streamOpened', data);
+    });
+    this.bridge.on('management:streamClosed', (data: { edgeId: string; streamId: number }) => {
+      this.emit('streamClosed', data);
+    });
+  }
+
+  /**
+   * Start the hub — spawns the Rust binary and starts the tunnel server.
+   */
+  public async start(config: IHubConfig = {}): Promise<void> {
+    this.savedConfig = config;
+    this.stopping = false;
+
+    const spawned = await this.bridge.spawn();
+    if (!spawned) {
+      throw new Error('Failed to spawn remoteingress-bin');
+    }
+
+    // Register crash recovery handler
+    this.bridge.on('exit', this.handleCrashRecovery);
+
+    await this.bridge.sendCommand('startHub', {
+      tunnelPort: config.tunnelPort ?? 8443,
+      targetHost: config.targetHost ?? '127.0.0.1',
+      ...(config.tls?.certPem && config.tls?.keyPem
+        ? { tlsCertPem: config.tls.certPem, tlsKeyPem: config.tls.keyPem }
+        : {}),
+    });
+
+    this.started = true;
+    this.restartAttempts = 0;
+    this.restartBackoffMs = 1000;
+  }
+
+  /**
+   * Stop the hub and kill the Rust process.
+   */
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    if (this.started) {
+      try {
+        await this.bridge.sendCommand('stopHub', {} as Record<string, never>);
+      } catch {
+        // Process may already be dead
+      }
+      this.bridge.removeListener('exit', this.handleCrashRecovery);
+      this.bridge.kill();
+      this.started = false;
+    }
+  }
+
+  /**
+   * Update the list of allowed edges that can connect to this hub.
+   */
+  public async updateAllowedEdges(edges: TAllowedEdge[]): Promise<void> {
+    this.savedEdges = edges;
+    await this.bridge.sendCommand('updateAllowedEdges', { edges });
+  }
+
+  /**
+   * Get the current hub status.
+   */
+  public async getStatus() {
+    return this.bridge.sendCommand('getHubStatus', {} as Record<string, never>);
+  }
+
+  /**
+   * Check if the bridge is running.
+   */
+  public get running(): boolean {
+    return this.bridge.running;
+  }
+
+  /**
+   * Handle unexpected Rust binary crash — auto-restart with backoff.
+   */
+  private handleCrashRecovery = async (code: number | null, signal: string | null) => {
+    if (this.stopping || !this.started || !this.savedConfig) {
+      return;
+    }
+
+    console.error(
+      `[RemoteIngressHub] Rust binary crashed (code=${code}, signal=${signal}), ` +
+      `attempt ${this.restartAttempts + 1}/${MAX_RESTART_ATTEMPTS}`
+    );
+
+    this.started = false;
+
+    if (this.restartAttempts >= MAX_RESTART_ATTEMPTS) {
+      console.error('[RemoteIngressHub] Max restart attempts reached, giving up');
+      this.emit('crashRecoveryFailed');
+      return;
+    }
+
+    await new Promise(resolve => setTimeout(resolve, this.restartBackoffMs));
+    this.restartBackoffMs = Math.min(this.restartBackoffMs * 2, MAX_RESTART_BACKOFF_MS);
+    this.restartAttempts++;
+
+    try {
+      const spawned = await this.bridge.spawn();
+      if (!spawned) {
+        console.error('[RemoteIngressHub] Failed to respawn binary');
+        return;
+      }
+
+      this.bridge.on('exit', this.handleCrashRecovery);
+
+      const config = this.savedConfig;
+      await this.bridge.sendCommand('startHub', {
+        tunnelPort: config.tunnelPort ?? 8443,
+        targetHost: config.targetHost ?? '127.0.0.1',
+        ...(config.tls?.certPem && config.tls?.keyPem
+          ? { tlsCertPem: config.tls.certPem, tlsKeyPem: config.tls.keyPem }
+          : {}),
+      });
+
+      // Restore allowed edges
+      if (this.savedEdges.length > 0) {
+        await this.bridge.sendCommand('updateAllowedEdges', { edges: this.savedEdges });
+      }
+
+      this.started = true;
+      this.restartAttempts = 0;
+      this.restartBackoffMs = 1000;
+      console.log('[RemoteIngressHub] Successfully recovered from crash');
+      this.emit('crashRecovered');
+    } catch (err) {
+      console.error(`[RemoteIngressHub] Crash recovery failed: ${err}`);
+    }
+  };
+}

ts/classes.token.ts

@@ -0,0 +1,66 @@
+/**
+ * Connection token utilities for RemoteIngress edge connections.
+ * A token is a base64url-encoded compact JSON object carrying hub connection details.
+ */
+
+export interface IConnectionTokenData {
+  hubHost: string;
+  hubPort: number;
+  edgeId: string;
+  secret: string;
+}
+
+/**
+ * Encode connection data into a single opaque token string (base64url).
+ */
+export function encodeConnectionToken(data: IConnectionTokenData): string {
+  const compact = JSON.stringify({
+    h: data.hubHost,
+    p: data.hubPort,
+    e: data.edgeId,
+    s: data.secret,
+  });
+  // base64url: standard base64 with + → -, / → _, trailing = stripped
+  return Buffer.from(compact, 'utf-8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Decode a connection token back into its constituent fields.
+ * Throws on malformed or incomplete tokens.
+ */
+export function decodeConnectionToken(token: string): IConnectionTokenData {
+  let parsed: { h?: unknown; p?: unknown; e?: unknown; s?: unknown };
+  try {
+    // Restore standard base64 from base64url
+    let base64 = token.replace(/-/g, '+').replace(/_/g, '/');
+    // Re-add padding
+    const remainder = base64.length % 4;
+    if (remainder === 2) base64 += '==';
+    else if (remainder === 3) base64 += '=';
+
+    const json = Buffer.from(base64, 'base64').toString('utf-8');
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error('Invalid connection token');
+  }
+
+  if (
+    typeof parsed.h !== 'string' ||
+    typeof parsed.p !== 'number' ||
+    typeof parsed.e !== 'string' ||
+    typeof parsed.s !== 'string'
+  ) {
+    throw new Error('Invalid connection token: missing required fields');
+  }
+
+  return {
+    hubHost: parsed.h,
+    hubPort: parsed.p,
+    edgeId: parsed.e,
+    secret: parsed.s,
+  };
+}

ts/connector.private.ts

@@ -1,26 +0,0 @@
-import * as tls from 'tls';
-
-export class ConnectorPrivate {
-  private targetHost: string;
-  private targetPort: number;
-
-  constructor(targetHost: string, targetPort: number) {
-    this.targetHost = targetHost;
-    this.targetPort = targetPort;
-    this.connectToPublicRemoteConnector();
-  }
-
-  private connectToPublicRemoteConnector(): void {
-    const options = {
-      // If your server requires client certificate authentication, you can specify key and cert here as well
-    };
-
-    const tunnel = tls.connect({ port: 4000, ...options }, () => {
-      console.log('Connected to PublicRemoteConnector on port 4000');
-    });
-
-    tunnel.on('data', (data: Buffer) => {
-      // Similar logic for forwarding data to and from the target
-    });
-  }
-}

ts/connector.public.ts

@@ -1,32 +0,0 @@
-import * as tls from 'tls';
-import * as fs from 'fs';
-
-export class ConnectorPublic {
-  private tunnel: tls.TLSSocket | null = null;
-
-  constructor() {
-    this.createTunnel();
-    this.listenOnPorts();
-  }
-
-  private createTunnel(): void {
-    const options = {
-      key: fs.readFileSync('path/to/key.pem'),
-      cert: fs.readFileSync('path/to/cert.pem')
-    };
-
-    const server = tls.createServer(options, (socket: tls.TLSSocket) => {
-      this.tunnel = socket;
-      console.log('Tunnel established with LocalConnector');
-    });
-
-    server.listen(4000, () => {
-      console.log('PublicRemoteConnector listening for tunnel on port 4000');
-    });
-  }
-
-  private listenOnPorts(): void {
-    // Implement similar logic for listening on ports 80 and 443
-    // Keep in mind you may need to adjust how you handle secure and non-secure traffic
-  }
-}

ts/index.ts

@@ -1,3 +1,3 @@
-import * as plugins from './remoteingress.plugins.js';
-
-export let demoExport = 'Hi there! :) This is an exported string';
+export * from './classes.remoteingresshub.js';
+export * from './classes.remoteingressedge.js';
+export * from './classes.token.js';

ts/plugins.ts

@@ -0,0 +1,7 @@
+// node native scope
+import * as path from 'path';
+export { path };
+
+// @push.rocks scope
+import * as smartrust from '@push.rocks/smartrust';
+export { smartrust };

ts/remoteingress.plugins.ts

@@ -1,4 +0,0 @@
-const removeme = {};
-export {
-  removeme
-}