@kadi.build/file-sharing 1.1.2 → 1.2.0

package/README.md

@@ -141,6 +141,8 @@ The `.env` loader supports monorepo layouts: if your `.env` is at the workspace
 | `KADI_TUNNEL_PORT` | KĀDI frps server port | `7000` |
 | `KADI_TUNNEL_SSH_PORT` | KĀDI SSH gateway port | `2200` |
 | `KADI_TUNNEL_MODE` | Connection mode: `ssh`, `frpc`, or `auto` | `auto` |
+| `KADI_TUNNEL_TRANSPORT` | Transport protocol: `wss` (via gateway on :443) or `tcp` (direct) | `wss` |
+| `KADI_TUNNEL_WSS_HOST` | WSS gateway hostname (e.g., `tunnel-control.kadi.build`) | — |
 | `KADI_AGENT_ID` | Agent identifier for proxy naming | `kadi` |
 | **Tunnel — Ngrok** | | |
 | `NGROK_AUTHTOKEN` | Ngrok auth token (also accepts `NGROK_AUTH_TOKEN`) | — |
@@ -162,6 +164,8 @@ KADI_TUNNEL_DOMAIN=tunnel.kadi.build
 KADI_TUNNEL_PORT=7000
 KADI_TUNNEL_SSH_PORT=2200
 KADI_TUNNEL_MODE=ssh
+KADI_TUNNEL_TRANSPORT=wss
+KADI_TUNNEL_WSS_HOST=tunnel-control.kadi.build
 KADI_AGENT_ID=my-agent
 
 # Optional: Ngrok (fallback)
@@ -248,6 +252,8 @@ const server = new FileSharingServer({
     kadiSshPort: undefined,
     kadiMode: undefined,           // 'ssh' | 'frpc' | 'auto'
     kadiAgentId: undefined,
+    kadiTransport: undefined,       // 'wss' (default) | 'tcp'
+    kadiWssControlHost: undefined,  // WSS gateway hostname
     // Ngrok-specific
     ngrokAuthToken: undefined,
     // Advanced
@@ -565,6 +571,17 @@ KĀDI is the default and recommended tunnel service. It supports two connection
 
 Set `KADI_TUNNEL_MODE=ssh` (or `frpc`) in your `.env` to force a specific mode.
 
+### Transport Protocol
+
+When using **frpc** mode, the control channel transport can be configured:
+
+| Transport | Description | Default |
+|-----------|-------------|---------|
+| **wss** | Routes the frpc control channel through a WSS gateway on port 443. Works reliably on enterprise/campus networks that block non-standard ports. | ✅ Default |
+| **tcp** | Direct TCP connection to the frps server port (typically 7000). | — |
+
+Set `KADI_TUNNEL_TRANSPORT=wss` and `KADI_TUNNEL_WSS_HOST=tunnel-control.kadi.build` in your `.env` to use WSS transport. TCP mode can be forced with `KADI_TUNNEL_TRANSPORT=tcp`.
+
 If KĀDI credentials are not provided, the tunnel will automatically fall back to free services (serveo → localtunnel → pinggy → localhost.run) unless `autoFallback: false` is set.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadi.build/file-sharing",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "File sharing service with tunneling and local S3-compatible interface",
   "type": "module",
   "main": "src/index.js",
@@ -43,7 +43,7 @@
   ],
   "dependencies": {
     "@kadi.build/file-manager": "^1.0.0",
-    "@kadi.build/tunnel-services": "^1.0.2",
+    "@kadi.build/tunnel-services": "^1.0.5",
     "chalk": "^5.3.0",
     "cors": "^2.8.5",
     "express": "^4.18.0",

package/src/FileSharingServer.js

@@ -80,6 +80,8 @@ function _loadEnvFile() {
  *   KADI_TUNNEL_PORT    — KĀDI frpc port (default: 7000)
  *   KADI_TUNNEL_SSH_PORT— KĀDI SSH gateway port (default: 2200)
  *   KADI_TUNNEL_MODE    — ssh | frpc | auto (default: auto)
+ *   KADI_TUNNEL_TRANSPORT— wss | tcp (default: wss)
+ *   KADI_TUNNEL_WSS_HOST — WSS gateway hostname (e.g., tunnel-control.kadi.build)
  *   KADI_AGENT_ID       — Agent identifier for proxy naming
  *   NGROK_AUTHTOKEN     — Ngrok auth token (also: NGROK_AUTH_TOKEN)
  *   KADI_S3_ACCESS_KEY  — S3 access key (default: minioadmin)
@@ -104,6 +106,8 @@ function loadSecrets() {
     kadiSshPort:    process.env.KADI_TUNNEL_SSH_PORT ? Number(process.env.KADI_TUNNEL_SSH_PORT) : undefined,
     kadiMode:       process.env.KADI_TUNNEL_MODE,
     kadiAgentId:    process.env.KADI_AGENT_ID,
+    kadiTransport:      process.env.KADI_TUNNEL_TRANSPORT,
+    kadiWssControlHost: process.env.KADI_TUNNEL_WSS_HOST,
     ngrokAuthToken: process.env.NGROK_AUTHTOKEN || process.env.NGROK_AUTH_TOKEN,
     s3AccessKey:    process.env.KADI_S3_ACCESS_KEY,
     s3SecretKey:    process.env.KADI_S3_SECRET_KEY,
@@ -251,6 +255,9 @@ export class FileSharingServer extends EventEmitter {
       kadiSshPort:  tunnelCfg.kadiSshPort  || secrets.kadiSshPort,
       kadiMode:     tunnelCfg.kadiMode     || secrets.kadiMode,
       kadiAgentId:  tunnelCfg.kadiAgentId  || secrets.kadiAgentId,
+      // KĀDI transport (WSS gateway)
+      kadiTransport:      tunnelCfg.kadiTransport      || secrets.kadiTransport,
+      kadiWssControlHost: tunnelCfg.kadiWssControlHost  || secrets.kadiWssControlHost,
       // Ngrok auth (env vars as fallback)
       ngrokAuthToken: tunnelCfg.ngrokAuthToken || secrets.ngrokAuthToken,
       // Pass through any extra service-specific options